# Dee Wan CMS documentation: full text

> What Dee Wan is, how the live CMS API differs from a standalone backend you own, and where to start reading the documentation.

Documentation revision `903447f1d74348b67db0dbc34302c9553f0de5fb23acaf757e8fc2e89383efe4`. Every public English page, in navigation order. Each page starts on its own line with `<!-- dee-wan-docs page: <path> -->`.

<!-- dee-wan-docs page: / -->

# Dee Wan CMS documentation

Source: https://dee-wan-docs.pages.dev/

Dee Wan is a multilingual, multi-site headless CMS in your own Cloudflare account.

## Live CMS or a backend you own

Generate a standalone backend you own: Prisma schema, migrations, routes, database and deployment. Its API runs independently; website blog, search, comments and forms [remain connected](/detachment-contract/#what-still-depends-on-dee-wan).

The CMS public API reflects published changes immediately. Generated APIs and static pages use a snapshot; regenerate and deploy to update them.

A standalone backend is optional. See the [standalone overview](/guides/standalone-backend/) or [Dee Wan and Strapi](/reference/strapi-comparison/).

![The seeded Dee Wan dashboard](/assets/screenshots/dashboard.webp)

## Getting started

[Install Dee Wan](/guides/installation/), [create the first administrator](/guides/first-administrator/), then follow the [first-site walkthrough](/guides/first-site/).

## Common tasks

Editors use the [page builder](/guides/page-builder/), [Blog](/guides/blog/) and [content planner](/guides/content-planner/). Administrators define [models and fields](/reference/models-and-fields/) and manage [people and access](/guides/people-and-access/).

Developers start with [preview and the TypeScript client](/guides/preview-and-client/) and the [public API](/reference/public-api/). Scripts and agents use the [management API](/reference/management-api/). Extend Dee Wan by [writing a plugin](/plugins/authoring/).

Operators [import from Strapi or WordPress](/guides/import-migration/) and maintain [backups](/guides/backup-restore/).

Feature guides cover [draft-body search](/guides/content-editing/#find-and-open-an-item), [editing from the rendered preview](/guides/preview-and-client/#edit-from-the-preview), [browser origins](/reference/public-api/#browser-origins), [generated application accounts](/reference/standalone-backend-api/#application-account-administration) and [selected-content refresh](/guides/import-migration/#refresh-selected-content).

## Navigate the CMS

**Search** or **Cmd/Ctrl+K** opens permitted workspace and **Settings** destinations. In the page builder, the shortcut may open the section gallery; **Search** still opens navigation.

This site's **Search** searches documentation.

## Maturity

Dee Wan is pre-MVP, not released. Features are tested locally; complete acceptance on a real Cloudflare account remains pending. The [1.0 product boundary](/boundary/) identifies supported features, supervised pilots and unavailable capabilities.

<!-- dee-wan-docs page: /guides/installation/ -->

# Install Dee Wan

Source: https://dee-wan-docs.pages.dev/guides/installation/

This guide installs Dee Wan CMS into your own Cloudflare account. An installation is the admin
Worker, the public read Worker, the admin UI on Cloudflare Pages, one control D1 database, media
storage, and the credentials behind them. It is created once, has one claim link, and serves many
sites (see the [product vocabulary](/reference/vocabulary/)).

To look around first without a Cloudflare account, use the
[local trial](/guides/local-development/#try-it-locally-with-no-cloudflare-account) instead: it runs the whole
product against a local database on your machine.

You install with the command-line installer: `npm run setup` for an interactive run, and
`npm run install:cms -- <verb>` for planned, resumable and scriptable runs. It needs a Cloudflare
API token. It keeps your answers in `backend/wrangler.jsonc` and its progress in a step ledger, and
runs the list of steps that `npm run plan` prints.

A browser-based installer also exists, but it needs a Cloudflare OAuth application you register
yourself and is not a supported installation path. See [Web installer preview](/guides/web-installer-preview/).

> Dee Wan 1.0 is pre-release. Installing against real Cloudflare is one of the acceptance gates that
> remain open. See the [1.0 product boundary](/boundary/) for what is and is not
> covered.

GitHub credentials depend on the workflow. Configure the admin GitHub App separately from the CLI device flow. The installer’s optional App link does not configure the Worker. Use the [authentication matrix](/guides/github-authentication/), then follow [first site to published content](/guides/first-site/).

## Before you start

### What you need

- A Cloudflare account with Workers, D1, Pages, and R2 **or** Cloudflare Images.
- Node 22 (22.14 or later) or Node 24 (24.10 or later). The repository ships an `.nvmrc`
  (24.18.1), so `nvm use` selects the right version.
- npm exactly as `package.json` declares it (11.16.0), which is the npm that the `.nvmrc` Node
  ships with.
- Git, to clone the repository with its submodules.
- Optionally, your own domain. To use it, the domain must be a zone in the same Cloudflare account.
  Without one, the installation uses the addresses Cloudflare provides (`pages.dev` and
  `workers.dev`).
- Optionally, an inference provider key for AI features. DeepInfra is the default; an OpenAI-compatible provider can be configured after installation.

Cloudflare Access (Zero Trust) is not required. The installer offers it as an extra perimeter in
front of the admin, and it is off unless you turn it on.

### Get the code and install dependencies

```bash
git clone --recurse-submodules https://github.com/dee-wan-cms/dee-wan.git
cd dee-wan
node scripts/install-dependencies.mjs
node scripts/install-dependencies.mjs frontend
```

The first dependency-install command installs the root and backend dependencies. The second installs the admin UI dependencies,
which the installer builds and deploys. Always install with `node scripts/install-dependencies.mjs`,
never with a bare `npm install` or `npm ci`. It refuses any other npm version, installs the locked
dependency tree with install scripts disabled, and then rebuilds only the packages whose scripts
are approved.

A fresh clone needs no manual build step: `setup`, `deploy` and `migrate:d1` build the packages and
the Prisma client if they are missing.

### What gets created

These are the steps the installer runs, in order. `npm run plan` prints the same list for your
configuration, with the state of each step.

| Step | What it creates or does |
| --- | --- |
| Check Node and Wrangler | Checks only. |
| Resolve the Cloudflare API token | Checks only. |
| Choose the Cloudflare account | Checks only. |
| Preflight — token scopes, plan, existing resources | Checks only. Stops the run before anything is created if a check fails. |
| Create the control D1 database | A D1 database (default name `dee-wan-cms-db`). |
| Apply migrations to D1 | The schema, and the seeded roles and workflow. |
| Provision the private import archive bucket | A private R2 bucket for import archives. The installer creates it only when you choose it. |
| Connect the initial site to its hostname | A public hostname for the initial site. |
| Build the admin UI | Builds only. |
| Deploy the admin UI to Pages | A Pages project (default name `dee-wan-cms`). |
| Deploy the admin Worker | A Worker (default name `dee-wan-cms-backend`). |
| Generate and store the session signing secret | A Worker secret. |
| Provision media storage | An R2 media bucket, or a Cloudflare Images binding. |
| Deploy the public API | The public read Worker (named after the admin Worker, with `-public` appended) and its hostname. |
| Deploy the website form intake | The form intake Worker (named after the admin Worker, with `-intake` appended). Skipped when `DEPLOY_FORM_INTAKE` is `false`; website forms then take no submissions. |
| Generate and store the site-token signing key | A Worker secret on the admin and public Workers. |
| Attach the Worker routes | Two Worker routes on your zone: `<admin host>/api/*` and `<admin host>/.well-known/oauth-*`. The installer creates them only with your own domain. Teardown removes them only while they still point at this Worker. |
| Point DNS at the deployment | DNS records under your domain. The installer creates them only with your own domain and DNS setup turned on. |
| Put Cloudflare Access in front of the admin | An Access application and policy. The installer creates them only when you turn Access on. |
| Check the deployment answers | Checks only. |
| Mint the first administrator's claim link | A single-use link, shown once. |

Resources such as the Workers, the Pages project, the D1 database and the R2 buckets are billable
Cloudflare resources in the account you choose.

With your own domain, the admin UI is served at `cms.<your-domain>` and the public API at
`content.<your-domain>` by default. Without one, the admin UI is served at
`<pages-project>.pages.dev` and the public API at
`<admin-worker>-public.<your-workers.dev-subdomain>.workers.dev`.

## Command-line installer

### Credentials

The installer needs a Cloudflare API token. `npm run setup` prompts for one if none is set, prints
the permissions it needs with a reason for each, and gives a link to Cloudflare's token editor with
those permissions selected. Include all accounts and zones.

| Permission | Needed for | Why |
| --- | --- | --- |
| Account · Account Settings · Read | Every install | Read the account name and settings. |
| Account · D1 · Edit | Every install | Create the database and apply migrations. |
| Account · Workers Scripts · Edit | Every install | Deploy the admin, public-read and form-intake Workers, their secrets and custom domains. |
| Account · Cloudflare Pages · Edit | Unless the admin UI deploy is turned off | Create and deploy the admin UI project. |
| Account · Workers R2 Storage · Edit | Media in R2, or the import bucket | Create the media and import buckets. |
| Zone · Zone · Read | Your own domain | Find the zone your domain belongs to. |
| Zone · Workers Routes · Edit | Your own domain | Route the admin and site hostnames to the Workers. |
| Zone · DNS · Edit | Your own domain with DNS setup on | Point the admin hostname at the deployment. |
| Zone · Zone WAF · Edit | Your own domain (optional) | Install the sign-in rate-limit rule and the optional public API rule. Without it both are skipped with a warning; the Worker's own sign-in limiter still applies. |
| Account · Access: Apps and Policies · Edit | Cloudflare Access only | Create the Access application and policy in front of the admin. |
| Account · Access: Organizations, Identity Providers, and Groups · Read | Cloudflare Access only | Read your Access team domain. |

`npm run setup` and `npm run doctor` print this list for the choices already in your config. The
Access rows are requested only once you turn Access on. Any other choice you have not made yet is
requested and marked with its condition, and a choice you turned off is not requested. The pre-filled token link selects the same rows, except Zone · Zone WAF · Edit, which
the printed list tells you to add by hand. Verifying the token needs no extra permission.

If you use Cloudflare Images, `setup` recommends a separate token with only the Cloudflare Images:
Edit permission.

To skip the prompts, set the token and account in the environment:

```bash
export CLOUDFLARE_API_TOKEN=…    # skips the token prompt
export CLOUDFLARE_ACCOUNT_ID=…   # skips the account picker
```

Credentials are resolved in this order: a variable exported in your shell, then the repository's
`.env` file, then values in `backend/wrangler.jsonc`. When the environment overrides a different
value in the config, the installer says so.

The token is checked before anything is created. An interactive run allows three attempts. A
non-interactive run stops at the first failure. Either way, a token that cannot be verified means
no Cloudflare resources are created.

Application secrets are never stored in `wrangler.jsonc`. See [Secrets](/guides/local-development/#secrets).

### Interactive install: `npm run setup`

```bash
npm run setup
```

`setup` walks through the installation and saves each answer to `backend/wrangler.jsonc` as it
goes, so a second run does not ask again. In order, it:

1. Finds or creates `backend/wrangler.jsonc` and resolves the token and account. If the token
   reaches several accounts, it asks which one to use.
2. Asks which D1 plan the account uses. Free allows 500 MB per database. Paid allows 10 GB per database.
3. Runs preflight and prints a report. If a check fails, it stops before creating anything ("Setup
   stopped before creating any Cloudflare resources. Fix the FAIL rows above."). If resources will
   be created or modified, it asks you to confirm.
4. Asks where the installation will live (your own domain, or the addresses Cloudflare provides),
   then the domain, the admin subdomain (default `cms`) and the public content API subdomain
   (default `content`).
5. Asks whether to set up DNS, whether to set up Cloudflare Access (default no), and whether to
   install a rate-limiting rule on the public API (default no).
6. Asks for the Pages project name and the Worker name.
7. Asks for the storage provider, **Cloudflare R2** or **Cloudflare Images**. For R2 it creates the
   bucket (default `dee-wan-cms-images`), enables public access through the managed `r2.dev`
   address or a custom media domain, and checks that uploaded files are actually served.
8. Asks whether to enable data import, which creates a private R2 bucket for uploaded archives
   (default no).
9. Creates the D1 database and offers to apply the schema (default yes). A fresh install needs no
   separate migrate step.
10. Builds and deploys the admin UI, the admin Worker, the public read Worker and the form intake
    Worker, stores the Worker secrets, and attaches the route, DNS records and Access application
    you chose. It writes `backend/wrangler.public.jsonc` and `backend/wrangler.intake.jsonc` once
    the account, zone and database id are settled, and never overwrites an existing one.
11. Offers to run health checks.
12. Asks for the first administrator's email, if `BOOTSTRAP_ADMIN_EMAIL` is not already set, and
    prints the claim link.

It ends with "Setup complete!", a configuration summary and the next steps. If a required part is
missing, it ends with "Setup did not complete" and names what is missing instead.

`setup` also accepts `--access` / `--no-access` and `--public-rate-limit` /
`--no-public-rate-limit` to answer those questions on the command line, for example
`npm run setup -- --no-access`.

### Plan first: `npm run plan`

```bash
npm run plan
npm run plan -- --json
```

`plan` prints every step an installation would perform and the state each one is already in. It
works only from the configuration and ledger on disk: it touches no network, creates nothing and
costs nothing. `--json` prints a machine-readable plan with a `planVersion`.

Each step has one of these states:

| Mark | State | Meaning |
| --- | --- | --- |
| `✓` | done | Recorded as completed. |
| `•` | to do | Will run. |
| `–` | not applicable | Skipped for this configuration, with the reason. |
| `✗` | blocked | Cannot run yet, for example because no Cloudflare API token was found. |
| `?` | unresolved | A previous run asked for this and never recorded an answer, or it failed. `apply` checks the account before repeating it, and refuses rather than guesses. |
| `↻` | re-checked | A check that runs on every apply. |

### The installer verbs: `npm run install:cms`

```bash
npm run install:cms -- <verb> [options]
```

| Verb | What it does | Changes the account |
| --- | --- | --- |
| `plan` | Says what an install would do. The same as `npm run plan`. | No |
| `apply` | Runs the install. | Yes, creates billable resources |
| `resume` | Continues an install that stopped part-way. Refuses if no step has been completed yet. | Yes, creates billable resources |
| `doctor` | Preflight checks. Changes nothing. | No |
| `verify` | Drives a deployment end to end. Never point it at production. Add `--read-only` there. | Creates a site, a model and content, unless `--read-only` |
| `teardown` | Removes what the install created. A dry run unless `--apply` is passed. | Only with `--apply` |
| `manifest` | Prints a redacted record of the install (account, resource names, step history) for handing it over. It never contains a credential. | No |

`apply` and `resume` run the same engine as `npm run setup`. The step ledger is what makes a
second run continue rather than repeat: each completed step is recorded in a ledger file in the
repository root, one file per Cloudflare account (`.dee-wan-cms-install.<account>.json`). A
ledger file that cannot be read completely stops the run instead of being ignored.

Options:

| Option | Meaning |
| --- | --- |
| `--config <file>` | Which installation to act on. Default `wrangler.jsonc`. A bare name is looked up in `backend/`. |
| `--account <id>` | The Cloudflare account to target, explicitly. Every step the command runs targets that account. |
| `--json` | Machine-readable output. Implies `--yes`. |
| `--yes`, `-y` | Never prompt. Fail instead of asking. |

`verify` also forwards `--read-only`, `--public`, `--admin`, `--email`, `--model` and
`--disposable`, and `teardown` forwards `--apply` and `--yes`. Any other option, a repeated option,
or an option given with an empty value (such as `--account=` from an unset shell variable) is
refused, not ignored.

`apply`, `resume`, `teardown` and `verify` (unless `--read-only`) need an account. They take it
from `--account`, then `CLOUDFLARE_ACCOUNT_ID`, then `account_id` in the config, and refuse if
none is named.

### Exit codes

`install:cms` exits with a fixed code, so a script can branch on the result:

| Code | Name | Meaning | What to do |
| --- | --- | --- | --- |
| 0 | ok | The install is complete. | Nothing. |
| 1 | usage | The command line was wrong, or `resume` found nothing to resume. | Fix the command. |
| 2 | blocked | Something only you can supply is missing, such as a token or an account. | Supply it, then run again. |
| 3 | failed | The run failed. | Read the output and fix the cause before repeating. |
| 4 | incomplete | The run did not fail, but work remains. | Safe to retry as it is, usually with `resume`. |
| 5 | unresolved | A step was started and its outcome is unknown. | Look at the account before repeating anything. |

`plan` uses the same codes to describe the current state: 2 when a step is blocked, 5 when one is
unresolved, 4 when work is left, and 0 when everything is done.

### Running unattended

With `--yes`, `--json`, `DEEWAN_YES=1` or `CI=true`, every prompt takes its default. A question
with no safe default is an error that names the setting to add, instead of a guess:

- Where the installation lives: set `"DOMAIN_MODE": "custom"` with `"DOMAIN"`, or
  `"DOMAIN_MODE": "cloudflare"`, under `vars` in `backend/wrangler.jsonc`.
- The D1 plan: set `"D1_PLAN": "free"` or `"paid"` under `vars`, or export `D1_PLAN`.
- The account, when the token reaches several: set `account_id` in the config or export
  `CLOUDFLARE_ACCOUNT_ID`.
- The first administrator: set `BOOTSTRAP_ADMIN_EMAIL` under `vars`. An unattended run does not
  ask for it, and without it no claim link can be minted.

For example:

```bash
npm run install:cms -- apply --account <account-id> --json
```

### Sharing a Cloudflare account

The default resource names (`dee-wan-cms-backend`, `dee-wan-cms-db` and so on) are fixed, so two
installations in one Cloudflare account collide. Set `DEEWAN_RESOURCE_PREFIX` to namespace every
resource a run provisions:

```bash
DEEWAN_RESOURCE_PREFIX=test-a1b2 npm run setup      # creates test-a1b2-dee-wan-cms-db, …
```

The prefix must contain only lowercase letters, digits and dashes, start with a letter or digit,
and be at most 24 characters long.

Set it for a fresh installation, not an existing one. Wrangler finds the D1 database by the name in
`backend/wrangler.jsonc`, so the prefix only works once `setup` has written the prefixed names into
that file. See [Running the installer against a shared account](/guides/local-development/#running-the-installer-against-a-shared-account).

Teardown does not decide by name. It deletes only what the install record says this installation
created. See [Starting over or tearing down](#starting-over-or-tearing-down).

## After installing

### Claim the installation

Nobody has an account until the installation is claimed. `npm run setup` prints a single-use claim
link once, with the email address it is bound to and when it expires. It expires after 15 minutes.
Only its hash is stored, so it cannot be printed again.

Open it and create the first administrator as described in
[Create and replace the first administrator](/guides/first-administrator/#claim-the-installation).

If the link expires before anyone uses it, run the installer again (`npm run setup` or
`npm run install:cms -- resume`). An expired claim link counts as not done, so the run mints a new
one as long as the installation has not been claimed. `npm run claim:link` can also replace it. See
[Create and replace the first administrator](/guides/first-administrator/#claim-the-installation).

### Verify it works

- `npm run health` runs post-deploy checks against the deployed addresses. With Access enabled, it
  also checks the perimeter, using the service token in `CF_ACCESS_CLIENT_ID` and
  `CF_ACCESS_CLIENT_SECRET`.
- `npm run verify -- --read-only --public <public-api-url>` checks a deployment without writing
  anything. Add `--model <slug>` to read one published model.
- `npm run verify -- --admin <url> --public <url> --email <address> --disposable`, with
  `VERIFY_PASSWORD` in the environment, creates a site, a model and content. Use it only on a
  disposable deployment: the admin API can deactivate a site but not delete it.
- `npm run doctor` is a read-only preflight that names anything missing and how to fix it.
- `npm run plan` should report nothing left to do.

### Add secrets for optional features

Secrets are set with `wrangler secret put` from the `backend/` directory, never in a file. For
example, the AI features need a DeepInfra key:

```bash
npx wrangler secret put DEEPINFRA_API_KEY
```

For an OpenAI-compatible provider, set `AI_PROVIDER="openai-compatible"`, `AI_BASE_URL` and `AI_TEXT_MODEL` as Worker variables, then add `AI_API_KEY` with `wrangler secret put`. Optional `AI_VISION_MODEL` and `AI_IMAGE_MODEL` enable those capabilities; deployment-owned model lists use `AI_TEXT_MODELS`, `AI_VISION_MODELS` and `AI_IMAGE_MODELS`. See [Inference provider](/guides/local-development/#inference-provider).

See [Secrets](/guides/local-development/#secrets) for every optional secret and setting: mail, the GitHub App for
repository delivery, cache purge, AI limits and error reporting.

Large media uploads: the admin streams documents, audio, video and other files up to 100 MB, the
request body limit of Cloudflare's Free and Pro plans. Business allows 200 MB and Enterprise up to
5 GB ([Workers limits](https://developers.cloudflare.com/workers/platform/limits/), read
2026-10-12). Set it only if your plan allows more: `"MEDIA_REQUEST_BODY_LIMIT_BYTES": "200000000"`
under `vars`. Values above 5 GB are capped at 5 GB. Settings → Site → Media files and the upload
dialog show the current limit. Images and every whole-file path (management API, plugins,
legacy buffered imports) stay at 32 MiB. Chunked native site/history transfers carry larger accepted files; see [Import and migration](/guides/import-migration/).

### Deploy changes

The installer deploys everything once. After you change code or configuration, deploy again:

```bash
npm run deploy   # admin UI, admin Worker, public read Worker and form intake Worker
npm run health
```

`deploy` refuses to run without `backend/wrangler.public.jsonc`. An installation that deliberately
serves no public content deploys with `npm run deploy -- --admin-only`. See
[Deploy](/guides/local-development/#deploy).

`deploy` also ships `backend/wrangler.intake.jsonc` when it exists. Without it, or with
`--no-form-intake`, it deploys no intake Worker and says that website forms take no submissions. With
a non-default admin config, name the intake config with `--intake-config <file>`.

Website forms post to `/v1/interactions/form.submit` on the site's own host. A route
`<host>/v1/interactions/*` sends those posts to the intake Worker; it is more specific than the public
API's `<host>/v1/*`. Managed delivery attaches it to each site host when the deployment service runs
with `MANAGED_RENDER_INTAKE_WORKER_SCRIPT` set to the intake Worker's name. For any other site host,
add that route to the intake Worker yourself. `npm run provision:site` binds each site's database to
the intake Worker too, when `backend/wrangler.intake.jsonc` exists.

## Upgrading

To move an installation to a newer release, from the repository root:

```bash
git pull
npm run submodules:sync                            # update packages/ to the new pins
node scripts/install-dependencies.mjs              # reinstall root and backend dependencies
node scripts/install-dependencies.mjs frontend     # reinstall admin UI dependencies
npm run build:packages && npm run prisma:generate  # rebuild the vendored packages and Prisma client
npm run migrate:d1                                 # apply new migrations to the control database
npm run tenant:upgrade                             # only if you used npm run provision:site
npm run deploy
npm run health
```

- The rebuild step is needed because `setup`, `deploy` and `migrate:d1` build the packages only
  when they are missing, not when they are out of date.
- `migrate:d1` prints the config and database it is about to change before it runs. Add
  `-- --config <file>` for an installation that is not `backend/wrangler.jsonc`, and pass the same
  `--config` (with `--public-config`) to `deploy`.
- `tenant:upgrade` brings existing per-site databases forward. Run `npm run tenant:upgrade -- --plan`
  first to see what each site is missing without writing anything.
- `deploy` refuses to ship the admin Worker while the control database has pending migrations, or
  when it cannot tell, so running it before `migrate:d1` stops rather than deploying new code over
  an old schema. `--skip-migration-check` overrides this. Use it only when you know the new code
  does not need the pending migrations.

See [Database migrations](/guides/database-migrations/) for what the migration commands do and how
to recover from a failed one.

## Starting over or tearing down

`npm run teardown` deletes what setup created for an installation. Without `--apply` it is a dry
run: it lists every resource it would delete and every resource it will keep, with the reason, and
changes nothing.

```bash
npm run teardown                # dry run of the default installation
npm run teardown -- --apply     # delete it
```

### Which installation

Without options, teardown acts on the default installation: `backend/wrangler.jsonc`, with
`backend/wrangler.public.jsonc` and `backend/wrangler.intake.jsonc`. For another installation, name
its config files:

```bash
npm run teardown -- --config <admin config> --public-config <public config> --intake-config <intake config>
```

A companion config you do not name is treated as absent. Teardown never borrows the default
installation's companion files.

### What it removes

- the admin, public-read and form-intake Workers, with their routes and custom domains.
- the Pages project.
- the D1 databases.
- the R2 buckets. Each is emptied, then deleted.
- the Access application.
- the DNS records and rate-limit rules setup created.
- the managed renderers recorded for the selected sites.

### What it keeps

Setup writes an install record, `.dee-wan-cms-install.<account>.json` in the repository root. It is
the same file as the step ledger. Teardown deletes only resources that the record says this
installation created and that still match the identity recorded for them. It lists and keeps:

- resources setup found already in place and adopted, including R2 buckets.
- resources that changed since setup recorded them.
- resources setup did not confirm creating, for example after an interrupted run. Running setup
  again confirms them.
- resources it cannot read. Teardown deletes nothing until they answer.
- the D1 databases and R2 buckets while any Worker of the installation stays deployed.

Teardown never deletes your local config files.

### Deleting

With `--apply`, you choose whether to export each D1 database to a local `.sql` file first. Then
teardown names the Cloudflare account and asks yes or no. The answer defaults to no.

Unattended, pass `--yes`, plus `--export-dir <directory>` or `--skip-export`. Without `--yes`, an
unattended run answers no and deletes nothing.

Teardown deletes in this order: routes, custom domains, DNS records and the Access application
first, then the Workers and the Pages project, then the R2 buckets and D1 databases. It confirms
each deletion by reading the resource back.

If something fails, the install record stays and teardown lists what remains. Fix the cause and run
it again. The record is removed only when everything it lists is gone.

An install record written by an older installer version is refused with a message. Move that file
aside before running teardown.

`npm run install:cms -- teardown` runs the same script for the chosen config and account. It
forwards `--apply`, `--yes`, `--public-config`, `--intake-config`, `--export-dir` and
`--skip-export`.

## Troubleshooting

**Start with `npm run doctor` and `npm run plan`.** `doctor` names what is missing and how to fix
it. `plan` shows which step is done, left, blocked or unresolved, without touching the network.

**Building the admin UI fails because a package or `vite` cannot be found.** The admin UI's
dependencies are not installed. Run `node scripts/install-dependencies.mjs frontend`.

**The installer says `DOMAIN` is set but `DOMAIN_MODE` is not.** A domain without a mode is
refused, not read as a custom domain. Under `vars` in `backend/wrangler.jsonc`, set
`"DOMAIN_MODE": "custom"` to use that domain, or set `"DOMAIN_MODE": "cloudflare"` and remove
`DOMAIN`. Then run again. Nothing was created.

**A run stopped part-way.** Resume it with `npm run install:cms -- resume`. Completed steps are
not repeated. `resume` refuses when nothing has been completed yet.
Use `apply` then.

**Exit code 4 (incomplete).** The run did not fail, and it is safe to retry without changes. Read the
output for what was left, usually something to fix at Cloudflare, then resume.

**Exit code 3 (failed).** Read the output, fix the cause, then run again.

**Exit code 5, or a step marked `?` (unresolved).** A previous run asked Cloudflare for something
and never recorded the answer, or it failed. The installer checks the account before repeating the
step, and refuses if it cannot tell. Look at the named resource in your Cloudflare account, resolve
it, then run again.

**Preflight fails.** `setup` stops before creating anything. Fix the rows marked FAIL in the report
and run again.

**The token cannot be verified.** Check its permissions, its expiry, and that it covers the
account. Nothing is created until verification succeeds.

**"the API token lacks Zone → WAF → Edit".** A rate-limit rule was skipped. The install continues
without it. Add the permission and run `setup` again if you want the rule.

**An unattended run stops with a missing answer.** The message names the setting to add to
`backend/wrangler.jsonc` (or the environment variable to export). Add it and run again. See
[Running unattended](#running-unattended).

**"Setup did not complete: this deployment has no way in."** No claim link could be minted, or the
session signing secret is not installed. Set `BOOTSTRAP_ADMIN_EMAIL` under `vars` in
`backend/wrangler.jsonc` (exactly one address), fix any cause the output names, and run `setup`
again.

**`deploy` refuses with pending migrations.** Apply them with `npm run migrate:d1`, then deploy
again. See [Upgrading](#upgrading).

**The claim link expired.** Run the installer again to mint a new one. See
[Claim the installation](#claim-the-installation).

## Next step

Open the claim link and [set up the first administrator](/guides/first-administrator/).

<!-- dee-wan-docs page: /guides/first-administrator/ -->

# Create and replace the first administrator

Source: https://dee-wan-docs.pages.dev/guides/first-administrator/

Dee Wan has no public registration. A fresh installation has no account until someone consumes its one-time claim link. The installer binds that link to one normalized `BOOTSTRAP_ADMIN_EMAIL`. The claim page never accepts a different address.

## Configure the methods before deployment

`BETTER_AUTH_SECRET` is required and is generated by the installer. Put provider credentials in Worker secrets, never in `vars`. Put the non-secret settings in `backend/wrangler.jsonc`.

| Method | Required configuration |
| --- | --- |
| Password | `BETTER_AUTH_SECRET` |
| Magic link | `BETTER_AUTH_SECRET`, secret `RESEND_API_KEY`, and var `MAIL_FROM` |
| Google | `BETTER_AUTH_SECRET`, var `GOOGLE_CLIENT_ID`, and secret `GOOGLE_CLIENT_SECRET` |
| GitHub | `BETTER_AUTH_SECRET`, var `GITHUB_CLIENT_ID`, and secret `GITHUB_CLIENT_SECRET` |
| Passkey | `BETTER_AUTH_SECRET` and a valid `BACKEND_URL` (plus `FRONTEND_URL` when the admin UI has its own origin). It cannot claim the installation. |

On an unclaimed installation, `AUTH_INITIAL_METHODS` is a comma-separated list such as `"password,magic_link,google,github"`. If it is absent, password is the only initial method. A listed method is still unavailable when one of its required bindings is missing. `passkey` is accepted only beside a method that can claim the installation: a passkey is added under Account security after the first sign-in.

After the first administrator exists, a superadmin can change the registry on the **Installation** page, under **Sign-in methods**. **Installation** is in the sidebar for superadmins only. The API refuses to enable an unconfigured method or leave every active superadmin without a usable method.

## Claim the installation

Open the installer claim link and choose an available method:

- **Password** sets a 12–128 character password on the bound address.
- **Magic link** sends only to the bound address. There is no email field on the claim page.
- **Google** must return that exact verified email.
- **GitHub** must return that exact primary, verified email.

The email domain does not have to match the provider's brand. For example, GitHub sign-in may prove an address ending in `@google.com`. Only an exact match between the normalized email addresses matters.

The claim and any verification challenge are single-use and expire no later than 15 minutes after the original claim was minted. Password, magic-link, Google and GitHub sign-in never create an account. A verified provider with an unknown email is refused. Only a site's Cloudflare Access rule can admit a new person at sign-in (see [Sign in through Cloudflare Access](/guides/people-and-access/#sign-in-through-cloudflare-access)).

If the unclaimed link is lost or expires, mint a replacement for the configured address:

```bash
npm run claim:link -- --remote --bootstrap --email owner@example.com
```

Without `--bootstrap`, the command resets the password in an emergency for the sole active superadmin. It does not create the first account. See [Password ownership and recovery](/guides/people-and-access/#password-ownership-and-recovery).

## One account, several methods

Provider callbacks cannot change the account's canonical email. The signed-in owner can change it through Account security after verifying the new mailbox. A verified Google or GitHub identity with the same normalized email links to the existing account instead of creating another one. GitHub requires the matching address to be primary as well as verified. Provider access, refresh and ID tokens are not retained.

When you first claim the installation with a password, a later magic-link sign-in keeps that original setup password. You can continue to use either method without setting the password again.

## Replace a superadmin

Do not edit the old account's email. Use this sequence:

1. In **Settings → People**, under **Add person**, enter the replacement email, pick a role and use **Add**.
   - **The address already has an account**: it gets the role at once. If its row says it cannot sign in yet, use **Create link** and send that password link privately. A matching verified Google or GitHub identity can also link on sign-in.
   - **No account yet**: no account is created. An invitation is made instead (see [Add a person](/guides/people-and-access/#add-a-person)). The replacement opens the invitation link, types the address it was sent to, enters the emailed code when mail is configured, and chooses a password. Only then does the account exist.
2. Confirm the replacement is in the People list and its row says **Can sign in** (or **Cloudflare Access** where Access is set up). A pending invitation is not an account and cannot be promoted.
3. On that People row, use the shield button (**Make … a superadmin**) and confirm **Make superadmin**. An account with no usable sign-in method is refused. Existing sessions for the promoted account are revoked.
4. Sign in as the replacement account. Confirm **Installation** is in its sidebar.
5. On the **Installation** page, under **Superadmins**, deactivate the old account.

Deactivation signs the old account out and preserves content and historical references. Reactivation requires a fresh sign-in. The API refuses self-deactivation and any change that would remove the last active, usable superadmin.

## Account security

Every signed-in user can open **Account security** from their identity menu (`/account/security`),
including users without a site grant. It covers your own account only: admin language, linked
Google and GitHub connections, and your passkeys. Password setup, magic-link configuration and the
deployment-wide sign-in methods are not on this screen.

Keep a second way to sign in, or a second superadmin who can sign in, before you remove your last
method. For lost devices, forgotten passwords and a locked-out superadmin, see
[Password ownership and recovery](/guides/people-and-access/#password-ownership-and-recovery).

### Admin language

Under **Language**, pick English, ไทย, Русский, Español, Français or Deutsch. **Same as browser** follows your browser language and falls back to English. The choice is saved in your account and applies on every site and device. It changes only the admin interface, dates and numbers. It never changes a site's content Languages, which stay under **Settings → Languages**. Screens not translated yet stay in English.

### Disconnect a sign-in provider

Account security lists your Google and GitHub connections. A connection can remain linked even when sign-in through that provider is unavailable.

Choose **Unlink**, review the provider name and session warning, then confirm. The server removes that exact connection and revokes every CMS session for your account, including the current session, in one atomic operation. You must sign in again. No provider tokens or provider identity ids are returned by this screen or its API. Passwords and pending verification links are not removed.

An ordinary user may remove their last provider. A superadmin may also remove their last personal method if another active superadmin can still sign in. The server refuses any unlink that would leave the deployment with no active superadmin able to use an enabled, configured method. A configured method without a usable account link does not count. When magic-link sign-in is configured and enabled, it uses the user's email. A refusal preserves the connection and all sessions.

Unlinking disconnects the CMS account. It does not revoke the OAuth application's authorization at Google or GitHub. A later permitted sign-in with the same verified email can link the provider again through the existing sign-in flow. There is no provider-link button on Account security.

### Passkeys

Passkeys are off until a superadmin switches them on (see [Passkeys](/guides/people-and-access/#passkeys)). Then each person adds their own under Account security, after signing in another way within the last 24 hours. **Sign in with a passkey** asks for no address. You can rename and remove your own passkeys. The last way you can sign in cannot be removed. Removing a passkey keeps current sessions. A deactivated account cannot sign in with a passkey.

To check real email delivery, provider callbacks and passkeys on a real deployment, follow [authentication acceptance](/guides/authentication-acceptance/). Local checks do not prove them.

## Next step

Take [your first site to published content](/guides/first-site/).

<!-- dee-wan-docs page: /guides/first-site/ -->

# Create your first site and publish content

Source: https://dee-wan-docs.pages.dev/guides/first-site/

This walkthrough uses the CMS admin and public read API, not a detached backend. The example model `article`, field `title`, slug `hello` and hostname `www.example.com` are illustrative. Use the values you create in place of these examples.

## 1. Install and claim the administrator

Complete [installation](/guides/installation/). Open the one-time administrator claim link and set your password. Keep deployment credentials outside content and screenshots. On a local seeded rig, follow the [repository setup](/guides/local-development/#try-it-locally-with-no-cloudflare-account) instead. Do not treat local fixture credentials as production accounts.

## 2. Create or select the site

When you create a site, choose **Website** or **Blog**. The choice cannot be changed later. A Blog gets one starter Post model and a Posts screen; see [Blog sites](/guides/blog/). This walkthrough uses a Website.

Select the intended site before editing. Set its public hostname and languages in site settings. Choose a default language and strict or fallback locale policy. The selected site determines the scope of admin requests. The public Worker resolves the site by the request hostname. A raw Worker hostname is not automatically your site's hostname.

![Site settings for the selected site, including its public domain](/assets/screenshots/site-settings.webp)

![Language settings with the default language and missing-translation policy](/assets/screenshots/language-settings.webp)

## 3. Define an Article model

In the model builder, create `article`, add a required text field `title`, and apply the model. Review every breaking-change warning before confirming. Choose public visibility only for information meant to be public. The [field reference](/reference/models-and-fields/) explains relations, media and components. Creating an Article model does not automatically create a rendered web page.

![The Content Builder model library](/assets/screenshots/model-builder.webp)

![The Article model editor with fields and model settings](/assets/screenshots/model-editor.webp)

## 4. Save and review content

Open Content, choose the model, create an item in the intended language, enter its title and set the slug to `hello`. Save the draft. Saving is not publishing. Reopen it to confirm that it was saved. With review mode enabled, submit it through the displayed workflow and have an authorized reviewer approve it. Do not bypass a refused transition.

![The content list with stage, language and delivery information](/assets/screenshots/content-list.webp)

![A content item open for editing with the Publishing panel](/assets/screenshots/content-editor.webp)

![Workflow settings with review enabled](/assets/screenshots/workflow-settings.webp)

## 5. Publish and verify

Use a role with publishing permission and select the available publish transition. From a server or terminal, request the site's public hostname:

```sh
curl --fail --silent --show-error 'https://www.example.com/v1/article/hello?locale=en'
```

A successful response contains the published item under `data`. Draft-only items are not public. A missing host, private model, unavailable locale or missing published slug can produce 404. Read the [public API refusals](/reference/public-api/) before changing visibility or access to fix a failure.

## 6. Connect a renderer and confirm withdrawal

Connect your frontend using the [generated client and preview guide](/guides/preview-and-client/). Rendered websites need their own build and deployment. Publishing a CMS record alone is not proof of a deployed page. Unpublish a disposable example and verify it disappears from public reads and, after a successful rebuild, from [search](/guides/search/). A failed search crawl must not replace the previous live index.

## Next step: choose how the site runs

Everyday use needs no extra setup. The CMS keeps serving your content while you edit and publish. Continue with the [page builder](/guides/page-builder/), [Blog](/guides/blog/), [models and fields](/reference/models-and-fields/) and [people and access](/guides/people-and-access/).

A standalone backend is optional. Choose it only when you want your own repository with a generated API Worker, database and deployment. It is generated from an existing site, so you can decide later. See [what Dee Wan generates](/guides/standalone-backend/).

## Start with an editable Astro website

From the repository root, generate the maintained reference starter into a new or empty directory:

```sh
npm run reference:starter -- --out ../my-website --config ./starter-config.json
cd ../my-website
npm ci
npm run check
npm run build
npm run preview -- --port 4321
```

Use the Node version in `.nvmrc`. Create `starter-config.json` before running the command:

```json
{
  "site_id": "YOUR_SITE_ID",
  "canonical_origin": "https://YOUR_PUBLIC_CMS_HOST",
  "routes": {
    "format": 1,
    "routes": [{ "model": "YOUR_PAGE_MODEL", "path": "/{locale}/{slug}" }]
  }
}
```

Replace the uppercase values with your site's actual ID, public API origin and page-model slug. The API origin's hostname must match the site's configured domain: public reads select a site by hostname, not by `site_id`. Each route needs `{slug}`; include `{locale}` for language-prefixed addresses. For a Blog, also set `"blog": true`. For a local CMS, set `"local": true`, use an explicit loopback API origin, and configure the site's domain to match that hostname, such as `127.0.0.1`. Run the website on a different port. Unknown configuration fields are refused.

The starter includes pinned dependencies and a lockfile, Astro source, Wrangler configuration and the current page-contract and renderer-protocol compatibility record. Edit `src/template/` for layout and styling; run `npm run dev -- --port 4321` while editing. Its runtime uses the existing public API for published content, media, forms and search. Alternate-language links use actual published addresses. SEO and supported rich blocks use the same renderer as managed delivery and preview. No CMS management token, database or plugin server is included.

Forms submit to the website's registered public interaction endpoint. The portable runtime forwards the bounded submission to the configured CMS origin; the CMS retains and delivers it through the existing form service. Browser submissions must originate from that website. No management credentials are forwarded.

You own the emitted source. When updating the CMS, generate a fresh starter elsewhere and merge its maintained runtime and contract files together, preserving your template changes. The generator refuses to overwrite an existing website. This starter reads live CMS content; [standalone delivery](/guides/standalone-backend/) separately exports a backend and content snapshot. A local build does not deploy the website or prove provider acceptance.

## Reference website: reproduce it locally

The repository ships a fictional reference website, Meridian Review. It is a fixed selection from the seed corpus (`scripts/seed-corpus/reference-site.ts`): English and German, three translated Blog posts with a cover picture, and one composed page with rich sections and three pictures. Nothing in it describes a real organisation.

One test builds it end to end on a fresh database. From `backend/`, with the Node version in `.nvmrc`:

```sh
DEEWAN_SITE_BUILD=1 npx vitest run test/reference-site-acceptance.test.ts --maxWorkers=1 --no-file-parallelism
```

It installs the site's dependencies and runs a real build, so it takes a few minutes and needs the machine to be otherwise idle. It listens on ports 43261 to 43263; set `DEEWAN_SITE_BUILD_REFERENCE_PORT` to move them. Without `DEEWAN_SITE_BUILD=1` it is skipped, and a skipped test proves nothing.

In order, it:

1. creates the site from the repository migrations, with both languages, the Blog and the page model;
2. uploads the pictures, creates and publishes the posts and the page;
3. mints a saved preview link for a draft and checks that only that link opens it;
4. generates the site, builds it and serves it with Wrangler;
5. checks the localized page and post addresses, the rich content and the pictures in the built output;
6. adds a model field, publishes a post, renames the page and regenerates over the same destination, then checks that the file you own is byte for byte unchanged, that a migration was appended and that no applied migration was rewritten;
7. rebuilds and checks that the renamed page now serves;
8. publishes a wrong edit, restores the earlier version, and checks the Blog serves the original;
9. takes a SQLite backup copy of the database and checks that generating from the copy gives the same site data, ignoring creation and update times.

This test checks recovery by restoring a saved version and by generating a site from a database backup copy. The repository has no one-command restore; see [backup and restore](/guides/backup-restore/).

This is local evidence only. Deployed acceptance of the reference website is pending authority and has not been run: it needs a Cloudflare account (Workers, D1, R2), a GitHub repository, and a hostname, and it includes a provider restore. Pictures in the local run go to a recording bucket, not to R2. Do not read a passing local run as proof of a deployment.

<!-- dee-wan-docs page: /guides/content-editing/ -->

# Edit and publish content

Source: https://dee-wan-docs.pages.dev/guides/content-editing/

This guide covers items in **Content**: creating, saving, publishing, translating, reviewing, recovering and removing them. Pages have their own editor; see the [page builder](/guides/page-builder/). Blog posts live under **Posts**; see [Blog sites](/guides/blog/). Field types and their rules are in [models and fields](/reference/models-and-fields/). What a role may do is in [people and access](/guides/people-and-access/).

## Find and open an item

Open **Content** in the sidebar and pick a model. The list shows each item's title, slug, status and language.

- **Search content…** finds saved titles, names, addresses and rich-text bodies, including unpublished drafts. Results show the matching field and a short excerpt. Markup, HTML attributes and JSON keys are not searched. Model, language, stage and field-access rules apply before matches and counts.
- **Stage** filters by workflow stage. **Delivery** filters by **Live** or **Not live**.
- **Fields** filters and sorts one model's list by what its fields hold. It is described under **Filter and sort by fields** below.
- Open an item with **Edit** in its row menu. **Duplicate** copies it as a new draft.
- A single-entry model opens its one item directly. See [single-entry models](/reference/models-and-fields/#single-entry-models).

The first search prepares older saved content automatically in small batches. Keep the search open while it loads; change or clear the search to cancel it. A failed request leaves a retryable error, never a zero-result claim. Queries take up to 200 characters. This searches current saved content; public website search still searches published content separately.

The message **You can read this content but not change it. It belongs to someone else, or your role grants reading only.** explains why you cannot edit the item.

### Search API

The admin list `GET /api/content_instances?q=...` searches current saved text. Existing
`where`, model, language, state, field filters, sorting and pagination still apply.
Shared fields can match a secondary language through their primary saved value. The
primary source must also be readable; hidden fields or unreadable primary entries do
not contribute matches.
A matching body adds `search_match: { field, label, excerpt }` to its row. The count
endpoint and matching bulk selections use the same readable matches. The query is at
most 200 characters, including its normalized case form; `%` and `_` are literal text.

An older or changed value may need derived text. A bounded read can prepare small
sets itself; otherwise `409 editorial_search_preparing` means the search has no complete
count yet. Call `POST /api/content_instances/search/prepare` with the same filters as
query parameters until `data.more` is false, then repeat the original read. Each call
prepares at most 16 values and normally at most 1 MiB, reading a larger value alone.
The CMS does this automatically and stops when the query changes or a request fails.
No content or publication state changes. Derived fragments are internal and are not
part of exports or generic API includes. `/first` rejects `q`; use the paginated list.
The management `listEntries` contract remains separate and does not accept `q`.

### Filter and sort by fields

With one model open, **Fields** opens a dialog. Add up to four conditions. Choose **All conditions (AND)** or **Any condition (OR)** for each group. **Add group** nests a group, up to three levels including the outer group. For example, match a gold tier AND either more than 100 views OR an empty date. Matches use the latest saved values, including drafts. Saved views, matching bulk selections, counts and pages keep the same groups. Older flat filters still mean AND.

| Field type          | Conditions                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Text                | **is**, **contains** (ignoring case), **is empty**, **is not empty**                                                                 |
| Choice              | **is any of** the options you tick, **is empty**, **is not empty**                                                                   |
| Yes/no              | **is** yes or no, **is empty**, **is not empty**                                                                                     |
| Number              | **is**, **is more than**, **is at least**, **is less than**, **is at most**, **is empty**, **is not empty**                          |
| Date                | **is**, **is after**, **is on or after**, **is before**, **is on or before**, **is empty**, **is not empty**                         |
| Link to other items | **includes any of** the items you pick, **is empty**, **is not empty**; **Linked value** filters a configured readable display field |
| Point               | **within radius**, **within area**, **is empty**, **is not empty**                                                                   |

- Numbers compare as numbers, so 9 is less than 10. Ordinary dates compare by day. Timezone-aware dates compare their stored UTC instants.
- **Sort by** orders one text, choice, yes/no, number or date field, ascending or descending. A single-target, single-value relation can sort by its configured readable scalar display field; a multi-value relation cannot. A point field sorts by distance from the latitude and longitude you enter. Missing or unreadable values come last in both directions; ties keep a fixed order between pages.
- **Linked value** uses the display field’s text, choice, yes/no, number or date conditions. Only readable related entries and fields contribute. Shared references from another site support membership conditions, not display-value filtering or sorting.
- Point radii use latitude, longitude and metres. An area uses south, west, north and east bounds; west greater than east crosses the antimeridian. Edges are included.
- Rich text, media, components and JSON fields cannot be filtered or sorted. The dialog lists them under **Not available here** with the reason.
- A field your role cannot read is not offered. It is also not used if a saved view names it.
- A field that is shared between languages is read from the main language's item; a language-specific field is read from the item in that language.
- The conditions and the sort are part of the address, so they survive a reload and can be shared as a link. **Select all N matching**, the counts and the pages all use the same conditions. The list needs one model: with all models shown, **Fields** is not offered.

## Saved views

A view is a named setup of one model's content list: the stage and delivery filters, field conditions, the search term, which columns show and in what order, and one sort (by a column or by a field). Open it from **Views**, beside the list's other buttons.

- **Personal and shared.** **Save as new view…** keeps a view for you. A shared view is seen by everyone who can read the model. Creating, changing or deleting a shared view, and setting the site default, needs the permission to apply model changes (`model:apply`). Reading a model is enough to make personal views and to use shared ones.
- **Save.** Opening a view applies its filters, columns and sort. Changing the list marks the view **Modified**, and **Save** replaces it. If someone changed the view after you opened it, you can **Use their version**, or **Keep my changes and save**. **Save as view** keeps the current list as a new view without touching the open one.
- **Columns and sort…** chooses which columns show, their order, and sorting by **Created** or **Updated**. Columns can be the built-in ones or any text, number, yes/no, choice, date or relationship field of the model. Relationship columns show readable labels and a count. Open a cell to inspect up to 20 related entries; each opens its editor. Names and counts follow your current access.
- **Defaults.** In the **⋯** menu, **Make my default** and **Make site default** pick the view a model opens with. Your default wins over the site default. A default applies when you open a model whose address has no filters and names no view, so a link that carries filters, such as a dashboard tile, is never replaced. A shared view can be your default; only a shared view can be the site default.
- **Who sees what.** A view stores filters, columns and a sort, never content. Each time it is read, your own access is checked again: columns, field conditions and a field sort that use a field your role cannot read are left out and the view says how many parts are ignored without naming the fields, and the rows are the ones your role may read, as in any list. Saving a view stores the columns currently visible to you.
- **Fields that no longer exist.** A column, condition or sort on a field that was deleted, or whose type no longer allows it, is left out of the list. The view still opens and is not rewritten. A notice names the removed fields, and **Remove them and save** repairs the view in one action for people allowed to change it. Everyone else is told to ask someone who manages models. Columns hidden by your role are not removed.
- **Limits.** A name has up to 80 characters and is unique among your views of the model, and among the shared ones. Each person keeps up to 25 personal views per model, and a model has up to 25 shared views. A view has up to 40 columns and a search term of up to 200 characters. Deleting a view also removes the defaults that name it.

Views are an admin preference. They change nothing that is published, nothing in the public API, and need no generation or deployment.

## Create an item

1. Pick the model and press **Create content**.
2. Fill in the fields. A new item starts in the site's default language. If your role cannot create that language, it starts in the first language your role can create. The language list offers only languages your role can create.
3. Press **Create draft**. The screen says **Content created as a draft.**

Creating is refused for a language the site does not have (`unknown_locale`). If the language is removed while the item is being created, nothing is written (`language_changed`).

Each language has its own address. Leave **Address** empty to make one from the title. The rules are in [item address](/reference/models-and-fields/#item-address).

### Vendor widgets in rich text

In a rich-text field, choose **Vendor snippet** (under **More** on phones) to insert a provider's HTML, CSS and JavaScript. Give it an accessible title, then paste each part into its labelled code editor. The editors provide syntax highlighting, line numbers, bracket matching, search and undo/redo.

Use **Format document** from the editor's right-click menu or visible actions menu, or press **Shift+Alt+F**. Prettier formats locally in your browser. Formatting does not save or run the code. Undo restores the previous text; invalid code stays unchanged with an explanation. Tab moves to the next control.

**Preview snippet** runs the widget inside its isolated frame. Save the entry to keep it; publish separately to show it on the site. The provider handles submitted booking or form data.

## Save and publish

Saving and publishing are separate steps. Saving never makes anything public.

### Save

Press **Save**. Each save writes a new version of the item.

- The **Unsaved** badge shows edits that are not saved yet.
- What you type while a save is running is not part of that save. It stays **Unsaved** until you save again.
- Leaving with unsaved edits asks first: **Keep editing** or **Discard and leave**.
- **Preview here** can show unsaved edits in the site's design without saving them, where the site's renderer supports it. See [Preview unsaved changes](/guides/preview-and-client/).
- A field rule or a plugin check can refuse a save. The editor names the field and keeps your edit. See [plugin content checks](/reference/models-and-fields/#plugin-content-checks).

### Proposed changes

An integration can propose field changes for you to review. **Proposed changes** shows the source, requester, date, language and affected fields. Select a field label to jump to and focus that field.

**Apply** needs you to save or discard your local edits first. It uses the ordinary version-checked save and your current permissions. **Dismiss** leaves the entry unchanged; the integration can propose again. If the entry changed after the proposal, the proposal is stale. Dismiss it or ask for a new proposal.

### Incomplete drafts 

By default, a draft may leave required fields empty. A new draft may also have no address. Invalid values, broken references, duplicate unique values and invalid component structure still refuse a save. An existing address cannot be cleared. A model's **Draft validation** setting can require complete values on every save instead.

Publishing always checks the exact saved version in every affected language: required fields, address rules, references, plugin checks and required review tasks must pass. This also applies to publication overrides, imports, plugins and scheduled releases. A complete draft in English does not make an incomplete Thai translation publishable.

### Publish

The **Publishing** panel shows the moves your role may take. You never see a move that would be refused.

- With the review flow off, **Publish** makes the saved version public at once.
- A move or a publish saves unsaved edits first. If that save is refused, nothing moves.
- **Unpublish** takes the item out of public view. It stays as a draft. Nothing is deleted.

The review flow is a site setting: **Settings → Workflow → Enable review flow**.

### Review flow

With review on, an item moves through the site's review stages, for example **Submit for review**, **Approve**, **Send back** and **Publish**. Each move can carry a note for the next person.

The **Dashboard** lists **Waiting for review** and **Sent back**. A row says what you can do, or who it is waiting for. Open the row to act. The move itself happens in the editor.

### Publish without review

A role with the override permission (`content:publish_override`) sees an **Override** box. No built-in role holds it. A superadmin can always use this override.

1. Press **Publish all languages now** (or **Publish now** on an item with one language).
2. Write the reason under **Why is this necessary?**. It is required.
3. Confirm.

The override applies to the whole translation group. The activity shows it as **Publication override**. It still checks the role's publish and unpublish language limits. It is refused (`locale_denied`, naming the languages) only when it would change a language outside them. A language that already serves the version being published, or is already offline on an unpublish, does not count. **Unpublish all languages now** works the same way, but it does not save unsaved edits first.

### Unpublish and what links to this

Before an unpublish, the dialog checks what links to the item.

- It names how many items link here, and how many of them are live. Their published copies keep the link, so those links will break.
- Items in Trash that link here are marked **In Trash**. Links only in a draft are marked **draft only**.
- If the list changes before you confirm, the move is refused with **What links to this changed. Check the list again.**

## Translations

An item and its languages form one translation group. **Each language is saved separately.**

### Start a translation

In the **Language** panel, press **Start a {language} translation**. The new language starts empty. Fill it in and save.

- Shared (non-translatable) fields are edited in the primary language. The panel says how many there are.
- When a language is not live yet, the panel says what visitors get instead, for example **Not live in Thai yet. Visitors see English.** See [languages](/guides/languages/).

### One language or all languages

The **Publishing** panel has two scopes:

| Scope         | Buttons                                                                                 | Effect                                                                                                                                                                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| This language | **Publish {language}**, **Unpublish {language}**, a move with **· {language}**          | Only this language changes. Other languages stay as they are.                                                                                                                                                                                                  |
| All languages | **Publish all languages**, **Unpublish all languages**, a move with **· All languages** | Every language of the group moves. A move between two unpublished stages, such as **Approve · All languages** or **Send back · All languages**, leaves a language that is already published live and **Published**. Take it off with **Unpublish {language}**. |

Other language-only actions:

- **Move this language to Trash** removes one language. The language that holds the item's history cannot go alone; move the whole item instead.
- **Restore {language} only** in History restores one language from an older version.

A role limited to some languages can act only in those languages. An action that spans languages is refused in its entirety. See [limit a role to some fields or languages](/guides/people-and-access/#limit-a-role-to-some-fields-or-languages).

## Assign and review

Press **Assign** (or **Reassign**) in the **Publishing** panel.

- Pick one **Assignee** and an optional **Due date**. The date is today or later.
- The assignee must be able to move the item on from its current stage.
- One assignment covers the item and all its languages.
- The person you assign gets a notification in the admin; see [feedback and notifications](#feedback-and-notifications). The panel shows **Due {date}** and, after the due date, **Due {date} · Overdue**.
- A workflow move clears the assignment. **Clear assignment** removes it by hand.
- **Deactivated** or **No access** next to an assignee means that person cannot act now.

### Language assignments and review tasks

**Review tasks** keeps work separate from the item's workflow assignment. Under **Language assignment**, choose an owner and due date for the current language, then **Save**. Other languages and the whole-item assignment keep their owners. Only eligible people are offered; simultaneous changes are refused rather than overwritten.

Choose the task language before its owner. Changing language refreshes the eligible people; **All languages** offers only people who can read every language of the entry.

For a task, enter **Task**, choose **Owner**, language and optional **Due**, then **Add task**. Keep **Required before publishing** on when publication depends on it. The owner must be able to read that entry and language. The owner or an authorized assigner can **Complete** it. **Reopen** starts another review; **Remove** removes the requirement.

Completion records the content reviewed. Changing that language or shared content shows **Review changed content** and blocks publishing until the task is completed again. Changing only another language does not invalidate it. A task for **All languages** covers every affected language. When editing a future version, completion refers to that version's content, not the ordinary draft.

## Feedback and notifications

### Feedback on an entry

The **Feedback** section in the side column holds notes from the people reviewing this entry. It is private to the admin. It is not the public [comments](/guides/blog/) feature and never reaches the site.

- Type a note and press **Add feedback**. A note is 1 to 2000 characters, and an entry holds at most 500.
- Each note shows who wrote it, when, and the version it was written on. When the entry has a newer version, the note says **Written on an older version (version {version}, now version {current}).**
- **Resolve** closes a note and hides it. **Show {count} resolved** lists closed notes, and **Reopen** opens one again.
- Reading follows read access to the entry. Writing and resolving need update access to it. A role limited to its own items can write only on its own items. Someone who can read but not update sees the notes without the box.
- A note belongs to the item and the language you wrote it in.

### Field threads and mentions

Choose **Field** before adding feedback to anchor a thread to a field, or leave **Whole entry** selected. **Reply** keeps the same field and language; **Resolve** closes the thread and its replies. Version labels show when a note predates later edits.

Open **Notify** and select people or editorial teams. Choices include only people who can currently read the thread's entry, field and language. Up to 20 mentions can notify up to 50 people; a team grants no content access. The notification opens the relevant entry and language. Access is checked again when it is read, so a revoked reader sees no hidden title or field.

People with site-grant permission can open **Editorial teams** under **Review tasks** to create or edit a site's teams and members. Task assignments, completions and mentions appear in the notification bell alongside workflow notifications.

### Notifications

If notifications cannot be loaded, use **Try again** in the notification panel. Existing notifications stay visible if a refresh fails.

The bell in the header lists notifications that need your attention. The badge counts unread notifications.

| Kind               | You get it when                                                                                                                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assignment         | Someone assigns the item to you. Assigning yourself, or saving the same assignee again, sends nothing.                                                                                                                                                                            |
| Review request     | The item, or one of its languages, moves into a review stage. It goes to the person named as next to act. With no one named, it goes to everyone who can move the item on from that stage and may review the moved language, up to 50 people, never the person who made the move. |
| Return for changes | An item, or one of its languages, in a review stage goes back to the starting stage. It goes to the person named as next to act, otherwise to the author of that language, if the author can still read it.                                                                       |

- Each notification names the item and its **current** review state, not the state it was created in, and links to it. A notification about one language names it (**Language: th**), shows that language's state and opens that language.
- If you can no longer read the item or that language, because your role changed or it moved to Trash, the notification reads **An entry you were notified about is no longer available to you.** It shows no title and no link.
- **Mark read**, **Mark unread** and **Mark all read** change only your own list.
- A notification is written together with the move or assignment that causes it. A move that fails sends nothing, and a retried move sends nothing twice.
- The editor, the management API and plugin commands notify the same way, because they share one path. A move of one language notifies like a move of the whole item.
- An import is quiet by default. Whoever runs an import can choose to notify with **Notify reviewers about review changes in this import** on the run screen; the choice is stored on the job and needs the same `data:import` permission. Carried history, such as a carried assignment, never notifies.
- Email is optional. When the install has mail configured (see [people and access](/guides/people-and-access/)) and `FRONTEND_URL` is set, the person also gets a short email with a link and no content. A failed email is not retried. The notification in the admin exists either way.
- There are no reminders and no chat.

## Workflows

Unsaved workflow edits are protected when leaving Settings or replacing or closing the editor. On mobile, Save and Cancel stay available while scrolling. If workflows cannot be loaded, choose **Try again**; a failed refresh keeps the current draft.

**Settings → Workflow → Workflows** lists the site's named workflows. A workflow is the set of states an item moves through and the moves between them. The site starts with one, marked **Site default**.

- **New workflow** starts from a copy of the site default. Give it a name. Add states, mark exactly one as the **Starting state**, mark the ones that publish, and add the moves. A move can need **Approvers**, **Publishers** or people who can unpublish.
- A workflow has at most 16 states and 80 moves, and a site has at most 20 workflows. A state key is lowercase letters, digits and underscores, starting with a letter. The starting state must be able to reach a state that publishes.
- **Edit** changes names, states and moves. **Delete** is offered only for a workflow no model uses and no item is attached to. The site default cannot be deleted.
- **Workflow for each model** gives each model one workflow, or the site default. An item uses the workflow it is already attached to, then its model's workflow, then the site default. Changing a model affects new items.
- Settings → History records creating, changing, deleting and assigning a workflow.
- If someone else changes, deletes or starts using a workflow while you save, the save is refused with `workflow_changed`, `workflow_in_use` or `workflow_assigned`. Nothing is written and no item loses its review state. Reload and try again. An item move that was checked against an older version of the workflow is refused the same way (`workflow_changed`).

### Moving items in review

A change that would leave items in a state that no longer applies is refused until you review a plan. This covers removing a state that items are in, and giving a model another workflow while its items are in review.

- **Review how entries move** lists the states, how many items are in each, and some of the items. Choose a new state for each. For a model change you can also choose **Leave on their current workflow**.
- **Move entries and apply** moves the items one by one and lists each result: **Moved**, **Refused**, **Changed meanwhile** or **Unchanged**. Each move is recorded in the item's history.
- A reviewed move cannot publish or unpublish an item. Move those items with their ordinary buttons first.
- A request moves 25 items. The screen repeats it until none are left. The edit or the model change is applied only when no item remains. If one could not be moved, nothing else changes. Fix it and apply again.
- While items are attached to a workflow, its starting state and the publishing flag of its states cannot change.

## Edit together

### Who is editing

The first person to open an item in a language holds it for editing. Others see **{name} is editing this.** They can read along: the form follows the holder's unsaved work, refreshed every 10 seconds.

- **Also open: {people}. Shared fields and relations save for every language.** names people working on other languages of the same item.
- **You are editing this in another tab.** means your own other tab holds it.
- The hold ends about two minutes after the holder's tab stops renewing it, for example when the tab is closed or hidden.

### Take over

Press **Take over** to edit. The hold moves at once.

- The previous holder sees **{name} took over.** Their next save or move is refused.
- Their unsaved changes are kept as their own recovery draft. They get them back when they hold the item again.
- Holding or taking over a language needs your role to change that language (or to create it, when the item has no row in it yet). A role that edits only its own items must own that language's row. Otherwise the server refuses (`locale_denied` or `not_owner`).
- While someone else holds an item, saves, moves, assignment, restore, the override and Trash from other sessions are refused. Plugins, imports, scheduled publication and spreadsheet apply are not blocked by a hold.

### Shared draft

Unsaved work autosaves a moment after you stop typing. It is one shared draft per item and language, written by the holder.

- People who may read the item see it after a reload, on any device. They see only the fields they may read, also in a conflict. A role that reads only its own items sees only drafts of the language rows it owns.
- Read access is checked on its own, apart from the right to change. A role that may change an item but not read that row or language can still write the draft. It never sees the draft it replaces, and a conflict answer carries no draft.
- An autosave or a discard after someone took over is refused and changes nothing. A refused autosave becomes your recovery draft. A refused discard says **Not discarded — taken over. Your work is kept.** What you typed stays recoverable as your recovery draft.
- A draft is never a version. **Save** turns it into a version and clears the draft.
- A draft is kept 30 days after its last change.
- A new item, before its first save, keeps your own private draft.

The status next to **Save** says what happened:

| Status                        | Meaning                                                 |
| ----------------------------- | ------------------------------------------------------- |
| **Saving draft…**             | The draft is being saved to the server.                 |
| **Draft saved**               | The draft is saved on the server.                       |
| **Offline — kept here**       | Kept on this device. Sent on reconnection or **Retry**. |
| **Draft not saved**           | The write failed. Press **Retry**.                      |
| **Changed on another device** | Press **Choose** to pick a version.                     |
| **Not saved — taken over**    | Someone took over. Your work is your recovery draft.    |

## Recover unsaved work

| You see                                                                        | What happened                                                | What to do                                             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------ |
| **Someone else saved this content**                                            | Another save landed first. Your edits are still in the form. | **Load theirs**, or **Overwrite with mine**.           |
| **Unsaved changes from {age}**                                                 | A draft you never saved.                                     | **Restore them** or **Discard**.                       |
| **Unsaved changes from an older version**                                      | Someone saved after your draft was made.                     | **Compare**, then **Apply my changes** or **Discard**. |
| **Another device kept different unsaved changes {age}. Choose which to keep.** | Two devices wrote different drafts.                          | **Use the other device's** or **Keep this one**.       |
| **Your own unsaved changes**                                                   | Your work was kept when someone took over.                   | **Restore them** or **Discard**.                       |
| **An old draft was removed**                                                   | The draft passed 30 days.                                    | The saved version is on screen.                        |

## Version history

Open **History** from the editor. It lists versions oldest first and marks **the version being edited** and **the version the public sees**. Step with **Previous revision** and **Next revision**. Each version shows its fields, links and images. Reading history changes nothing.

Expand grouped fields to read nested blocks. Rich text appears as readable text; exact stored values remain under **Technical details**. Shared fields remain visible when you switch languages; language-specific links follow the selected language.

Use **Compare with** to choose another saved version. Changed fields show removed text struck through and added text underlined. The selected version is the result side of the comparison. Use the language buttons to compare translations, search settings and page facts. Only fields and related labels you can currently read are shown. **Absent** means the field was not stored; **Empty** means an explicit empty value. A changed link or file is marked even when its visible label stays the same. Comparison never saves, restores or publishes. Load older history first to include older retained versions in the selector.

### Related entries

In a relationship picker, **Create {model}** opens the ordinary entry editor without leaving your parent draft. The pencil button edits an existing related entry. Child fields, media, translations, validation and save conflicts work as in the full editor. Saving refreshes the selected entry and its label; it does not save the parent. Closing without saving keeps the previous selection and parent edits. If the child has unsaved changes, choose whether to discard them. Publication remains separate.

### Restore a version

- **Restore this version** loads that version into the editor and saves it as a new version. It covers every language and every field. It needs the restore permission in every language of the item.
- **Restore {language} only** restores one language. Other languages and what is live stay as they are. It needs the restore permission in that language.
- Restoring never publishes. Publish afterwards if you want the public to see it.

### How many versions are kept

**Settings → Workflow → Version history → Versions kept per item** sets the number. The default is 50. The minimum is 1.

- Each save or restore of an item deletes its oldest versions beyond that number.
- The version being edited and every published version are always kept. Future-version heads and history, and the base versions of open proposals, are retained while they are needed.
- Lowering the number deletes nothing at once. Each item is trimmed at its next save.
- A deleted version cannot be opened or restored. History says **Version {version} is no longer retained — this site keeps a limited number of versions. Showing the nearest one that is.**

## Trash

### Move to Trash

Press **Move to Trash** in the editor or the list. This moves every language to Trash. **Move this language to Trash** removes one language.

- A live item or language is refused. Unpublish it first.
- Items in Trash leave lists, search, relation pickers and previews.
- You need delete access to the model.

### Restore from Trash

Open **Trash** above the content list. **Restore** brings the item back as a draft, with its versions, translations, links and media.

- The dialog lists links that will not work, such as links to items still in Trash or deleted for good.
- If another item took its address, restore is refused. Change that item's address first.

### Delete for good

**Delete permanently** removes every language, version and link of the item, and its visitor comments. It asks first. It cannot be undone.

### Automatic deletion

An item or language is deleted for good 30 days after it went to Trash. The **Deleted on** column shows that date.

- A scheduled job runs once a day. In the supplied Worker configuration it runs at 03:17 UTC.
- Each run deletes at most 50 items per site, oldest first. When more are due, the rest wait for the next run.
- Sites that are deactivated are skipped until they are active again.
- Restoring before deletion stops it.

## Bulk actions

Tick rows in the content list. You can act on at most 25 at a time.

- **Move to…** a stage, then **Move**.
- **Publish now** and **Unpublish now**, for roles with the override permission. They need a reason, recorded as an override.
- **Move to Trash**.
- In Trash: **Restore** and **Delete permanently**.

Each item is checked on its own, with the same rules as the single action. A refusal does not stop the others, and nothing is rolled back. The result shows **{done} updated, {refused} refused.** It lists each refused item with its reason, for example **not yours**, **live — unpublish it first** or **changed by someone else**. Languages of one item move together, so a second row of the same item is counted once.

## Change many items at once

Tick the page checkbox at the top of the list. When more items match your filters than one page shows, a line appears: **Select all N matching**. Click it to select every match across all pages. Untick a row to leave that item out; the exclusion is kept as you turn pages. Changing the filters, the field conditions, the search or the content type ends the selection.

### Select every match

- The selection is every item your role can read that matches the filters, field conditions and search at the moment you start. It is fixed then. Items that are added or change later do not join it.
- A change covers at most 5,000 items. When more match, the list says so and does not offer the selection; narrow the filters first.
- The available actions are **Move**, **Publish now** and **Unpublish now** (roles with the override permission), **Move to Trash**, and **Edit fields**. **Edit fields** needs the list narrowed to one content type.
- Items that other content links to are skipped when they would go offline or to Trash. They are listed afterwards as refused; there is no way to approve them in bulk.

### Edit fields for many items

**Edit fields** lists the fields of the content type that can be set to one value for every selected item: text, number, yes/no, date and choice fields. Tick a field, give it a value, and choose **Apply to N items**.

Fields that are not offered are listed with the reason:

- Rich text, links, files and structured content are edited one item at a time.
- A field that must stay different on every item (unique).
- A field filled in automatically.
- A private field.
- A field your role cannot change.

Each item is saved like a normal edit: the same checks, field and language permissions, version history and cache refresh. Each changed item gets one new version. An item that already holds the value is left alone and reported as **No change needed**.

### Progress and results

The change runs in steps of at most 25 items. A bar shows how far it is, and **Stop** ends it where it is; items not reached are not touched. If you close the page or lose the connection, the list offers **Continue** next time. After a failed step, **Try again** continues the same change and does not repeat what was already done. Only the person who started a change can see and continue it.

Every item is checked again when its turn comes, with the same rules as the single action. The result lists each item as:

- **Changed**.
- **No change needed**.
- **Refused**, with the reason, for example **not yours** or **live — unpublish it first**.
- **Changed meanwhile**: someone saved or moved the item after the list was fixed. Nothing is overwritten.

Use the buttons above the result to show one group.

## Spreadsheet round trip

The **Export spreadsheet** → **Import spreadsheet** round trip updates existing items of one model without changing their IDs or addresses. Each changed item gets a new saved version. To create items, upsert or add translations from CSV/XLSX, use **Collection files** with the modes described below.

1. **Export spreadsheet** downloads an Excel workbook, one sheet per language.
2. Edit cells. Leave the `id`, `slug` and `current_version_id` columns as they are.
3. **Import spreadsheet**, choose the `.xlsx` file, or a `.csv` file with **Language of this CSV**.
4. **Check file**. Checking writes nothing. It shows rows, changes and blocked rows, with the row and column of each problem.
5. **Apply N changes**. Apply works only when no row is blocked, and only on the exact file you checked. Each changed item gets a new version. Nothing is published.

What the file holds:

- Only the items you may read and change. A role limited to its own items exports only those. A row for anyone else's item is blocked as not found.
- Only the fields your role may both read and change, and one sheet per language your role may read. A file exported by a field-limited role can be checked and applied without the other columns. Their stored values are kept. A file that adds such a column back, or a sheet in a language your role cannot read, is blocked.
- Each sheet's `slug` is that language's own address.
- A change in a language your role may read but not change is blocked with `locale_denied` at its row and column. A shared (non-translatable) field is stored in the primary language, so changing it on any sheet counts as a change in the primary language.
- In this update-only round trip, values for a translation that does not exist are blocked with `spreadsheet_locale_missing`. Add it in the editor first, or use **Collection files** to add it with the required language and field grants.
- A rule problem on a field or language your role cannot see is shown without naming that field or language.
- Relation cells contain JSON references, for example `[{"model":"author","id":"entry_id"}]` or `[{"model":"author","slug":"jane","lang":"en"}]`. References must name existing entries in this site and fit the field's target models and cardinality.
- Media cells contain JSON references such as `[{"id":"media_id"}]` or `[{"storage_key":"folder/image.png"}]`, with optional `crop` and `focal`. They select existing library files; they do not upload a file or accept an arbitrary URL.
- Component cells contain the same JSON values as a collection file, including nested and repeatable component values. Keep a structured cell blank to preserve its value; enter JSON `null` to clear a value or link list. Empty required values are allowed in draft mode; strict models and publication require them. Shared link or media values must agree across language sheets.
- A row whose item changed after the export is blocked. Export again.
- A workbook exported before each sheet carried its own address can be blocked with `spreadsheet_slug_mismatch` on the other languages' sheets. Export again.
- Formulas are refused. A file is at most 10 MiB, with at most 20,000 rows per sheet.

If the apply stops part-way, the screen says **Apply stopped** and which row. Rows saved before it are kept. Export again before you retry.

A whole-site export is a different, operator task. See [import and migration](/guides/import-migration/).

## Collection create, update and upsert

Use **Collection files** to import JSON, CSV or XLSX and create or update items of one model, including components, related items, media references and translations. It is separate from the update-only spreadsheet round trip above, whole-site copy and [migration from another CMS](/guides/import-migration/). Open it from the model’s content list. The button shows for roles that can read the model and create or update it.

**Download collection** saves a `.json` file of the items your role may read: the languages, fields, related items and media you may read, and only your own items when your read grant is limited to those. A model with many items downloads in parts (**Download part 2**, and so on); each part imports on its own.

For CSV/XLSX, use field keys as column headers, alongside `id`, `slug` and `current_version_id` where needed. Choose **Language of this CSV** for a CSV; workbook sheet names identify the site languages. Cells for components, JSON, relations, media and points contain JSON values, not flattened subfield columns. Timezone-aware date cells also use JSON, for example `{"datetime":"2026-11-01T06:30:25.123Z","timezone":"America/New_York"}`; `datetime` is the UTC instant, not the local clock time. Rows with the same match across language sheets form one translated item; shared values must agree. Spreadsheet selection starts with update-by-ID: choose a different mode and match explicitly to create or upsert. The same checks, per-row permissions and 500-entry limit apply to all three formats.

### The file

```json
{
  "format": "dee-wan-collection",
  "version": 1,
  "model": "article",
  "entries": [
    {
      "id": "…",
      "current_version_id": "…",
      "primary_lang": "en",
      "slugs": { "en": "hello", "th": "sawasdee" },
      "locales": {
        "en": { "title": "Hello", "faqs": [{ "question": "Why?" }] },
        "th": { "title": "สวัสดี" }
      },
      "relations": { "related": [{ "model": "author", "id": "…" }] },
      "locale_relations": {
        "th": { "tags": [{ "model": "tag", "slug": "news", "lang": "th" }] }
      },
      "media": { "cover": [{ "id": "…", "storage_key": "…", "crop": null }] }
    }
  ]
}
```

- `locales` holds field values as the item stores them: nested components, JSON and rich text keep their structure. A field left out is not touched. `null` clears it.
- `relations` names related items as `{ "model", "id" }`, or `{ "model", "slug" }` with an optional `lang` (default: the site's main language). A relation with different links in each language goes under `locale_relations`. The `model` is always written, and it must be the model of the item found. A field that accepts one model refuses another.
- `media` names files already in this site's library by `id` or `storage_key`. Importing a reference never uploads or copies a file. `crop` and `focal` are kept when written.
- `slugs` holds each language's address. `id` and `current_version_id` are only read when matching by id.
- A file is at most 10 MiB, 500 entries and 32 levels of nesting. Apply saves 20 rows per request and the screen continues until none are left.

### Modes and matching

Choose what the file does and how existing items are found.

| Mode             | A row with no matching item            | A row with a matching item                  |
| ---------------- | -------------------------------------- | ------------------------------------------- |
| Create           | Created.                               | Refused (`collection_match_exists`).        |
| Update           | Refused (`spreadsheet_row_not_found`). | Updated if it differs.                      |
| Create or update | Created.                               | Updated if it differs, otherwise unchanged. |

Match on **ID**, **Address (slug)** or a field of the model that is set to be unique. The slug is read in the entry's `primary_lang`. ID matches existing items only, so create and upsert by ID never make a new item; match on the address or a unique field to create. A row with no value to match on, two rows with the same value, two rows for one item, or a value that more than one item holds are all refused before anything is written (`collection_match_missing`, `collection_duplicate_match`, `collection_duplicate_target`, `collection_match_ambiguous`).

### Check, then apply

1. **Check file**. Checking writes nothing. It shows rows to create, rows to update, unchanged rows, kept rows and blocked rows, with the row, language and field of each problem.
2. **Apply changes**. Apply works only when no row is blocked, only on the exact file you checked, and only while the model's fields and rules are still the ones you checked against (`collection_definitions_changed`: check again).

Each row is written like a manual edit: the same validation, history, cache clearing and audit. Nothing is published.

What is blocked: a field or language that does not exist; a relation or media reference that names nothing, an item in Trash, an item of another site or the wrong model (`collection_relation_missing`, `collection_relation_in_trash`, `collection_relation_wrong_model`, `collection_media_missing`); a value the editor would refuse; a relation written in `locales`, or the reverse (`collection_field_reference`); a model you cannot create, read or update; a translation the item does not have yet when your role may not create that language or change that field (`locale_denied`, `field_denied`); and a changed field or language your role may not write (`field_denied`, `locale_denied`). A field or language you did not change is not checked against your write grants.

### Conflicts, results and retry

If a row's `current_version_id` is not the item's current version and the row differs from the item, the item is **kept** as it is (`spreadsheet_version_conflict`). The other rows still apply. Export again to change a kept item. If you leave out `current_version_id`, the row is compared with the item as it is when you apply. A version from another site's file is ignored when the `id` is not the matched item's.

Apply reports each row as **created**, **updated**, **unchanged**, **kept** or **refused**; a refused row shows the reason. It never claims the whole file applied as one step. If the screen says the last step could not be confirmed, choose **Resume**. Rows already written read as unchanged. Retrying the same file never creates a second item: a created row is remembered for 30 days by the file and its row number, and after that a create refuses the existing item and an upsert reads it as unchanged.

Apply works only on a file that was checked, and it keeps the version each item had when you checked. An item that changed after the check is **kept** (`spreadsheet_version_conflict`) and the editor's change stays. A check that is older than 30 days, or an apply that skips the check, is refused with `spreadsheet_not_checked`: check the file again.

A retry never overwrites an edit made after the file's first run. An item the file created and someone then edited reads as **unchanged** (already created by this file). An item the file updated and someone then edited is **kept** (`spreadsheet_version_conflict`). A translation the file started is not written again, so later edits to it stay.

### Add a translation

A row that gives a language the existing item does not have yet starts that translation inside the item's translation group, with its address (`slugs`), field values, components, related items and media references. This needs the update grant on the model, the create grant for that language and write access to the fields. Without them the row is blocked (`locale_denied`, `field_denied`). A language that is not set up for the site is blocked as an unknown language. Invalid supplied values and addresses already used by another item block the row (`field_validation_failed`, `slug_reserved`). Missing required values block saves only for strict models; publication always requires them.

## Generate with AI

AI generation needs the `ai:generate` permission and an AI provider set up for the installation. Without a provider, generation is refused. Each site has an hourly allowance, 250 requests by default.

- **Text fields.** A field set up for AI generation in the model shows a **Generate with AI** button. **AI prompt not configured** means the field has no prompt.
- **Rich text.** **AI Generate** opens a prompt. Write what you want and press **Generate**.
- **Components with A/B variants.** **Generate variants with AI** adds variants.

In text fields and rich text, the answer is shown for review first. Nothing changes until you press **Apply**. In a text field, Apply replaces the field. In rich text, Apply inserts at the cursor. An answer over the field's limit is truncated, and the panel says so before you apply.

Images are generated in the media library, see [media](/guides/media/#generate-an-image-with-ai). The [content planner](/guides/content-planner/) writes whole drafts.

## Next step

Manage files in the [media library](/guides/media/), and set up [languages](/guides/languages/).

## Update translations after save

Open **AI translation updates** in the entry sidebar. Opt in, select existing target languages, then allow replacement of existing text, including manual translations. The source is saved first. AI translates only changed translatable text and rich-text fields into selected languages and saves one draft version through normal permissions and version checks. A save that changes no source text makes no AI request. Other fields and languages stay unchanged. Clearing source text clears that selected translated field without inventing replacement text. Switching source language resets consent. Failure keeps the source save and reports the translation failure. Publishing remains a separate step.

Page settings also offer **AI translation updates** for existing composed-page languages. Select targets and explicitly allow replacement, including manual wording. The source saves first. AI compares previous and current source text with each target’s own text; it updates only existing text fields. Each target keeps its section IDs, order, layout, media, links, code, component pins, shared references and facts. Rich paragraph formatting and link destinations stay. Shared and component-pinned content is excluded. Targets save sequentially through ordinary page permissions and version/facts checks. If the page changes after the source save, review the latest page before retrying translation. Each target reports success, no corresponding change, or failure. An unchanged source or a source with no previous or current text makes no AI request. Clearing source wording can remove corresponding target wording. Source page, language or site changes reset consent. Translation failure keeps the source save; typing during translation stays in the source editor. Publication remains separate.

## Entry folders

Open the compact **Entry folders** control on Content to browse one folder or **Unfiled**, across models or within the selected model. The folder filter stays in the address and survives reload and Back. Folder counts include only entries you can read; translations count as one logical entry.

People with `site:settings` choose **New folder** to create a folder, or select a folder and choose **Edit** to rename it or change its parent. **Cancel** closes the form without saving. They can also delete empty folders. Names contain 1–80 characters; sibling names are unique ignoring case. A site can hold 500 folders with five levels of nesting. Move live entries and child folders out before deleting a folder. The confirmation shows entries in Trash that will become Unfiled if restored; their placement history stays. Creating or renaming a folder shows a success message.

Open **Current folder** on an existing entry, then choose a folder and **Move entry**. The controls and placement history stay collapsed until opened. Moving needs read and update access to that entry, including ownership and entry rules. Every translation shares the primary entry's folder. A folder move changes no URL, revision or publication pointer. **Placement history** records moves separately from content revisions; restoring an old content revision keeps the current folder. The latest 100 moves appear in the editor.

**Duplicate** keeps the source entry's folder, including for composed pages. A site copy carries empty folders and current placement. History transfer also carries placement events and actor labels. Destination IDs are remapped; folders with the same path of names are reused. Reimport does not move entries created by an earlier job. Undo keeps an entry if someone changed its placement after import.

## Context-dependent choices

Model field configuration can limit relation choices with `filterChoices`, and select options with `when`. These use the same bounded conditions as field filters: at most four conditions and three group levels. Relation conditions test candidate target fields; select `when` conditions test sibling fields in the current form. Nested component choices use siblings inside that component instance.

```json
{
  "type": "relation",
  "targetModel": "article",
  "relationType": "manyToMany",
  "filterChoices": [
    { "field": "department", "op": "eq", "values": ["$field:department"] }
  ]
}
```

```json
{
  "type": "select",
  "options": [
    { "value": "general", "label": "General" },
    {
      "value": "sales",
      "label": "Sales",
      "when": [{ "field": "department", "op": "eq", "values": ["sales"] }]
    }
  ]
}
```

Operands can use `$field:key`, `$user:id`, `$user:email`, `$entry:id`, `$entry:model`, `$entry:locale`. Prefix a literal dollar value with `$$`. Missing context gives no matching choices. Unsaved sibling edits recompute the picker. An incompatible saved select value stays visible with a warning and a **Clear** action; you can also choose a replacement. Save checks selected values again, including retained dependent values; change an incompatible selection before saving. Relation choices also respect the person's existing read access. A choice rule grants no extra access.

## Structured inline content

An active plugin can declare an inline item in **Blocks → Plugin blocks**. Place the caret inside a
paragraph and choose its label. The item stays inside that paragraph. Select its visible label to
edit the plugin's declared fields in a dialog; close the dialog to continue writing.

The host draws the controls and preview. Values are structured data with the plugin type and version,
not pasted markup. Undo, saved versions, restore, site copy and native import keep the values and
references. The public and generated renderers allow inline markup only; a plugin cannot insert a
block element into a paragraph. A disabled or unavailable plugin keeps the stored item but does not
render it publicly. Existing block items remain available separately.

## Collection order

For a collection, open **Collection order** and enable **Enable manual order**. This requires `model:apply`. Select **Use manual order** to request it in the list, then move entries with the arrow buttons or drag them before another visible entry. Translations share one position. Filtered, hidden and off-page entries keep their order relative to each other; a move uses the visible entry as its anchor. New groups append; Trash and restore preserve their position. Reordering creates no content version.

Manual order is optional and supports up to 20,000 translation groups per model. Concurrent changes return a conflict: reload before moving again. Public consumers explicitly request `order=manual`; other sort modes keep their behavior. A field sort cannot be combined with manual order. Cursors bind the order revision, so an old cursor is refused after reordering. Native copies carry the source order for newly copied groups and preserve existing destination groups. Undo restores an imported order flag only if subsequent ordering or membership changes have not superseded it.

## Field groups 

Models may group fields under localized headings. The heading and its info control use the admin language, with the site's default language and original label as fallbacks. Group names do not change saved field keys or content values.

## Future versions 

Use Scheduling to add an entry to a release with **Version → Independent future version**. Give the release a name and time. Open **Future versions** on the entry and select that release's version. Each release has its own saved content and history; editing it leaves the ordinary draft and public version unchanged. Different campaigns can prepare different versions of the same entry or composed page.

In the future editor, choose a language, edit fields or the page's sections and facts, then **Save**. **Future history** lists its saved versions. Required review tasks are checked against this future content. Return with **Back to entry** to edit the ordinary draft.

**Preview through this release** uses the published site plus earlier scheduled releases, including their publication and unpublication actions, then this release. Composed pages use the preview in their page controls. Choose a release time first; unreadable content stays hidden. It is a private preview and changes no public cache or publication.

The release freezes the exact future revision when its publication command starts. It then becomes read-only. Later ordinary draft edits are preserved. A normal release item still publishes the latest ordinary saved draft. Two releases cannot act on the same entry and overlapping languages at exactly the same time; choose different times.

## Batch AI

Open one content type, select entries or **Select all matching**, then choose **Batch AI**. Choose text fields and **Rewrite**, **Translate**, **Terminology**, or **Summarize**. Translation also needs different source and target languages; terminology needs your glossary in **Instructions**.

**Generate proposals** freezes the current selection. Later matches are excluded. Generation requires permission to use AI and read the source content; it does not save entries. Each result retains its base revision and original values. Translation creates at most one proposal per selected translation group.

Use **Review proposals** to compare the original text, edit a proposal, apply it, or reject it. Applying uses your current field, locale and content permissions, validation and version checks. If an entry changed after generation, the proposal is refused as stale. Editing and resolving a proposal compare its revision too, so one reviewer cannot silently overwrite another's changes. Translation can add a missing configured language through the normal versioned save.

Leaving the page keeps pending work available through **Continue**. **Stop** cancels pending generation permanently; it preserves proposals already produced and an in-flight result. Transient provider failures can be retried up to three attempts; committed proposals are not generated again. Reopen **Batch AI** to review the latest run, or open an entry to see its retained proposals. AI credentials stay on the server.

<!-- dee-wan-docs page: /guides/media/ -->

# Media library

Source: https://dee-wan-docs.pages.dev/guides/media/

The media library holds a site's images and files. Each site has its own library. Another site's files are never shown or matched.

## Open the media library

Open **Media** in the sidebar to manage the library. The same library opens as the **Media Center** dialog wherever you pick a file:

- a media field of an item: **Media center**;
- rich text: **Insert Image** → **Media Center**, or **Upload New** to upload straight into the text;
- an image slot of a page section in the [page builder](/guides/page-builder/).

If the library cannot load, press **Try again** without closing it.

Pick one or more files and press **Use N selected**. A media field takes only the kinds of file its model allows, up to its own size. See the `media` row in [field types](/reference/models-and-fields/#field-types).

Reading the library follows media read access. Changes need three separate permissions:

| Permission | Allows |
| --- | --- |
| `media:upload` | Add files: uploads, files saved from AI generation, files an import or a plugin brings in, files copied from an external source, and private uploads. |
| `media:update` | Change what exists: alt text and descriptions, focal points, loading and fetch priority, replacing a file, folders, tags and public or private visibility. |
| `media:delete` | Delete a file. A file in use is still refused. |

The built-in admin and editor roles hold all three. The author role holds `media:upload` only: an author can add files and cannot change or delete one. The viewer role holds none. A custom role holds exactly what it lists under **Settings → Roles**. Where a control is unavailable for lack of a permission, it is disabled and says which permission it needs.

## Upload files

Press **Upload** and choose files. They go into the folder on screen. The dialog states the size limit. Files are public unless you keep them private. See [Private files](#private-files).

### File kinds and formats

Each site chooses what its library takes under **Settings → Site → Media files**. Turning a kind off keeps the files already in the library.

| Kind | Formats | Default |
| --- | --- | --- |
| Images | PNG, JPEG, WebP, AVIF, GIF, SVG | Always on |
| Documents | PDF, Word, Excel, PowerPoint; also ODF text, spreadsheet and presentation, RTF, Text, CSV | On, with PDF and the Office formats |
| Audio | MP3, M4A, Ogg, WAV; also FLAC, AAC | Off |
| Video | MP4, WebM; also QuickTime, Ogg video | Off |
| Other files | **Any other safe file** | Off |

- Programs, scripts and web pages are never accepted, whatever the setting.
- The format is checked from the file's bytes, not only from its name.
- SVG is an image: select it in image fields, preview it and render it with `<img>`. It stays vector. The static subset accepts shapes, text, gradients and internal `#id` references, up to 1 MiB. Scripts, event handlers, style sheets, external resources, animation, entities and unsafe XML are refused. SVG uses R2 even when raster images use Cloudflare Images; public SVG needs `IMAGES_BUCKET` and `R2_PUBLIC_DOMAIN`.
- An installation without public file storage takes images only.

### Size limits

Each kind has its own size limit in the same setting. Every kind starts at 32 MiB.

- Images: at most 32 MiB.
- Documents, audio, video and other files uploaded here: the limit can be raised to the installation's upload bound. That bound is 100 MB unless an operator declares a larger Cloudflare plan limit in `MEDIA_REQUEST_BODY_LIMIT_BYTES`, at most 5 GB.
- Formats checked as a whole file (Word, Excel, PowerPoint, ODF, Text, CSV): at most 32 MiB.
- Ordinary imports, plugins and management API uploads: at most 32 MiB per file. Native `.deewan` transfers copy files in chunks and follow the destination installation's file-type and size limits, up to 5 GB where enabled. See [Import and migration](/guides/import-migration/#transfer-a-site-with-its-history).

### Duplicates

Uploading a file the library already holds uploads nothing. The dialog says **Already in the library** and offers:

- **Use existing**: use the file already there. It keeps its own description and tags.
- **Upload a separate copy**: store a second copy.

**Do the same for other duplicates in this upload** applies your choice to the rest of the batch.

## Find files

- **Search by file name or alt text**.
- **File type**: All, Images, Documents, Audio or Video.
- A folder, or **All media** and **Unfiled**.
- A tag filter. **Untagged** shows images without tags.

## Folders

Folders organize the library. They never move or rename a stored file or change its address.

- Each file is in one folder or in **Unfiled**.
- **New folder** creates one inside the folder on screen. Folders nest at most 5 levels.
- A site holds at most 500 folders. A name has 1 to 80 characters and is unique under its parent, ignoring case.
- **Folder options** holds **Rename**, **Move folder to** and **Delete folder**.
- Select files and use **Move N selected to** to move up to 200 files at once.
- **Delete folder** removes it and its subfolders after one confirmation. No file is deleted. Its files become **Unfiled**.

## Tags

Tags are flat labels on images, separate from folders.

1. Select images.
2. In **Tags · N selected**, type a name in **Add a tag** and press **Add tag**. Remove a tag from the selection with its remove button.

- A tag name has 1 to 64 characters and is unique in the site, ignoring case.
- **Manage tags** renames and deletes tags. Deleting a tag never deletes an image. A tag in use asks first and names how many images carry it.
- Tags are private to the admin. No public API serves them.

## Alt text and descriptions

Select files and press **Edit Selected**. Each site language has its own tab.

- An image needs **Alt text** in every language of the site, 1 to 125 characters. **Save** is refused until every language has it: **Every language needs alt text before this can be saved.** A tab without it says **alt text missing**.
- Other files have an optional **Description** per language.
- A content item's version stores one alt text per image, copied from the library when the item is saved. On the ordinary save it is the site's default-language alt text. The public API serves that stored value as `alt`. A library change reaches the public API after the item is saved and published again.

## Frame an image in content

Framing decides which part of an image shows. It never changes the file.

- In an item's media field, set a **Focal point** on the image: click the part that must stay visible, then **Use this point**.
- When the field has an aspect-ratio rule, the crop follows the field's shape.
- Framing belongs to that one use. The same image elsewhere keeps its own framing.
- **Default focal point** in **Edit Selected** starts new uses of the image. Existing uses keep their own focal point and crop.
- Only images can be framed.

How a website shows framed images is in [images on a generated site](/guides/preview-and-client/#images-on-a-generated-site).

## Image loading

In **Edit Selected**, **Fetch priority** sets the browser hint: **High**, **Low** or **Auto**. **Loading** chooses **Eager** for immediate loading or **Lazy** to wait until the image is needed. Leave priority on Auto unless the image needs an explicit preference. These settings do not change the stored file.

## Edit an image

### Crop and rotate into a copy

1. Select an image, press **Edit Selected**, then **Crop and rotate**.
2. Rotate with **Rotate left** and **Rotate right**. Drag the crop or its corners. On the keyboard, arrows move the crop, Alt and arrows resize it, R rotates.
3. Press **Save as copy**, or Enter.

The copy is a new file with its own size and uses. It takes the original's alt text, folder and tags, and says **Edited from {name}**. The original and every place that uses it are unchanged. If the library already has the exact result, that file is selected instead.

### Replace the original

**More actions** → **Replace original** writes the edit over the original file.

- First it lists the items that use the image. Their published pages will show the edited image.
- It also counts uses in places you cannot open.
- When the new file has a different shape, it says how many items frame the image with a crop or focal point, so you can check them.

A linked file from an external source cannot be replaced or edited.

Scripts and agents use `POST /api/manage/v1/media/{id}/replace` with multipart `file` and an idempotency key. The media id and content references stay the same; the delivery URL may change. Use the returned URL. Published versions that pin an older object keep those bytes. See [Management API](/reference/management-api/).

### Change the image format

**Image format** in **Edit Selected** converts an image to **WebP** or **AVIF**, or leaves the current format unchanged. The conversion runs in your browser. Saving it replaces the original, so it shows the same where-used review first.

## Where a file is used

Before a replace or a delete, the dialog says where the file is used: **Nothing references it.** or **Still used by {count} content reference(s): {names}.**

- A use in content you cannot read is counted, never named.
- Older versions an item still keeps also count as uses. See [how many versions are kept](/guides/content-editing/#how-many-versions-are-kept).

## Delete a file

Press **Delete image** (or **Delete file**) on the file.

- Deleting needs `media:delete`. Deleting a private file removes it from private storage.
- A file in use cannot be deleted: **This image is in use**. Update the content that uses it first. Retained versions can keep it in use until they are trimmed.
- A file that starts being used during the delete is kept.
- Deleting asks first and cannot be undone.

## Private files

Files are public by default: anyone with a file's address can open it, and content can use it. A private file is stored apart from the public site, has no public address, and opens only through a link made for you.

- **Needs private storage.** An operator binds a private R2 bucket as `PRIVATE_MEDIA_BUCKET` (see `backend/wrangler.example.jsonc`). It must be its own bucket, with no public domain or public access: the public media bucket must not hold private files. Without it, **Keep new files private** is not offered and **Make private** is disabled with **This installation has no private file storage.** Setup does not create this bucket and does not check that it is private.
- **Upload privately.** Tick **Keep new files private** before choosing files. It applies to the uploads that follow, including large files uploaded as a stream. Files a plugin or an external source adds are always public. A site copy or history file brings private files in as private.
- **See what is private.** A private file shows a **Private** badge in the library and in its details.
- **Open or download.** Press **Open** or **Download** in a private file's details. Each press asks the server for a link that opens that one file of this site and expires after 5 minutes. The library's previews and the audio and video players ask for the same kind of link. Any member who can read the library can ask for one. Nothing else serves the file: the public media address does not hold it, and image transformations cannot reach it. If a private audio or video preview cannot load, choose **Try again**. If **Open** or **Download** fails, **Try again** repeats that action and keeps your edits.
- **Protected image previews.** Private raster uploads create WebP thumbnails (up to 320 px) and previews (up to 1280 px) in the same private bucket. Each is at most 2 MiB. Delivery checks the parent file and uses its short-lived link; neither the source nor a preview has a public URL. Older images or failed local conversions fall back to the original. In file details, **Refresh private previews** retries generation; it needs `media:update`. SVG stays vector and uses its original. Site copies and generated application transfers carry existing previews with checksums. Replacing or deleting an unreferenced private object removes its previews too.
- **Protected rich content.** A private model can use private images, galleries and downloadable attachments in ordinary rich-text fields, including rich children inside plugin blocks. The editor opens them through the same protected library delivery. Public models, page sections, snippets, social images and Site Chrome still refuse private media (`media_private`). A private model requires an API token and cannot become public while any retained version pins a private file (`model_holds_private_media`). API answers keep file identities and withhold storage locators. Generated applications read rich-content files through the owning row’s guarded file route; see the next point.
- **Site copies keep private files private.** A site copy and a history file carry every private file with its bytes, checksum, details and visibility. The import stores each one in the destination's private storage, under the private provider, and never in the public bucket; undo removes it from there. A private model arrives private. If this installation has no private file storage, the check blocks with `private_storage_unavailable` before anything is written. Building the file needs read access to the media library (the same access that opens a private file) as well as `data:export` when the site holds any private file (`export_private_media_forbidden`); `media:update` is not needed. Access is checked again on every download. Content-only exports (CSV, JSON, XLSX) never depend on private library files. If private storage is not bound, a site-copy or history export is refused by name without building a file (`export_private_storage_unavailable`). No storage credential or bucket name travels.
- **A generated application serves its own private files.** When you exit to your own repository with private files, they are copied into your own private bucket (never the public one) and the row's address column holds a `private-file:` marker, not a URL. The application serves a file at `GET /api/<model>/files/<field>/<row id>`, only to a caller who may read that row under the model's own access: your account sessions, your service credential or your read tokens. Membership of the CMS library proves nothing there. Each request is checked again; nothing expires and nothing is minted. The Worker reads the bytes from its `PRIVATE_FILES` bucket; the Node server reads them from the directory in `PRIVATE_FILES_DIRECTORY`, and without either it answers `503 private_files_unavailable`. See [Standalone backend reference](/reference/standalone-backend-api/).
- **Duplicates.** The duplicate check compares every file in the library, public or private.

For a rich-text field, use `GET /api/<model>/files/<field>/<row id>?media=<media id>` and add `&variant=thumb` or `&variant=preview` for a protected image variant. The generated `src/private-files.ts` exports `privateRichText(html, endpoint, rowId)` to replace stored private markers with these same-origin, session-protected URLs before display. It rewrites only identity-bearing media from that field; the route reads the owning row again for every request.

### Make a file private or public

Select the file, press **Edit Selected** and use **Visibility**. It needs `media:update`.

Changing visibility never just flips a flag. The server copies the file to the other store under a new key, checks that the copy has the same length and SHA-256 as the recorded original, and only then switches the file over. After that it removes the old copy. The control shows **Copying and checking the file…** while it works, then says what happened:

- **The file is private now. The public copy was removed.** (or the reverse for public).
- **The change is saved. The old copy was kept because retained history still names it.**
- **The change is saved, but the old copy could not be confirmed removed. It may still be reachable at its old address until it is deleted from storage.** Copies a browser or a cache already holds are outside the library's reach.
- **The file was not moved. {reason}** when the copy failed or did not match: nothing changed and the unfinished copy was removed. If it could not be removed, the message says so.

Making a file private is refused while any content or retained version uses it (`media_in_use`); update that content first. A file kept by an external media source cannot be made private.

## External media sources

A plugin can offer media sources. Then the dialog shows **Sources** beside **Library**.

1. Pick a source, search, and use **Show more** for more results.
2. Add a file:
   - **Add** copies the file into your library. It follows the same kinds, formats, size limits and duplicate check as an upload. It keeps the source's credit.
   - **Link without copying** keeps the file with the source. The library holds only a link to it.

You can edit a linked file's details, tags, folder and framing as you would for any other file. Its bytes cannot be replaced or edited. Deleting it removes only the library entry. If the plugin is turned off or removed, existing content keeps the stored address, the details say **The source is not available now.**, and new links from it are refused.

A copied file's credit is saved with the item and served by the public API as `credit`. Show it under the image.

## Generate an image with AI

Press **Generate** in the library.

1. Describe the image. Choose the **Model** and the **Aspect Ratio** (9:16, 1:1 or 16:9) under **Settings**.
2. Press **Generate**. **Regenerate** and **Generate New** try again. Nothing is saved yet.
3. Press **Save** to add it to the library, in the folder on screen. The duplicate check applies.

Generating needs `ai:generate`. Saving needs `media:upload`. A generated image is always public. The installation needs an AI provider set up. Generation counts against the site's hourly AI allowance.

## Next step

Use files in [content](/guides/content-editing/) and on [pages](/guides/page-builder/).

## AI alt text and captions

Open the image details. Choose a language and a vision model from the live catalogue, then choose **Suggest alt text and caption**. The image bytes go to the configured AI provider; private images stay private. Review and edit both suggestions. **Apply and save descriptions** replaces the saved text for that language. Discarding the suggestions keeps the author's text. Concurrent metadata edits block the apply. After an upload, the optional **Review AI descriptions after upload** control opens the selected files for review. Inference accepts JPEG, PNG and WebP images, up to 10 MiB.

## Asset fields and history

Open **Media** in the sidebar to manage files without choosing one for an item. File pickers use the same library.

In **Asset fields**, a site administrator can add up to 24 text, number, boolean, select, date, media or relation fields. **Localized** stores separate language values; other fields share one value. Fields start private. Enable **Public** only for values the website should read. Field configuration requires `site:settings`; changing a file's values requires `media:update`.

Open a file's **Asset metadata**, choose a language and enter values. The editor's footer **Save** saves custom metadata together with descriptions and file options for the selected files. There is no separate metadata save button. **Metadata history** offers retained revisions. History keeps up to 50 revisions within 512 KiB for current values and history together; the oldest whole revisions are removed first. Current values are never truncated. Changing a field's type, configuration, language mode or public setting makes retained values unavailable for public projection and historical restore until you enter values under the current definition.

Relations follow the current site's model, document and language access. Public values can reference only public media and published public entries. Private metadata and its history are absent from ordinary media responses and public content. Public content exposes declared values under `mediaMetadata`, keyed by asset ID. This metadata follows the asset's current revision, including when many entries reuse the file. Generated website artifacts capture the projection at generation time; regenerate to update it. Version-pinned file bytes, framing and descriptions keep their existing behavior.

Native site copies carry asset fields, values and retained history, remapping carried entry and media references. A copy does not overwrite metadata on an existing destination file. Undo keeps a changed or still-used file with its metadata, and refuses dependent cleanup; this includes retained references and reference cycles. Field definitions still used by retained values stay too. Public-cache clearing failures are shown after saving.

If metadata cannot be saved, the editor stays open with your draft and opens **Asset metadata** to show the error. Correct the values and press the footer **Save** again. If the fields or values changed elsewhere, choose **Reload** to discard the local metadata edits and load the current version, then enter your changes and retry **Save**.

## Localized originals

Open **Media → Edit Selected → Localized originals**. Choose **Language**, then **Replace file**. **Remove original** returns that language to its fallback. Both actions require `media:update`. The asset ID, references and language-specific descriptions stay the same.

Resolution order: requested language, configured language fallbacks, default original. Published versions pin their exact files. Replacing or removing a language original keeps files needed by retained versions. Private originals use the ordinary private-file access rules. Site copies and full-history transfers carry explicit original languages and retained files.

Management operations: `listMediaOriginals`, `replaceMediaOriginal`, `removeMediaOriginal`. Replacement is multipart `file` plus `expected_object_id`; use the empty string when that language has no original. Removal names the current `expected_object_id`. A changed pointer returns `409 media_changed`. Default-original replacement keeps its existing operation.

<!-- dee-wan-docs page: /guides/languages/ -->

# Languages

Source: https://dee-wan-docs.pages.dev/guides/languages/

Each site has its own languages, one default language, and a rule for what visitors get when a translation is missing. Set them under **Settings → Languages**. Changing them needs the site settings permission (`site:settings`).

For the full public contract, see [locales in the public API](/reference/public-api/#locales). For field and address rules, see [models, locales and pages](/reference/models-and-fields/#models-locales-and-pages) and [item address](/reference/models-and-fields/#item-address).

## Add a language

1. Open **Settings → Languages**.
2. Open **Select language** and search for the language. **Show dialects of {name}** lists its regional variants.
3. Press **Add language**.

A language can be added once per site. When the site has no default language yet, **Set as default** makes the new one the default.

Adding a language changes no content. Items get the new language only when someone starts a translation. See [translations](/guides/content-editing/#translations).

## Choose the default language

The default language is marked **Default**. Press **Make default** on another language to change it.

- A read with no `locale` gets the default language.
- Under the fallback rule, the default is the last language tried before the item's own primary language.
- A new item starts in the default language.
- Changing the default clears the site's cached public reads. If that fails, the screen says so, and readers may get the previous default for a while.
- The default language cannot be removed.

## Choose what visitors get when a translation is missing

Under **Missing translations**, set **When this language is missing**:

| Choice | Rule | A visitor asking for a missing language gets |
| --- | --- | --- |
| **Show the default-language page** | fallback | The first published language in the chain below. The response's `locale` says which one. |
| **Show page not found** | strict | Nothing. Lists leave the item out. A direct read answers 404 `locale_unavailable`. |

Only published languages are ever served. A draft language never fills in for another.

When nothing is set, the screen says **No behaviour is set, so this site's public API is not serving.** Pick one to repair it.

### Fallback languages

With **Show the default-language page** and more than one language, **Fallback languages** appears. Each language can list languages to try, in order, before the default.

1. Press **Edit** on a language.
2. Under **If {language} is missing, show**, press **Add a fallback language** and choose one.
3. Order them with the move buttons. Remove one with its remove button.
4. Press **Save**.

Before you save, the screen counts what visitors of that language would get: **Translated**, **Shown in {language}** and **Not shown**.

- A fallback language's own fallbacks follow it. With `pt-BR → pt` and `pt → es`, a `pt-BR` visitor gets `pt-BR`, then `pt`, then `es`, then the default.
- The screen warns when your change **Also changes what … visitors see** for other languages.
- A list holds at most 8 languages.
- A save is refused when languages would fall back to each other, when a language falls back to itself, lists one twice, or names a language the site does not have.
- With no list, a language falls back to the default alone.
- Under **Show page not found**, fallback languages are ignored.

## What visitors get

A public read names its language with `?locale=`. Without it, the read serves the default language.

- Under fallback, a read tries the requested language, its fallback languages, the default language, then the item's primary language. It serves the first one that is published.
- Under strict, it serves only the requested language, and only while that language is published.
- Each language of an item has its own address. A single-item read lists every live language and its address in `alternates`.
- The editor shows the result for each language. For example, **Not live in Thai yet. Visitors see English.** or **Not live in Thai yet. Visitors get page not found.**

The site determines the rule. A visitor or caller cannot change it.

## Field fallback

To fill individual missing fields, open the model field's **Properties** and enable **Field fallback**. It is off by default. The field must be optional and translated: text, rich text, number, Boolean, date, select, JSON or component. Addresses, relations, media and shared or required fields do not offer this option.

In the content editor, **Use fallback** removes that field's translation. **Enter translation** starts a local value again. Clearing a field is intentional: an empty value, `null`, `false`, zero or an empty list never borrows another language's value.

With the site's fallback rule, an absent field uses the first published value in the fallback chain, then the item's primary language. Each source language is read from its own published version; a newer draft cannot fill the field. With the strict rule, field fallback is ignored.

Public single-item reads, lists, filters, sorting, search and generated website pages use these effective values. The response's `locale` still names the item's served language. The editor keeps local values separate, so borrowing a value does not copy it into the translation.

Management saves can remove a translation with `unset_fields: {"th": ["subtitle"]}`. Only opted-in fields are accepted. A field cannot be set and unset in the same save; field and language permissions still apply. Omitted keys in an ordinary partial save keep their existing values.

## Limit roles to languages

A role can access every language by default. To limit it, open **Settings → Roles**, edit the role and open **Limit fields and languages**.

- **Limit languages** picks the languages the role works in. It applies to create, update, delete, restore, review, publish and unpublish.
- **Can read every language** keeps reading open, so a translator can read the source language while editing only their own.
- An action outside the role's languages is refused with `locale_denied`. An action that spans languages, such as publishing a whole item or performing a bulk action, is refused in its entirety.
- Shared fields, shared relation lists and media live on the primary language. Changing them needs the right to update the primary language.

The full rules are in [limit a role to some fields or languages](/guides/people-and-access/#limit-a-role-to-some-fields-or-languages).

## Work on one language

These actions change one language and leave the others as they are:

- **Start a {language} translation** adds a language to an item.
- **Publish {language}** and **Unpublish {language}** in the item's **Publishing** panel.
- **Move this language to Trash**, and restoring that language from Trash.
- **Restore {language} only** in the item's History.
- Each language's own address.
- Relation fields with **Different links in each language**. See [different links in each language](/reference/models-and-fields/#different-links-in-each-language).
- Alt text and descriptions per language in the [media library](/guides/media/#alt-text-and-descriptions).

Actions marked **All languages** move every language of the item. A move between two unpublished stages, such as **Approve · All languages**, leaves a language that is already published live; take it off with **Unpublish {language}**. See [one language or all languages](/guides/content-editing/#one-language-or-all-languages).

## Remove a language

Press **Remove** on the language. The confirmation counts what the language holds: content items written in it, translation groups whose primary language it is, and media descriptions.

- Removing takes the language out of the authoring controls. Nothing stored is deleted.
- Published content may keep serving this language until it is changed and published again.
- The default language cannot be removed. Make another language the default first.
- A language that is a fallback for others cannot be removed: **{language} is a fallback for {languages}. Remove it from their lists first.**
- If what the language holds changes before you confirm, the removal is refused. Review the new counts and try again.
- New content cannot be created in a removed language, or in one the site never had (`unknown_locale`). A create request that runs while the language is being removed writes nothing (`language_changed`).

## Fix common problems

| Problem | Cause | Fix |
| --- | --- | --- |
| The public API answers 500 `site_locale_policy_invalid`. | No missing-translation rule is stored. | Choose one under **Missing translations**. |
| A read answers 404 `locale_unavailable`. | The item is published, but in no language the rule may serve. Under strict, only the requested language counts. | Publish that language, add a fallback language, or switch to **Show the default-language page**. |
| Visitors see another language. | The fallback rule applies, and the requested language is not published. | Check the response's `locale`. Publish the translation. |
| **Remove** is refused. | It is the default, or a fallback for another language. | Change the default, or edit the fallback lists. |
| A fallback list does not save. | A loop, a repeat, an unknown language or more than 8. | Fix the list as the screen says. |
| Adding a language to an item is refused with `language_in_trash`. | That language of the item is in Trash. | Restore it from Trash. |
| A translator cannot publish their language. | The role lacks publish in that language, or the action spans languages. | Use the language's own button, or extend the role. |

## Next step

Translate and publish items in [edit and publish content](/guides/content-editing/).

<!-- dee-wan-docs page: /guides/page-builder/ -->

# Build and edit pages

Source: https://dee-wan-docs.pages.dev/guides/page-builder/

Pages are structured documents with a title, facts and up to 24 sections. You type on the page
itself, pick sections from a visual gallery and set each section's style in a side panel. Unsaved
changes are kept as the page's draft until you save them as one version.

## Open or create a page

Open **Pages** from the main navigation. The library lists the site's pages, most recently changed
first. Each row shows a small picture of the page's sections, its address, when it changed,
whether it is **Live**, **Live · edited** or a **Draft**, and how many of the site's languages it
has, for example "2 of 3 languages · Missing TH". Search by title or address, and filter by
**All**, **Live** or **Draft**. A row's **⋯** menu opens, renames, duplicates or moves the page to
Trash. A duplicate is an unpublished copy of every language.

**Trash**, beside **New page**, lists pages moved there in the last 30 days, every language
together. **Restore** brings one back as a draft with its history and opens it. **Delete
permanently** removes it for good after asking. A live page is unpublished first; Move to Trash is
not offered while it is live. After 30 days a page in Trash is deleted for good.

![The Pages library with search, the status filter and one live page](/assets/screenshots/pages-library.webp)

**New page** offers three starts:

- **Start from template**: Landing, About, Service, Event, Menu, Pricing or Blog post. A template adds
  empty sections for you to fill in. It never adds sample text.
- **Describe it to AI**: say what the page is for and press **Generate page**. The four examples
  (landing, about, service, event) only fill the prompt.
- **Blank page**: start empty and add sections.

Template and blank pages ask for a page name. **Page address** is optional. Without one, the address
is made from the name's Unicode letters and numbers, including Thai and Cyrillic, with spaces
replaced by hyphens. A name with no letters or numbers opens **Page address** and asks you to type one.
**Page address** takes at most 180 characters.

## The top bar

The top bar holds:

- the page name, with a pencil to rename it
- one status for this language: **Live**, its own workflow state such as **Draft** or **In review**,
  or **Not published** when its state says published and nothing is live
- a language choice, when the page exists in more than one language
- the save state (**Saved** or the number of unsaved changes) and **Save**
- **Preview**, only when the site has a verified renderer (see [Site preview](#site-preview))
- **View page** once this language is published and the site has a public address. It opens the
  live page in a new tab
- the next workflow step. With unsaved changes it saves first, for example **Save and publish** or
  **Save and submit for review**. Review is never skipped
- **⋯** (More page actions).

**⋯** holds **Ask AI to change the page**, **Site preview** when available, **Page settings**,
**Discard changes** while you have unsaved work, and a step that takes the page off the site, such
as **Unpublish**. On a narrow screen, **Preview** and **View page** move into this menu too.

## Edit on the page

The canvas is a **Structure preview**: section types, order, images, style and arrangement are
exact. Typography, colour and theme may differ from the site. **Phone**, **Tablet** and **Desktop**
above it set the canvas to 390, 768 or 1024 pixels wide. Choose the active one again for the full
width. When the section panel leaves less room than the chosen width, the canvas keeps that width and
scrolls sideways. A phone shows no width choice.

### Site design

The canvas offers **Site design** and **Structure preview** only when all of these hold:

- the site has an active managed release;
- the installation has the render signing key (`MANAGED_RENDER_HMAC_KEY`, 32 or more characters);
- the site's own bound host, as `https://<host>`, is the address that release was made for.

**Site design** draws your unsaved working page through that release's own template, so fonts,
colours and spacing are the site's. Otherwise the editor shows the Structure preview only.

- The render is private. It goes from the editor to the site's renderer and back, and is never
  stored, cached or published.
- The drawn page keeps up with your edits. Typing waits for a short pause. Adding, removing or
  moving a section redraws at once.
- Click a section or a text value in the rendered page to select it. The section panel opens at that field.
  Selecting a section or field in the panel highlights it in the drawn page.
- <kbd>Esc</kbd> in the drawn page returns to the Structure preview with the same selection.
- A failed render never touches your working page. The last drawn version stays with a note such as
  "Not updated. Showing the last design." **Retry** appears when trying again can help: a lost or
  slow answer, a renderer fault, or a render that did not start. A page the design cannot draw (an
  empty required field, something the release cannot show, a missing translation, a page too large)
  is not retried: change the page or switch releases. **Structure preview** is always one press away.
- A page with an empty name, no sections or an empty required field is not sent. The note says
  what to fill in.

**Site design** is different from [Site preview](#site-preview): Site preview shows a _saved_
version through a custom renderer. A managed release is prepared and activated in Settings → Source &
delivery → Site template (see [Managed site templates](/guides/managed-templates/)). A site without an active managed release
sees the Structure preview only.

Click a heading, paragraph, list item or button label on the canvas and type. Bold, italic and
linked words keep their formatting while you type around them. Empty required fields show a
placeholder such as **Add heading**. Controls for everything you cannot edit by typing are in the section
panel beside the canvas (at the bottom of the screen on a phone or tablet): links, images, adding
and removing list items, paragraph formatting and style.

![The page editor with the first section selected and its panel open at Style](/assets/screenshots/page-editor.webp)

A selected section shows a small toolbar above its content: drag handle, move up, move down,
duplicate, Ask AI (the sparkles button) and **⋯**. The section's **⋯** holds **Change section type**, **Duplicate section**,
**Copy section**, **Paste section after this one** and **Remove**. A copied section can be pasted on
any page of this site.

**Sections N / 24** opens the section list, where the up and down buttons and the drag handles also
reorder sections. Dragging is optional. The buttons and keys do the same.

### Add a section

Use **Add section here** on the canvas, **Add section** in the section list, or press <kbd>/</kbd>
or <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>K</kbd>. The gallery shows a picture of every section type in
each of its visual variants, and patterns such as **Page header**, **Big statement**, **Quote** and **FAQ**.
Search by name or description.

The section you pick enters the page at once, with its required fields empty and the cursor in the
first one. Save stays unavailable until those fields are filled.

| Group               | Section types                                                    |
| ------------------- | ---------------------------------------------------------------- |
| Openers             | Hero                                                             |
| Text                | Text, Text with image                                            |
| Lists & proof       | Feature grid, Cards, Stats, FAQ, Testimonials, Logo strip, Steps |
| Media               | Gallery and video                                                |
| Pricing & menus     | Pricing, Menu                                                    |
| Contact             | Contact details                                                  |
| Posts & collections | Latest entries (pattern: **Latest posts**)                       |
| Forms               | Form                                                             |
| Custom              | The sections your developer registered for this site             |
| Calls to action     | Call to action, Site search                                      |
| Shared sections     | This site's shared sections, by name                             |

**Latest entries** lists the newest published entries of a public collection. The **Latest posts**
pattern fills it in for a Blog's posts. Choose the collection, fields and count in the inspector; see
[Blog sites](/guides/blog/#latest-posts).

**Form** collects what visitors type. In the inspector you set its fields (label, kind, required,
help text and, for a choice, its options), an optional consent statement, the button text and the
message shown after sending. Where submissions go is not part of the page: set it in **Settings →
Integrations → Website forms** (an email address or a signed webhook). Forms take no submissions
until that is switched on. On the canvas, select the form and use **Preview** to see each state a
visitor can encounter: sending, needs fixes, already received, sent, too many tries, not sent and not
taking submissions.

For files, choose **File upload**. Set **File types** (for example `.pdf, .png`), **Maximum files**
and **Maximum size per file**. Empty file types allow all supported images and documents. Uploads
are bounded to 5 files and 10 MiB per submission, with at most 5 MiB per file. Files stay private with
the submission and are downloaded from its receipt; see [File attachments](/guides/website-forms/#file-attachments).

**Custom** sections are ones a developer registered through the site design (see
[Managed templates](/guides/managed-templates/#registered-sections)). Each is a fixed version: its fields
come from that version, and the canvas shows the values with a note that the site design draws the
final look. When a newer version is available, the inspector offers **Update section**. Values the
new version still accepts are kept and the rest start empty. Updating changes this language only.

**Site search** puts the site's search box on a page, with an optional heading and the text shown
inside the box. Visitors get results in the page's language. It is offered only while site search is
on in Settings, whichever design draws the site. If search is turned off later, a page that still
holds the section cannot be saved until it is removed.

**Saved patterns** come first in the gallery when the site has any. A saved pattern holds sections
with their words, saved from a page. Inserting one adds a copy: later changes to the pattern never
change a page that already used it. To save one, open a section's **⋯** menu and choose **Save as
pattern…**, then name it and tick the sections to keep. **Manage saved patterns**, below the gallery,
renames or deletes them; pages keep their copies either way.

**Shared sections** keep one piece of content in one place and show it on many pages: an
announcement, a promotion, footer content, a call to action. Make one under **Pages → Shared
sections → New shared section**. It opens in this editor: add up to 6 sections (no form, site search,
custom section or other shared section), then save and publish it like a page. It has no address of
its own, and the editor shows **Used on N pages**.

Pick one from the gallery's **Shared sections** group to add it to a page. The page keeps a link to
it, not a copy:

- The canvas draws it as it is published, marked **Shared**, with **Edit shared section**. Change it
  there; once you publish it, every page using it shows the change. A draft never shows on a page.
- **⋯ → Make a separate copy** turns it into ordinary sections in the current language, using the content shown in that language. Other languages keep the link. Later changes to the shared section no longer reach the
  copy.
- A page cannot be published while a shared section on it is unpublished. The quality list says
  which one.
- Unpublishing a shared section lists every page using it and asks you to confirm. Those pages then
  show nothing in its place.
- A saved pattern cannot hold a shared section. Copy and paste keeps the link on this site only.

The gallery offers only what the site's renderer can show. Without a renderer, every type is offered,
except Site search while search is off.

### Reusable components

A reusable component is a section you made once and can add to any page of this site. It is made
from a section on a page, built in isolation and reviewed before anyone can use it.

**Make one.** Open a section's **⋯** menu and choose **Save as reusable component…**, name it, and
optionally say what should change, for example "larger heading". The section's words become fields
people fill in each time it is used. This needs the `site:deploy` and `ai:generate` permissions. A
section made of words and images can be saved; a form, site search, latest entries, custom or shared
section cannot, and a section with missing fields must be completed first. AI writes the component
and its fields, the platform refuses code that imports anything but the page contract or accesses the network, and the build then runs with the network off. It takes several minutes. If no answer
arrives the form says the component may still have been made.

**Review it.** **Pages → Components** lists every component with each version's state: **Awaiting
review**, **Ready to use**, **Rejected** or **Removed**. **Review** shows the 8 build checks, the
fields it asks for, what it imports, a preview of its own sample content (every field filled, or only
the required ones) and, with `site:infra`, its source code. **Use this component** needs `site:deploy`.
The same person who made the component may approve it; there is no second reviewer. If the site's
design changed after the build, **Use this component** is unavailable until you choose **Rebuild**. **Reject** keeps the
record and cannot be undone. Using a component changes no page.

**Use it.** A component that is ready appears in the gallery with the other custom sections, under
its name. The page keeps the exact version it was given. A newer version never changes a page: the
section panel offers **Update section**, as for any custom section, and updating takes the newer
version of that component. A page that uses a component is stored in page format 3 (see
[Page contract](/reference/page-contract/#reusable-components-format-3)).

**New versions and copies.** In the Components tab, **⋯** on a component with a ready version offers
**Make a new version…**, which asks AI to change the current code, and **Copy as a new component…**,
which starts a separate component from the same code. **Copy to site…** copies the ready version to
another site where you have permission to build (the list shows only those sites). You need `site:infra` here to read
the component's source and `site:deploy` in the other site; AI is not needed. The copy is a new
component there, with its own name and key, built and reviewed in that site like any other and
awaiting review there. It shares nothing with this site: no page, no pinned version, no build. This
site's component and pages are not changed. Only a version that was reviewed can be copied. If an
answer is lost, try again: the same copy is returned instead of a second one.

**Limits.** The site's design holds at most 16 custom sections and components together; every older
version still in it counts. Making components needs the same setup as template candidates: AI, the
isolated build service, its sandbox image and artifact storage. Without them the tab says what is
missing and nothing is built. A build that no version of any page pins, and that is neither the
accepted design nor part of a release, is removed from storage 90 days after a daily check first
finds that nothing references it (a version never promoted counts its 90 days from when it was made or
rejected). A page that pins a removed version cannot be published, and a page version that pins one
cannot be saved or restored; the message names it. A removed version cannot be used or approved
again, and making the same content again is refused by name. Save the section as a new component under another name, or change its content.

### Style

The section panel shows a style line, for example "Side by side · Muted · Roomy". Click it to
choose:

- **Look**: the section's layout, shown as pictures, such as **Centred**, **Side by side** or **Full
  image** for a hero
- **Image position** for a text-with-image section
- **Background**: Default, Muted, Dark or Accent
- **Spacing**: Default, Compact or Roomy
- **Motion**: None, Reveal or Parallax. The canvas names the motion. The site plays it.

Style applies to the language you are editing.

### Links, images and text

A link goes to a page of this site (search by name or address), a web address or an email.
Paragraphs support bold, italic, links and bulleted or numbered lists from the toolbar above them. An image
comes from the media library. **Add alt text** saves the description to the media library for this
language.

## Undo, save and the quality check

<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Z</kbd> undoes and <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd>
(or <kbd>Ctrl</kbd>+<kbd>Y</kbd>) redoes up to 100 changes to the page since the last save. Facts and required wording are not included in undo history: undo leaves them as they are, but
they are saved, discarded and kept in the draft with your other changes. Alt text saved to the
media library stays saved. Typing in one field counts as one step. History clears when you save or
discard.

With a section selected and no text field focused: <kbd>Alt</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd> moves it,
<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>D</kbd> duplicates it, <kbd>Delete</kbd> or <kbd>Backspace</kbd> removes it after asking,
and <kbd>Esc</kbd> deselects it.

**Save changes** or <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>S</kbd> creates one version from all your
changes to the language you are editing: the page name, facts, required wording, sections and the settings that enable layout controls. It never changes another language. Either all changes are saved or none are: a refused save writes nothing and keeps your changes. If
the answer is lost, or the server answers in a way the editor cannot read, the save may have
happened. The save state reads **Save outcome unknown** and **Retry save** sends the same save again.
It is replayed, never saved twice. The same holds for creating a page, applying AI changes and
setting the first address. The address, workflow, publishing, preview and deleting the page are
separate actions, not part of **Save changes**. **Discard changes** asks first, then returns to the
saved version. Removing a section shows a notice
with **Undo**, which puts the section back without saving anything, and **View history**, which
opens the saved versions.

Below the top bar, **Finish before saving (N)** opens by itself while something must be fixed. N
counts every row. **Check the page** lists them, for example "2 to fix · 1 suggestion". When only
suggestions remain it reads **Suggestions (N)** and stays closed until you open it. Each row takes
you to its section and field.

- To fix (Save is unavailable): an empty required field, text that is too long or contains `<` or
  `>`, an unusable link, a site search section while site search is off.
- Suggestion (never blocks): an image without alt text, a link to an address that no page on this site uses, a section that holds only a heading, another language of the page not translated yet. The
  language row opens that language.

An empty page name also blocks Save. It is listed under the top bar.

## Drafts and editing together

Unsaved changes to a page are kept on the server as that language's shared draft, for 30 days after
the last change. The draft belongs to the page and language, not to you: other people who may read
the page can see it.

- **One editor at a time.** The first editor to open a page language holds its editing lease. Only
  that editor writes the draft, saves, or moves the language through the workflow. The lease is
  renewed while the tab is visible, ends when the tab closes, and lapses two minutes after the last
  renewal. Imports, plugins and scheduled publication are not blocked; the version check still
  protects the editor's save.
- **Others read along.** Another person who can edit the page sees "\<name\> is editing this." The
  editor is read-only and follows the holder's draft: it checks for a newer draft every 10 seconds
  while the tab is visible. Your own second tab says "You are editing this in another tab."
- **Who can see it.** A person who may only read the page sees the draft as it was when they opened
  the page. Seeing a draft needs read access to the page itself: a role that reads only its own
  pages sees a draft only for a page language it owns. A role that cannot read the page title gets
  the draft with an empty title, and a role that cannot read the page's sections gets no draft at
  all (`field_denied`). This holds for every draft answer, a conflict included.
- **Take over** moves the lease to you at once, and you go on from the holder's shared draft. They
  see "\<name\> took over." and their next save is refused. Their unsaved changes are also kept
  as their own recovery draft, and their draft state reads **Not saved — taken over**. An autosave
  or a discard they send after the takeover is refused and changes nothing. A refused discard says
  **Not discarded — taken over. Your work is kept.** **Back to list** leaves
  without taking over. Holding or taking over a language needs your role to change that language
  (`locale_denied` otherwise), and a role that edits only its own pages must own that language's
  page (`not_owner` otherwise).
- **Recovery drafts are private.** Only you see your recovery draft. When you hold the lease again,
  the editor offers it: **Restore changes**, or **Review changes** if the page was saved in the
  meantime. **Discard** drops it.
- **AI drafts are private.** An AI answer you have not applied, and an AI request for a page that
  does not exist yet, are kept as your own drafts. No one else sees them.

The top bar says **Saving draft…**, **Draft saved**, or **Draft not saved** with **Retry**. A draft
that cannot reach the server stays in this browser (**Offline — kept here**) until it can. A shared
draft made on the version on screen opens with the page. One made on an older version shows
**Unsaved changes from an older version** with **Review changes** or **Discard**. If the server's
draft changed while this browser held changes it had not sent, choose **Use the other device's** or
**Keep this one**. If someone saved first, the review lists what overlaps and never saves on its
own. **Save changes** removes the draft. A draft is not a version and never appears in the history.

## Ask AI for a change

Choose **⋯** → **Ask AI to change the page**, or the sparkles button on a section. The Ask
AI panel floats at the bottom of the screen. Choose **Whole page** or **Section N**, describe the
change, and press **Generate changes** (**Generate section changes** for a section) or
<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Enter</kbd>. A page with no sections shows the request box on
the page itself, with **Generate page**. For a section, **Shorter**, **Friendlier**, **Fix spelling** and **Fill empty fields** fill in a request
for you. They do not send it.

**Recent** lists the last 20 requests you sent from this browser, newest first. Choose one to fill the box; it is not sent. **Clear recent** empties the list. The list belongs to this browser, this site and your account. It is never sent to the server.

![The Ask AI panel for one section, with the one-click requests](/assets/screenshots/page-editor-ai.webp)

AI works from the page as you see it, including unsaved changes, plus the site settings and the
page's saved facts. You can type a request at any time, but it is not sent while a required field is
empty or while facts have unsaved edits. The panel says why, and **Save changes** saves the facts
first. It only uses section types and styles the site's renderer can show.

The answer is a proposal shown on the canvas. Switch between **Current** and **Proposed**. Inserted,
changed, moved and removed sections are marked, and **Previous change**/**Next change** walk through
them. You may keep some text changes and drop others. An answer that adds, removes or moves sections
is applied or discarded as a whole. Applying the proposal puts the accepted changes into the page, together with
your unsaved edits, and saves everything as one new version. The answer stays until that save
succeeds or you discard it. If the save is refused, for example because the answer omits required wording from the facts, nothing is saved: the page goes back to how it was before you applied the proposal, your own unsaved
edits stay, and the answer is still there. If the changes would leave the page with something to fix,
nothing is applied. If another save completed first, the changes are kept for review. An answer that
has not been applied is kept as your own draft. After a reload, or on another device, **Show it**
brings it back; it is never applied until you choose to apply it.

## Page address

A page without an address can be saved as a draft but cannot be published. The editor shows "This
page needs an address before it can be published." with an **Address** field and **Set address**,
and the publish step names the same reason. Save or discard your page changes first: the field is
unavailable while there are unsaved changes. An address another page already uses is refused.

**Set address** sets the first address. People who cannot edit the page see that someone who can has
to give it an address.

To change an address later, open **⋯** → **Page settings** and press **Change** beside the address.
The change is saved as a new draft version. The live page keeps its old address until that version is
published; publishing adds a redirect from the old address (see
[Search and sharing](#search-and-sharing)).

## Page settings

**⋯** → **Page settings** opens a panel with the page address, **Facts**, **Workflow**, **Version
history** and **Move to Trash**.

Facts are generation inputs, not text pasted into sections. **Required wording** must appear exactly
as written: an AI proposal that leaves it out is refused, and so is a save of a page without it.
Editing facts or required wording changes the page like any other edit: there is no separate save in
the panel, and **Save changes** saves them with the rest of the page.

![Workflow settings with review enabled and the version-history limit](/assets/screenshots/workflow-settings.webp)

Review is a site setting under **Settings** → **Workflow**. The page's **Workflow** panel shows its
assignment, its history and the actions the workflow allows. Publishing exposes a saved version.
On a page with more than one language, each language has its own state and its own actions, such as
**Publish Thai** or **Unpublish Thai**; they move that language only. The other actions move every
language, such as **Publish all languages**. One language can stay live while another is in review.
An all-languages move between two unpublished stages, such as an approval, leaves a language that is
already live as it is; take it off with its own **Unpublish** action.
Drafts and unapplied AI proposals are never published. A page that uses something the
site's design cannot draw is refused, and the message names it: a custom section version the active
design does not include.

## Site preview

Without a verified renderer, the editor shows the Structure preview only and offers no **Preview** or
**Site preview**. Publishing works. The editor cannot verify how the site renders the page. Editing never depends on a renderer. **View page** does not need one: it opens
the published page at the site's public address.

A renderer is verified under **Settings** → **Source & delivery** → **Advanced — custom renderer**
(see [Preview and the generated client](/guides/preview-and-client/)). Its address must use HTTPS. Plain
HTTP is allowed only for a loopback address such as `localhost`. Once it is verified, **Preview**
opens the saved page in a new tab. When the renderer also supports the editor, **⋯** → **Site
preview** shows a saved version as the site renders it and names it, for example "Saved version 7
as the site renders it". The site marks it "Preview of a saved version. The live page may differ."
Unsaved changes are never sent to the renderer, and the preview says when you have some. After a
save it keeps the previous render on screen until the new version is ready, and keeps it with
**Retry** when a refresh fails. Select a section in the preview to edit it. **⋯** → **Back to
editing** returns to the Structure preview. The last render is kept while you edit, so coming back
to **Site preview** shows it again even when the next refresh fails.

## Site menus, footer and SEO 

**Settings** → **Generation** → **Site context** contains the shared inputs used to generate pages. It has three documents: **Site brief** (approved facts, audiences, voice, terminology, calls
to action, required legal wording and forbidden claims), **Theme** (colour, typography, spacing,
motion and accessibility tokens, and the section shapes the renderer may use) and **Menus &
SEO**.

**Menus & SEO** has:

- **Menus**: lists of links. **New menu** makes one; **Edit** opens it. A menu's **Name** is the
  same in every language. Each language has its own items: labels, order, nesting and which items
  exist may differ. Each item has a **Label** and **Goes to**: a **Page**, **Post**, **Category**,
  **Tag** or **Author** found by name, the **Blog** list, a **Web address** (https), an **Email**, a
  **Phone** number or a **Site path**. A top-level item can be **Nothing (heading)** over the items
  under it. Drag an item by its handle, or focus the handle and press the up and down arrow keys, to
  reorder it; **⋯** has **Move up**, **Move down**, **Add item under** and **Remove**
- **Where menus appear**: which menu shows at the **Top of every page** and at the **Bottom of
  every page**, per language
- **Footer note**: a line at the bottom of every page, per language
- **Regions**: places your template shows on every page. The built-in template has **Above the page
  content** and **Below the page content**; the template decides where each appears. Per language,
  **Add…** puts a menu, a shared section or **Search** in a region; on a Blog site also **Recent
  posts** (choose how many, up to 10), **Categories**, **Tags** and **Posts by month**. **Posts by
  month** links the 30 newest posts at most, grouped into 12 months at most; a month has no page of
  its own. A shared section with **Latest entries** shows the newest published entries in the
  page's language, as it does on a page: a managed site reads them on each request (at most 8
  different lists per language; a later one shows its refusal), and a generated site pins them when
  it is generated. A Website rejects Blog items with a specific error
  (`region_item_unavailable`). A region holds up to 8 items and shows each one once: one
  **Search**, one of each Blog list, and a given menu or shared section once
  (`duplicate_region_item`). Move items up or down, or remove them. A region with no items shows
  nothing. A language without its own list shows the one its language rule serves (**Same as
  \<language\>.**); its first change starts its own list, and **Use language rule** drops it
  again. A managed site that has accepted no template has no regions yet. A list for a region the
  template no longer has is marked **Not in this template**; **Remove** drops it
- **Route names**: a name and a path for each route
- **Default SEO**: **Title template**, **Site description** and **Default social image** (chosen from
  the media library; used when a page sets no image of its own)
- **Who runs this site**: an organization or a person, a **Name**, a **Logo** (a **Photo** for a
  person) and up to 8 https **Profile links**. Search engines can show them with the site; they go
  into each page's structured data (see [Search and sharing](#search-and-sharing))
- **Search engine verification**: the code Google Search Console, Bing Webmaster Tools, Yandex
  Webmaster or Pinterest gives you. Paste the code or the whole meta tag; only the code is kept
- **Sitemap and robots**: **Publish a sitemap** (every live page that is not hidden from search
  engines), **Change frequency** and **Paths to disallow**
- **Redirects**: an **Address** on this site and **What happens** there (see
  [Redirects](#redirects))

**Language** switches the language whose menu items, placements and footer note you edit. A
language with no version of a menu yet says so and shows what visitors see there now. **Copy**
starts it from another language's items (they get new identities); **Start blank** starts it
empty. **Delete \<language\> version** removes that language's items after you confirm; other
languages keep theirs. A language without its own placements uses the ones its fallback gives it
and says **Same as \<language\>**; changing one gives it its own.

A language with no version of a menu, no menu placements or no footer note follows the site's language
rule (**Settings** → **Languages**): with fallback, it shows the first language along its fallback
chain that has one; with strict, it shows nothing. The site marks a menu or note shown in another
language with that language. **Also shown in** names the languages that see a version through
fallback.

A menu item names the page, post or archive it goes to, not its address. The reading language's
live address is used when the site is read, so a moved page keeps its menu link. An item whose page
is not live yet is hidden on the site and says **Not live yet — hidden** here; **Hidden in** names
the languages it is missing from. Every item needs a label.

A generated site gets its menus when it is generated. A managed site reads them on every page, so
saving and accepting a menu change, or publishing a page, needs no new release.

Regions work the same way. A generated site's layout places `page_start` and `page_end`. What they
show is resolved at generation and pinned in `apps/site/src/lib/chrome.json`; published changes
reach the site with the next generation. A Latest entries section there reads public models only; a
private model shows `collection_model_missing`. Its summaries embed content only from origins accepted at generation. A managed site reads them on every page.

![Settings, Generation, Site context: Menus & SEO](/assets/screenshots/generation-context.webp)

**Save a new version** keeps a version, with an optional note in **What changed (optional)**. It
does not change what pages are generated from. **Use this version** in **Version history** accepts
a version: later generations use it, and pages that already exist keep the version they were
written from. If someone else saved first, nothing is saved and **Reload** shows their version.
Editing these documents needs the site settings permission. Without it they are read only, or not
shown at all.

## Search and sharing

**Search and sharing** sits under the page address in **Page settings** (the page menu) in the page
editor, and under the fields in the content editor. It is closed until you open it. It sets, for the language you are editing:

- **Search title**: replaces the title template for this page. About 60 characters show in results.
- **Search description**: about 160 characters show in results. Without it, a `description` field
  is used, then the Site Chrome **Site description**.
- **Social image** and **Image description**: shown when the page is shared. Without it, the Site
  Chrome **Default social image** is used.
- **Canonical address**: an `https` address or a path on this site, only when another address serves the main copy of this page.
- **Hide from search engines**: the page asks not to be indexed, leaves the sitemap and is not listed
  as another language of its translations.
- **Page type**: **Ordinary page**, **About page**, **Contact page** or **Article**. Search engines
  read it from the page's structured data.

Nothing here is filled in from the page's text or images. **Save search settings** saves a version
like any other save. The live page changes only when that version is published. Save or discard
other changes on the screen first. The management API takes the same `seo` key on an entry save and
on a page save. A site copy and a history transfer carry the overrides of every version (bundle
1.7), with the social image moved to the copy's media. Delivering a standalone backend moves social images, the default one
included, to the adopter's media storage with the rest of the site's images.

Both renderers write the same head from these values: the meta tags, each verification code as its
engine's meta tag, and one `application/ld+json` block. A home page carries `WebSite` and the
organization or person; a Blog post is a `BlogPosting` with its date, cover and authors; any other
page is its **Page type**. A page hidden from search engines carries no structured data. Nothing is
stored as JSON-LD or script: the renderers build it from the values above.

**Sitemap.** `/sitemap.xml` is an index. Each model's live pages are listed in chunks of 5,000 at
`/sitemap-<model>-<number>.xml`, each page with its last publication and up to 20 images (its social
image, then the images it shows). Hidden pages are left out. On a generated site, page chunks are
written at generation and a Blog's posts are read live. `/robots.txt` names the index when indexing
is allowed and the site has an origin.

When a publication moves a live address, for example after the slug changes, publishing adds a
permanent redirect from the old address to the new one in Site Chrome and accepts it. The workflow
panel says "Redirect created" with both addresses and a link to **Menus & SEO → Redirects**. A
redirect that already pointed at the old address is pointed at the new one, so no visitor follows
two hops. When an entry moves back to an address its own redirect held, that redirect is removed. No
redirect is made, and the panel says why, when the old address is now used by another page or route,
when the redirects would loop, or when Site Chrome already holds 256 address redirects. The
publication itself still succeeds. Unaccepted Site Chrome changes are kept and get the same redirect.
A draft address change never moves the live page or makes a redirect.

Publishing at an address another redirect holds is refused: a live page would silently disable that redirect. The workflow panel names the address and offers **Remove redirect**, then publish
again. When Site Chrome has unaccepted changes, remove it in **Menus & SEO → Redirects** instead.

## Redirects

**Menus & SEO → Redirects** lists each **Address** on this site and **What happens** there:

| What happens                      | Status | Send to                                      |
| --------------------------------- | ------ | -------------------------------------------- |
| Moved permanently                 | 301    | a path on this site or an `https` address    |
| Moved for now                     | 302    | the same                                     |
| Moved for now, keep form data     | 307    | the same                                     |
| Moved permanently, keep form data | 308    | the same                                     |
| Removed                           | 410    | none: the site's error page answers with 410 |
| Unavailable for legal reasons     | 451    | none: the site's error page answers with 451 |

**Advanced: patterns** holds rules for many addresses at once. `{name}` matches one part of an
address and a final `{name*}` matches everything after it; **Send to** may reuse the names, but
never in the host. Examples: `/news/{slug}` to `/blog/{slug}`, and `/{rest*}` to
`https://old.example.com/{rest}` for everything the site does not serve.

Rules are applied in this order: a live page always wins, then an exact address, then the pattern with the most
fixed parts, a one-part pattern before a catch-all. A site holds up to 256 addresses and 32
patterns. Saving refuses, by name:

- a redirect from an address a live page uses, or one the site serves itself (`/sitemap.xml` and its
  chunks, `/robots.txt`, search, the feed, `/preview`, `/owned/…`, the Blog list and archives);
- redirects that can lead back to where they started, through any mix of addresses and patterns
  (for example `/{rest*}` to `/archive/{rest}`). A second hop that ends is allowed: `/news/{slug}` to
  `/blog/{slug}` beside a catch-all to another domain works, one redirect at a time;
- two patterns that can match one address when neither is more specific.

**Check covered pages** lists the live pages each pattern covers. They keep working; the pattern
answers there only when no live page occupies that address. Saving a new or changed pattern needs that check: when
the check is out of date, saving stops, shows the covered pages, and **Save with these patterns**
saves.

A generated site pins the accepted rules in its artifact (`src/lib/redirects.json`) and answers
them from its on-demand 404 route. A managed site reads `GET /v1/_redirects` and keeps the answer
for 30 seconds. Both run the same matcher, so a rule answers the same way in either.

## Languages and permissions

Each language owns its page: its sections, their order, type, look, style and words. Adding,
removing, moving, changing the type of or restyling a section, and every save, change only the language you are
editing. Two languages of one page may look completely different.

A language with no page yet shows **\<Language\> has no page yet** with two choices:

- **Copy** starts it from the language chosen beside it: the same sections, order, look and words,
  under new section identities. A shared section stays a link to the same shared section. Then
  edit the copy; the source language does not change.
- **Start blank** starts it with no sections.

Either choice saves one version holding that language only. Nothing is copied until you choose.

In history, a version with several languages offers **Restore \<language\> only**: that language
gets its sections and page name back from the version, and every other language stays as it is now.
**Restore** still brings back every language of the version. Neither changes what is live.

A refused save changes nothing: no language, fact, page name or version.

People who may only read a page can open it and its history but get no editing controls. Page
settings, AI writing, facts, publishing and renderer settings keep their own permission checks.

See [Models and fields](/reference/models-and-fields/) for the page model, [Preview and the generated client](/guides/preview-and-client/)
for renderer verification, and the [page-document contract](/reference/page-contract/) for the stored shape.

## Next step

Next, read [Blog sites](/guides/blog/) if your site is a Blog. Otherwise go on to [models and fields](/reference/models-and-fields/).

<!-- dee-wan-docs page: /guides/blog/ -->

# Blog sites

Source: https://dee-wan-docs.pages.dev/guides/blog/

A site is created as a **Website** or a **Blog**. The choice is made once, when the site is created,
and cannot be changed later.

- **Website**: pages first. Add your own content models in Content Builder when you need them.
- **Blog**: posts first. Dee Wan adds one small Post model and shows Posts in the main navigation.

Sites created before this choice existed are Websites.

## What a Blog adds

After the site record is created, Dee Wan runs Blog setup. Setup adds one ordinary content model:

| Field              | Type       | Required | Language                  |
| ------------------ | ---------- | -------- | ------------------------- |
| `title`            | text       | yes      | per language              |
| `cover`            | media      | no       | per language              |
| `body`             | rich text  | yes      | per language              |
| `publication_date` | date       | no       | shared by all languages   |

The model is `Post` (slug `post`), localized, with `title` as its display field. Setup adds no
components, categories, keywords or other models. Categories, tags and credited authors are an
optional add-on: see [Categories, tags and authors](#categories-tags-and-authors).

A post's **address** is the ordinary content address (its slug). `publication_date` is a date you
show to readers. It does not publish anything.

## Publishing posts

Posts use the ordinary content lifecycle: the same editor, validation, versions, workflow, review,
publish, unpublish, history and permissions as every other model. A post is public only when it is
published. Drafts never appear on the public Blog or in Latest posts.

Publishing a post does not rebuild the site. Blog pages read published posts when they are
requested.

## Navigation

On a Blog site the sidebar is:

- **Main**: Dashboard, Posts, Pages, and Planner for people who may use AI writing (`ai:generate`).
- **Advanced**: Content, and Content Builder for people who can read models.
- **Configuration**: Settings, and Installation for superadmins.

An item your role cannot use is not shown, and a group with nothing in it is left out.

Website navigation is unchanged.

**Posts** is a view of the `post` model in the ordinary content list: search, workflow filters, cover,
title, address, publication date, status and the usual row actions. Creating or opening a post uses
the ordinary content editor; its breadcrumb and Cancel return to Posts.

**Content** and **Content Builder** still show every model, including `post`.

## Public Blog pages

| Address                 | Shows                                                    |
| ----------------------- | -------------------------------------------------------- |
| `/blog`                 | Published posts, 12 per page                             |
| `/blog?page=2`          | The next 12, and so on                                   |
| `/blog/<post-slug>`     | One published post: title, cover, publication date, body |
| `/blog/category/<slug>` | Published posts in one category, 12 per page             |
| `/blog/tag/<slug>`      | Published posts with one tag, 12 per page                |
| `/blog/author/<slug>`   | Published posts credited to one person, 12 per page      |

Outside the default language, the same addresses start with the language code, for example
`/th/blog`, following the site's existing locale routing and fallback policy. A post answers at
its own slug in each language: `/th/blog/<thai-post-slug>`.

- Posts are listed newest `publication_date` first. Posts without a date come last.
- `page` must be a positive whole number. A page past the end answers 404.
- A Blog with no published posts shows an empty Blog page, not a 404.
- A missing, draft, unpublished or unavailable-language post answers 404.

A page, Site Chrome route or redirect may not use `/blog` or anything under it on a Blog site. Such a
conflict blocks rendering with `blog_route_conflict` until you change one of the addresses. One
exception: a redirect may start at a post's own address (`/blog/<post-slug>`) that no live post
uses, so a post published under a new address keeps its old link working. A post's **Search and
sharing** settings apply to its page.

### RSS feeds

Each Blog language has an RSS 2.0 feed of its 20 newest published posts:

| Address           | Feed                                  |
| ----------------- | ------------------------------------- |
| `/rss.xml`        | Posts in the site's default language  |
| `/<code>/rss.xml` | Posts in another language, `/th/rss.xml` |

Each item has the post's title, its full address, a summary, its credited authors and its
publication date. The summary is the post's search description, or the start of its text. A post
leaves the feed as soon as it is unpublished or moved to Trash, without a rebuild. Every Blog page
names its feed in its head, so a feed reader finds it from the page address. A language without its
own Blog address has no feed of its own.

## Comments

Visitors can comment on published posts. Comments are off until you turn them on in **Posts →
Comments** with **Accept new comments**. That switch is the post model's **Visitor comments**
setting, the same one any model has; see [Visitor comments](/reference/models-and-fields/#visitor-comments).
Off hides every comment and refuses new ones; nothing is deleted.

New comments wait for moderation. Nothing is shown until you approve it. Each comment is **Waiting**, **Approved**,
**Spam** or **Refused**. Approve, Refuse or Mark as spam one comment, or up to 25 selected at once.
**Delete permanently** removes a comment and its replies.

| Action                    | Permission                                   |
| ------------------------- | -------------------------------------------- |
| Read and moderate         | `content:publish`                            |
| Delete permanently        | `content:publish` and delete on `post`       |
| Turn comments on or off   | `site:settings` in **Posts → Comments**, or `model:apply` for the model's **Visitor comments** switch in Content Builder |
| Mark Helpful as yourself  | read on `post`                               |

Every action sends the state you saw. A comment someone else moved meanwhile is left as it is, and
the list is read again. Moderation never sends notifications.

- A comment belongs to its post and one language, not to the address. Renaming a post keeps its
  comments. Each language has its own thread.
- One reply level. A reply answers an approved top-level comment of the same post and language.
- Visitors and team members can mark an approved comment **Helpful**, once each. The count shows on
  the comment, and **Most helpful** orders comments by it. Who reacted is never shown.
- Unpublishing a post or moving it to Trash hides its comments. Publishing it again shows them.
- **Delete permanently** in Trash also deletes the post's comments, and so does the automatic
  deletion after the Trash retention. The confirmation states how many comments will be deleted.
- A comment stores the display name, an optional website, an optional email, the text, the
  consent, the time and the state. The email is private: no public read, page or cache carries it.
  Dee Wan never emails a visitor. A comment without an email shows **Not provided** in its details.
- The form asks for a name, the comment and consent. Website and email are optional and are checked
  only when filled in. The consent covers only what the visitor enters.
- A comment imported without consent, such as one from a WordPress export, shows **No consent**.
  Its source never recorded that the person accepted this site's comment form, and nothing in
  Dee Wan changes that. It arrives pending and visitors do not see it. **Publish imported comment…**
  shows it to visitors after you confirm the dialog. That is your decision to republish it; it does
  not record consent, and the comment keeps **No consent**. Settings → History records who
  published it and when, never the text. Approving a selection skips these comments and says how
  many need review one by one. **Refuse**, **Mark as spam** and **Delete permanently** stay
  available. Moving a published imported comment out of Approved hides it again; showing it again
  needs **Publish imported comment…** once more.

| Limit                          | Value                                    |
| ------------------------------ | ---------------------------------------- |
| Name                           | 80 characters                            |
| Website                        | 200 characters, `https://` or `http://`  |
| Email                          | 254 characters, optional                 |
| Comment                        | 4,000 characters                         |
| Comments per client and site   | 10 every 10 minutes, apart from forms    |
| Reactions per client and site  | 60 every 10 minutes, apart from comments |
| Replies shown under one thread | 20                                       |
| Count shown                    | up to 999, then `999+`                   |

Each form carries a key. Sending the same comment again with its key answers with the first receipt;
the same key with different text is refused. A hidden field catches simple bots. The limit counts a
keyed hash of the visitor's address, never the address, and the count is erased after a day.

### Comments on the public Blog

A post page shows approved comments, 20 threads a page (`?comments_page=2`), and the form. Visitors
sort them **Oldest** (the default), **Newest** or **Most helpful** (`?comments_order=`), and each
comment has a **Helpful** button. The form works without JavaScript: it posts to
`/v1/interactions/comment.submit` on the site's own host and returns to the post with the outcome;
**Helpful** posts to `/v1/interactions/comment.react` the same way. A generated site also sends it in place and shows
busy, error, repeat, limit and success states without leaving the page. A preview never takes a
comment. The intake route `<host>/v1/interactions/*` must reach the intake Worker, as for website
forms. Renderers read comments from `GET /v1/_comments`; see [the public API](/reference/public-api/).

### Comments in copies and backups

A site copy and a site history transfer carry the comments of every exported post in
`comments.jsonl`, with their state, private email (or `null` when none was given) and reaction
counts. Who reacted does not travel. Importing
recreates them on the posts that import created, replies under their own thread. Importing the same
copy again never duplicates them, and undoing the import removes them. A comment without consent
always arrives pending, even one published on the source site: publish it again on this site if
you want it shown. Spreadsheet exports do not include comments. A WordPress
import brings reader comments in held for moderation and without consent; see
[Import from WordPress](/guides/import-migration/#import-from-wordpress). Strapi imports never create
comments. A database backup includes them like all site data.

## Categories, tags and authors

An optional add-on for a ready Blog. Open **Posts**, press **⋯**, then **Add categories, tags and
authors**, then **Add**. You need the right to change models (`model:apply`). The menu item is shown while the
`post` model lacks any of the three fields below.

It adds ordinary models and fields, nothing else:

| Model      | Slug       | Fields                                                                                                 |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `Category` | `category` | `name` (text, required, per language), `parent` (one other category, optional)                         |
| `Tag`      | `tag`      | `name` (text, required, per language)                                                                  |
| `Person`   | `person`   | `name` (text, required, per language), `bio` (short text, per language), `photo` (media, per language) |

and three many-to-many relation fields on `post`: `categories` → `category`, `tags` → `tag` and
`authors` → `person`. The three models are public and show `name`. All three are translated: each
language has its own name and address. A person's bio and photo also belong to each language.
`parent` and a post's `authors` list are shared by every language.

- After setup, you manage their structure in **Content Builder**, like any other model.
- **The post editor** assigns them, with the ordinary relation fields. Authors are shown in the
  order they were added to the post; to change it, remove an author and add them again.
- **A person is a credited name**, not an account. It is never linked to a user, to who created or
  owns a post, or to who a workflow step is assigned to.

Adding it is safe to repeat. Everything already in place and identical is kept. If a `category`,
`tag` or `person` model already exists and differs, or `post` already has a `categories`, `tags` or
`authors` field that differs, nothing is added and the panel lists each one. A `category`, `tag` or
`person` model that is not translated is listed as having different language settings. Rename or
remove it in Content Builder, then press **Try again**. All models and fields are added together or
not at all.

### Parent categories

`parent` is a hierarchical link. A save that makes a category its own parent, or puts it under one
of its own subcategories, is refused and the message is shown on the **Parent category** field. A
restored version is held to the same rule. In Content Builder this is the **Hierarchy
(parent/child)** switch, offered on any to-one relation to its own model; see
[Models and fields](/reference/models-and-fields/). A generated standalone API keeps `parent` and refuses the
same loops inside its database write.

### Categories and tags on many posts

On **Posts**, select posts, press **Categories and tags**, choose **Categories** or **Tags**, then
**Add** or **Remove**, pick up to 10 items and apply. Each post saves a new draft version with its
own permissions and version check. Nothing is published. A post that already has the change is left
as it is. A post that changed meanwhile, that you may not change, or whose own fields need fixing is
listed as not changed, with the reason. Authors are not offered here.

### Deleting a category, tag or person

The ordinary content rules apply. A published item must be unpublished before it can go to the
Trash, and unpublishing lists the posts that link to it. In the Trash it keeps its links and
**Restore** brings it back. **Delete permanently** removes the item and its links from posts and
keeps the posts.

### On the public Blog

A post page shows **By** and its authors under the title, and its categories and tags after the
body. Each name links to its archive: `/blog/category/<slug>`, `/blog/tag/<slug>` or
`/blog/author/<slug>`, with the language prefix outside the default language.

- A post uses the current published names and addresses of its categories, tags and authors.
  Publish a correction to that related item; the post itself does not need another save or publication.
  Draft edits stay private. Withdrawn, trashed, deleted or private related items are not shown.
- Existing public caches follow the normal invalidation and cache lifetime rules. The post body and
  its saved revisions remain unchanged.
- In each language a category, tag or author shows its own name and links to its own address.
  Under a strict language policy one without that language is not shown on the post. Under fallback
  it shows in the language the site falls back to. An archive lists the posts that show that address
  in its language. The feed credits authors the same way.
- An archive lists published posts linked directly to that item, newest `publication_date` first,
  12 per page. Posts in a subcategory are not included. An archive with no published post answers 404.
- A Blog without the add-on answers 404 on these addresses.

If `post` has a field named `categories`, `tags` or `authors` that is not a relation to `category`,
`tag` or `person`, the Blog is not renderer-ready (`blog_contract_drift`) until it is changed back.

## Rich text safety

The post `body` is one rich document, stored as canonical HTML. Every save checks it: markup
outside the document is refused by name (field, language, element or attribute) and nothing is
written. Dee Wan's previews and renderers never insert the stored value without processing it: both renderers render it
with the page contract's `renderRichDocument`.

The document holds paragraphs, headings, lists, quotes, code blocks, rules, bold, italic,
underline, strike, inline code, sub- and superscript, links and images, plus:

- tables, up to 12 columns and 200 rows, with an optional caption, header row and row headers. A
  wide table scrolls inside its own box on a phone;
- image galleries of 2 to 24 library images, each with an optional caption;
- audio, video and file blocks naming one library file of that kind. Audio and video play in the
  page with a download link under the player; a file is a link with its name, type and size;
- embeds, made by pasting one https link: YouTube and Vimeo are built in, and an administrator can
  allow other origins (see below). A block stores the provider id, the canonical https address and
  a title. It never stores markup, script or CSS.
- plugin blocks, declared by an installed plugin (see below). A block stores its type, the version
  it was saved with and its field values. It never stores markup, script or CSS.

Links may be relative, `http`, `https`, `mailto` or `tel`. Images may be relative, `http` or
`https`. External links get `rel="noopener noreferrer"`.

The public API serves the validated HTML. Media and embed blocks are data, not players. If you build
your own renderer, draw them with `renderRichDocument` or your own renderer of the same document.

### Plugin blocks

An active plugin can declare rich text block types in its manifest (`rich_blocks`, see
[plugins/authoring.md](/plugins/authoring/#rich-text-blocks)). The editor lists them under **Blocks**,
draws their fields with its own controls and previews each block from the plugin's declared render
tree. Nothing from the plugin runs in the editor or on the site.

- Stored form: `<figure data-block="plugin" data-type="<plugin id>/<name>" data-version="2"
  data-values="{...}">`, with one empty `<a data-field data-media-id href>` per media field. The
  values are strings, numbers and booleans as sorted JSON. Media fields are pinned, copied and
  remapped like any library media.
- A save that adds or changes a block is checked against the site's active plugins: an unknown type
  is refused with `rich_block_unregistered`, a version newer than declared with
  `rich_block_version_unknown`, and values the declared fields refuse with
  `rich_block_values_invalid` (each names the field and language). A block saved under an older
  declared version is accepted when its migrated values pass, and is stored as sent.
- A block already in the same field and language keeps saving when its plugin is disabled or
  removed. The editor shows it as kept and not shown on the site. Imports and site copies carry
  blocks with their versions, whatever is installed on the destination.
- Older blocks move to the current version only when an author asks: opening a block's form or
  **Update** on the block, or **Blocks → Update blocks ({count})**. Published content is never rewritten in
  bulk.
- Renderers read the definitions from `GET /v1/_rich-blocks` only for a page that holds a plugin
  block, and draw each block with the host adapter: a fixed element list, every value escaped, every
  address checked. When no adapter draws a block (plugin not active, no render tree, or a version
  newer than the definition), a public page shows nothing for it and a preview shows a placeholder
  naming it.
- Search text, search excerpts and feed summaries include a block's text and textarea values and
  the labels of its select values, read through the active plugin's definition at save time. A
  block with no active definition adds no words. Private fields add none either way.
- Snippets follow the same save rules: a snippet that adds or changes a plugin block is checked
  against the active plugins; an unchanged block is kept.
- The editor lists, under the field, every block the site will not show and why (plugin not
  installed, plugin turned off, newer version, no layout). Each entry selects its block.
- Managed and generated sites read the definitions live rather than from the generation payload:
  their blog posts and lists are read live too, so a pinned copy of the definitions would go stale
  as soon as a plugin is installed, upgraded or disabled. Region summaries pinned into a generated
  site at build time show nothing for a plugin block.

### Embed origins

**Settings → Integrations → Embeds** lists the built-in YouTube and Vimeo players and the origins
from which this site may embed content in frames. Only people with `site:infra` see this screen and change the list. The editor
reads the list for every member of the site, so anyone who may edit a post can paste an allowed
link.

- An origin is `https://` and one exact host, with an optional port. No path, query, fragment,
  password, wildcard, IP address or local name. A YouTube or Vimeo domain is refused: they are built
  in.
- A site holds at most 20 origins, each with a name of 1 to 60 characters.
- A YouTube watch, share, Shorts, live or player link becomes the privacy-enhanced
  `youtube-nocookie.com/embed/…` address. A Vimeo link becomes `player.vimeo.com/video/…?dnt=1`. A link
  on an allowed origin is framed as given. Anything else is refused by name: `embed_url_malformed`,
  `embed_url_not_https`, `embed_url_credentials`, `embed_url_ambiguous` (a provider link that names no
  single video) or `embed_provider_unknown`.
- The editor never loads the provider. It shows a placeholder, and **Preview** opens the address in a
  new tab.
- Both renderers draw the same frame: `sandbox="allow-scripts allow-same-origin allow-presentation
  allow-popups allow-popups-to-escape-sandbox"`, `allow="encrypted-media; picture-in-picture;
  fullscreen"`, `referrerpolicy="strict-origin-when-cross-origin"`, `loading="lazy"` and a 16:9 box.
  No entry changes it.
- Renderers read the allowed origins from `GET /v1/_embeds` only for a document that holds such an
  embed. A managed page's `frame-src` names the built-in players and those origins only.
- A save that adds or changes an embed from an origin not on the list is refused with
  `rich_embed_origin_not_allowed`, naming the field and language. This holds for the editor, the
  management API, plugins and spreadsheet import. An embed already in the same field and language
  keeps saving after its origin is removed, and restoring an older version is not refused: those
  embeds draw as plain links until the origin is added again. A site copy or Strapi import carries
  the embeds its source held, the same way. Nothing embeds content from an origin that is not on the list.
- Only this screen changes the list. The generic settings API refuses to create, change or delete
  the `embed_providers` row (`setting_server_owned`).

## When setup does not finish

The site is kept whatever happens during setup, and Posts shows what to do:

- **Blog setup did not finish** (for example a network failure): press **Try again**. Nothing was
  marked ready.
- **Blog setup is blocked by an existing “post” model**: the site already has a model with the slug
  `post` that does not match the starter. Dee Wan leaves it unchanged. Press **Open Content
  Builder**, rename or remove that model or make it match, then press **Try again**.

The state is stored with the site, so a reload shows the same screen. A Blog is not rendered publicly
until setup has finished.

## Latest posts

**Latest posts** is a section for any page. Add it from **Add section → Patterns → Latest posts**. It
lists the six newest published posts with their cover, title and publication date.

It is a preset of the **Latest entries** section, which can list any public collection. In the
inspector, choose:

- **Collection**: the model to list. It must be public.
- **Title field**, and optionally **Image field**, **Summary field** and **Date field**.
- **How many**: 1 to 12.
- **Text when nothing is published**: shown only when the collection has no published entries.

When a date field is chosen, entries are newest first by that date. Otherwise they are newest
published first.

The page stores only these choices, never the entries. If a chosen model or field no longer exists,
the inspector names it and the section shows an error instead of an empty list.

### Example: a project list on a Website

A Website with an ordinary public model `project` (fields `name` text, `photo` media, `intro` rich
text, `completed_on` date) can show its newest projects with:

| Choice        | Value          |
| ------------- | -------------- |
| Collection    | `project`      |
| Title field   | `name`         |
| Image field   | `photo`        |
| Summary field | `intro`        |
| Date field    | `completed_on` |
| How many      | 3              |

The projects are created, reviewed and published in Content like other content items. Nothing about the
`project` model changes.

## Generated source

Whole-site generation records Website or Blog, and a Blog's sorted language list, in the generation
source identity and the site manifest. Adding, removing or changing a Blog language changes the
public `/blog` routes, so the deployed source reports as out of date until it is regenerated.
Reordering the same languages changes nothing.

`npm run backend:generate -- --model post` is not a Blog export. Single-model generation emits that model's
API only: no site pages, no `/blog` routes and no Blog frontend. Generate the whole site instead.

The generated website reads published posts from `/v1` on the site's own host when a Blog page or a
page with Latest entries is requested. Latest entries in a shared section shown in a Site Chrome
region are read at generation and pinned in the site, so they never make a page render on each request. Its Worker needs the `global_fetch_strictly_public`
compatibility flag for that. New projects get it in `apps/site/wrangler.jsonc`. That file belongs to
you once it exists: Dee Wan never rewrites it. If your existing file lacks the flag, generation and
deployment refuse with `public_fetch_compatibility_flag_required` and name the flag to add. See
[Detach and verify your standalone site](/guides/detachment/#site-worker-compatibility-flag).

## Renderers

The built-in managed template and the generated website draw Latest entries and serve the RSS
feeds. A Blog site is not
renderer-ready while setup is unfinished, the `post` model is missing or changed in a way the Blog
cannot render (including a `categories`, `tags` or `authors` field that is not the add-on's relation),
or a Blog route collides.

## Next step

Define or extend your content types in [models and fields](/reference/models-and-fields/).

<!-- dee-wan-docs page: /guides/content-planner/ -->

# Content planner

Source: https://dee-wan-docs.pages.dev/guides/content-planner/

The planner finds topics, researches them, writes ordinary draft entries and lists the work in a queue. It never publishes. Open **Planner** in the sidebar. It needs the `ai:generate` permission on the site.

Everything a plan writes is a normal draft. It goes through the same editor, workflow, versions, history and audit record as a draft you write yourself.

## Plans

Leaving an edited plan asks whether to discard unsaved changes, including Back and Queue. Stay to keep editing, or leave to discard them. Switching plans ignores late responses for the previous selection.

A plan targets one content model and one or more of the site's languages. It holds:

- a goal, an audience and a list of exclusions;
- the field mapping;
- the sources;
- an optional list of topics;
- the number of items per run (1 to 10) and per day (1 to 50, never less than the per-run number);
- an optional cadence;
- the final action: **Save drafts** (default) or **Schedule passed drafts**.

The accepted Site Brief is always part of the context. Saving changes to a plan creates a new immutable version of that plan. A run keeps the version it started with, so later edits never change a run in progress. A site can have up to 20 active plans, up to 10 languages per plan, up to 30 topics and up to 10 sources per plan.

### Field mapping

A plan names which model field takes the headline, the body and, optionally, the summary, web address, search title, search description, a main image field and up to 5 relation fields (the plan form's **Where it saves** section).

- The starter blog model has a preset: its title is the **Headline** and its body is the **Body**. The preset is offered only while the model still has those fields.
- A custom model has no preset. You map each field once, in the plan. The planner never guesses a field.
- The headline must be a text field. The body must be a rich text or long text field. A field can be used once.
- A required model field that the mapping does not cover, and that has no default, makes the mapping invalid.
- The mapping is checked when you save the plan, before an automatic run starts, before every stage of a run and before every draft is saved. If someone changes the model so the mapping no longer fits, the run stops before more AI work, its running items wait in **Needs review** (`profile_invalid`), and a due run waits with the reason until you edit the plan.

With **Create an image with AI** ticked on the **Main image** field, the planner generates a picture (see Main image). A relation field offers only published entries of the model it points to, the 50 most recently changed.

## Sources

Turn on any of these source modes on a plan.

| Mode | What it reads |
| --- | --- |
| Topics | The topics you list. Each has a label, an optional angle and optional included and excluded terms. |
| Entries on this site | Entries you select. The current published text is used. |
| Web pages | Manual HTTPS addresses. |
| News feeds | RSS or Atom feeds. The 5 newest entries are used. Their own text is used when present, otherwise the linked page. |

There is no built-in search provider and no built-in list of topics, industries or countries.

### What a fetch can do

Page and feed fetches are limited:

- HTTPS only, without credentials or a fragment in the address;
- no private, local or reserved addresses, and no names without a dot;
- at most 3 redirects, and every redirect is checked again;
- at most 1 MiB per source and 10 seconds per fetch;
- page types `text/html`, `application/xhtml+xml` and `text/plain`; feed types `application/rss+xml`, `application/atom+xml`, `application/xml` and `text/xml`;
- at most 50 entries are read from a feed.

A refused source is marked `source_refused`. A source that does not answer is marked `source_unavailable`. Timeouts, 408, 429 and 5xx answers are retried. An address that fails the policy is refused when you save the plan.

The check inspects the address itself. It cannot determine which address a public hostname resolves to.

## Coverage

A plan may name a source model and a rule. Set them under **More options** at the end of the plan form: **Cover entries from** and **May propose updates to drafts it created**. The planner then proposes one new item per language for each published source entry that has no item yet. When the rule allows revisions, it proposes a revision when the source entry changed since the item was made, and only for the entry an earlier item of the same plan saved. It records the source entry and version that caused the proposal. A proposal for a new entry follows the same duplicate rule as a topic idea (see Duplicates): an exact match stops it by name, and a near match is re-angled at most twice before it waits in **Needs review** with the compared entries of each language. The languages of one proposal stay together. A proposal that cannot run is kept in **Needs review**, never dropped. The planner never makes an item for every row without the rule, never changes an entry silently, and never infers ownership.

Revisions need permission to update entries of the target model, not only to create them. The same is true of a plan with more than one language or a generated main image, because adding a language and attaching an image are updates.

## Topics and rotation

A topic has a name, an optional angle, optional included and excluded terms, and a switch, **Use this topic**. Runs use only the topics that are switched on. A topic that is off stays in the plan with its history and is never used. **Remove** takes a topic out for good: it is deleted, or, when items already name it, it is hidden from the plan and the rotation while those items keep showing its name. The plan screen shows, for each saved topic, when it was last tried and when it last made an item.

An automatic run writes only about the selected topics. For each topic the planner proposes one idea, written in every language of the plan.

- The topic tried least recently goes first, then the one that made an item least recently, then the order in the list. Every selected topic is tried once before any is tried again, across runs too.
- A topic with no useful idea records "no candidate" (`no_candidate`) and the run moves on to the next topic in the same step budget. The planner does not widen a topic or invent another one to reach the requested number.
- A topic that came up empty in a run, or whose idea was an exact duplicate, is skipped for the rest of that run. It goes to the back of the order for the next run.
- An idea that uses an excluded term, or none of the included terms when you set some, is not used.
- When no selected topic can give another idea, the run ends as partial with the reason "The selected topics had no more grounded, new ideas."

A topic counts as tried after every attempt to find an idea in it. It counts as having made an item when the attempt produced one, and again when that item becomes a draft or is scheduled.

## Duplicates

The planner compares a proposal, from a topic or from coverage, with its other items, with drafts and with published entries of the target model in the same language. It checks the 500 most recent items and the 500 most recent entries.

- An exact match of title or intent stops the idea. No item is made for a topic idea; a coverage proposal is kept in **Needs review** so the source entry is not lost.
- A near match (word overlap of 0.6 or more) is re-angled, at most twice. If it is still near, the item is made in **Needs review** with the compared entries shown.
- Checks run again before a draft is scheduled. An exact match with a published entry stops there.

The comparison is lexical. It works without any embedding model.

## Research, evidence and claims

Before writing, the planner reads the sources and extracts claims. It keeps a claim only when its excerpt is an exact quote of the source text, or an exact fact from the accepted Site Brief. Excerpts are at most 1,000 characters, and an item keeps at most 40.

- If no claim is supported, or claims conflict, the item goes to **Needs review** with named issues.
- A draft may leave a source claim out. It may not invent a fact.
- Required wording from the Site Brief must appear word for word.
- The item shows its sources, claims and issues next to the draft.

## Draft, checks and repair

One model call writes the mapped fields. The body uses the rich document format, never executable HTML. Internal links go only to current published pages of the site. External links go only to recorded evidence addresses or to the Site Brief's valid destinations.

Checks run on the server and do not depend on a model's opinion. Each issue has a code, a field and a plain sentence.

| Code | Meaning |
| --- | --- |
| `schema_invalid` | A value does not fit its field. |
| `required_missing` | A required field is empty. |
| `length_bounds` | A field is too long or too short. |
| `rich_invalid` | The body is not a valid rich document. |
| `required_wording_missing` | Required wording is absent. |
| `forbidden_claim` | The draft makes a claim the Site Brief forbids. |
| `claim_unsupported` | The draft relies on a claim without evidence. |
| `duplicate_intent` | The draft repeats existing content (a near match is a warning). |
| `link_not_allowed` | A link or picture is not allowed. |
| `source_rule` | The draft uses a term the plan excludes. |
| `relation_invalid` | A chosen related entry is not allowed. |

A body may not contain pictures or embeds; media comes only through the media library. A number in the draft that no supported claim or Site Brief fact states is `claim_unsupported`.

Errors start a repair. A repair rewrites only the failing fields or passages and runs at most twice. If errors remain, the item goes to **Needs review** with the best result so far kept. A score never publishes, schedules or hides a failed check.

## Saving

The draft is saved once through the normal content lifecycle, as the plan owner. The key comes from the plan version, the source and the language, so a replay returns the same entry instead of a second one. A revision pins the version it read. If the entry moved, the item stops as a conflict.

Before the save the planner rechecks the owner's permission, the field mapping and duplicates.

The languages of one idea are saved as translations of one entry. The first language creates the entry. Each later language is added to it through the lifecycle's add-language path, pinned to the entry's current version. Later languages write only translatable fields. Relation fields stay with the first language. If a language already exists on the entry, for example one a person added, the item stops as a conflict (`target_conflict`) and nothing is overwritten.

### Main image

When the mapping says **Create an image with AI**, the planner generates one image per idea after the first draft is saved. It spends site AI credit, stores the picture in the media library through the normal media upload path, and attaches it with a second save of the draft. It never replaces an image already in the field, and it does not attach the image if a person edited the draft meanwhile (the image stays in the library). A retry does not pay for a second image.

If the image fails, the item gets the warning `image_failed`, the draft is kept and the item still becomes ready.

A required main image field cannot use generation, because the image arrives after the first save. The plan refuses this setup.

## Final action: schedule

**Schedule passed drafts** is offered only when the Scheduling plugin is installed, active and granted for the target model. You choose the publish transition, a timezone and a delay from 5 minutes to 30 days after the draft is ready.

The planner saves the draft first. Then it asks Scheduling to schedule exactly the version it saved, as the plan owner, with the owner's live permissions. It uses Scheduling's `schedule-draft` operation, which only the planner calls: it is not an operation people or agents run from an entry, Settings, the management API, the CLI or MCP. Core keeps no copy of the schedule; the item keeps Scheduling's reference and the queue shows when it publishes. The planner never publishes. An existing active publication schedule on the entry is never replaced.

The due time is the moment the draft was ready plus the delay. If Scheduling is missing, refuses or fails, the draft stays as it is and the item goes to **Needs review** with **Retry scheduling**. Temporary Scheduling failures, such as a timeout or an unreachable service, are retried automatically first. **Retry scheduling** asks Scheduling again with a new request; when the planned time has already passed, the delay counts from the retry. If an answer was lost after Scheduling accepted it, the planner asks again with the same request and gets the same schedule back, so a draft is never scheduled twice.

If a person changed the draft after the planner saved it, nothing is scheduled. The planner checks before it asks, and Scheduling refuses (`draft_changed`) when the entry's current draft is not the saved version. The draft stays as the person left it and the item waits in **Needs review** with "The draft changed after it was saved. Schedule it from the entry." Open the draft and schedule it there. **Retry scheduling** schedules only while the current draft is still a version the planner saved.

## Runs

**Run now** starts a separate run at once. It does not move the automatic schedule. A plan has one live run at a time, and Run now is refused while one is working. An automatic run that falls due while a Run now run works waits; when that run ends, one automatic run starts.

Each run keeps the plan version, the accepted Site Brief version and the AI model it started with. A Site Brief accepted while a run works does not stop that run: it finishes with the version it started with, and the next run uses the new one. Work is stored before each model call, and the state survives restarts.

The plan screen shows the next run before you turn it on: when it would start, how many items it makes, what happens to a draft, and the topics in the order it will try them.

### The background step

Dee Wan uses the admin Worker's existing every-minute trigger. There is no separate cron per plan or topic. Each minute it:

- visits up to 8 sites, starting at a different site every minute so none is always last;
- on each site, finds up to 5 plans whose next run is due and starts their automatic runs, after the checks in AI credit;
- advances each active run by one stage under a 5-minute lease, at most 8 stages in total per minute;
- re-reads the owner's permission, the content model and the field mapping before each stage;
- picks up a stage whose worker stopped once its lease runs out, from the last saved checkpoint.

The plans list shows each plan as **Not scheduled**, **Active**, **Due now**, **Running** or **Paused**, with the reason a plan waits and the result of its last run.

### Automatic cadence

Enabling a cadence is one explicit action. Later runs need no new confirmation. Choose daily, weekly or monthly, a time and a timezone.

- Weekly runs on a weekday. Monthly runs on a day from 1 to 28.
- A time that does not exist on a day the plan fires is refused, so a daylight-saving gap never skips a run silently.
- A time that happens twice needs your choice: **The first time** or **The second time**.
- A missed run becomes one due run. The planner never makes up every missed occurrence.
- The next run is always the next occurrence after now.
- **Pause plan** stops new automatic runs and stops active runs of that plan from advancing. A stage already working when you pause finishes and is kept; nothing after it starts. Pause keeps the setup, history and drafts. **Resume plan** continues the paused run where it stopped and works out the next occurrence from now.

The person who enables a cadence becomes the owner of the plan. The plan displays its owner.

## AI credit

A run spends the site's hourly AI credit, 250 calls an hour unless the installation sets another limit. One model call spends one unit. A retry spends again.

One item uses up to 8 calls: one to find the idea (up to 2 more when re-angling), then research, outline and draft, and up to 2 repairs. The planner reads the remaining credit without spending it.

Before an automatic run starts, the planner checks, in this order: no other run of the plan is working, the content model and field mapping still fit, the owner's permission, the daily item limit, the site's active-run limit (2), a provider wait, and at least 8 units of credit left. If any check fails, no run or item is created, and the plan shows a plain reason. When the owner lacks permission, the plan waits for its next occurrence. For the other checks, the planner tries again the next minute. **Run now** applies the same checks and answers with the reason.

You see the per-run and per-day limits and the credit before you turn a cadence on.

## Retries, cancel and recovery

- A temporary provider or fetch failure is retried at the same stage up to 3 times, with increasing delays. A rate-limit answer also holds back the site's runs.
- A stage that crashed is picked up again after 5 minutes.
- Invalid output, failed checks, exhausted repair attempts, a conflict, lost permission or a refused source stop that item with a specific reason. The run goes on with the others and ends as partial.
- **Retry** continues from the last saved stage in the same run and topic. If the run had finished, it is reopened, never replaced. It is refused while another run of the plan is live.
- A retried save returns the entry saved before, and a retried hand-off returns the schedule made before, so retries never make a second draft or schedule.
- **Cancel** stops an item. Work in flight is thrown away. A draft already saved is kept and stays linked. A scheduled item cannot be cancelled here, because only Scheduling can withdraw its schedule.

## Permission loss

The plan owner is checked again at every stage, before every write and every outside call: the account exists, belongs to the site and is allowed `ai:generate`, and can create entries of the target model (and update them when the plan revises, has more than one language or creates images).

If the owner loses any of this during a run, running items become **Blocked** with the reason and the run stops. If it is lost before a due run, no run starts, the plan shows the reason and moves to its next occurrence. The cadence stays on in both cases. Once the owner's permission is back, the next due run starts by itself; nobody has to turn the cadence on again. Drafts and evidence stay. **Pause plan** is the way to stop automatic runs. There is no hidden automation account.

When you act on an item yourself, you act as yourself, and the owner does not change.

## Queue

The Queue groups items by what you need to do.

| Group | States |
| --- | --- |
| Needs you | Proposed, Needs review, Blocked |
| In progress | Approved, Running |
| Ready | Draft ready, Scheduled |
| Done | Done, Cancelled |

An item becomes Done when its own language is live. The queue and the background step both notice this.

Each row shows the title, state, stage (for example **Writing**, **Checking**, **Saving draft**, **Scheduling**), the content type it saves to, the language, the plan, the topic, whether the run was **Automatic** or **Manual**, when Scheduling publishes it, the reason it stopped, the next step, and a link to the draft once one is saved.

An item shows its stage, target, language, sources, compared duplicates, issues, attempts, and its draft or schedule. Actions:

- **Approve** a proposed item.
- **Edit** the title, angle, intent or keyword of a proposed or review item.
- **Run** a proposed or approved item. It joins the plan's active run, or gets a run of its own with no discovery.
- **Retry** a review or blocked item. After a failed hand-off it reads **Retry scheduling**.
- **Cancel item** an item that is not scheduled or finished.
- **Open draft** for the saved entry.
- **Pause plan** and **Resume plan** on the plan, and **Turn on automatic runs** to enable the cadence.

**Generate ideas** asks for 5 to 7 ideas at once, one per language, as proposed items. It writes no draft. Repeating the same request returns the same items.

## What is kept

The planner keeps plans and their versions, topics, sources, runs, items, the claims, evidence excerpts, issues, comparisons and attempts of each item (the last 20 attempts), and a stage checkpoint of at most 64 KiB. Planner records belong to one site.

It does not keep the full text of fetched pages or the prompts it sent.

Planner records are editorial records of the site, not telemetry. Settings → History lists each planner save as "Draft saved by the Planner". Site copy and site history transfer do not carry them.

<!-- dee-wan-docs page: /guides/website-forms/ -->

# Website forms

Source: https://dee-wan-docs.pages.dev/guides/website-forms/

A **Form** section on a page collects what visitors type. This guide covers where those submissions
go: turning intake on, adding destinations, reading delivery outcomes, erasing values and receiving
the signed `form.submitted` webhook. To add the form itself to a page, see
[Add a section](/guides/page-builder/#add-a-section).

## Before you start

- You need the `site:infra` permission. The built-in `admin` role has it, and so does a superadmin.
  Without it, the Integrations section is not shown.
- The form intake Worker must be deployed, with a route for `<host>/v1/interactions/*` on the site's
  host. Without it, forms take no submissions. See [Deploy changes](/guides/installation/#deploy-changes).
- Email destinations need mail set up for the installation (`RESEND_API_KEY` and `MAIL_FROM`, or your own
  [mail transport](/guides/people-and-access/#mail-transport)). See
  [Add secrets for optional features](/guides/installation/#add-secrets-for-optional-features).

## Turn on submissions

1. Open **Settings → Integrations**. The **Website forms** card is below the outbound webhooks.
2. Switch on **Take submissions**. The label changes to **Forms take submissions**.
3. Set **Keep what visitors send for (days)**: 1 to 365. The default is 30.
4. Add destinations if you want site-wide operator delivery, then press **Save form settings**.
   Destinations are optional when you only want to store submissions.

While the switch is off, every form on the site answers that it is not taking submissions, and
nothing is stored. Switching it off later does not cancel deliveries already queued.

Each site has its own settings. Forms on one site never send to another site's destinations.

## Add destinations

A site sends each submission to at most 5 operator destinations. A form can override these defaults
and send a separate acknowledgement email. Visitors never choose an operator destination, and
nothing on the page names one.

- **Add email** adds an **Email address**. Enter one address.
- **Add webhook** adds a **Webhook URL** and a **Signing secret**. The URL must start with
  `https://` and must not contain a username or password. The secret needs at least 16 characters
  (at most 256).

Each destination has its own **Send to this destination** switch: **On** or **Paused**. A paused
destination gets no new submissions, and deliveries already queued for it end as **Not delivered**.
**Remove** asks first. Submissions already stored are kept, and their queued deliveries to that
destination end as **Not delivered**.

The secret is write-only. After saving, the field says **A secret is stored. Type a new one to
rotate it.** Leave it empty to keep the stored secret. Each accepted submission keeps its destination
URL, recipient and signing secret. Changes apply only to new submissions; retries keep the accepted
settings. Keep the old secret available at your receiver while older deliveries remain queued.

With no site-wide destination, the card says **No default destination.** Submissions are still
stored and listed. Form-specific destinations and acknowledgement emails can still deliver.

If mail is not set up, the card shows **Email is not set up for this installation**. Email deliveries
then fail and are retried, like any unreachable destination, and end as **Not delivered**. After mail
is set up, use **Send again** on each one.

## Recent submissions

If recent submissions cannot be loaded, choose **Try again** in that section. This reloads the history only and keeps unsaved form settings. “No submissions yet” appears only after a successful read finds none.

The **Recent submissions** card lists the 50 newest receipts. The list itself does not show what a
visitor typed; open a receipt to read retained values.
Each receipt shows:

- the receipt id and when it arrived
- the page id, the language and when its values are erased (or **Values erased**)
- one line per delivery, with its channel, accepted recipient or webhook address, state and a short
  detail such as `HTTP 503`

Recipient addresses appear only while the submission values are retained. After expiry or erasure,
the delivery line keeps its channel and state but withholds the target. Webhook addresses show only
the origin and path, never query parameters or signing secrets. Legacy receipts without an accepted
target snapshot show only the channel.

| State               | Meaning                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Waiting to send** | Queued. The next delivery run sends it.                                                                                         |
| **Will try again**  | The last attempt failed for a potentially temporary reason. Another attempt is scheduled.                                       |
| **Delivered**       | Email: the mail provider accepted it. Webhook: the receiver answered 2xx.                                                       |
| **Not delivered**   | Stopped. The receiver refused it, every attempt failed, the destination was removed or paused, or the values were erased first. |

Deliveries run once a minute, at most 10 per site per run. A run claims each delivery just before
it sends that one, and only one run can win a claim. A claim lasts 5 minutes from that moment. Each
send gives up after 10 seconds, for email and for webhooks, and then counts as a failed attempt that
is retried.

A run slowed down on one delivery never sends a later delivery that another run claimed or finished
meanwhile. Before authorizing each send, it checks that the values have not expired or been erased.
If a send is still unfinished when its claim ends, a later run can claim and send that delivery again; the late answer of the first run is
ignored. A delivery can therefore be sent more than once: see [Deduplicate](#deduplicate).

### Send again

**Send again** appears on **Will try again** and **Not delivered** lines. It resets the attempt count
and queues the delivery now. The toast says **It will be sent again within a minute.** It reuses the
same delivery, so the receiver sees the same `receipt` and the same `X-Deewan-Delivery` value.

While a delivery run is sending that delivery, **Send again** is refused with
`409 delivery_in_progress` and the message _This delivery is being sent right now. Check it again in
a few minutes._ Nothing changes. Try again after the run finishes.

Sending again does not help when the values expired or were erased, or the destination was removed
or paused. The delivery ends as **Not delivered** again. Retrying keeps the accepted recipient, URL,
template and signing secret; it does not pick up later settings.

### Erase values

**Erase values** deletes what the visitor sent, now, after a confirmation. The receipt stays, so a
repeated send of the same submission is still recognised and nothing is stored twice. Deliveries not
yet sent end as **Not delivered**.

## File attachments

In the page editor, choose **File upload** as the field kind. Set **File types** to comma-separated
extensions or exact MIME types, for example `.pdf, .png` or `application/pdf`. Leave it empty to
allow the supported image and document formats. Wildcards such as `image/*` are not accepted.
Set **Maximum files** (1–5, default 1) and **Maximum size per file** (up to 5 MiB, default 5 MiB).
The whole submission may contain at most 5 files totalling 10 MiB. **Required** also applies to uploads.

Supported formats are PNG, JPEG, WebP, AVIF, GIF, PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, RTF, TXT and
CSV. The intake checks the actual file bytes, not just the filename or browser's reported type.
Empty files, unsupported files and files over a configured limit are refused with a field error.
The published form supports file selection and submission with or without JavaScript. Without
JavaScript, a validation refusal reloads the page; the browser clears the file selection, so choose
the files again before resending.

Open a retained receipt in **Recent submissions** to see each file's name, type and size, then choose
**Download**. Downloads need the same `site:infra` permission as the submission details and use the
currently selected site. Visitor uploads stay in private submission storage; they are not public
Media library assets and do not get public URLs. The installation needs its private storage bucket
configured to accept attachments. Bind the same private R2 bucket as `PRIVATE_MEDIA_BUCKET` on the
intake Worker and the CMS Worker that handles downloads and scheduled cleanup. Generated intake
configuration copies the existing private bucket binding.

Attachments have the submission's retention date. **Erase values** immediately removes their details
and download access; expired submissions also refuse downloads before background cleanup runs.
The retention job deletes their stored files and retries storage failures. The receipt stays.
Already downloaded files and files copied by a recipient cannot be recalled.

Default operator emails list filenames and sizes, not file bytes. Webhooks include an optional
`attachments` map from field name to arrays of `{ id, name, type, size }`; these are retained-file
references, not download URLs. Custom email template variables remain scalar field values.

## Retention

Each submission gets its erase date when it arrives: the arrival time plus the retention days set
then. Changing the retention later affects only new submissions. At expiry, values and attachment
downloads become inaccessible immediately, even before cleanup runs. The cleanup job runs once a
minute for active and inactive sites. It removes retained values and attachment files, retries storage
failures, and keeps the receipt. Disabling a site stops delivery, not retention cleanup.

## What visitors meet

The intake checks each submission against the page's published form, never a draft. A client may
send 10 submissions per site in 10 minutes. A repeated send of the same submission is answered as
already received without creating another receipt or delivery record. Use
**Preview** on a selected form in the page editor to see each visitor state; see
[Add a section](/guides/page-builder/#add-a-section).

## Email delivery

The default email has the subject `New form submission` and one body line per field, in the form's
order, as
`label: value`. A checkbox shows `Yes` or `No` and an empty answer shows `—`. A given consent adds
`Consent: given`. The last line names the receipt, the page, the language and the arrival time.

The mail provider has 10 seconds to accept an email. No answer, a network failure or a refusal is
retried like a webhook failure, up to 5 attempts. A mail the provider accepted but whose answer was
lost is sent again, so a mailbox can get the same submission twice. The default message includes
the receipt id in its last line. Use it to identify duplicate messages. Custom
templates contain the text you configured and do not automatically append receipt details.

## Webhook contract

These destinations are separate from outbound webhooks. They are set only in **Website forms**, and
they send only `form.submitted`. The outbound webhook contract in
[Outbound webhooks](/reference/outbound-webhooks/) does not apply to them.

### Request

Dee Wan sends `POST` to the destination URL:

| Header               | Value                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Content-Type`       | `application/json`                                                                                               |
| `X-Deewan-Event`     | `form.submitted`                                                                                                 |
| `X-Deewan-Delivery`  | The delivery id: one submission to one destination                                                               |
| `X-Deewan-Signature` | `sha256=` and the lowercase hex HMAC-SHA256 of the exact body bytes, keyed with the destination's signing secret |

The body (values are illustrative):

```json
{
  "event": "form.submitted",
  "receipt": "<receipt id>",
  "page": "<page id>",
  "locale": "en",
  "section": "<form section id>",
  "submitted_at": "2026-10-13T09:30:00.000Z",
  "values": { "email": "visitor@example.com", "subscribe": true },
  "labels": { "email": "Email", "subscribe": "Send me news" },
  "consent": true,
  "attachments": {
    "brief": [
      {
        "id": "<attachment id>",
        "name": "brief.pdf",
        "type": "application/pdf",
        "size": 1024
      }
    ]
  }
}
```

- `receipt` is the submission id, the same one **Recent submissions** shows.
- `values` maps each field name to a string or a boolean. `labels` maps each field name to its label
  on the published form.
- `submitted_at` is when the intake stored the submission, as ISO-8601 UTC.

### Answers and retries

- Any 2xx is **Delivered**.
- No answer within 10 seconds, a network failure, 408, 429 or any 5xx is retried.
- Every other status is final and ends as **Not delivered**. Redirects are not followed, so a 3xx is
  final too.
- At most 5 attempts in total. The wait starts at 1 minute and doubles, up to 1 hour, with random
  jitter of 50–100 %. A valid `Retry-After` (seconds or an HTTP date) can make the wait longer, up to
  1 hour.
- Each attempt uses the URL and signing secret accepted with that submission. Later edits apply only
  to new submissions. The destination's current disabled or removed state still stops queued delivery.

### Verify the signature

Verify the raw body bytes before parsing them. Re-serialized JSON does not match the signature. The
signature covers only the body; `submitted_at` is inside it. There is no separate timestamp header.

```js
async function verifyFormWebhook(secret, rawBody, signatureHeader) {
  const hex = signatureHeader?.startsWith("sha256=")
    ? signatureHeader.slice(7)
    : "";
  if (!/^[0-9a-f]{64}$/.test(hex)) return false;
  const key = await crypto.subtle.importKey(
    "raw",
    new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["verify"],
  );
  const signature = new Uint8Array(
    hex.match(/../g).map((pair) => parseInt(pair, 16)),
  );
  return crypto.subtle.verify(
    "HMAC",
    key,
    signature,
    new TextEncoder().encode(rawBody),
  );
}
```

### Deduplicate

Expect the same submission more than once. A lost 2xx is retried, **Send again** sends it again, and
a send that outlives its 5-minute claim can be sent once more. Do not rely on exactly one request.
Email can also repeat; the default message includes the receipt id in its last line.

- Deduplicate on `receipt`. It is in the signed body and stays the same on every attempt, on **Send
  again** and for every destination of that submission.
- `X-Deewan-Delivery` also stays the same across attempts and **Send again**, but it differs per
  destination and is not signed. Use it to tell two destinations apart, not as the only key.
- Store the `receipt` and apply your application's change in a single atomic operation, before you answer 2xx. Then a repeat does
  nothing.

## Next step

Add the form to a page in the [page builder](/guides/page-builder/#add-a-section), or read the
[outbound webhook contract](/reference/outbound-webhooks/) for content events.

## Submission details and delivery options

In **Settings → Integrations → Website forms**, open a receipt to read its retained values. Only operators with `site:infra` can read settings, receipt details or delivery history. Expired or erased values cannot be read or retried, even before scheduled cleanup runs. Erasing values also removes the queued delivery snapshots that contain them.

**Delivery options** lets you select an actual published page form and override its destinations. Forms without an override use the site defaults. An empty override sends no operator deliveries for that form; acknowledgement email is configured separately. Email destinations can use a plain-text **Subject** and **Text template · {{field}}**; **Insert field** inserts a declared form field. Templates accept `{{field}}` placeholders only, without executable expressions. Webhook secrets and destination configuration remain server-only and are excluded from public page data and site transfers.

**Acknowledgement email** sends a plain-text email to a chosen email field only when the published form has a consent control and the visitor checks it. It uses the same retained submission, queue, retries and erasure rules as operator delivery. It does not change the form's success message.

A delivery keeps the recipient or webhook URL, template and signing secret accepted with the submission. Editing settings never redirects an old retry. Disabling or removing its destination stops queued delivery; disabling acknowledgement stops queued acknowledgements. Erasure and expiry are checked again immediately before starting transport. A provider request already in flight cannot be recalled.

An exact retry of an accepted request returns its existing receipt, even if forms were disabled, the published form changed or disappeared, the client rate limit was reached, or retained values were erased. It creates no new submission or delivery. A changed payload with the same key is refused. The final live check authorizes one transport attempt; erasure cannot atomically recall a provider request already authorized or in flight.

<!-- dee-wan-docs page: /guides/sites/ -->

# Sites

Source: https://dee-wan-docs.pages.dev/guides/sites/

One installation can hold many sites. Each site has its own content, models, media, settings, roles
and plugins. Content stays isolated unless its source explicitly grants a published public shared reference. An account belongs to the installation, and a grant
gives it a role on one site. See [People and access](/guides/people-and-access/).

## Create a site

Only a superadmin can create a site.

1. Open **Settings → Site**. Under **Create a site**, press **New site**.
2. Enter a **Name**. The **Slug** fills in from the name; you can edit it before you create the site.
3. Enter the **Domain**: the hostname the public API answers on for this site, such as
   `www.example.com`.
4. Under **What is this site for?**, choose **Website** or **Blog**. This cannot be changed later.
   See [Blog sites](/guides/blog/).
5. Press **Create site**.

Name, slug and domain are all required. Each slug and each domain can belong to only one site, even
when that site is inactive. A taken slug or domain is refused.

The **Slug** cannot be changed after creation. The name and the domain can.

Creating a site writes the site record only. Dee Wan does not set up DNS or a Worker route. Until
the domain routes to the public Worker, the site is not served there. The screen says so after
creation. See [First site to published content](/guides/first-site/).

A new site starts with the default editorial workflow, one default language and the built-in roles.

## Switch sites

The site switcher in the sidebar shows the site you are working on. Open it and choose from
**Switch site**. It lists active sites. **Manage sites & access** opens Settings.

The admin reloads after a switch, because every screen belongs to one site. When there is more than
one site, **Settings → Site** also shows **Current site** with a button per site.

## Jump to a screen

Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>K</kbd>, or choose **Search** in the top bar, then type a screen name and press <kbd>Enter</kbd>. It lists only the screens and Settings sections your role can open. Escape closes it and returns focus. In the page editor, <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>K</kbd> opens the section gallery instead; use **Search** there.

## Change the name or domain

Open **Settings → Site**, edit **Name** or **Domain**, and press **Save changes**. You need the site
settings permission (`site:settings`). The built-in `admin` role has it, and so does a superadmin.

A new domain moves the public API to that hostname in one step. Dee Wan does not set up DNS or a
Worker route for the new name. Do that yourself, as at creation.

A site served by its managed design changes its address elsewhere: **Change address** in
**Settings → Source & delivery → Site template**. See
[Change address](/guides/managed-templates/#change-address).

## Deactivate a site

1. Open **Settings → Site** on the site you want to stop.
2. Press **Deactivate site** at the bottom of the site details.
3. Read the confirmation and press **Deactivate site** again.

You need `site:settings`, or must be a superadmin. When this is the only active site you can reach, the
confirmation says that you can reactivate it from the start screen.

What stops at once:

- The public API on the site's domain answers 404. Anything that reads this site through the CMS
  public API, such as a renderer, gets no content.
- Website forms on the site take no submissions.
- Nobody can work on its content or settings: not in the admin, not through the management API or
  MCP, and not through plugins. This includes superadmins.
- The site leaves **Switch site** for everyone. Only people who can reactivate it still see it, in
  **Settings → Site** and on the start screen. Everyone else no longer sees it at all.

What waits until the site is active again:

- queued website form deliveries and the erasing of form values past their retention date
- outbound webhook retries
- import jobs, content planner runs and the Trash purge

Because erasure is paused, a deactivated site keeps submitted form values past their erase date
until it is active again.

What fails: plugin work that comes due while the site is inactive is refused. For example, a
Scheduling schedule that comes due is refused and not retried.

Nothing is deleted. Content, media, settings, grants and plugin installations stay as they were. The
slug and domain stay reserved for this site.

## Reactivate a site

Whoever may deactivate a site may reactivate it: a superadmin, or a person whose role on that site
has `site:settings`, such as the built-in `admin` role. `GET /api/sites` lists an inactive site only to
these people. People whose role on that site lacks `site:settings`, such as the built-in `editor` and
`viewer` roles, do not see it, and their grants stay. When a grant is removed, the inactive site
leaves that person's list too.

Seeing an inactive site does not open it. **Switch site** lists active sites only, and nobody can work
on the site's content until it is active again.

From Settings, while at least one other site is active:

1. Open **Settings → Site** on an active site. The page is there for anyone who can reactivate a
   listed site, even if their role on the current site is only `editor` or `viewer`.
2. Under **Current site**, an inactive site has a greyed-out button with an **inactive** badge. Press
   **Reactivate** next to it.
3. The site is active again. Choose it under **Current site** or in **Switch site** to work on it.

When every site you can see is inactive, the admin opens a start screen that says **Every site is
inactive.** It lists each site you can reactivate, with its domain and a **Reactivate** button.
Pressing it reactivates that site and opens it. If the server refuses, for example because your grant
was removed in the meantime, the reason shows under the list.

A person whose every site is inactive, and who cannot reactivate any of them, sees **No sites yet.**
and is asked to contact an administrator. A superadmin or an administrator of that site can bring it
back.

Content was kept. Media, settings, grants and plugin installations are as they were. The waiting work
listed above resumes, including the erasure of form values past their erase date. Plugin work that was
refused while the site was inactive is not retried.

## Next step

Give people access to the site in [People and access](/guides/people-and-access/).

## Shared content

Open **Settings → Site → Shared content** on the source site. Choose **Content type**, **Entry**, **Destination site**, **Languages**, then **Share**. This action requires `site:settings` on both sites and permission to update the source entry. No destination membership or source editing access is granted to destination editors.

Enable **Shared references** (`sharedReferences`) on the destination model-level relation field. Component fields cannot enable it (`shared_reference_component_unavailable`). Only nonhierarchical `manyToOne` and `manyToMany` fields accept shared targets. Ordinary relation targets remain in their own site. Choose an explicit shared target in the relation picker.

Delivery reads the source site's current published public projection. Private fields and private models are excluded. **Revoke**, unpublishing, a disallowed language or an obsolete grant revision makes the reference unresolved; no old title is returned. The source remains its owner, including when sites use separate databases. Cross-database validation is rechecked on delivery; it does not claim one atomic transaction across sites.

Shared relations cannot combine `sharedReferences` with contextual target `filterChoices`; definition and runtime checks return `shared_reference_choice_unavailable`. Select-option conditions may still inspect whether a shared relation has a value.

A response resolves at most 128 distinct shared grant/language identities. Repeated references, including sync `data` and `changes`, reuse one current projection. Reduce the list or sync page size after `shared_reference_limit`.

Native bundle review checks the destination's compatible current grants and apply rechecks them. Another destination or an unavailable grant returns `shared_reference_destination_mismatch`; references are never silently removed. A detached backend cannot enforce live cross-site grant custody, so generation refuses effective shared references with `shared_references_require_live_delivery`. Remove or replace those references before generating it.

<!-- dee-wan-docs page: /reference/models-and-fields/ -->

# Models and fields reference

Source: https://dee-wan-docs.pages.dev/reference/models-and-fields/

A model defines a site's content structure. A field's `key` is its API identifier. `label` is its display name. Keep existing field IDs when editing a definition: changing an identity is not a safe rename. Changing a label never renames the key. A new field takes its key from its label until you type one. An existing key changes only through **Field key**, which keeps the field's ID, and the rename is reviewed before saving. Apply model changes only after reviewing their compatibility result.

If an existing model cannot load, choose **Try again**. Its editor stays unavailable until the definition loads. Saving locks the editor while compatibility checks and the save finish.

![The Content Builder showing the site's Page and Article models](/assets/screenshots/model-builder.webp)

![The Article model editor with its field list and model settings](/assets/screenshots/model-editor.webp)

## Field types

| Type        | Configuration to review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`      | Single or multiline, with rows, a placeholder and a default. Supports length and pattern validation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `rich`      | Rich-text editor with configurable toolbar. Stores one rich document as canonical HTML, up to 256 KiB: text blocks, tables, image galleries, audio, video and file blocks, and embeds of a YouTube, Vimeo or allowed https link ([embed origins](/guides/blog/#embed-origins)). A save that holds anything else is refused, naming the field, language and element. The public API serves the checked HTML; render it with the page contract's `renderRichDocument`, as Dee Wan's own renderers do for Blog posts and Latest entries summaries ([Blog sites](/guides/blog/#rich-text-safety)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `number`    | Step, default and display format: `integer`, `decimal`, `currency` or `percentage`. Supports numeric bounds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `boolean`   | Optional default boolean.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `select`    | Required option list of strings or `{value, label}`. Supports single or multiple values and a default. Custom values are available only for single selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `date`      | Format `date`, `datetime` or `time`. Supports a default and date bounds. There is no separate `datetime` field type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `point`     | Latitude and longitude stored together. See [timezone-aware dates and points](#timezone-aware-dates-and-points).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `media`     | Kinds of file (`image`, `document`, `audio`, `video`, `file`; images when none is chosen), maximum bytes, single/multiple files, and crop rules (aspect ratio, minimum size). A save that places a file of another kind is refused (`media_kind_not_accepted`), and so is one past the maximum bytes (`media_too_large_for_field`). Only images are framed: a crop or focal point on another file is refused (`media_framing_not_image`). On a top-level media field an editor sets a focal point per image. With an aspect rule the crop follows it. Framing is stored beside the reference as fractions of the image and never changes the file. Nothing resizes or crops the stored bytes; a generated site can deliver resized, cropped copies (see [preview and client](/guides/preview-and-client/#images-on-a-generated-site)). An image can have a default focal point (Media center → Edit image). It only starts a new use of that image; existing uses keep their own framing. A site copy carries it. Inside a component the framing travels in the value: a framed use is `{ media_id, crop?, focal? }`, an unframed one stays the bare id. A page section's image is framed per slot in the page inspector (page contract version 4). Which kinds and formats the library takes at all is a site setting (Settings → Site → Media files). An image can be cropped and rotated into a new copy (Media center → Edit → Crop and rotate); uses of the original are not changed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `json`      | Accepts any JSON value, array or object, with optional JSON Schema text. A page's `slides` document has the additional page contract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `relation`  | Target model slug (several models: see [A relation to several models](#a-relation-to-several-models)), display field and cardinality: one-to-one, many-to-one, one-to-many or many-to-many. In one-to-one and one-to-many each linked item belongs to only one entry; another entry pointing at it in the same field is refused with `relation_target_taken`. Every linked item shows the entries that point at it under **Related from**, by source model and field, for all four kinds. An editor who may read the item and update the source can add the item to the source or remove it. That change is the source's own save: a new draft version of the source, live after the source is published, and it applies to every language. When a one-to-one or many-to-one source already points at another item, the editor first confirms a replacement that names both items. Making an existing field one-to-one or one-to-many is blocked while two entries share a target (`relation_targets_shared`). Component fields do not offer one-to-many. Deleting either entry removes the link and keeps the other entry. Ordinary relations stay within the site. **Shared references** is available on model-level relation fields only; component fields cannot enable it (`shared_reference_component_unavailable`). A nonhierarchical many-to-one or many-to-many field can opt into explicit shared references (`sharedReferences: true`), requiring a grant from the source and destination administrators; these references read published public source entries and grant no source editing access. Shared-reference fields cannot use contextual target filters (`shared_reference_choice_unavailable`). A one-to-one or many-to-one relation to its own model can be marked **Hierarchy (parent/child)** (`"hierarchical": true`). Then a save or restore that makes an item its own parent, or puts it under one of its own children, is refused with `relation_hierarchy_cycle`. It cannot be turned on while stored links already loop; the model save lists them. The generated API refuses the same loops with the same code, inside the database write as well (see [relation and translation writes](/reference/standalone-backend-api/#relation-and-translation-writes)). |
| `component` | Allowed components (`components`: one slug, or several for a list of mixed blocks), repeatability, folding and per-use display overrides. Site-owned definitions can explicitly override shared definitions. See [mixed component fields](#mixed-component-fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Rich-text snippets

In a rich-text field of an item, select text and choose **Snippets** → **Save selection as snippet** to keep it under a name. **Snippets** → **Insert a snippet** searches the site's snippets and inserts one at the cursor. Insert makes a copy: renaming, changing or deleting a snippet later never changes text already inserted.

Anyone who may create or change items of the model can use snippets in its rich-text fields. You can rename, replace or delete the snippets you saved; people with `site:settings` can manage all of them. A site keeps at most 200 snippets, each up to 64 KiB. A name has 1 to 80 characters and is unique in the site, ignoring case. A snippet holds what a rich-text field accepts; raw HTML, styles and scripts are refused. Snippets are private: they never appear in the public API or on the website.

A site copy (format 1.12) carries the snippets and the images they show. Undo of its import removes only snippets the import added that nobody has changed since; a changed one is kept and listed.

## Shared field settings

Use required and translatable settings deliberately. Validation supports text length/pattern, numeric bounds, selection counts, repeatable component counts and date bounds. A minimum above its maximum, and a pattern that does not compile, are refused when the model is saved. The server checks content saves against the same rules as the editor. UI settings include hidden, grouping, ordering and help text. Hiding a field is not an authorization policy. Patterns support Unicode property escapes such as `\p{L}` (letters) and `\p{N}` (numbers). Custom ASCII-only patterns remain restrictive.

The generated standalone API retains declared text `minLength`, `maxLength` and `pattern` rules, including Unicode property escapes and deliberately ASCII-only patterns. After changing these rules, regenerate and redeploy the backend. See the [API reference](/reference/standalone-backend-api/) for generation refusals.

### Show only when

A model or component field can depend on sibling Boolean, Select, text, number or date fields. In **UI**, turn on **Show only when…**. Choose a controller, comparison and value. Combine up to four comparisons with **All conditions** (AND) or **Any condition** (OR); groups nest up to three levels.

- Boolean and Select keep the existing `{ "field": "featured", "in": [true] }` shape.
- Typed comparisons use `{ "field": "price", "op": "gte", "values": ["100"] }`. Text supports equality and contains; numbers and calendar dates support equality and ranges. Empty and not-empty take no values.
- Groups use `{ "all": [condition, condition] }` or `{ "any": [condition, condition] }`. Every controller must be a sibling. Invalid values, unavailable options, unsupported comparisons and dependency cycles are refused before a definition is saved.
- Hiding keeps the stored value. Required and other validation rules apply only while shown. Visibility is not access control.
- The editor, API, management tools and import checks use the same condition reader. Copies carry the condition; generated conditionally required columns accept empty values.

Derived-field configuration requires a predefined computation or AI configuration. Its presence does not prove an external AI provider is configured. Do not treat advanced schema options as evidence that every corresponding product capability is released.

## Models, locales and pages

The site chooses languages, a default language and a strict or fallback policy. Under fallback, each language can list fallback languages in order under Settings → Languages; a visitor sees the first one that has the item, then the default. The entry editor shows which language visitors see while a translation is not live. Check the returned item's locale rather than assuming it matches the requested one. A private model needs appropriate API access. Moving content into a public model exposes it to public readers.

A generated page model needs the documented `title` and `slides` structure. See the [page contract](/reference/page-contract/). Other models remain API data, not automatic pages. Shared component slugs are stable. A site fork replaces the shared definition for that site's references only.

![Per-model standalone API access, operation overrides and response-cache settings](/assets/screenshots/model-standalone-api.webp)

Changing a component’s field list retains the previous definition automatically. Existing entries keep their values and pinned version; the change creates no content revision and publishes nothing. New instances use the new definition. Use **Update component** on an existing instance when you are ready to migrate it. The write barrier briefly refuses concurrent content writes with `component_migration_in_progress`; repeat the save after it completes.

## Component definition versions

In the component editor, **Retired** removes the type from Add and Duplicate. Existing instances stay readable and editable. Retirement does not delete content. Removing the type from a mixed field’s allowed list still requires migrating or removing its instances first.

Every field-list change automatically keeps the previous definition. Existing ordinary and mixed instances retain their earlier fields and definition; new instances use the current version. **Update component** on an instance deliberately adopts the current definition after confirmation. Compatible fields keep their values; removed or changed-type fields are discarded and new fields start with defaults. Review and save the entry, then publish when ready.

The library keeps up to 64 retained definitions and 2 MiB of definition JSON. The current fields, retained definitions and metadata must also fit one stored row: at most 1,900,000 UTF-8 bytes including reserved overhead. A save or import that exceeds either bound is refused as `component_retention_limit` before the component is written. Retention and retirement hold affected writers through the existing component migration barrier. Shared components on split tenant databases keep the existing cross-database mutation refusal. Site copies and generated artifacts carry retirement, retained definitions and instance pins. Saving a component definition never deletes its retained definitions.

## Mixed component fields

A component field that allows several components is a list of mixed blocks, like a dynamic zone. In the field's Configuration, pick each component it allows; the order you pick is the order editors are offered. Two or more make the field a list, so it is always repeatable (`mixed_component_not_list` otherwise). Each component may be allowed once.

- The config is `{ "type": "component", "components": ["hero", "quote"], "repeatable": true }`. A field allowing one component uses the same key: `"components": ["seo"]`.
- The stored value is an ordered list. Each block carries `_id` (its identity), `_component` (its component), `_version` (the version of that component it was last saved against), `enabled` (`false` hides the block) and its component's fields. Every save checks each block against its own component; a retained instance keeps its `_version` until an explicit update.
- A component's version starts at 1 and goes up by one each time its field list changes. Existing instances keep their definition and `_version` until an explicit update.
- In the editor, **Add block** offers the allowed components. Each block's ⋯ holds Move up, Move down, Duplicate, Hide or Show, and Remove. Drag the handle, or focus it and press the arrow keys, to reorder.
- A hidden block stays in the stored list with `enabled: false` for editors, history and copies. Public reads, the managed renderer, a generated site and a generated backend's anonymous and read-token answers leave it out. An A/B variant's `enabled` on a single-component field is not affected.
- Adding a component to the allowed list is always safe. Removing one is refused while stored items still hold its blocks (`component_type_removed`).
- Allowing a second component on a field of one component converts its stored values into blocks (`_id` `block-1`, `block-2`, …, the component, its current version, shown). Going back to the one component that remains converts blocks into instances. Each item gets a new current version labelled "Component field changed shape"; older versions keep the old shape. Going back to a field that holds one instance is refused while an item holds more than one block (`storage_shape_changed`). A conversion is refused when it would rewrite more than 200 stored values (`component_migration_too_large`).
- History, restore, export, site copy, import and generated backends keep the list as stored. CSV/XLSX cells carry the blocks as JSON and can be imported through Collection files. Media inside blocks is tracked per component, so a key of another block type is never read as media.
- A relation inside a component value (any component, any depth, any block) names its targets by id. A public read and published generated output drop a target that is gone, in Trash, unpublished or not readable by that reader: a single link becomes `null`, a list keeps the rest in order. The stored version is not changed.
- Editorial previews resolve the latest authorized saved target drafts, including never-published entries, under the same field, locale and privacy rules as ordinary relationships. New shared preview links also recheck their creator’s current rights. See [draft previews](/guides/preview-and-client/#preview-unsaved-changes).
- A site copy carries the components this site owns that its models use (`components.json`, with each one's version) and writes them before the models, reusing a component the destination owns with the same fields and refusing a different one under the slug (`component_slug_taken`, `component_shadows_shared`, `component_name_taken`). Each relation inside a component value is mapped to the entry the copy made; one the copy does not carry blocks the check (`unresolved_relation`). Undoing an import removes the components it wrote once no field uses them.
- A mixed field has no AI generation or A/B variants (`mixed_component_context`). A/B variants are the instances of one repeatable single-component field, one shown at random; they are not set per block.

## Item address

Each language of an item has its own address, its `slug`: the public API serves the French language at `/v1/<model>/<slug>?locale=fr` under the French slug, and a language answers only at its own slug. A single-item read lists every live language and its slug in `alternates`. A model can also have a text field keyed `slug`. When the field is translatable, each language's value is that language's address. When it is shared, it holds the primary language's address. The editor, the content API, the management API, plugins, spreadsheet import, bundle import and Strapi import all follow these rules. The spreadsheet check reports `slug_invalid`, `slug_cleared` and `slug_reserved` before apply, including two rows of one file that name the same address in the same language. The Strapi import check reports `slug_invalid`, `slug_conflict` and `slug_taken` before the run.

| Save   | Address of a language comes from                                                                                        | Refused                                                                                                                                                                                                                     |
| ------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create | `slugs[lang]`, else that language's `slug` field, else its own title, else (a translation) the primary's address.       | A named slug with no letters or digits (`slug_invalid`). A named slug another item holds in that language (`slug_reserved`, `slug_taken`). `slugs[lang]` and the `slug` field naming different addresses (`slug_conflict`). |
| Update | `slugs[lang]`, or that language's `slug` field value that differs from the stored one. Anything else keeps the address. | The same refusals. Clearing an address, or a `slug` field that held a value (`slug_cleared`).                                                                                                                               |

- Every refusal names the field and the language: `{ reason, field: "slug", locale, slug, held_by?, version? }`. The editor shows it under that language's address, never as a toast.
- A named slug is normalized: Unicode letters, numbers and combining marks joined by single hyphens, normalized with NFKC and lowercased. `Harbour Wall` becomes `harbour-wall`. The normalized address is written into that language's `slug` field, and the save response returns every language's address as `slugs`.
- A title is not an address, so it never refuses. A taken title slug gets `-2`, `-3` and so on, in that language only. A slug is taken when another item's draft, current or published version holds it in the same language. Thai, Cyrillic, Japanese and other native-script titles produce native-script addresses. A title with no letters or numbers makes no address; a translation then takes the primary's address. On create, `slugs[lang]: null` means no address in that language. An address made from a title is cut to 180 characters before any `-2` suffix.
- Adding a language without a slug gives it the primary's address, suffixed when that language already holds it.
- An older item whose `slug` field already differs from its address keeps both through unrelated saves. Editing the field repairs it.
- Renaming a draft does not move the published address until that language is published.
- Each language keeps the address of its own published version. Publishing one language under a new address moves and redirects that language only.
- Publishing claims each moving language's address. A page language without an address cannot be published (`page_address_required`, with its `locale`). An address another item already holds in that language is refused (`slug_reserved`), and nothing is published.
- A managed route without `{locale}` gives an address only to the language a read with no locale serves: the default language, else the site's fallback order, else the primary.
- Restore puts back each language's address the version recorded. A bundle import, site copy and history transfer carry each language's address in its versions.

## Different links in each language

A relation field of a model with translations can hold **Different links in each language**: in the
field's Configuration, turn the switch on. It is stored as `config.localizedMembership: true`. Without
it, every language shows one shared list.

- Each language keeps its own list and order. The editor shows and saves the list of the language you
  are editing, on every language, including translations.
- The save API takes these lists under `locale_relations` (language → field → list, `{ set }` or
  `{ connect, disconnect, move }`, where `connect` items may carry a position). Sending such a field under `relations` is refused with
  `relation_localized_field`; sending a shared field per language is refused with
  `relation_not_localized`. A language the item does not have is refused with
  `relation_locale_missing`.
- Every rule applies to one language's list at a time: to-one cardinality, item limits, one owner per
  target in one-to-one and one-to-many (`relation_target_taken` only when another entry holds the
  target in the same language), and **Hierarchy (parent/child)** loops.
- A version stores these lists under `locale_relations`. Publish, preview, restore, Trash, a bundle
  import, a site copy and a history transfer keep each language's list. Deleting a language for good
  deletes its lists. A new language starts with empty lists.
- **Related from** changes the list of the language that is open. Its view merges an entry's
  languages into one row (the primary language when it links the item); removing there changes that
  row's language list only.
- The bulk **Categories and tags** action changes the list of each selected language. Several selected
  languages of one entry change in one save against one version; the other rows answer `covered`.
- Turning the option on copies each item's current list to every language. Turning it off keeps each
  item's primary-language list and removes the others; the model review warns about it first. Turning
  it off on a one-to-one or one-to-many field is blocked while two items' primary-language lists would
  share a target (`relation_targets_shared`), and on a **Hierarchy (parent/child)** field while those lists would put an
  item under itself (`hierarchy_cycles_shared`). A restored version from before the change follows the
  same rule.
- The option is refused on a model without translations and in a component
  (`localized_membership_unsupported`, `localized_membership_not_in_component`).
- A generated backend stores such a field, to-one included, in a join table whose rows carry `locale`;
  every uniqueness rule holds per language. The migration loads each live language's list from the
  version serving it. `PUT /api/<owner>/relations/<field>` takes `locale` and writes that language's
  list with the same item limits, one-owner and parent-loop rules (`unknown_locale` for a missing or
  unknown language). The read-only join table route serves one language's list with
  `where[locale][equals]=<lang>`; a language with no list reads as empty, never another language's.
  A shared list keeps its join table without `locale`, because SQLite treats NULLs as distinct in a
  unique index.

## A relation to several models

A relation field on a model or inside a reusable component can accept items of more than one model. In the field's Configuration, keep
the **Target Model** and tick the models under **Also accept**. It is stored as
`config.allowedModels`, a list that starts with the target model. Without it, the field accepts its
target model alone.

- A list can mix models, in any order. The picker searches every accepted model together, newest
  first, and each row names its model. Narrow it to one model with the buttons above the list. **Create
  new** asks which model to create when the field accepts several.
- A reference names its target's model. The save API accepts either the instance id or
  `{ "model": "<slug>", "id": "<instance id>" }` wherever it takes an id in a relation write (`relations`,
  `locale_relations`, in a list, `set`, `connect`, `disconnect` and `move`). When `model` is given, it must be the
  target's own model.
- A save is refused with `relation_target_not_found` when a target does not exist in this site, is of a
  model the field does not accept, names a different model than it has, or is one the person saving may
  not read. The answer does not tell these apart. A duplicate is refused with `relation_duplicate_target`
  and a second target on a to-one field with `relation_cardinality`.
- A version, a published version and a restore store each target's model beside its id. A restore is
  validated against the models the field currently accepts: a version that links a model the field no longer
  accepts is refused with `relation_target_not_found`.
- Publishing, unpublishing and Trash treat an item the same whichever model points at it: unpublishing an
  item that live entries link to through a field lists them, and **Related from** shows the entry from
  every model the field accepts.
- A public read serves each target as `{ instance_id, model, slug, display }`; see
  [Public read API](/reference/public-api/). A target of a model the field no longer accepts is not served.
  `relation`, `tag` and `expand` over a field that accepts several models are refused.
- A site copy and a bundle import keep the list's order and each target's model. An entry whose
  reference names the wrong model, or a model the destination field does not accept, is not imported.
- Removing an accepted model while items link to it is blocked in the model review
  (`relation_model_removed`), which names the items. Adding a model, or changing the order of the list,
  needs no review. Moving the **Target Model** to another model follows the same rule.
- A **Hierarchy (parent/child)** link still accepts one model (`mixed_relation_hierarchical`).
  The label shown for a target is the field's **Display Field**; a target whose model has no such field
  shows a short form of its id.

## Unique values

A `text` or `number` field of a model can be **Unique**: in the field's Properties, turn on Unique. A translated field also chooses **Unique in each language** (`locale`: no two items hold one value in the same language) or **Unique across all languages** (`model`: a value appears once in the whole model, including one item's own languages). A shared field is unique across all items. The setting is stored as `config.unique`. Component fields, other types and a per-language scope on a shared field are refused (`unique_unsupported`).

- Values compare exactly as stored: text is case-sensitive and not trimmed, numbers compare by value. An empty value never collides. Unique text is at most 255 characters.
- An item's current and published versions both hold their values, like an address. One item's own versions never collide. An item in the Trash keeps its values until it is purged.
- A save, restore, import, spreadsheet apply or publish of an older version that would repeat a value is refused with `field_value_taken` (409). The editor shows it under the field and keeps the edit. The other item is named only to someone who may read it. The spreadsheet check reports it before apply. The import check reports it before the run, including entries of one import that give the same value, and the run blocks such an entry with a problem row.
- Turning Unique on, or changing its scope, is reviewed first. The review lists items that share a value (`unique_duplicates`, with sample values) and items holding a value over 255 characters (`unique_value_too_long`). Apply is refused with `model_change_blocked` (409), naming each, until every one is resolved. A change made while Apply runs is refused (`model_change_stale`).
- A generated backend gets a unique column: `@unique` on the field's column, or `@@unique([field, lang])` for per-language scope. A one-to-one relation's column is unique too. Generation readiness and the build refuse published items that share a unique value (`unique_value_shared`) or a one-to-one target (`one_to_one_target_shared`) before anything is generated. Empty unique text is written as `null`.

Number inputs use decimal notation, including decimal exponents; hexadecimal, binary and octal strings are refused.

### Unique combinations

In model settings, **Unique combinations** defines up to eight named groups of two to four text or number fields. Choose **Across all languages** or **In each language**. All fields in a group must use the same shared or translated storage; language scope needs translated fields. The setting is `settings.unique_groups`: `[{ "name": "catalog_sku", "fields": ["catalog", "sku"], "scope": "model" }]`.

A combination participates only when every member has a value. Text compares exactly, numbers by value. Text members are bounded to 255 characters. Current and published versions reserve the tuple; save, restore, import and publication use the same atomic claim guard. Turning a group on checks existing duplicates before applying it. Generated schemas get a compound unique index, with `lang` included for language scope; readiness refuses duplicate published tuples.

## Single-entry models

A model is a **collection** (any number of entries) or **single** (one entry, such as a home page or site settings). Turn on **Single entry** in the model's general settings. The kind is stored as `content_model.kind` and travels in the model apply body as `model.kind`, through the Model Builder, the management API (REST, CLI and MCP) and a site copy. Omitting `kind` on an update keeps the stored kind.

- A single model holds one entry, whatever languages it has. An entry in the Trash still holds the place. Restore it, or delete it permanently to make another.
- A second create is refused with `single_entry_exists` (409), naming the existing entry and whether it is in the Trash. Saves, imports, site copies, spreadsheet applies, plugins and the management API all create through the same path. Two creates at once cannot both win: the check runs again inside the write.
- A site copy that carries more than one entry for a single model is blocked before the run (`single_entry_conflict`). So is one whose single model already holds an entry on this site, in the Trash too (`single_entry_taken`), unless that entry came from the same source entry, as on a re-import.
- A collection becomes single only while it holds at most one entry, counting the Trash. Otherwise the change is refused with `model_change_blocked` and a `single_entry_conflict` change. A single model can always become a collection; nothing is lost.
- In **Content**, choosing a single model opens its entry. When there is none, the list offers one **Create entry** action. When the entry is in the Trash, it offers **Restore**.
- The public API is unchanged: `GET /v1/<model>` answers a list of at most one item, and `GET /v1/<model>/<slug>` answers it by address. See [public API](/reference/public-api/#single-entry-models).
- A generated backend holds a single model's table to one row. A unique index refuses a second row whatever writes it, and the create route answers `single_entry_exists` (409).

## Content folders

A model can sit in a **folder** in the Content list, so a site with many models stays easy to scan. Set it in the model's general settings under **Folder**. It is 1 to 40 characters after trimming, and `Blog` and `blog` are the same folder. Clear the field to take the model out.

- A folder exists while a model uses it. There is no folder list to manage, and folders do not nest.
- Models without a folder are listed first. Folders follow by name, each opens and closes, and the browser remembers which are closed. A folder holding the open model opens itself.
- The folder saves on its own when the field loses focus, not with **Save**. It needs the permission that applies model changes (`model:apply`).
- It is organization for editors only. It does not change the model's revision, so it never makes an open editor stale or triggers a breaking-change review. It is not part of generation input, a generated backend or any public answer.
- A site copy carries the folder with each model it creates. A model the destination already has keeps its own folder. The management API sets it with `setModelFolder` (`PUT /models/{id}/folder`, `schema:write`) and lists it as `folder` on each model.

## Private fields

Any field of a model or of a component can be **Private**: in the field's Properties, turn on Private. The setting is stored as `custom_field.private`, or as `private: true` in a component's field list.

- Editors see and edit private values. History, restore, export, site copy, import and authorized management reads keep them.
- Every public read leaves them out: `GET /v1` items, expanded relations, related pages, the Blog feed, site search, the generated public TypeScript client, generated sites, and a generated backend's anonymous and read-token answers. A private relation or media field leaves `relations` and `media` too. Inside a component value, each private component field is removed wherever the value is served, generated sites included.
- A public query that names a private field in a filter, `sort`, `fields`, `relation`, `expand` or a related-page cursor is refused exactly as if the field did not exist.
- Renaming or deleting a private field never exposes its value. Published versions keep the old key in storage, but public reads, site search and generated sites serve only the fields the model declares now.
- A model field cannot take a key that saved versions still hold under an earlier field. This covers new model fields, renames, and changes that reinterpret a model’s component field. A model save returns `409 model_change_blocked` with `retained_key_reuse`. Choose another key while any retained version holds that value. Component field-list edits instead keep the old definition and pins; they do not reinterpret old values. Each retained component definition keeps its own privacy plus the current definition’s private flags, matching field identity across renames and using its key when identity is absent. Other historical versions do not change that pin’s privacy. An old private value never becomes public because a later definition changes. Imports compare carried values with the recorded source and reviewed destination definitions (`unmapped_source_key`, `source_private_value`, `import_definition_changed`). See [Import](/guides/import-migration/#check-run-and-resume).
- A component created or forked under a slug a site already reads is a new definition for that site's stored values. It is compared with the definition the slug read before. A key that definition did not have counts as a new field. So does a key it had as private that the new one would serve. A refusal is `409 retained_key_reuse`, and nothing is created. Confirming the override (`acknowledge_shadow`) does not lift it. A fork copies the shared definition exactly, so it changes no reading. Making a field of the site's own component public later is an ordinary privacy change.
- On a deployment with separate site databases, changing a shared component’s field list or retirement state is refused with `409 split_topology_migration_unsupported`. Name-only edits remain available. Fork the component for the site before editing its fields. Creating a new shared definition or an owned shadow still refuses a reading that could expose values already stored (`retained_key_reuse` or `split_topology_reinterpretation_unsupported`); an unavailable site database returns `503 site_database_unavailable`. An owned component holds affected content types during its change. Concurrent save, restore, carried history and language restoration return `component_migration_in_progress`; an earlier planned writer returns `model_contract_changed`. Retry after the definition change and run an import check again when its reviewed definition changed.
- Renaming, deleting or retyping a field also aborts any save planned against the old definition (`model_contract_changed`); retry it. If a version holding the key is saved while the check runs, the change is refused (`model_change_stale`, or `component_changed` for a component); try it again.
- Turning a field private, or public again, re-indexes the model's site search and purges its cached public reads. Cached reads are also keyed by the model's private fields, so a field made private is never served from a response cached before the change. The change also aborts any save planned against the old definition (`model_contract_changed`); retry it.
- A generated backend keeps private columns for editors. Anonymous reads, read tokens and every write response select only public columns. A component column holding a private field anywhere below is left out of those answers whole: the generated routes return the guard's own select, and a partial JSON projection would need a second response rewrite over every read and write route. A private list relation's join table is not served to readers.
- A saved query bound to a trusted route whose operation is served anonymously (`public` in the backend policy) may not select, filter or sort by a private field. Binding such a query, or editing a bound one to name one, is refused (`private_field_on_public_route`, 422), and generation refuses the set (`saved_query_private_field`) when a policy or a field changed since. A component field holding a private field at any depth counts as private here too, as it does for the generated reader; when the component definitions cannot be read, every component field does.

## Visitor comments

Any model can take visitor comments on its published entries. Turn on **Visitor comments** in the
model's general settings. The setting is the model's own `comments` key in its settings
(`{"comments": true}`); nothing else stores it. A Blog's post model is one such model:
**Posts → Comments → Accept new comments** changes the same key. A model that is not public never
shows comments.

- A comment belongs to the model, the entry and one language, never to an address. Renaming an entry
  keeps its comments. Each language has its own thread. A reply answers an approved top-level
  comment of the same entry and language; there is one reply level.
- Comments show only on an entry that is live now. Unpublishing or Trash hides them. Turning the
  setting off hides every comment and refuses new comments and new reactions; nothing is deleted.
  **Delete permanently** in Trash deletes the entry's comments and their reactions.
- New comments wait: **Waiting**, **Approved**, **Spam** or **Refused**. Moderate them in
  **Content → Comments**, which covers every model and filters by model, or on a Blog in
  **Posts → Comments**. The rules are the Blog's: see [Blog comments](/guides/blog/#comments).

| Action                             | Permission                                                                                                                                                                    |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read and moderate                  | `content:publish`                                                                                                                                                             |
| Delete permanently                 | `content:publish` and delete on the comment's model                                                                                                                           |
| Turn a model's comments on or off  | `site:settings` (**Posts → Comments**, `PUT /api/comments/settings`), or `model:apply` (the model's **Visitor comments** switch, saved with the model in **Content Builder**) |
| Mark a comment Helpful as yourself | read on the comment's model                                                                                                                                                   |

### Reactions

A comment takes one kind of reaction: **Helpful**.

- One reaction per visitor or person, comment and kind. Sending it again counts once. It can be
  taken back. Only an approved comment takes a reaction.
- A visitor is told apart per comment by a digest of the site, the comment and the client address,
  keyed with the intake Worker's `FORM_INTAKE_HMAC_KEY`. Setup generates that key once and never
  replaces it. The address is never stored, and one visitor's reactions on two comments cannot be
  linked. Visitors on one shared address count as one.
- An intake Worker without the key refuses visitor reactions (`not_configured`, 503) and says
  **Reactions are not set up on this site yet.** Comments keep working. Run setup again to add it.
- A signed-in person marks a comment Helpful in the moderation list, as themself.
- The count shows on the comment. Dee Wan keeps no reaction statistics.
- One client may send 60 reactions every 10 minutes per site, counted apart from comments and forms.

### Order

Visitors choose **Oldest** (the default), **Newest** or **Most helpful** (`?comments_order=`), and the
public read takes `order=oldest|newest|best`.

- `best`: most Helpful reactions first; equal counts oldest first; then by comment id. It reads only
  stored reactions and times, never the clock, so the same comments always come in the same order.
- Replies always read oldest first under their comment.

### Where comments show

- The managed renderer draws comments under every Blog post and every entry page a route serves. A
  page whose model takes no comments draws none.
- An exported site draws them on Blog posts and on the entry pages of every model that takes
  comments. Those pages are served at request time, like Blog posts, and read the comments live;
  other pages stay pre-rendered. Which models take comments is fixed when the site is generated:
  after turning a model's comments on or off, generate the site again.
- Renderers read `GET /v1/_comments?entry=&order=`; visitors post to
  `/v1/interactions/comment.submit` and `/v1/interactions/comment.react` on the site's host. Both
  work without JavaScript. See [the public API](/reference/public-api/).
- With the public edge cache on, a reaction refreshes cached comments at once only when the intake
  Worker has the purge settings (`PUBLIC_CACHE_MAX_AGE`, `CF_PURGE_ZONE_ID`, `CF_PURGE_API_TOKEN`).
  Otherwise counts refresh within five minutes. Moderation and the model setting purge from the
  admin.

### Copies and the management API

- A site copy and a site history transfer carry every comment of every exported entry, with its
  state, private email and reaction counts. Who reacted does not travel: the counts arrive as the
  comment's imported reactions and add to new ones, so a copied comment keeps its place in `best`.
- The management API lists, reads, moderates and deletes comments and turns a model's comments on or
  off, over REST, the CLI and MCP alike. See [the management API](/reference/management-api/#visitor-comments).

## Plugin content checks

An installed plugin may check content before it is saved or published (**Settings → Plugins**,
under the plugin). Dee Wan's own rules run first; a check never replaces them.

- A check that refuses stops the save, restore or publication. The editor names the plugin and the
  check, shows its message on the fields it names, and keeps your edit. Nothing is written.
- A check that warns lets the change through and shows the warning. You do not save twice.
- When a check does not answer, the plugin's setting decides. By default the change goes through with
  a note. With **Block changes if it does not answer** turned on, nothing changes and the editor says
  the plugin did not answer.
- Saves, restores, publications, bulk actions, spreadsheet applies, imports, the management API and
  other plugins' writes are all checked. A plugin that is off, or not granted the content type, is
  not asked.

## Change safely

Review the model-change preview before applying. Preserve a backup before destructive or incompatible changes. An accepted model change is not a backup. Regenerate the [public TypeScript client](/guides/preview-and-client/) after model changes and rebuild the consuming site.

The field configuration authority is `frontend/src/lib/eav/field-config-schema.ts`. Generated-backend supported field types are enumerated in `backend/src/lib/graduate/input.ts`. The [standalone backend API reference](/reference/standalone-backend-api/) and [implementation details](/reference/standalone-backend-internals/#content-tables-and-mappings) describe the exported API and database rather than the CMS storage layout.

## Translated labels

In the model settings or a field's **Properties**, open **Translated labels** and choose an admin language. Translate the model name and description, field label, description, help and placeholder, group labels/help, and select-option labels. Group translations appear in model settings; option translations appear in the option editor.

Labels follow the person's admin language, independently of the entry's content language. Fallback is the exact admin locale, its base language, the site's default language, then the canonical label. Empty translations use the fallback. API keys, model slugs, group keys and option values never change. Model definitions, management operations and site copies retain these translations; public content values remain unchanged.

```json
{
  "model": {
    "settings": {
      "translations": {
        "ru": { "name": "Статьи", "groups": { "seo": { "label": "Поиск" } } }
      }
    }
  },
  "field": {
    "ui": {
      "group": "seo",
      "translations": {
        "ru": { "label": "Заголовок", "placeholder": "Название статьи" }
      }
    },
    "config": {
      "type": "select",
      "options": [
        {
          "value": "gold",
          "label": "Gold",
          "translations": { "ru": "Золотой" }
        }
      ]
    }
  }
}
```

## Draft validation

**Draft validation** defaults to **Allow incomplete drafts**. Missing required values may be saved, including required members inside components and groups. Provided values still have to satisfy their type, range and structure. Publishing checks all required fields. Choose **Require complete fields** to apply required-field checks to draft saves too. The setting is `model.settings.validation_mode`: `draft` or `strict`.

## Timezone-aware dates and points

For a `date` field with format `datetime`, turn on **Retain timezone** (`withTimezone: true`). The editor keeps the local date/time and chosen IANA timezone together. A nonexistent daylight-saving time is refused; a repeated local time requires an explicit offset choice. Changing the timezone preserves the entered local time and resolves its instant again. The offset choice stays available for repeated times, and seconds and milliseconds are preserved. Consumers receive both values:

```json
{ "datetime": "2026-10-18T05:30:00.000Z", "timezone": "Asia/Bangkok" }
```

Date-only, time-only and existing datetime fields keep their string representation. Timezone storage cannot be switched while saved values exist: their original intended timezone is unknown. Use an explicitly populated new field. Sorting and comparisons use the instant; the timezone remains part of the stored value.

A native `point` field stores finite latitude from −90 to 90 and longitude from −180 to 180. Zero is a valid coordinate. Its two inputs save one value:

```json
{ "latitude": 13.7563, "longitude": 100.5018 }
```

Point filters support a radius in metres or a bounding box, including boxes across the antimeridian. Nearest sorting uses exact great-circle distance with a stable entry-ID tie-break. Counts, pagination and filtered selections use the same query. Points and zoned datetimes retain their object shape through history, imports, public responses and generated backends.

## Next step

Invite your team and set their roles in [people, accounts and access](/guides/people-and-access/).

### References inside components

**Also accept** is available for relation fields in reusable components, including nested components,
repeatable components and mixed component lists. Each selected item retains its `{ model, id }` pair
and its position. The server checks the actual target model, site and current read access when links
change. Existing cardinality and field validation still apply.

History and restore preserve these values. Native site copy and import map the destination entry ID
and model together; an unresolved target blocks import. Public reads and generated output omit
unpublished, deleted or unreadable targets without changing the stored version.

### Published ancestor chains

A public hierarchical field exposes its localized published ancestors under `ancestors[field]`.
Each entry carries its ID, served locale, current published display label and real site address.
Each chain contains at most 32 nearest ancestors, shown from the oldest retained ancestor to the parent. At most eight public hierarchical fields are returned, in field-key order. Longer chains stop at that bound. An unavailable ancestor, a private display field or a model
without a configured public address stops the chain; no URL or label is guessed.

The shared SEO renderer emits `BreadcrumbList` when a valid chain and the current item's label and
address are available. Changing a draft leaves live breadcrumbs alone. Publishing a renamed or moved
ancestor updates the next read and invalidates the model's dependent cached output. Generated sites
carry the accepted published chain from their generation input; regenerate after changing that input.

<!-- dee-wan-docs page: /guides/people-and-access/ -->

# People, accounts, roles and access

Source: https://dee-wan-docs.pages.dev/guides/people-and-access/

An account belongs to the installation. A grant gives that account a role on one site. Selecting a site does not grant access to it. Review the selected site before adding, changing or revoking a grant.

## Add a person

Open **Settings → People** with permission to grant site access. Under **Add person**, enter the email, select the role and use **Add**. The role cannot be raised above your own.

- **The address already has an account**: it gets the role at once. No email is sent.
- **No account yet**: no account is created. An invitation is made instead. Nobody gets access until the person accepts.

How the invitation travels:

- **Mail configured** (`RESEND_API_KEY` and `MAIL_FROM`, or your own [mail transport](#mail-transport)): the link is emailed. The screen says so only when the provider accepted the message.
- **Mail not configured**: nothing is emailed. Copy the link and send it privately. The link is shown once.

The person opens the link and types the address it was sent to. With mail configured, a code is emailed to that address and must be entered: the code, not the link, proves the address. Without mail, the typed address is the only check, and a new account is recorded as unverified. A person accepting an invitation for a new address chooses their own password. An existing account gets the role and keeps its password. An existing account with no way to sign in gets a password only after the code proves the address; without mail it gets the role, and a superadmin issues a password link.

Links work once and expire after 7 days. **Resend the invitation for {email}** issues a new link and the old one stops working. Resend is refused with `escalation_refused` when the invitation's role is above your own; the old link keeps working. **Cancel the invitation for {email}** asks for confirmation and invalidates the link. Pending and expired invitations are listed under **Invitations**, below the people, with their actions. Accepted and cancelled ones move under **Earlier invitations ({count})**. An expired, cancelled or used link shows the same refusal, whichever it was.

If a role or your own access changes while you add someone, invite or resend, nothing is granted, created or sent, and a resend keeps the old link working. When you may no longer grant site access, or the role is now above your own, the refusal says so (`missing_permission` or `escalation_refused`). Otherwise the screen says a role or your own access changed and nothing was saved: try again.

![Settings, People: the current access list and the Add person controls](/assets/screenshots/people-access.webp)

Each row shows where the person stands:

- **Can sign in** (a password, a linked provider or a verified address)
- **Link pending** with its expiry
- **Link expired**
- **Needs setup link**
- **Cloudflare Access** (Access is configured and the product cannot tell whether the person uses it)
- **Deactivated**

After **Add** grants an existing account that cannot sign in yet, a superadmin is offered **Create link**. Anyone else is told to ask a superadmin. Share that link privately. Never put it in content or screenshots. A superadmin can revoke a live link from the row, including a recovery link for someone who can already sign in. Revoking also removes a pending sign-in link the person requested. A deactivated account gets no link: reactivate it first.

Neither a grant nor an invitation is public self-registration.

## Mail transport

Resend is the default. To send through your own service instead, set `MAIL_TRANSPORT_URL` (a var),
`MAIL_TRANSPORT_TOKEN` (a secret) and `MAIL_FROM`. Dee Wan has no mail server and no SMTP client; your
service does the delivery.

- **When it is used.** With `MAIL_TRANSPORT_URL` set, every message goes to your service and Resend
  is not used. If the token or `MAIL_FROM` is missing, or the address is refused (it must be
  `https://`, with no credentials and a public address), mail is **not configured**: nothing is
  sent and the invitation or password link is shown to you to pass on.
- **The request.** One `POST` per message, with `Authorization: Bearer <token>`, an `Idempotency-Key`
  header and JSON `{ "message_id", "from", "to", "subject", "text" }`. `message_id` equals the key.
  The same message sent again carries the same id.
- **The answer.** Your service answers HTTP 200 with JSON: `{ "status": "sent" }` (optionally with an
  `id`), `{ "status": "sent", "duplicate": true }` when it already delivered that `message_id`, or
  `{ "status": "failed" }`. Any other status, body or redirect, or no answer within 10 seconds, counts
  as failed. A retry of one message id therefore delivers it once and is never reported as a second
  delivery.
- **What you see.** Sent, failed or not configured, as your service reported it. A failed or missing
  delivery never undoes what was created: the invitation or password link exists and is shown to you.
- Plugins never receive the token, and never see a message.

## Choose the smallest sufficient role

| Built-in role | Scope |
| --- | --- |
| `admin` | Full site administration. This does not make the account a deployment superadmin. |
| `editor` | Content creation, editing, publishing, unpublishing, approval and export; full media access. No model or site administration. |
| `author` | Read and create content. Edit owned entries only. Add media files, not change or delete them. No publishing, unpublishing, approval or restore. |
| `viewer` | Read-only access. |

Custom site roles can differ: inspect their definitions under Settings → Roles rather than inferring permissions from a name. Author ownership is checked on content, including both translation and primary where an operation affects both. A shared draft and the editing lease follow ownership of the row in that language: an own-only role (`read:own`, `update:own`) reaches them only on a language row it owns, and is otherwise refused with `not_owner`. A superadmin has deployment-level authority across sites.

<a id="role-matrix"></a>

In Settings → Roles, **All models** grants apply to every model, including models with their own row. Buttons edit direct grants; the ↳ indicator shows inherited grants. Access combines both: removing a direct grant does not remove inherited access. Editing a `*` all-actions grant replaces that token with individual actions; an unchanged save preserves it.

## Media permissions

Files in the [media library](/guides/media/) have three separate permissions, so you can grant the right to add, change or delete them independently:

| Permission | Allows |
| --- | --- |
| `media:upload` | Add files, including private files. |
| `media:update` | Change alt text, focal points, replace a file, folders, tags and public or private visibility. |
| `media:delete` | Delete a file. Deletion is refused if content or retained history uses the file, regardless of who requests it. |

`admin` and `editor` hold all three. `author` holds `media:upload` only, so an author can add files and cannot change or delete one. `viewer` holds none. A management API credential with the `media:write` scope carries all three, narrowed to what its creator holds when it is used. An import needs `media:upload` for the files it adds and `media:update` for the folders it creates, and undoing one needs `media:delete` and `media:update`.

[Rich-text snippets](/reference/models-and-fields/#rich-text-snippets) follow content access: anyone who may create or change items of a model can use them there and manage the ones they saved. `site:settings` manages every snippet.

[Workflows](/guides/content-editing/#workflows) are administered with `site:settings`: creating, editing and deleting a named workflow, choosing the workflow of a model and reviewing the move of items in review. [Feedback](/guides/content-editing/#feedback-and-notifications) on an item follows access to that item: reading it needs read access, writing and resolving need update access. A notification is shown only while its recipient can read the item.

## Limit a role to some fields or languages

By default, a role can access every field and language of the models it may use. No additional configuration is needed. To narrow a custom or built-in role, open **Settings → Roles**, edit the role and open **Limit fields and languages**.

- **Limit fields** lists the model's fields, plus **Search and sharing** and **Address**. Tap a field to cycle it through **Edit**, **View** and **Hidden**.
- **Limit languages** picks the languages the role works in. The choice applies to every action the role holds: create, update, delete, restore, review, publish and unpublish. **Can read every language** keeps reading open, so a translator can see the source while editing only their own language.
- The **All other models** row limits languages for every model the role reaches through its default grants. A model's own setting replaces it.

What a limit does:

- A hidden field is left out of the editor, version history and comparisons, the content list search, the spreadsheet export and the management API. A view-only field is shown disabled.
- A save that names a field the role may not change is refused with `field_denied` and names the field. Nothing is dropped silently, and what is stored in fields the role cannot see is kept.
- An action in a language outside the role is refused with `locale_denied` and names the language. An operation that spans languages, such as a whole-entry publish or a bulk action, is refused in its entirety.
- A shared (non-translatable) field, a shared relation list and media live on the primary language. Changing them needs the role to update the primary language. Sending a shared value unchanged with a translation is not a change.
- **Restore French only** in version history (the button names the language) restores one language: its fields, its own relation lists and its address. Shared fields, shared relations, media and every other language stay as they are. It needs the restore action in that language only, so a translator can recover their own language.
- **Restore this version** restores the whole entry: every language and every field. It needs the restore action in every language of the entry.
- Either way, a field-limited role may restore only where the fields it cannot change already match the version.
- A shared draft follows the same limits. Every draft answer, conflicts included, carries only the fields the role can read. A page draft shows an empty title without read on the title and is refused with `field_denied` without read on the sections. Joining or taking over the editing of a language needs the role's change grant there (create, when that language has no row yet); otherwise it is refused with `locale_denied`.
- Feedback follows the same limits. A note belongs to the language it was written in. A role sees only the notes of languages it may read, writing a note needs the update action in that language, and resolving or reopening a note needs both read and update in the note's language. Otherwise the request is refused with `locale_denied`.
- Languages the role may not read are hidden from the editor's language list and from content lists. A preview link serves only what its maker may read and never falls back to a language outside the role.
- The update-only **Export spreadsheet** → **Import spreadsheet** round trip needs read and update on the model. An own-only grant (`read:own` or `update:own`) exports and accepts only the person’s own items; a row for anyone else’s item answers `spreadsheet_row_not_found`. Columns include only fields the role may both read and change. View-only fields are left out; stored hidden values are preserved on apply. Sheets include only readable languages. Changing a language without update access is blocked with `locale_denied`. CSV/XLSX create and upsert use the collection path below instead.
- **Collection files** exports JSON with `read` on the model and only the rows, fields, related items and languages that read grant reaches. Its JSON, CSV and XLSX imports check permissions per row: creating needs `create`; updating needs `read` and `update`, and an own-only grant reaches only that person’s items. Upsert needs the grant for each row’s actual action, not both actions for every row. Adding a translation to an existing item also needs create access in that language. Every changed field and language needs its write grant; unchanged values stay untouched. See [content editing](/guides/content-editing/).
- A whole-site export copies every field and language, so a role that limits reading cannot start one.
- When someone holds several roles, each field and language keeps the strongest grant that covers it. A role with no limit for an action makes that action unlimited. `update:own` in one language beside `update` in another stays owner-restricted in the first: the merged set records it as an `update:own` language list.
- You can hand out only limits within your own. Saving a role that reaches a field or language you cannot is refused with `escalation_refused`, and the editor says so before Save.
- Limits name fields by key. Renaming a field key in the model builder rewrites every role's limits to the new key once the rename is saved.
- The page composer opens a page only in a language the role reads and refuses a page whose sections the role may not read. The page library hides titles and languages the role may not read.
- Roles, limits included, can also be managed through the [management API](/reference/management-api/#roles) with the `roles:write` scope.

## Change or revoke access

Change a grant's role in the People list or revoke that site's grant. Revocation is not account deletion. A superadmin can deactivate an account and revoke its sessions. Reactivation requires a fresh sign-in. Self-deactivation and removal of the last active superadmin are refused. Site access also protects the last administrator.

## Sign in through Cloudflare Access

This needs an installation with Cloudflare Access set up. Open **Settings → People → Cloudflare Access sign-in** with permission to grant site access.

A rule maps one exact email domain, such as `example.com`, or one Access group to one role of this site. When the switch is on and a person verified by Access signs in with a matching domain or group, they get an account and that role in one step. Subdomains do not match. A group name must match your identity provider's exactly, including case.

Groups are read from Cloudflare Access (`get-identity` on your team domain), not from the sign-in token, which can drop groups. They are read only when some site has a group rule, and once per Access sign-in session.

- **Later sign-ins** update the role to match the rules. Removing a rule removes the role it gave.
- **People added by hand or by invitation keep their role.** No rule changes or removes it. People shows **Access** beside a role a rule gave.
- **Several rules match one person** (a domain and groups): the role that includes the others applies. If none includes the others, that site gives no role. Two rules for the same domain or group that cannot combine are refused when saved. One that becomes ambiguous after a role edit shows **Conflict**.
- **Groups cannot be read**: no account or role comes from a group rule, and roles a group rule gave are not changed or removed. Domain rules still apply. A first sign-in that only a group rule could admit is refused and can be retried.
- **The last administrator** of a site is never removed or downgraded by a rule. The screen names who is kept.
- **Off** stops every automatic change: no new accounts, no role changes, no removals. Existing accounts and roles stay.
- A deactivated account stays refused. No rule makes anyone a superadmin. Password, email link, Google and GitHub sign-in still create no accounts.
- You can only hand out a role within your own. Changing a rule, even only its domain or group, is refused with `escalation_refused` when the rule's role is above your own. Deleting such a rule, or changing it to a role within your own, is allowed.
- If a role or your own access changes while you save a rule, nothing is saved. When the rule's role is now above your own, or you lost permission to grant site access, the save is refused with `escalation_refused` or `missing_permission`. Otherwise the screen shows the latest rules; try again.
- A role a rule uses cannot be deleted. Change the rule first. A site holds at most 100 rules.

Every change to the switch or the rules, and every role a rule gives or removes, is recorded in the site's administrative history.

## Replace a superadmin

Follow [Replace a superadmin](/guides/first-administrator/#replace-a-superadmin). A replacement person uses a separate account promoted with **Make superadmin**. To change only your own email, use the verified Account security flow below.

## Passkeys

A superadmin switches passkeys on from the **Installation** page, under **Sign-in methods**. They are off by default. Passkeys require the admin interface to be served from a domain name or `localhost`. On an IP address such as `127.0.0.1` browsers refuse them, so the switch stays unavailable and says why. Each person then manages their own passkeys under Account security. See [Passkeys](/guides/first-administrator/#passkeys).

**Lost device.** Sign in another way (password, email link, Google or GitHub) and remove the lost passkey under Account security. With configured mail, use an enabled email sign-in link or the password-reset request on the sign-in screen. Without mail, a superadmin issues a password link from the People list, as described below. The person sets a password and signs in with it, then removes the lost passkey.

## Password ownership and recovery

Claim and reset links expire after 15 minutes and are single-use. Issuing a new one invalidates the previous link. The password must have at least 12 characters. Public signup is unavailable. With mail configured, sign-in offers a self-service password-reset request; without mail, an authorized issuer provides the recovery link.

For the existing sole active superadmin who is locked out, the deployment owner may use `npm run claim:link -- --remote --email <existing-email>` from the CMS repository. It refuses to create a new account or reset an arbitrary user. First installation uses the installer claim instead. See [installation](/guides/installation/) for prerequisites.

Authorities: `backend/src/api/sites.ts`, `backend/src/api/users.ts`, `backend/src/lib/invitation.ts`, `backend/src/lib/access-provisioning.ts`, `backend/src/lib/access-identity.ts`, `backend/src/api/access-provisioning.ts`, `frontend/src/routes/settings/components/tabs/People.svelte` and `scripts/claim-link.ts`. Access in a standalone backend is separate: see [optional artifact authentication and access](/reference/standalone-backend-api/#optional-artifact-authentication-and-access). CMS accounts and roles are not exported into it.

## Next step

Build with Dee Wan, starting with [preview and the generated TypeScript client](/guides/preview-and-client/).

## Change your email or recover your password

Open **Account security → Change email address** and enter your new address. Enter the code sent to the new mailbox; it expires after 15 minutes. The new address must be unused. Your account ID, site access, credentials and content history stay unchanged. All sessions end after confirmation, so sign in with the new address. This requires mail delivery. Google and GitHub callbacks never change the account email.

On the sign-in screen, choose **Forgot password?**, then enter your email and request a link. The option is available when mail is configured; no email is needed to open it. The response is the same for known and unknown addresses. An active account receives a single-use link, valid for 15 minutes. Open the link and choose a new password. Without mail, ask a superadmin for a reset link from People. The last superadmin uses `npm run claim:link -- --remote --email <address>` with deployment credentials.

## Entry rules in custom roles

Open **Settings → Roles**, edit a custom role, and open **Limit access by entry**. Choose a model and action, then **Add entry rule**. Match the creator or a field value; choose an operator and a fixed value, current user ID, email or roles. Combine conditions with **All conditions (AND)** or **Any condition (OR)** groups. The builder allows four conditions and three group levels; incomplete rules disable Save. Server refusals remain visible when a field or permission changed. Model permissions still decide which actions the role grants. Entry rules narrow those actions using current entry values. Field, language and ownership limits still apply. A scoped update must satisfy both read and update rules before and after the change; changing a department cannot move an entry outside your rule. Create checks the proposed values. Delete and workflow actions check the current values.

Saving or restoring one language checks the primary entry and each language changed. Unchanged sibling languages add no permission requirement.

```json
{"article":{"read":{"field":"department","op":"in","values":[{"user":"roles"}]},"update":{"field":"assigned_editor","op":"eq","values":[{"user":"id"}]}}}
```

Each model key is its slug. Actions are `create`, `read`, `update` and `delete`. A condition uses a field key, `op` (`eq`, `in`, `contains`, `empty`, `not_empty`) and `values`. Values are strings or `{"user":"id"}`, `{"user":"email"}`, `{"user":"roles"}`. `{"owner":true}` means an entry created by the current person. Combine conditions as `{"join":"and","conditions":[...]}` or `{"join":"or","conditions":[...]}`. A rule has at most four conditions and three group levels. Shared fields use the primary language's values.

Roles add authority: a person holding an unrestricted role can still read its permitted entries. Ownership and entry rules from one role stay together when several roles are combined. Invalid rules cause that role's grant to be refused. A delegated role cannot relax your entry-rule ceiling. Rules do not change public publication or URLs.

Existing saved links keep their IDs when their targets become unavailable to your role; hiding a name does not disconnect the link. Revision history shows target names and addresses only when your current access permits them. The stored revision is unchanged.

Value rules support text, select, boolean, number and date fields. Select `eq` and `in` match exact choice IDs, including values in a multi-select; `[]` counts as empty. `contains` works only on text. Number comparisons use numeric values, boolean comparisons use `true` or `false`, and dates use `YYYY-MM-DD`. Missing or renamed fields deny access, including an `empty` rule. Use `empty` or `not_empty` with `values: []`; blank comparison values are refused.

## Administrative history

Open **Settings → History** with `audit:read` permission to review changes to this site’s models, roles, access, tokens, settings, hostname and deployments. Filter by action, outcome, person, target or dates; **Download CSV** exports the filtered results. An **Unknown** outcome does not confirm success or failure. Rows cannot be edited or deleted here. Content changes have their own [version history](/guides/content-editing/#version-history).

<!-- dee-wan-docs page: /guides/preview-and-client/ -->

# Preview and the generated TypeScript client

Source: https://dee-wan-docs.pages.dev/guides/preview-and-client/

The generated public client talks to the CMS public `/v1` API. It is not a client for the detached backend's different API. The [standalone backend API reference](/reference/standalone-backend-api/) describes that API.

## Generate the client

Open **Settings → API → TypeScript client**. The card shows the schema identity of the client for the models your role can read and lets you copy or download the file. The file starts with a `@dee-wan/public-client` comment that records the site, public URL, contract version, schema identity and the contract itself. The schema identity is a SHA-256 digest of the locales, the locale policy, and each model's visibility and field types. Labels, names and field order do not change it.

To refresh the client from your repository, download `dee-wan-client.mjs` from the same card and commit it. It needs Node 18 or later and no packages. It reads a site API token from `DEE_WAN_SITE_TOKEN`. Create the token under Settings → API and keep it in a server or CI secret. Private models must be in its scope. Substitute your site's public origin; the values below are placeholders.

```sh
DEE_WAN_SITE_TOKEN=dw_site_… node dee-wan-client.mjs pull --url https://www.example.com --out src/dee-wan-public.ts
```

The command reads `GET /v1/_client` on the public origin. It writes the file only when the response is complete and its header matches the served identity. The pulled client covers public models and the private models in the token's scope. Its identity matches the one in Settings only when both cover the same models.

Before each deploy, for example in CI, check the committed file:

```sh
DEE_WAN_SITE_TOKEN=dw_site_… node dee-wan-client.mjs check --file src/dee-wan-public.ts
```

`check` exits 0 when the identity matches, or when every change is compatible: an added model, field or locale, a field made required, a model made public, or a removed select value. It lists those changes. It exits 1 on a breaking change: a removed model, field or locale, a changed field type or list shape, a field made optional, a new select value, a model made private, or a changed site, default locale or locale policy. It exits 2 when it cannot run: bad arguments, no token, a network or HTTP error, or a file without the header. After a change, run `pull`, fix what no longer compiles, and commit.

An admin session can still fetch the same file by hand:

```sh
curl --fail --silent --show-error   -H "X-Site-Id: $DEE_WAN_SITE_ID" -b "$DEE_WAN_SESSION_COOKIE"   'https://admin.example.com/api/models/public-client.ts'   -o /tmp/dee-wan-public.ts
```

The file contains exact model fields, locale and query types, response envelopes and model methods. It is dependency-free TypeScript, not a package to install. Your application never imports the command, and Dee Wan never changes your repository.

## Use a model method

This example assumes you actually created a public `article` model and an `en` locale. Use your site's public hostname, not the admin origin and not a base ending in `/v1`.

```ts
import { createClient } from './dee-wan-public';

const client = createClient({ baseUrl: 'https://www.example.com' });
const first = await client.article.list({ locale: 'en', limit: 20 });
const item = await client.article.get('hello', { locale: 'en' });
```

Server-side and build-time reads need no CORS setup. For a browser app on another origin, allow it under **Settings → API → Browser origins**; see [browser origins](/reference/public-api/#browser-origins). Private models require `token` in `createClient` options, kept in a server secret. Never publish it in a browser bundle. Inspect `data` and the list's `page` metadata. Forward opaque cursors unchanged and check the returned locale under fallback. See the [public API](/reference/public-api/) for error and pagination contracts.

## Activate a reported Astro origin

After managed source delivery, Source & delivery shows the repository owner and name, exact deployed commit and reported Astro origin. Completion labels that origin **Preview unverified** and leaves the existing preview target active. While signed in with `site:settings`, choose a readable saved item and locale and select **Verify and activate preview**. The server loads the recorded origin and its renderer contract, then runs the existing draft preview proof. The browser cannot substitute another origin in this action.

A successful proof marks that candidate active. A failed proof, unreachable origin, wrong-site contract or concurrent settings change leaves the previous active target unchanged and displays an actionable refusal. No build callback or system principal activates a renderer. The **Advanced — custom renderer** flow remains available for explicitly configured renderers.

## Open an actual rendered draft preview

The editor's preview action creates a one-item capability valid for 30 minutes. It reads that draft and its authorized related saved drafts, not the whole site, and does not bypass private-model access. New links recheck the creator’s current account, site membership and read permissions on every request. The root fields and languages remain limited by the permissions recorded when the link was created. Older links without this related-draft grant keep published-only relationships. Never log, index or share the capability as a public URL. Invalid capabilities are refused. Request a new preview rather than reusing an expired link.

Configure the site's preview renderer origin and per-model route template under **Settings → Source & delivery → Advanced — custom renderer**. The contract uses an HTTPS origin (plain HTTP only for a loopback address: localhost, 127.0.0.1 or [::1]). It uses route placeholders `{slug}` and `{locale}`, and a token query-parameter name. The renderer must pass verification for that site before the CMS reports `rendered: true`. Configuration alone is insufficient. Without a verified renderer, Preview opens the public API JSON and reports `rendered: false`.

For a generated Astro site, explicitly set `previewApiOrigin` in `apps/site/src/owned/extensions.ts` to the CMS public API origin and verify the renderer contract. It is `null` by default. Only `/preview` uses that runtime bridge. Normal published pages use their generated snapshot, except pages with a Latest entries section and a Blog's `/blog` routes: those read published entries at request time from `/v1` on the site's own host (the Dee Wan public Worker in the reference topology), or from the owned `publicApiOrigin` in local development, and answer `no-store`. Latest entries in a shared section shown in a region are pinned at generation instead. Preview responses are `no-store` and must not enter search or public caches. A detached site should disable this bridge when it no longer uses the CMS.

## Edit from the preview

In the entry editor, **Preview here** opens the saved render beside the fields. It is offered when
the site's verified renderer routes the model and speaks an editor bridge. Wide screens (1280 pixels
and up) show fields and render side by side. Narrower screens show one pane at a time, with
**Fields** and **Preview** tabs. **Preview on site** still opens the render in a new tab.

The render shows the saved version unless the site supports previewing unsaved changes (see Preview unsaved changes below). Without that support, unsaved changes do not appear until you save, and the pane says so.

The current managed and generated Blog renderers let you edit ordinary text and rich text at the rendered value. Double-click the value, choose its **Edit** badge, or focus its field link and press **Enter** to open the normal field control over the preview; format rich text there, then choose **Done**. Changes remain in the editor draft until **Save**. Other fields and older renderers open the matching form field. A custom-model renderer can opt in with `data-dw-editor-inplace` on its bridge identity marker; it must draw field links and the verified draft. The frame only identifies the field and its position; the editor checks the current field and permissions and owns all changes.

With a field-linked renderer (editor bridge 3, which generated sites declare):

- Double-click a rendered value, Alt-, Ctrl- or Cmd-click it, press its **Edit** badge, or focus it
  and press Enter. Where in-place editing is unavailable, the editor switches to the fields, opens the component, block or panel that holds
  the field, and focuses it.
- Focus a field in the editor. The render outlines every element that shows it and scrolls to the
  first.
- On a page model the sections, the title and the facts are edited in the page editor. Selecting one of these values
  offers **Open page editor**.
- A plain click in the render follows no link, so the preview stays open.

With a renderer that speaks only editor bridge 1, the preview works and the editor says that field
links are not available for this renderer. In the pages workspace, **Site preview** uses the same
frame: selecting a value focuses the section field it names.

The built-in renderers (a generated site and the managed renderer) link page models and Blog posts.
On a post, the title, the date, the cover, the author, category and tag links, and each body block
(including text in plugin blocks) link to their fields. Their renderer contracts route
the `post` model, so verify and activate the renderer again after you regenerate or redeploy. Other
ordinary models get field links only from a custom renderer that speaks bridge 3. See
[the page-document contract](/reference/page-contract/#editor-bridge-and-field-links).

A managed preview may be framed only by the editor origin its link names, and only with the
editor's nonce. It then allows that one ancestor and the bridge script by hash. Any other preview
or published page keeps `frame-ancestors 'none'`.

## Preview unsaved changes

When the site's verified renderer declares that it draws a model from a signed draft, **Preview here** shows what you have typed and not saved. Text, components, relationships, the images you picked and the language-specific address update after you pause typing; one update is in flight at a time. The managed renderer declares this for the Blog `post` model. Any other model, and any renderer that declared nothing, shows the saved version and the pane says why. Verify and activate the renderer again after you update the site design.

- Nothing is saved. The values undergo the same validation as a save and are then rendered; they never change the stored draft, the published version, a revision or a public read. The server does not log them. A request is refused when it is over 1 MiB.
- Previewing unsaved changes requires permission to edit the entry in the language shown. A reader sees the saved version.
- Relationships use each target’s latest saved draft, including entries never published. Your unsaved relationship choices are included; edits still unsaved in another entry are not. Ordinary and component relationships follow the same current item, field and language permissions and private-field projection. Expansion follows the site’s language fallback policy, stops after four levels or 128 targets, and truncates cycles to stable identities. Related items arrive under `item.expanded`; public reads stay published-only.
- Images are the files you picked in each image field, with the crop and focal point you set, rendered as they would be in a saved entry. The server looks every file up by its id in this site's library with your current permissions; it never uses an address the browser sends. A file from another site, a file that no longer exists and a private file placed where a saved entry would refuse it (anything but a field of a private model) are refused, and the pane identifies the rejected file. A private file in a private model's field shows its facts and no address, as a saved entry does. The language's address is the one you typed, drawn at that address. Nothing is reserved: no address is claimed, no redirect is written, and the preview does not change the live site's published address.
- The same field links apply: click a rendered value to open its field, and focus a field to outline its value.
- A page model is previewed in the page editor, not here.
- If the entry changed elsewhere, its language has no saved content, or the site's design cannot draw it, the pane keeps the last good render and says so. Retry after fixing the cause.

### Generated and owned renderers

A generated Astro Blog site carries the verifier. It checks the draft with a **public** key: no render secret, account, session or provider credential is placed in the site, and signature verification does not call the CMS. The installation needs `MANAGED_RENDER_HMAC_KEY` and `FRONTEND_URL`; without them the key is not available and **Settings → Source & delivery → Advanced — custom renderer** says so.

1. Open **Settings → Source & delivery → Advanced — custom renderer** once. **Unsaved-entry preview key** records the site's public key for generation.
2. Generate the site again and deploy it. The generated site carries that public key, so you do not need to paste it. While no key is recorded the site declares nothing and its endpoint answers `501`.
3. Press **Verify and activate** in **Settings → Source & delivery → Advanced — custom renderer**. The site declares `entry_preview` with its Blog model and the key id in `/.well-known/dee-wan-renderer.json` only while a key is present. **Preview here** then shows unsaved changes.

To override the generated key, press **Copy key** and paste the JSON into `apps/site/src/owned/entry-preview.config.ts` in place of `null`. The file is yours: regeneration never replaces it, and a value there wins over the generated key.

- The signed draft names the site, the renderer's origin, the entry, the language, the version you loaded, the exact bytes and a 60-second expiry. The renderer refuses any other site, origin, entry, language, version, bytes, editor origin or expiry. The frame must be opened from the editor origin named in the signed draft.
- The endpoint is `/.well-known/dee-wan-entry-preview`. It takes the editor's form post and writes, caches and logs nothing.
- Astro refuses cross-origin form posts, and the editor's frame is on another origin. A generated Blog site therefore turns that check off and repeats it in `src/middleware.ts` for every address except this endpoint.
- **Rotate key** starts a new key and is recorded in the audit ledger as a site settings change. The old key stops working at once: generate and deploy the site again (or update your override) and press **Verify and activate** again. Until then **Preview here** shows the saved version and says the site verifies an older key.
- If the site declares no key, or an older one, the pane shows the saved version and says why.

A renderer you own copies `apps/site/src/lib/entry-preview-verifier.ts` from a generated site. It has no imports and uses only Web Crypto Ed25519 (Node 24, Cloudflare Workers, current browsers). Call `verifyEntryPreview({ envelope, body }, config, context)` with the two form fields `envelope` and `body`, the pasted configuration, and a context of your renderer's `site_id`, own `origin`, release identity (`renderer_contract_digest`), the `models` it draws, `now` in Unix seconds and the `editor_origin` query parameter of the frame's address. On success it returns the verified `item` to draw with your own post view; otherwise a refusal with `status` (`403`, `409`, `413`, `422` or `501`) and `reason`. Declare support in `/.well-known/dee-wan-renderer.json` with `entry_preview: { "version": 1, "models": ["post"], "key_ids": [<kid from the configuration>] }`, each model also routed; `entryPreviewDeclaration(config, models)` builds it, and returns `null` while there is no configuration. Do not declare it until the endpoint works. A renderer that shares the installation's render key (the managed renderer) declares no `key_ids`.

## Images on a generated site

A generated Astro site draws every image through one rule, `deliverImage` in `apps/site/src/lib/media-presentation.ts`. The preview route and published pages use the same rule and the same settings, so they produce the same URLs.

- Each image gets `width` and `height` from its recorded size, or from its crop when the use has one. An image with no recorded size gets neither and no `srcset`.
- The crop and focal point of that one use are applied. The same image used twice keeps two framings.
- The stored file never changes.

Transformed delivery is off until you declare the media hosts whose Cloudflare zone has Image Transformations enabled. Set `imageTransformOrigins` in `apps/site/src/owned/extensions.ts`, for example `["https://media.example.com"]`. A wrong entry fails the build by name. An image on a declared host is then served as `https://media.example.com/cdn-cgi/image/width=640,quality=85,format=auto,fit=scale-down,trim=<top>;<right>;<bottom>;<left>/<key>`, with a `srcset` of 320, 640, 960, 1280 and 1920 pixels capped at the framed width, and `sizes="100vw"`. `trim` cuts the crop in pixels before the resize. Every other image keeps its original URL; a crop is then shown by CSS (`aspect-ratio`, `object-fit: cover`, `object-position`), and a focal point by `object-position`.

Deployed acceptance is a manual gate. Run it once per media host:

1. In the Cloudflare dashboard, open the zone that serves the media host, then **Images → Transformations**, and enable transformations for that zone. Expected: the zone shows as enabled.
2. Add the host to `imageTransformOrigins`, build and deploy the site.
3. Open a published page with a framed image. In the browser's network panel the image request goes to `/cdn-cgi/image/...` on the media host and answers `200` with an image content type. Expected: the picture shows the crop, and `width`/`height` on the `img` match the framed size.
4. Narrow the window to 390 pixels and reload. Expected: a smaller `srcset` candidate is fetched.
5. Request the original URL. Expected: the original bytes, unchanged.

A `404` or `9xxx` error on `/cdn-cgi/image/` means transformations are not enabled for that zone: remove the host from `imageTransformOrigins` until they are.

Authorities: `backend/src/api/models.ts`, `backend/src/lib/public-types/generate.ts`, `backend/src/lib/public-types/contract.ts`, `frontend/static/dee-wan-client.mjs`, `backend/src/api/content_lifecycle.ts`, `backend/src/lib/site-settings.ts`, `backend/src/lib/graduate/site-media-presentation.ts`, `backend/src/lib/graduate/site-emit.ts`, `backend/src/lib/field-link-runtime.ts` and `backend/src/lib/page-contract/field-links.ts`.

## Next step

Read the [public read API](/reference/public-api/) for the full read contract, filters and refusals.

<!-- dee-wan-docs page: /reference/public-api/ -->

# Public read API (v1)

Source: https://dee-wan-docs.pages.dev/reference/public-api/

The public read API serves published content to your site. Every endpoint below resolves the site from the `Host` header and from nothing else. There is no site parameter or site header for selecting another site. Site tokens remain bound to the resolved site. An explicit shared-content grant can add a source-owned published public projection; it never permits arbitrary source-site queries or source editing.

This API only reads. To create, edit, publish or upload from a script or an AI agent, use the [CMS management API](/reference/management-api/) with a management credential.

## Hostnames, CORS and rate limits

The public API runs as its own Worker. It serves a site on the hostname stored as
that site's domain: the `Host` header, lowercased and without a port, must equal
it exactly. There is no `www` aliasing and no fallback to another site.

### Browser origins

Under **Settings → API → Browser origins**, an infrastructure administrator can
allow website origins to read this live API directly. Enter one complete HTTP(S)
origin per line, without a trailing slash or path: `https://www.example.com` or
`http://localhost:5173`. The default empty list allows no cross-origin browser
reads. `*` allows public reads from every origin. It never enables browser
cookies; no response grants credentialed CORS. Keep private site API tokens on
your server.

Allowed origins receive CORS headers on successful reads and errors. An
`OPTIONS` preflight accepts only `GET`, `HEAD` and `OPTIONS`, with
`Authorization`, `Content-Type`, `X-Site-Key`, `X-Site-Token` and
`X-Dee-Wan-Preview-Challenge` headers. Unknown origins receive no allow-origin
header. Every request still resolves the site by hostname and checks its normal
publication and token rules. This setting affects only the live `/v1` reader;
it does not change the admin, management or generated application API.

Server-side and build-time calls do not need CORS configuration.

The Worker applies no rate limit of its own. If you need one, configure it on the
Cloudflare zone that serves the public hostname.

## GET /v1/_sync

**Synchronize published content.** Read a bounded initial snapshot, then ordered entry and public-media changes with signed checkpoints. Existing scoped site tokens and CORS apply.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `cursor` | no | Unmodified next_cursor or checkpoint from the previous page. |
| `limit` | no | Page size 1–100; default 50. |
| `model` | no | Restrict entries to one authorized model slug. |
| `locale` | no | Restrict entries to one locale. |

| Status | Meaning |
| --- | --- |
| 200 | Snapshot or ordered changes, plus continuation or checkpoint. |
| 400 | sync_query_invalid: invalid or unauthorized model/query. |
| 404 | Unknown host or invalid site token. |
| 409 | reset_required: start a new snapshot. |
| 503 | sync_dependency_unavailable: retry the same checkpoint. |

```bash
GET /v1/_sync?limit=50
```

```json
{ "data": [], "deleted": [], "changes": [], "phase": "entries", "next_cursor": "opaque", "checkpoint": null, "reset_reason": null }
```

## GET /health

**Check whether this host serves a site.** Answers only for a host this deployment knows. An unknown host is a 404 here, as it is on every other route, so this route cannot be used to discover which sites exist.

| Status | Meaning |
| --- | --- |
| 200 | This host serves a site. The body carries the site's slug. |
| 404 | `unknown_host`: no active site answers on this host. |

```bash
curl https://example.com/health
```

```json
{ "ok": true, "site": "acme" }
```

## GET /v1/:model

**List published items of one model.** Published items only, ordered by publication time and then by id unless `sort` names a field. Locale membership, filters and pagination are handled in the database. So a page is never shorter than `limit` because something was dropped afterwards. A page shorter than `limit` with `has_more: false` is the end of the list.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `locale` | no | Which language to serve, as a code matching `^[A-Za-z0-9_-]{1,64}$`. Defaults to the site's default language. What happens when an item has no content in that language is decided by the site's locale policy, not by this parameter. See Locales below. |
| `origin` | no | Latitude,longitude for nearest point sorting; required with sort on a point field. |
| `limit` | no | Page size, a whole number from 1 to 100. Default 20. Anything else, including a value over 100, is refused with 400 `public_filter_invalid`. It is never clamped. |
| `cursor` | no | Opaque. Take it from `page.next_cursor` and send it back unchanged, with exactly the query it was issued under: the same model path, `locale`, `order` or `sort`, filters and their values, `fields` and `expand`. Only `limit` may change. A cursor sent with any other query is refused with 400 `public_cursor_mismatch`. One that does not decode, or one issued before cursors carried their query, is refused with 400 `public_filter_invalid`. Start again from the first page. Its contents are not a contract and will change. |
| `order` | no | `asc`, `desc`, `manual` — Direction by publication time. `desc` (newest first) is the default. `manual` requests the collection-wide editorial order when enabled; it is shared across languages. Do not use `order` with `sort`. A manual-order cursor is refused after that order changes; restart from the first page. |
| `filter` | no | `filter[<field>]=<value>` keeps items whose field equals the value in the served locale. Repeat it for alternatives: `filter[kind]=guide&filter[kind]=news` keeps items whose kind is either, at most 10 values per field. Text, slug and select fields compare text. A boolean field takes `true` or `false`. A number field takes a decimal number. A date field takes `YYYY-MM-DD` and compares the calendar day. On number and date fields, `filter[<field>][gt]` and `[lt]` are exclusive bounds, `[gte]` and `[lte]` inclusive ones. A field takes one lower bound (`gt` or `gte`) and one upper bound (`lt` or `lte`), never both kinds of one side and never with equality. A range no value can satisfy, such as `[gt]=5&[lt]=5`, is `public_filter_invalid`. Different fields are ANDed, at most 4 fields per request. Each value is at most 255 characters. More fields is `public_filter_too_many`, more values `public_filter_too_many_values`, a field whose type cannot be filtered this way `public_filter_type_unsupported`, an unknown field or a malformed value `public_filter_invalid`. A request is never narrowed. A text value longer than 255 characters is never matched or sorted on. |
| `sort` | no | One number, date, text or select field: `sort=<field>` ascending, `sort=-<field>` descending, then by id. Items without a value of that type come last in both directions. Do not use it with `order`. |
| `fields` | no | Comma-separated top-level field keys to return, at most 32, no repeats. `id`, `slug` and `locale` are always returned. |
| `relation` | no | Filter by a relation field, as `relation=<field>:<target item id>`. Keeps items whose relation field serves that target in `relations`. A target this request cannot read never matches. `<field>` must be a relation field of this model that accepts one model; a field that accepts several is refused with `public_filter_type_unsupported`. You can repeat this parameter. Repeated parameters are ANDed. |
| `tag` | no | Filter by a relation field, matched by the target's slug: `tag=<field>:<target slug>`. Only a target the item serves in `relations` matches, by the published address served there: in the language the item is served in, then along the site's fallback chain. Under `strict`, a translated target with no published version in that language does not match. An untranslated target matches in any language. There is no separate tag field type. `<field>` must be a relation field of this model that accepts one model; a field that accepts several is refused with `public_filter_type_unsupported`. You can repeat this parameter. Repeated parameters are ANDed. At most 16 `relation` and `tag` pairs per request in total. More is refused with 400 `public_filter_too_many`, whose body carries `max`. A request is never silently narrowed to fit. |
| `expand` | no | For ordinary reads and older preview links without the related-draft grant: Comma-separated relation fields of this model, at most 3, no repeats. Each item then carries `expanded.<field>`: `{ data, page }`, where `data` holds the targets as items of the field's target model, in the field's order. Only published targets of this site that this request may read are served, in the requested locale under the site's locale policy, the same as a read of the target model. A private target model is served only on a private model's read whose token names it. At most 25 targets per field are inline; when there are more, `page.next_cursor` reads the rest from `/v1/_related/:model`. One level only: an expanded item carries `relations`, never `expanded`. A dotted path is refused with `public_expand_too_deep`, more fields with `public_expand_too_many`, and a field that is not a relation field of this model, or that accepts several models, with `public_expand_invalid`. New shared preview links automatically expand authorized saved drafts instead; see [draft previews](/guides/preview-and-client/#open-an-actual-rendered-draft-preview). |

| Status | Meaning |
| --- | --- |
| 200 | A page of items in `data`, with `page.limit`, `page.has_more` and `page.next_cursor` beside it. `next_cursor` is `null` on the last page. |
| 400 | `public_filter_invalid`: an unknown parameter, an empty value, a repeated parameter that is not `relation`, `tag` or `filter[<field>]`, or a malformed value. This reason also covers a `relation` or `tag` field that is not a relation field of this model, or a cursor that does not decode. `public_filter_too_many`, `public_filter_too_many_values`: past a cap, which `max` names. `public_filter_type_unsupported`: a field filter on a type that cannot take it. `public_cursor_mismatch`: a cursor from another query. `public_expand_invalid`, `public_expand_too_many`, `public_expand_too_deep`: see `expand`. |
| 404 | No site on this host (`unknown_host`), or no model with this slug, or a private model and no valid site API token. The last two give the same body with no `reason`, so a caller cannot tell a private model from a missing one. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl 'https://example.com/v1/article?locale=th&limit=10&order=desc'
```

```json
{ "contracts": { "page": { "served": 5 } },
  "data": [
    { "id": "ci_…", "slug": "hello", "model": "article", "locale": "th", "version": 3,
      "published_at": "2026-09-01T08:00:00.000Z",
      "fields": { "title": "สวัสดี" }, "relations": {}, "media": {} }
  ],
  "page": { "limit": 10, "has_more": true, "next_cursor": "…" } }
```

## GET /v1/:model/:slug

**Read one published item.** One item, by the slug of its published version. Each language has its own slug: `/v1/post/bonjour?locale=fr` serves the French language of the entry whose English slug is `hello`, and a language answers only at its own slug. A slug is unique within a model and a language on a site, never across sites. Renaming a draft does not move a published address until the rename is published. The item carries `alternates`: `[{ locale, slug }]`, every language the entry is live in with that language's own slug, the served one included.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `locale` | no | Which language to serve, as a code matching `^[A-Za-z0-9_-]{1,64}$`. Defaults to the site's default language. What happens when an item has no content in that language is decided by the site's locale policy, not by this parameter. See Locales below. |
| `preview` | no | A preview token (`dw_prev_…`) minted by the CMS when an editor opens a preview. It serves the current DRAFT of ONE root item, matched against the draft's slug, for 30 minutes. A served preview is never cached. It does not make a private model readable. A token that does not verify answers 404, not 403. New shared links also read authorized related saved drafts and recheck their creator's current rights; the root field and locale scope stays within the recorded grant. See [draft previews](/guides/preview-and-client/#open-an-actual-rendered-draft-preview). |
| `expand` | no | For ordinary reads and older preview links without the related-draft grant: Comma-separated relation fields of this model, at most 3, no repeats. Each item then carries `expanded.<field>`: `{ data, page }`, where `data` holds the targets as items of the field's target model, in the field's order. Only published targets of this site that this request may read are served, in the requested locale under the site's locale policy, the same as a read of the target model. A private target model is served only on a private model's read whose token names it. At most 25 targets per field are inline; when there are more, `page.next_cursor` reads the rest from `/v1/_related/:model`. One level only: an expanded item carries `relations`, never `expanded`. A dotted path is refused with `public_expand_too_deep`, more fields with `public_expand_too_many`, and a field that is not a relation field of this model, or that accepts several models, with `public_expand_invalid`. New shared preview links automatically expand authorized saved drafts instead; see [draft previews](/guides/preview-and-client/#open-an-actual-rendered-draft-preview). |

| Status | Meaning |
| --- | --- |
| 200 | The item, projected into one locale. |
| 400 | `public_filter_invalid`: a parameter other than `locale`, `preview` and `expand`, a repeated or empty parameter, or a malformed `locale`. `public_expand_invalid`, `public_expand_too_many`, `public_expand_too_deep`: see `expand`. |
| 404 | `unknown_host`: no site on this host. `locale_unavailable`: the item is published but has no content the site's locale policy will serve. `ambiguous_slug`: two published items claim this slug, so neither is served. No `reason`: no such model, no published item with this slug, or a preview token that did not verify. A private model without a valid token also returns this response. |
| 422 | Preview of a page only: the draft page's media cannot be presented. `reason` is one of `unreadable_page`, `page_media_unavailable`, `media_presentation_unreadable`, `media_presentation_revision_unavailable`, `media_presentation_mismatch`, `media_size_missing`, and `error` carries a readable message. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl 'https://example.com/v1/article/hello?locale=th'
```

```json
{ "contracts": { "page": { "served": 5 } }, "data": { "id": "ci_…", "slug": "hello", "model": "article", "locale": "th", "version": 3,
      "published_at": "2026-09-01T08:00:00.000Z",
      "fields": { "title": "สวัสดี" }, "relations": {}, "media": {} } }
```

## GET /v1/_related/:model

**Read the rest of an expanded relation field.** The targets of one expanded relation field past the first page. `:model` is the model of the item that carried the field. The cursor names that item, its published version, the field and the locale. The same rules as `expand` decide what is served. The cursor works only on this site, for this model, and for a token with the same model scope as the request that minted it. A private model needs its token here too.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `cursor` | yes | The `expanded.<field>.page.next_cursor` of an item, or the `page.next_cursor` of a previous answer here. Send it back unchanged. One from another site, model or token scope is refused with `public_cursor_mismatch`. After the item is published again, it is refused with `public_cursor_stale`: read the item again. |
| `limit` | no | Page size, a whole number from 1 to 100. Default 25. |

| Status | Meaning |
| --- | --- |
| 200 | A page of related items in `data`, with `page.limit`, `page.has_more` and `page.next_cursor`. |
| 400 | `public_filter_invalid`: no `cursor`, a parameter other than `cursor` and `limit`, a repeated or empty one, a bad `limit`, or a cursor that does not decode. `public_cursor_mismatch`: a cursor from another site, model or token scope. `public_cursor_stale`: the item was published again, or the field is no longer an expandable relation field. |
| 404 | `unknown_host`: no site on this host. No `reason`: no such model, a private model without a valid token, or the item is no longer published in that locale. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl 'https://example.com/v1/_related/article?cursor=…&limit=25'
```

```json
{ "contracts": { "page": { "served": 5 } },
  "data": [ { "id": "ci_…", "slug": "ana", "model": "author", "locale": "en", … } ],
  "page": { "limit": 25, "has_more": false, "next_cursor": null } }
```

## GET /v1/_client

**Download the typed TypeScript client.** The dependency-free client for this host's site, with the schema identity it was generated from. Needs a site API token, even when every model is public. The client covers every public model and the private models the token may read. `schema_identity` is a SHA-256 digest of `contract`: locales, locale policy, and each model's visibility and field types. Labels and field order do not change it. `source` starts with a comment recording the same values. The Settings → API command reads this route. The response is never cached.

| Status | Meaning |
| --- | --- |
| 200 | `data` holds `contract_version` (1), `schema_identity`, `site`, `url`, `models`, `contract` and `source`. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | No site on this host (`unknown_host`), or no valid site API token for this site. A missing, expired, revoked or other-site token gets the same body with no `reason`. |

```bash
curl -H "Authorization: Bearer $DEE_WAN_SITE_TOKEN" https://example.com/v1/_client
```

```json
{ "data": { "contract_version": 1, "schema_identity": "sha256:9f2c…", "site": "acme",
    "url": "https://example.com", "models": ["article"],
    "contract": { "site": "acme", "default_locale": "en", "locales": ["en", "th"],
      "locale_policy": "strict", "models": { "article": { "visibility": "public",
        "fields": { "title": { "type": "text", "required": true, "multiple": false,
          "options": null } } } } },
    "source": "/* @dee-wan/public-client …" } }
```

## GET /v1/_redirects

**Read the accepted redirect list.** The redirect rules in the site's accepted Site Chrome: manual ones and the ones a publication added when it moved a live address. A renderer reads this when a path matches no page. `match: "exact"` names one path; `match: "pattern"` binds `{name}` segments and a final `{name*}` that `to` may reuse. An exact rule wins over a pattern, and the pattern with the most literal segments wins over the others. `status` is 301, 302, 307 or 308 with a `to` (a path on this site or an https address), or 410 (gone) or 451 (unavailable for legal reasons) with `to: null`. An unaccepted Site Chrome draft never appears here. The answer is the same with or without a token, is cached, and is purged when Site Chrome is accepted.

| Status | Meaning |
| --- | --- |
| 200 | `data.redirects`: a list of `{ from, match, status, to }`, possibly empty. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | `unknown_host`: no site on this host. |
| 500 | `site_chrome_unreadable`: the accepted Site Chrome version no longer matches its recorded digest. An administrator has to accept a version again. |

```bash
curl https://example.com/v1/_redirects
```

```json
{ "data": { "redirects": [
    { "from": "/tours-old", "match": "exact", "status": 301, "to": "/tours" },
    { "from": "/news/{rest*}", "match": "pattern", "status": 308, "to": "/blog/{rest}" },
    { "from": "/old-offer", "match": "exact", "status": 410, "to": null } ] } }
```

## GET /v1/_chrome

**Read the menus and regions of one language.** The menus, template regions and footer note of the site's accepted Site Chrome, resolved for one language. A menu item that points at a page, post, Blog list or archive carries that item's live address in this language today (the site's locale rule decides fallback); an item whose page is not live, or whose model is private, is left out, and a heading left with no items under it is left out too. Each language owns its own menu items; a language without its own version follows the site's strict or fallback rule. `placements` says which menu the header and the footer show in this language. `regions` holds each region the site's template declares that shows something in this language, with its items in order: a shared section's published sections, a menu, the search page, recent Blog posts, categories, tags or posts by month. A shared section carries the entries of each of its Latest entries sections, read as `GET /v1/:model` reads them: published only, in this language or its fallback, at most the section's limit. Posts by month links the 30 newest posts at most, grouped into 12 months at most; a month has no address of its own. A managed renderer reads this on every page, so menu and region changes and moved pages need no new release. The answer is the same with or without a token, is cached, and is purged when Site Chrome is accepted or a referenced model or shared section publishes.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `locale` | no | A language of this site. Absent means the default language. |

| Status | Meaning |
| --- | --- |
| 200 | `data`: `{ locale, menus: { [key]: { lang, items: [{ id, label, href, children: [{ id, label, href }] }] } }, placements: { header, footer }, footer_note: { lang, text } | null, regions: { [key]: { lang, items } } }`. `lang` is the language actually served: the menu’s or region’s own version for `locale`, else, under the site’s fallback rule, the first along its chain. A strict site serves only `locale`; a menu with no version there is absent. A heading has `href: null`. A region item is `{ kind: "shared_section", entry, lang, document, collections? }`, `{ kind: "menu", menu, name, lang, items }`, `{ kind: "search", href }`, `{ kind: "recent_posts" | "categories" | "tags", links: [{ label, href }] }` or `{ kind: "monthly_archive", months: [{ month: "YYYY-MM", links }] }` (Posts by month). `collections` maps each Latest entries section id to `{ ok: true, entries }` or `{ ok: false, code }`; it is absent when the shared section holds none. |
| 400 | `public_chrome_invalid`: `locale` is not a language of this site. `public_filter_invalid`: another query parameter, or `locale` twice. |
| 404 | `unknown_host`: no site on this host. |
| 500 | `site_chrome_unreadable`: the accepted Site Chrome version no longer matches its recorded digest. An administrator has to accept a version again. |

```bash
curl https://example.com/v1/_chrome?locale=th
```

```json
{ "data": { "locale": "th", "menus": { "main": { "lang": "th", "items": [
    { "id": "mi_about", "label": "เกี่ยวกับ", "href": "/th/about", "children": [] },
    { "id": "mi_help", "label": "Help", "href": null, "children": [
      { "id": "mi_call", "label": "Call", "href": "tel:+6621234567" } ] } ] } },
  "placements": { "header": "main", "footer": null }, "footer_note": null,
  "regions": { "page_end": { "lang": "th", "items": [ { "kind": "search", "href": "/th/search" } ] } } } }
```

## GET /v1/_embeds

**Read the embed origins.** The https origins an administrator added under Settings → Integrations, besides the built-in YouTube and Vimeo players. A renderer frames a rich-text embed from one of these origins only while it is listed here, and otherwise draws a plain link to the same address. Each `id` is the origin's host, and an embed block names it as `data-provider`. Dee Wan's renderers read this only for a document that holds such an embed. The answer is the same with or without a token, is cached, and is purged when the list is saved.

| Status | Meaning |
| --- | --- |
| 200 | `data.providers`: a list of `{ id, origin }`, possibly empty. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | `unknown_host`: no site on this host. |

```bash
curl https://example.com/v1/_embeds
```

```json
{ "data": { "providers": [ { "id": "maps.example.com", "origin": "https://maps.example.com" } ] } }
```

## GET /v1/_rich-blocks

**Read the plugin rich block definitions.** The rich-text block types the site's active plugins declare: fields, labels and a render tree built from a fixed element list, never markup. A stored block names its `type` and `version` in `data-type` and `data-version` on `<figure data-block="plugin">`. A renderer draws a block from its definition's `render` tree, escaping every value, and draws nothing for a block whose type is not listed, whose definition has no `render`, or whose version is newer than the listed one. Dee Wan's renderers read this only for a document that holds a plugin block. The answer is the same with or without a token, is cached, and is purged when a plugin is installed, upgraded, disabled, enabled or removed.

| Status | Meaning |
| --- | --- |
| 200 | `data.blocks`: a list of definitions, possibly empty. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | `unknown_host`: no site on this host. |

```bash
curl https://example.com/v1/_rich-blocks
```

```json
{ "data": { "blocks": [ { "type": "com.example.notes/callout", "plugin": "com.example.notes", "name": "callout", "version": 1, "label": "Callout", "fields": [ { "key": "title", "control": "text", "label": "Title" } ], "render": { "nodes": [ { "element": "strong", "children": [ { "field": "title" } ] } ] } } ] } }
```

## GET /v1/_sitemap

**Read the robots policy and the sitemap chunks.** What `/robots.txt` and `/sitemap.xml` say for this site. `robots` is the accepted Site Chrome policy. `sitemap.chunks` names every chunk of live addresses, per model, 5,000 addresses at most each; a renderer lists each at `/sitemap-<model>-<number>.xml`. Empty when the sitemap is off. Only public models and live versions count; a page marked noindex is never listed. Cached, and purged when Site Chrome is accepted or a listed model publishes.

| Status | Meaning |
| --- | --- |
| 200 | `data.robots`: `{ allow_indexing, disallow }`; `data.sitemap`: `{ enabled, change_frequency, chunks: [{ model, number, lastmod }] }`. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | `unknown_host`: no site on this host. |

```bash
curl https://example.com/v1/_sitemap
```

```json
{ "data": { "robots": { "allow_indexing": true, "disallow": [] },
    "sitemap": { "enabled": true, "change_frequency": "weekly",
      "chunks": [ { "model": "page", "number": 1, "lastmod": "2026-10-01T09:00:00.000Z" } ] } } }
```

## GET /v1/_sitemap/:model/:number

**Read one sitemap chunk.** The live addresses of one chunk `/v1/_sitemap` named: each language member at its own address, with its last publication and up to 20 images (the social image, then the images its live version shows). `model` and `number` are a chunk `/v1/_sitemap` listed. A Blog's list addresses lead the `post` chunks.

| Status | Meaning |
| --- | --- |
| 200 | `data.entries`: a list of `{ path, lastmod, images }`. |
| 400 | `public_filter_invalid`: the request carried a query string. |
| 404 | `sitemap_chunk_missing`: no such chunk, or the sitemap is off. |

```bash
curl https://example.com/v1/_sitemap/page/1
```

```json
{ "data": { "model": "page", "number": 1, "entries": [
    { "path": "/tours", "lastmod": "2026-10-01T09:00:00.000Z", "images": ["https://media.example.com/boat.jpg"] } ] } }
```

## GET /v1/_search

**Search the live site.** Site search over what is live now: published pages, Blog posts on a Blog site, and the other public models the site search setting names. A draft, an unpublished language, an item in Trash, a shared section and a private model never appear, and a publication, withdrawal or address move shows up at once. Each result is served in the requested language or, under the fallback policy, the first available language in its fallback chain; `slug` is that language's live address. Every word of `q` must match, by the model's matching from the search setting: `word` (the default) whole words, `english_stem` English word forms (`tours` finds `tour`) in a result served in English (`en`, `en-*` or `en_*`) and whole words in a result served in any other language, `substring` anywhere inside a word. Words are letters, marks and digits; anything else only separates them. Results with every word in the title come first, then the newest. A model the site tunes under Settings → Source & delivery is searched by its chosen fields only and ranks by the highest weight, 1 to 10, among those fields that hold every word; an untuned title match counts as 10. A relation field matches by the labels of the targets a public read serves the item in `relations`, read when searching. A target's draft label never matches, nor does a target that is unpublished, in Trash or in a private model, and `summary` never holds a relation label. Without `q` the answer is empty and says only that search runs here. The same answer for every caller, cached at most five minutes and purged on every publication.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `q` | no | What to find: 1 to 200 characters and at most 6 words of at most 64 characters each, compared without case. |
| `locale` | no | Which language to serve, as a code matching `^[A-Za-z0-9_-]{1,64}$`. Defaults to the site's default language. What happens when an item has no content in that language is decided by the site's locale policy, not by this parameter. See Locales below. |
| `limit` | no | Results per page, 1 to 20. Defaults to 10. |
| `cursor` | no | The `page.next_cursor` of the previous answer to the same `q` and `locale`, under the same search tuning, matching and language fallback. |

| Status | Meaning |
| --- | --- |
| 200 | `query`, `data`: a list of `{ kind, id, model, slug, locale, title, summary, published_at }` (`kind` is `page`, `post` or `entry`), `page`: `{ limit, has_more, next_cursor }`, `locale`: `{ requested, default }`. |
| 400 | `public_search_invalid`: an unknown or repeated key, an empty value, a query out of bounds, a bad `limit`, or a cursor from another query or from before the search tuning, matching or language fallback changed. |
| 404 | `search_off`: site search is off. `locale_unknown`: the site has no such language. `unknown_host`: no site on this host. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl "https://example.com/v1/_search?q=lighthouse&locale=en"
```

```json
{ "query": "lighthouse", "data": [
    { "kind": "page", "id": "ci_1", "model": "page", "slug": "tours", "locale": "en",
      "title": "Lighthouse tours", "summary": "Walk the cliffs at dawn.", "published_at": "2026-10-01T09:00:00.000Z" } ],
  "page": { "limit": 10, "has_more": false, "next_cursor": null },
  "locale": { "requested": "en", "default": "en" } }
```

## GET /v1/_search/suggest

**Suggest while typing.** Up to `limit` live items for a query still being typed, from the same rows and rules as `/v1/_search`: published pages, Blog posts on a Blog site and the chosen public models, in the requested language or the first available language in its fallback chain; never a draft, an unpublished language, Trash, a shared section or a private model. Every word of `q` matches by the model's matching, as in `/v1/_search`, except the last word, which may be partial: it matches the start of a word (anywhere inside one under `substring`); a tuned model matches by its chosen fields only. Items whose title starts with `q` come first, then items whose title contains every word, then text-only matches; then the newest. `slug` is the served language's live address, as in `/v1/_search`. Nothing about the query is recorded. The same answer for every caller, cached at most five minutes and purged on every publication. Managed and generated sites ask it through their own `/search?suggest=<q>&locale=<code>`, which answers `{ data: [{ title, summary, href, kind }] }` with each address as that site links it.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `q` | yes | What is being typed: 2 to 100 characters and at most 6 words of at most 64 characters each, compared without case. |
| `locale` | yes | Which language to serve, as a code matching `^[A-Za-z0-9_-]{1,64}$`. Fallback follows the site's locale policy, as in `/v1/_search`. |
| `limit` | no | Suggestions to return, 1 to 10. Defaults to 5. |

| Status | Meaning |
| --- | --- |
| 200 | `query`, `data`: a list of `{ kind, id, model, slug, locale, title, summary, published_at }` (`kind` is `page`, `post` or `entry`), `limit`, `locale`: `{ requested, default }`. |
| 400 | `public_search_invalid`: a missing `q` or `locale`, an unknown or repeated key, an empty value, a query out of bounds or a bad `limit`. |
| 404 | `search_off`: site search is off. `locale_unknown`: the site has no such language. `unknown_host`: no site on this host. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl "https://example.com/v1/_search/suggest?q=light&locale=en"
```

```json
{ "query": "light", "data": [
    { "kind": "page", "id": "ci_1", "model": "page", "slug": "tours", "locale": "en",
      "title": "Lighthouse tours", "summary": "Walk the cliffs at dawn.", "published_at": "2026-10-01T09:00:00.000Z" } ],
  "limit": 5, "locale": { "requested": "en", "default": "en" } }
```

## GET /v1/_feed

**Read the Blog feed.** The newest 20 published Blog posts in one language, exactly as the Blog list serves them, for a renderer to write as RSS at `/rss.xml` (the default language) and `/<code>/rss.xml`. `summary` is the post's search description, or the start of its text. A post leaves the feed when it is unpublished or moved to Trash. Cached at most five minutes and purged on every publication.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `locale` | no | Which language to serve, as a code matching `^[A-Za-z0-9_-]{1,64}$`. Defaults to the site's default language. What happens when an item has no content in that language is decided by the site's locale policy, not by this parameter. See Locales below. |

| Status | Meaning |
| --- | --- |
| 200 | `data`: `{ title, locale, default_locale, items }`, each item `{ id, slug, locale, title, summary, authors, date, published_at }`. |
| 400 | `public_feed_invalid`: a key other than `locale`, repeated or empty. |
| 404 | `feed_unavailable`: the site is not a Blog, or its posts are not public. `locale_unknown`: the site has no such language. |
| 500 | `site_locale_policy_invalid`: the site has no usable locale policy stored. An administrator has to set one under Settings → Languages. An unexpected failure returns a plain-text `Internal Server Error`. |

```bash
curl "https://example.com/v1/_feed?locale=en"
```

```json
{ "data": { "title": "Harbour notes", "locale": "en", "default_locale": "en", "items": [
    { "id": "ci_9", "slug": "first-light", "locale": "en", "title": "First light",
      "summary": "Fog lifted at six.", "authors": ["Ana Lima"], "date": "2026-10-01",
      "published_at": "2026-10-01T09:00:00.000Z" } ] } }
```

## GET /v1/_comments

**Read an entry's comments.** Approved visitor comments on one live entry of a model that takes comments (a Blog post, or any model whose comments setting is on), in the language of the item you name: top-level comments in the order you ask, each with at most 20 approved replies, oldest first. A comment carries only its id, display name, website, text, time and reaction counts. Email, moderation state, who reacted and anything used against abuse are never served. `count` counts approved comments and replies and stops at 999 (`count_capped`). Comments hide while the entry is unpublished or in Trash. While its model takes no comments the answer is a closed page (`open: false`, no threads). New comments are posted to `POST /v1/interactions/comment.submit` and reactions to `POST /v1/interactions/comment.react` on the site host, served by the intake Worker. Cached at most five minutes and purged on every moderation change, publication and change of the model's comments setting.

| Parameter | Required | Meaning |
| --- | --- | --- |
| `entry` | yes | The `id` of a published entry item. |
| `order` | no | `oldest` (default), `newest`, or `best`: most `helpful` reactions first, equal counts oldest first, then by id. |
| `cursor` | no | The previous page's `next_cursor`. A cursor works only for the entry and order it came from. |
| `limit` | no | Top-level comments per page, 1 to 50. Defaults to 20. |

| Status | Meaning |
| --- | --- |
| 200 | `data`: `{ entry, locale, order, open, count, count_capped, threads, next_cursor }`, each thread `{ id, name, website, body, created_at, reactions, replies, more_replies }` and each reply `{ id, name, website, body, created_at, reactions }`. `reactions` is `{ helpful }`. |
| 400 | `public_comments_invalid`: a missing or malformed `entry`, an unknown `order`, another key, a repeated or empty value, a bad `limit` or a cursor from another entry or order. |
| 404 | `comments_unavailable`: the entry is not live in its language, or its model is private. Never cached. |

```bash
curl "https://example.com/v1/_comments?entry=ci_9&order=best&limit=20"
```

```json
{ "data": { "entry": "ci_9", "locale": "en", "order": "best", "open": true, "count": 2, "count_capped": false, "threads": [
    { "id": "cm_1", "name": "Ana", "website": null, "body": "Lovely light.", "reactions": { "helpful": 3 },
      "created_at": "2026-10-02T08:00:00.000Z", "more_replies": false, "replies": [
        { "id": "cm_2", "name": "Bo", "website": "https://bo.example/", "body": "Agreed.",
          "reactions": { "helpful": 0 }, "created_at": "2026-10-02T09:00:00.000Z" } ] } ], "next_cursor": null } }
```

## Items

Both `/v1` routes return items of this shape:

| Key | Type | Meaning |
| --- | --- | --- |
| `id` | string | The item's id. Stable across edits and renames. |
| `slug` | string or null | The served version's slug; the draft's during preview. `null` when the item has none. |
| `model` | string | The model's slug. |
| `locale` | string | The locale the fields were served in. Under the fallback policy it can differ from the one you asked for. |
| `version` | number | The served saved version number; the draft’s during preview. |
| `published_at` | string or null | ISO 8601 publication time. |
| `fields` | object | Field values for the served locale, keyed by field key. A field the model does not translate has one value, served in every locale and used by `sort` and `filter` in every locale. |
| `relations` | object | For ordinary reads and older preview links without the related-draft grant: For each relation field, an ordered list of `{ instance_id, model, slug, display }` with only the targets this request can read: published, not in Trash, and in a public model, or in a private model only on a private model's read whose token names both. `slug` and `display` are the target's published address and label, read now. `display` is null when the label field is private. `model` is the slug of the target's model; a field that accepts several models serves targets of each in the list's order. Any other target is left out, as if it were not linked. A translated target is served in the item's language, then along the site's fallback chain. Under `strict`, a translated target with no published version in that language is left out. An untranslated target is served in any language. New shared preview links use each authorized target’s latest saved draft, including never-published entries; addresses and labels come from those drafts. The creator’s current item, field and locale rights apply. Private fields and unreadable or trashed targets are omitted. See [draft previews](/guides/preview-and-client/#open-an-actual-rendered-draft-preview). |
| `expanded` | object | For ordinary reads and older preview links without the related-draft grant: Only with `expand`. For each named relation field, `{ data, page }`: up to 25 targets as items, and `page.next_cursor` for the rest at `/v1/_related/:model`. New shared preview links populate this automatically for ordinary and component relationships, up to four levels and 128 targets across one root response. Cycles stop at stable identities. Draft expansion does not use public relation cursors. |
| `media` | object | For each media field, an ordered list of `{ media_id, name, mime_type, kind, size, url, thumbnail_url, alt, width, height }`. `kind` is `image`, `document`, `audio`, `video` or `file`; show an image with `<img>`, audio and video with their elements and a download link, and a document as a link with its name, type and size. `width` and `height` are null for anything that is not an image. An entry also carries `crop` (`{ x, y, width, height }`) and `focal` (`{ x, y }`) when the editor set them, as fractions 0–1 of the stored image. They describe how to show an image and are never set on other files. The bytes and `url` are unchanged, and no resized or cropped copy is served. A file copied from a media source also carries a read-only `credit`: `{ author, source, license, url }` (`author` and `url` may be null), as it was when the entry was saved. Show it under the image. A private file of a private model (it may be used only there) carries `visibility: "private"` with an empty `url` and a null `thumbnail_url`: its address is withheld, and the bytes come from your application's own sign-in, never from this API. |

Rich-text fields hold one rich document, stored as its canonical HTML: paragraphs,
headings, lists, quotes, code blocks, rules, tables, image galleries, audio,
video and file blocks, and embeds. Every write is checked, and
markup outside that set is refused, so the API never serves scripts, styles,
event attributes or frames. Blocks are written as data, not as players: a media
block is `<figure data-block="video|audio|file">` holding one link with
`data-media-id`, `type` and `data-size`, and an embed is
`<figure data-block="embed" data-provider data-url data-title>` with no `<iframe>`.
`data-provider` is `youtube`, `vimeo` or a configured origin's host, and
`data-url` is its canonical https frame address. Pass the origins from
`/v1/_embeds` to frame a configured provider; without them it renders as a link.
Render it the way Dee Wan's own renderers do, with `renderRichDocument` from the page
contract ([Blog sites](/guides/blog/#rich-text-safety)).

A preview response also carries `preview_identity`, may carry
`preview_attestation`, and for page models carries `mediaPresentation`.
Published responses never carry any of the three.

Each language of a translation group is published on its own and serves its own
published version, so the list returns one item per group: the language the
locale policy serves, from that language's own published version. A language
that is not published is never served from another language's version.

### Private fields

A field marked Private in the Model Builder is never served: it is absent from `fields`,
`relations` and `media` of every item, expanded item and related page, from the Blog feed and
from site search. Inside a component value, a private component field is absent too. A query
that names a private field in `filter[...]`, `sort`, `fields`, `relation`, `expand` or a related
cursor gets the same refusal as a field that does not exist, so a query cannot learn its value or
that it exists. This applies to private models read with a token as well.

Only the fields a model declares now are served. A published version keeps a renamed or deleted
field's old key in storage, but no public read serves a value under it: not in `fields`,
`relations`, `media`, inside a component value, the Blog feed or site search. So a field
that was private and is then renamed or deleted never reappears under its old key. A field
cannot take such a key while a kept version still holds a value under it: the model or component
save is refused with `retained_key_reuse`, so an old value never reappears under a new field.

### Single-entry models

A single-entry model holds at most one entry. Its routes are the ordinary ones:
`GET /v1/<model>` answers a list of at most one item, with the usual envelope, and
`GET /v1/<model>/<slug>` answers it by address. Read the list when the address is not known.

## Locales

Each site has a locale policy, set under Settings → Languages:

- **strict**: an item is served only in the requested locale, and only while that
  language is published. The list leaves out items without it. The item route
  answers 404 `locale_unavailable`. Fallback languages are ignored.
- **fallback**: the requested locale, then that locale's fallback languages, then
  the site's default language, then the item's own primary language, each only
  while that language is published. The item's `locale` key names the one
  actually served.

Fallback languages are set per language under Settings → Languages → Missing translations, in
order, while a missing translation shows the default-language page. A
fallback language's own fallbacks follow it: `pt-BR → pt` and `pt → es` serve
`pt-BR`, `pt`, `es`, then the default. Cycles and unknown languages are
refused when saved. A site with none set falls back to its default alone.

A caller cannot override the policy or the fallback languages.

## Errors

Every JSON error body has the shape `{ "error": string, "reason"?: string }`.
`public_filter_too_many`, `public_filter_too_many_values`,
`public_expand_too_many` and `public_expand_too_deep` add `max`. Branch on
`reason` and on the status, never on the text of `error`.

| Status | `reason` | When |
| --- | --- | --- |
| 400 | `public_filter_invalid` | Any rejected query: unknown or repeated parameter, empty value, bad `limit`, `order`, `locale`, filter or cursor. |
| 400 | `public_filter_too_many` | More than 16 `relation`/`tag` pairs, or `filter` on more than 4 fields. `max` is in the body. |
| 400 | `public_filter_too_many_values` | More than 10 values for one `filter[field]`. `max` is in the body. |
| 400 | `public_filter_type_unsupported` | `filter` on a field whose type it cannot compare, a range on a type that has none, or `relation` or `tag` on a relation field that accepts several models. |
| 400 | `public_cursor_mismatch` | A cursor sent with a query, site, model or token scope other than its own. |
| 400 | `public_cursor_stale` | A `/v1/_related/:model` cursor whose item was published again. |
| 400 | `public_expand_invalid` | `expand` names a field that is not a relation field of the model, a relation field that accepts several models, or repeats one. |
| 400 | `public_expand_too_many` | `expand` names more than 3 fields. `max` is in the body. |
| 400 | `public_expand_too_deep` | `expand` names a dotted path. One level only; `max` is 1. |
| 404 | `unknown_host` | No active site on this host. |
| 404 | `locale_unavailable` | The item has no content the locale policy will serve. |
| 404 | `ambiguous_slug` | Two published items claim the slug. |
| 404 | none | No such model, no such published item, a failed preview token, or a private model without a valid token. |
| 422 | a media presentation reason | Page preview only. See the item route above. |
| 500 | `site_locale_policy_invalid` | The site's locale policy is missing or invalid, or its stored fallback languages are malformed. |

Validation rules for both `/v1` routes:

- An unknown parameter is refused, never ignored.
- An empty value (`?locale=`) is refused.
- A parameter may appear once, except `relation`, `tag` and `filter[field]`
  (equality only) on the list route.
- Locale codes and filter field keys must match `^[A-Za-z0-9_-]{1,64}$`.
- A filter value (the part after the first `:`) is at most 255 characters, and
  neither side of the `:` may be empty.
- The item route accepts only `locale`, `preview` and `expand`.

## Private models

A model is public or private. Set this under Settings → API. A private model is
readable only with a site API token:

```
Authorization: Bearer dw_site_…
```

Tokens are created under Settings → API. Each one names the models it may read,
is shown once, can carry an optional expiry date, and can be revoked there at any
time. Revocation and expiry take effect on the next request. Tokens start with
`dw_site_`. After the operator rotates the signing key to its second era, new
tokens start with `dw_site2_`. The public Worker needs a valid signing-key configuration
(`SITE_TOKEN_HMAC_KEY`). Without it no private model is readable.

A request with no token and a request with a wrong one get the same answer: 404
with no `reason`, the same as a model that does not exist. That is deliberate:
distinguishing them would tell a caller who guessed the model name that the model exists.
So when a private model answers 404, check the token before the URL.

A public model ignores the `Authorization` header.

## Caching

Whether a response may be cached depends on the model, not on the request:

- **Public model, published read:** cacheable at the edge when caching is on.
  This holds whether or not the request carries an `Authorization` header.
- **Private model, or a served preview:** always `Cache-Control: private, no-store`,
  never stored. A served preview is one whose token verified: its item, and its 422
  media presentation refusal. A preview token that does not verify on a public model
  answers the ordinary public 404.
- **400 errors and 500 `site_locale_policy_invalid`:** `no-store`.

Caching is off by default: `PUBLIC_CACHE_MAX_AGE` is `0`, and public responses
say `no-store`. Set `PUBLIC_CACHE_MAX_AGE` to a number of seconds, at most
31536000 (one year), on both the public and the admin Worker to turn it on.
Publishing or unpublishing then purges the affected responses by cache tag. That
purge needs `CF_PURGE_ZONE_ID` and `CF_PURGE_API_TOKEN` (a token with
`Zone → Cache Purge`) on the admin Worker. Without them, the change reports that
the purge was skipped, and cached responses stay until they expire.

Response headers:

| Header | Public model | Private model or served preview |
| --- | --- | --- |
| `Cache-Control` | `no-store` when caching is off. `public, max-age=<min(60, TTL)>, s-maxage=<TTL>` when on | `private, no-store` |
| `X-Cache` | `MISS` from the Worker, `HIT` from the edge cache | `BYPASS` |
| `Cache-Tag` | `site:<id>`, `model:<slug>`, on the item route `instance:<id>`, and `model:<slug>` of models linked from component fields or expanded with `expand` | not sent |
| `Vary` | `Accept-Encoding` | `Authorization` |

The cache key is the host plus the normalized path and query, so the same query
written in a different parameter order shares one entry. For a model with private fields, the
key also names those fields, so a field turned private is never served from an older cached response.
Changing which fields are private also purges `model:<slug>` and site search.

## What is stable, and what is not

STABLE within `v1`: the paths, the parameter names, the
meanings of the status codes and `reason` values, and the top-level shape of a
response: `contracts`, `data`, and on the list route a `page` object holding
`limit`, `has_more` and `next_cursor`. An item's own keys are `id`, `slug`,
`model`, `locale`, `version`, `published_at`, `fields`, `relations` and
`media`. A page item also carries `page_contract`. With `expand`, an item
also carries `expanded`. An item whose published
version sets search and sharing overrides for the served language also carries
`seo`: `{ format: 1, title, description, image, canonical, robots, schema_type }`,
where `image` is `{ media_id, url, alt, width, height }` or null, `canonical`
is an https address or a path on this site or null, `robots` is `index` or
`noindex`, and `schema_type` is `WebPage`, `AboutPage`, `ContactPage`,
`Article` or null (a renderer's structured data names the page by it). Only the published version's values are served; a draft change is
not. Versioned plugin contributions may also add `seo.renderer_metadata`: declared metadata,
links and JSON-LD, keyed by plugin and contribution. Authored/core SEO takes precedence.
Published hierarchy may add `ancestors[field]` and `seo.breadcrumbs[field]`: ordered
`{ id, locale, label, url }` entries using current published ancestors and accepted routes,
under the site's locale policy. Draft labels and unavailable ancestors are omitted. Chains hold
at most 32 ancestors, for the first eight public hierarchy fields in field-key order.
Absent `seo` means no SEO overrides or derived additions are present.

An item referencing public library assets may carry `mediaMetadata`, keyed by asset id.
Each value contains only explicitly public custom asset fields. These values follow the asset's
current revision, independently of the entry's published version; changing a field's privacy
changes the public cache identity. Generated artifacts snapshot this public projection.

PAGE CONTRACT VERSIONS: `contracts.page.served` is the page vocabulary that
produced the response, currently `5`. A page item's
`page_contract.required` is the page-contract version a renderer must read to
render that page. Today every readable page answers the served version, so
`required` equals `contracts.page.served`. It is not the stored page
`format`, which is a different number. A renderer built for version N reads
every page whose `required` is at most N and refuses the rest whole.
It never renders part of a page. With `fields=`, `page_contract` is kept
only when `slides` is selected.

NOT stable, and do not parse: the contents of `next_cursor`, the text of
`error`, and the order of keys. A new optional parameter, a new `reason`, or a
new key inside an item may appear within `v1`. Nothing
documented here will change meaning without a new version in the path.

## Consumer examples

### Fetch every item, following the cursor

Run this on a server or at build time. Browser reads need an allowed origin; keep private site tokens on your server.

```js
async function* everyArticle(origin, locale = 'en') {
  let cursor;
  do {
    const url = new URL(`${origin}/v1/article`);
    url.searchParams.set('locale', locale);
    url.searchParams.set('limit', '50');
    // The cursor is opaque. Send back exactly what you were given; do not
    // decode it, and do not construct one.
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url);
    if (!response.ok) throw new Error(`${response.status} from ${url}`);

    const body = await response.json();
    yield* body.data;
    cursor = body.page.has_more ? body.page.next_cursor : undefined;
  } while (cursor);
}
```

### A private model

```bash
curl -H "Authorization: Bearer $DEE_WAN_SITE_TOKEN" \
  'https://example.com/v1/pricing'
```

Keep the token on the server. Anything shipped to a browser is public.

### Use the generated TypeScript client

Download `dee-wan-client.mjs` from Settings → API and commit it. It needs Node
18 or later and nothing else. Pull the client with a site API token:

```bash
DEE_WAN_SITE_TOKEN=dw_site_… node dee-wan-client.mjs pull \
  --url https://example.com --out src/dee-wan-public.ts
```

Before you deploy, check that the committed client still matches the site:

```bash
DEE_WAN_SITE_TOKEN=dw_site_… node dee-wan-client.mjs check --file src/dee-wan-public.ts
```

`check` exits 1 on a breaking change: a removed model, field or locale, a changed
field type, a model made private, a field made optional, a new select value, or a
changed default locale or locale policy. It exits 0 when nothing changed or every
change is compatible, such as an added model, field or locale, and lists them. It
exits 2 when it cannot run. After a change, run `pull` and commit the result.

The client contains the response envelope, the locale union, exact field types,
model-aware query types and one method per model. Settings → API can also copy
or download it by hand. Dee Wan does not change your repository.

### Types without the generated client

```ts
type RelationTarget = { instance_id: string; model: string; slug: string | null; display: string | null };
type Media = {
  media_id: string;
  name: string;
  mime_type: string | null;
  kind: 'image' | 'document' | 'audio' | 'video' | 'file';
  size: number | null;
  url: string;
  thumbnail_url: string | null;
  alt: string | null;
  width: number | null;
  height: number | null;
  visibility?: 'private';
};
type Item<F> = {
  id: string;
  slug: string | null;
  model: string;
  locale: string;
  version: number;
  published_at: string | null;
  fields: F;
  relations: Record<string, RelationTarget[]>;
  media: Record<string, Media[]>;
};
type Page<F> = {
  contracts: { page: { served: number } };
  data: Item<F>[];
  page: { limit: number; has_more: boolean; next_cursor: string | null };
};
type ApiError = { error: string; reason?: string; max?: number };

type Article = { title: string; body: string };

const response = await fetch(url);
if (!response.ok) throw new Error(`${response.status} from ${url}`);
const page: Page<Article> = await response.json();
```

## Spatial queries

A `point` value is `{ "latitude": 13.75, "longitude": 100.5 }`. Coordinates are finite degrees. Radius values use metres.

```text
GET /v1/places?filter[location][within_radius]=13.75,100.5,2000
GET /v1/places?filter[location][within_bbox]=13.5,100.2,14,100.8
GET /v1/places?sort=location&origin=13.75,100.5
```

Bounding-box order: south, west, north, east. Edges are inclusive. West greater than east crosses the antimeridian. Radius and nearest order use exact Haversine distance. Use `sort=-location` for farthest first. Missing values sort last; ID breaks ties. A cursor binds the origin and bounds. Private coordinates follow the normal field and model restrictions.

## Incremental synchronization

`GET /v1/_sync?limit=50` starts a bounded published entry/media snapshot. Optional `model` and `locale` restrict entries. Follow `next_cursor` until `checkpoint` is returned. Poll with `cursor=<checkpoint>`. Existing site tokens and CORS apply; a scoped token can include its authorized private models. Private media are excluded, matching ordinary public media delivery.

Apply snapshot `data`, then apply replay `changes` in ascending `sequence`. Each change has `operation: upsert|delete`, `entity: entry|media`, `id`, and an entry locale. Upserts carry `item`. Changes can repeat identities; apply idempotently. `data` and `deleted` are convenience arrays; do not apply those arrays in separate batches because a later republish can follow a delete.

Cursors are opaque signed values. Preserve them unchanged. `409 reset_required` requires a fresh snapshot after scope, publication policy, replaced database state, retention or a referenced shared source changes. A normal process restart preserves the checkpoint. Same-site ordinary, component, hierarchy and active rich-block references watch their authorized declared target models. A later publication or withdrawal in one of those models returns `409 reset_required` with `reset_reason: related_content_changed`, including streams restricted by `model`. This can include another entry in the same target model. Hidden relation fields and unreadable target models do not add dependencies. Current public projection and component privacy/definitions also bind the cursor; a change requires a fresh snapshot. Any published-content change in a referenced source site can also invalidate the checkpoint, including changes to related public display values. An unavailable shared-source database returns retryable `503 sync_dependency_unavailable`; retry the same cursor. There is no automatic journal purge. Journal rows retain identity and operation, never draft or private field bodies.

Shared relation output uses `shared[field]` slots `{ site_id, id, item }`; an unavailable or revoked target has `item: null`. Each delivery rechecks the source grant and published public fields. A response resolves at most 128 distinct grant/language identities. Repeated slots, including synchronization `data` and `changes`, reuse one current projection. On `422 shared_reference_limit`, lower the list or sync `limit` and retry.

<!-- dee-wan-docs page: /guides/search/ -->

# Search for your site

Source: https://dee-wan-docs.pages.dev/guides/search/

The [public read API](/reference/public-api/) serves published content. Its list routes are not a query engine, but it provides a live search endpoint, `GET /v1/_search`, and suggestions while a visitor types, `GET /v1/_search/suggest`. Managed and generated sites draw their search pages from it. Read the API from a server, build or Worker without CORS setup. A separately hosted browser app can read it after its origin is allowed under **Settings → API → Browser origins**; see [browser origins](/reference/public-api/#browser-origins). Never place drafts or private content in an unauthenticated public index.

## Turn site search on

Open **Settings → Source & delivery → Site search**. It needs `site:infra`. Tick **Turn on site search** and save.

Search always covers published pages and, on a Blog site, published posts. Under **Also search**, tick other public content types to add them, up to 16. A private content type is never offered and never searched.

## Tune ranking

By default a result whose title contains every word comes first, then the newest. To change that for one content type, open **Matching and ranking** under **Site search** and tick **Custom ranking** for that type.

- Tick the fields the type is searched by, up to 16. A field left out is not searched for that type.
- Give each field a weight from 1 to 10. A result ranks by the highest weight among its ticked fields that contain every word. 10 has the greatest weight.
- New custom ranking settings start with the title at 10 and every other text field at 1.
- A type you do not tune keeps the default ranking. Its title match counts as 10.
- Untick the type to go back to the default.

A change applies to the next search. Nothing is rebuilt, and managed and generated sites rank the same way. A results page opened before the change starts a new search when the visitor requests more results.

## Choose how words match

Each searched content type has a **Matching** choice under **Matching and ranking**. Every word of a search must match.

| Matching | Finds | Example |
| --- | --- | --- |
| **Whole words** (default) | The same word only | "tour" finds "tour", not "tours" |
| **English word forms** | Other forms of an English word | "tour" also finds "tours" and "touring" |
| **Parts of words** | The letters anywhere inside a word | "tour" also finds "tours" and "detour" |

- Words are letters, marks and digits. Marks are combining accents and the vowel and tone marks of scripts such as Thai, so they stay inside a word. Anything else only separates words: "don't" is the words "don" and "t".
- **English word forms** works on every site. A result in English (`en`, `en-GB`, `en_US` and the like) matches word forms. A result in any other language matches whole words. Each result follows its own language, so a search in Thai that falls back to an English item matches the English item by word forms and the Thai items by whole words.
- Languages written without spaces between words, such as Thai, match a whole run of letters under **Whole words**. Choose **Parts of words** for those.
- A change applies to the next search. Every form is stored when content is saved, so nothing is rebuilt and old and new matching never mix in one answer. A results page opened before the change starts a new search when the visitor requests more results.

## Linked items

An item is also found by the names of the items it links to through a relation field, such as a post by its author's name:

- A linked item counts only while it is published, its content type is public and it is not in Trash. Its published name counts, in the language the visitor is served. A draft name never counts. A rename counts once it is published.
- A private relation field, a private name field or a private content type adds nothing.
- A result's summary never shows linked names.

## Live search on a managed site

A site served by a managed renderer searches what is live now. Nothing is rebuilt:

- A publication shows up in search at once. Unpublishing a language, moving an entry to Trash, deleting it and moving its address take effect at once too.
- Results come in the visitor's language. Under the fallback policy an item without that language is shown in the first available language in its fallback chain.
- Drafts, private content types and items set to **Hide from search engines** never appear.
- `/search` searches in the default language and `/<language>/search` in another. These pages are not indexed by search engines.
- A **Site search** section on any page draws the same search box and shows results in place.

If search cannot answer, the page still loads and says "Search is not available right now. Try again later." A failing search never blocks a release.

A published page whose address is `/search` or `/<language>/search` blocks a new release while search is on. Change that page's address, or turn search off.

## Site search on a generated Dee Wan site

A generated site searches the same live index as a managed site, through the same endpoint and the same search box. Nothing is rebuilt to update search:

- `/search` searches in the default language and `/<language>/search` in another. A generated site has these pages for the default language and for each language that published content or the Blog uses. A site language with nothing published gets no search page until a build includes published content in that language. The site navigation links to them. They render on each request, are never cached and are not indexed by search engines.
- A **Site search** section turns its page into a page that renders on each request. Results show in place. Every search box on one page shares one search.
- Publishing content, unpublishing a language, moving an item to Trash, deleting it or changing its address updates search at once, including for Blog posts. The **Also search** and **Matching and ranking** choices apply too.
- A result links to its page at the address this build gave it, and a post to its Blog address. A page published after the last build, or another content type, shows without a link until the next build gives it an address.
- Search off or an unknown language answers 404. If search cannot answer, the search page answers 503 and says "Search is not available right now. Try again later." A search section on a page never fails the page.

Search reads `/v1/_search` on the site's own host, so the site Worker needs `global_fetch_strictly_public` in `apps/site/wrangler.jsonc`. New sites have it. An existing file without it blocks site preparation and deployment by name.

The verified generated-site commands stay the same:

```sh
node scripts/install-dependencies.mjs apps/site
npm run --prefix apps/site check
npm run --prefix apps/site build
```

Do not run a bare `npm install` in the generated tree. Regeneration preserves shared dependency files. See [extending your backend](/guides/extending-your-backend/).

## Suggestions while typing

Every search box on a managed or generated site suggests matches while the visitor types:

- Suggestions start at two characters and show up to five live items: title, short summary and link. Words match by the type's **Matching**; the last word may be unfinished and matches the start of a word (anywhere inside one under **Parts of words**). An item whose title starts with the typed words comes first, then items whose title contains them, then the rest. Only items with an address on this site are offered. A tuned type is matched by its ticked fields only.
- They read the same live content as search: drafts, private content types, Trash, unpublished languages and items hidden from search engines never appear. A publication or withdrawal shows up at once.
- Use the arrow keys to move through the list. Enter opens the highlighted item; with nothing highlighted it runs the ordinary search. Escape closes the list, a second Escape clears the box. A click or tap opens an item. Screen readers hear the list as a combobox and hear how many suggestions there are.
- If suggestions cannot load, the list stays hidden and the search box still works. Without JavaScript the box is the ordinary search form.
- Nothing about what visitors type is stored or counted.

The box asks the site's own `/search?suggest=<words>&locale=<language>`, which reads `GET /v1/_search/suggest` and links each item the way search results are linked. A managed site's security policy allows exactly that one script, by hash.

## Live search for a front end you host

A front end you build can call the same endpoint from its server:

```sh
curl "https://example.com/v1/_search?q=lighthouse&locale=en&limit=10"
```

Every word of `q` must match, according to each content type's matching mode (see [Choose how words match](#choose-how-words-match)). Results whose title contains every word come first, then the newest, unless the site tunes ranking (see [Tune ranking](#tune-ranking)). Pass `page.next_cursor` back as `cursor` for the next page of the same query. A cursor from before a ranking or matching change is refused with `public_search_invalid`; start the search again. A result gives `kind`, `model`, `slug` and `locale`; build its link with your own routes. `search_off` means search is off for the site. The [public read API](/reference/public-api/) lists every parameter and refusal.

For suggestions, send exactly one `q` (2 to 100 characters), one `locale` and optionally `limit` (1 to 10, default 5):

```sh
curl "https://example.com/v1/_search/suggest?q=light&locale=en"
```

Words match according to each content type's matching mode, and the last word may be partial. The answer holds `query`, `data`, `limit` and `locale`; each item has the same fields as a search result.

## Static search for a site you build yourself

For a generic static site, add Pagefind through that project's normal dependency workflow and run its pinned executable after building HTML. The command added to your site's build script is `pagefind --site dist` when `dist` really is its output directory. Publish the HTML and matching search files together. A failed build must not replace the last successful deployment.

## External indexes: replace only after a complete crawl

A service such as Typesense or Meilisearch needs explicit withdrawal semantics. Repeated upserts alone never remove an item that was deleted, unpublished or moved out of the selected scope. Dee Wan does not own those clients or their atomic index operations.

Define the complete scope as a reviewed set of `(site, model, locale)` tuples. Stage a fresh empty generation for **all** those tuples, crawl every page to completion, validate every response, and write only to that staged generation. Key documents by site, model, stable item ID and actual locale, not by mutable slug. Skip fallback-locale results on another locale's pass. Forward cursors unchanged. Missing, repeated or inconsistent cursors, invalid item shapes, HTTP errors, timeouts and scope failures abort the entire build.

Only after every scope finishes may the adapter atomically activate the complete generation, or perform an equivalently isolated full replacement. Readers must never observe partially reconciled deletes and inserts. An empty successful generation is valid and removes all previously indexed entries. If one scope fails, even after others finish, the old live generation remains unchanged. Abandoned stages can be cleaned up without touching the active one.

Capture the active generation's revision when staging begins. Activation must compare that revision atomically or serialize rebuilds so a slower older crawl cannot overwrite a newer one. A lost activation acknowledgment is ambiguous: the adapter must resolve whether that generation is active, and `discard` must never delete active data. Multi-key writes or a pointer in eventually consistent storage alone do not prove this contract.

## Executable adapter example

The [dependency-free staged crawler](/examples/search-index.mjs) exports `rebuildSearch({ scopes, readPage, stage, maxPages, maxDocuments })`. It performs no provider calls by itself. Supply these adapter operations:

| Operation | Required behavior |
| --- | --- |
| `readPage(scope, cursor)` | Enforce a request timeout and HTTP success. Return the public API's `{data, page}`. `page` has boolean `has_more` and nullable `next_cursor`. |
| `stage.begin(scopes)` | Allocate an isolated empty generation and capture the live revision. Do not clear or write the live index. |
| `stage.write(generation, batch)` | Write only into that generation. Reject failed or partial writes. Each item has a composite `key`, `scope` and original `item`. The adapter owns searchable field projection. |
| `stage.activate(generation)` | Publish the complete generation atomically with stale-writer protection. Resolve uncertain acknowledgments by generation identity. |
| `stage.discard(generation)` | Remove only inactive staged data. Never clear the current live generation, including after an ambiguous activation response. |

The example bounds pages per scope and total accepted documents. It intentionally leaves provider credentials, index configuration and field extraction to your existing search adapter. The focused source checks cover successful withdrawal, empty replacement, failure after a completed scope, malformed cursors, staging errors and concurrent activation conflicts. Run `node --test scripts/search-index.test.mjs` from the CMS repository.

## Freshness and acceptance

A completed paged crawl is not proof of a single-time snapshot while content is changing. For a strict cutover, coordinate a publishing pause or use an accepted published snapshot. Otherwise state the rebuild's freshness limit and repeat it. Public API caching, when enabled, can delay observed withdrawal. Do not promise instant disappearance.

Before production use, demonstrate these behaviors. A withdrawn item disappears after a complete rebuild. A failed crawl leaves every old scope intact. A valid empty result clears stale records. An older concurrent build cannot become live after a newer one. Private-model tokens belong in server secrets and require a search service enforcing the same access. A webhook may trigger rebuilding, but is not itself a complete index. See the [outbound contract](/reference/outbound-webhooks/).

## Next step

Tell other systems when content is published with [outbound webhooks](/reference/outbound-webhooks/).

<!-- dee-wan-docs page: /reference/outbound-webhooks/ -->

# Outbound webhook contract

Source: https://dee-wan-docs.pages.dev/reference/outbound-webhooks/

Outbound webhooks notify an external system about content changes. They are not plugin commands or a place to run CMS business rules. Configure subscribers in Settings → Integrations → Outbound webhooks with the appropriate site permission. A notification failure does not undo publication, and delivery is best-effort with bounded retries, not a guarantee that every subscriber eventually receives an event.

While **Save subscribers** runs, editing is locked. If someone else saved first, your edits stay in the form; **Reload and discard edits** replaces them with the latest list. A failed subscriber or delivery-history read offers **Try again**. Retrying history keeps subscriber edits.

## Events and envelope

Successful content, workflow, release, media and model mutations enqueue these events: `content.created`, `content.updated`, `content.trashed`, `content.restored`, `content.deleted`, `content.published`, `content.unpublished`, `workflow.transitioned`, `release.applied`, `media.created`, `media.updated`, `media.deleted`, `model.applied`. Refused writes, rolled-back transactions and idempotent replays create no new event. A coordinated release emits events only after its complete tenant commit.

The JSON body has `id`, `event`, `site_id`, `occurred_at` (ISO-8601) and `data`. Data identifies the affected item, model, media or release and includes the applicable committed version, revision and locale. Publication events identify the primary `instance_id`, model and publication state. Payloads omit private field snapshots and credentials. Read the appropriate API for current data; an unpublished or deleted item may no longer appear in public responses.

A successful mutation queues delivery as `pending`; it does not wait for a subscriber's network response. The existing scheduled delivery worker makes the first attempt and any retries. All deliveries of one event retain its stable ID and original body, including manual replay.

## HTTP and signature

The sender makes a POST with `Content-Type: application/json`. `X-Deewan-Event` names the event. **`X-Deewan-Delivery` is the subscriber configuration ID, not the event ID**. `X-Deewan-Signature` is `sha256=` followed by the lowercase hexadecimal HMAC-SHA256 of the exact UTF-8 body bytes using the configured subscriber secret.

Verify the raw bytes before parsing, compare the signature safely, check the intended site and supported event. Then deduplicate the body's stable `id` within your subscriber/site scope. Re-serializing JSON before verification changes the signed bytes. `occurred_at` is signed. Apply a replay policy that permits the legitimate retry window. There is no independent timestamp signature header.

The same event ID is used for delivery to multiple subscribers and for retries. Retries and replays retain the original body and are signed with the subscriber's current secret, so secret changes need coordinated receiver updates. Each delivery records the subscriber id and URL it went to. A retry or replay is sent only while the subscriber with that id still has that URL. It is refused when the URL changed, the subscriber was removed, or the delivery predates destination recording. A new subscriber gets a random id and cannot take an id that already has delivery history. Never deduplicate solely on `X-Deewan-Delivery`, which is reused for unrelated events.

## Acknowledgment and retry

Any 2xx acknowledges delivery. The default request deadline is 5 seconds. Unreachable requests, HTTP 408, 429 and 5xx are retryable. Other HTTP refusals are terminal. Up to five total attempts use exponential backoff from one minute, capped at one hour, with 50–100% jitter. A valid `Retry-After` in seconds or date form can increase the wait, capped at one hour. Exhaustion stops automatic retries.

The scheduled delivery worker claims records that are due and rechecks the current subscriber. Removed or disabled subscriptions do not receive retries. Do not assume ordering or exactly-once requests: a lost acknowledgment or lease recovery can repeat a notification whose effect already happened. A receiver should durably record its accepted event and apply its effect atomically before acknowledging it. Use existing delivery details in Settings to review failures or manually resend a notification. Do not interpret a failed response as proof that no effect occurred.

## Receiver acceptance checks

Verify rejection of an invalid signature, altered bytes, wrong site and unsupported event. Confirm duplicate event IDs do not repeat effects, different IDs on the same subscriber do run, and a lost acknowledgment can be retried safely. A search receiver must follow the [complete-generation withdrawal contract](/guides/search/), rather than continually adding or updating items without removing withdrawn content.

Authorities: `backend/src/lib/outbound-webhook.ts`, `backend/src/lib/outbound-retry.ts` and `backend/src/lib/lifecycle/publication-effects.ts`. These outbound retry rules are separate from the [plugin protocol](/plugins/protocol-v1/).

## Next step

Manage content from scripts and AI agents with the [CMS management API](/reference/management-api/).

<!-- dee-wan-docs page: /reference/management-api/ -->

# CMS management API

Source: https://dee-wan-docs.pages.dev/reference/management-api/

Post-1.0. A versioned API for scripts, command lines and AI agents that manage one site's content,
models and settings. It runs the same lifecycle services, model apply and admin handlers as the
admin UI. It is not the generated backend's CRUD API. A model change is made directly with
`schema:write`, or proposed for a person to apply in the Content Builder.

- Machine contract: [`openapi-v1.json`](/schemas/management/openapi-v1.json) (OpenAPI 3.1).
- TypeScript types: `backend/src/lib/management/client-v1.generated.ts`.
- Command line and MCP server: `dee-wan-manage.mjs`, downloadable from **Settings → API**.
- Remote MCP: `POST /api/manage/mcp`, the same operations over HTTPS with no download.
- All three are generated from `backend/src/lib/management/contract.ts` by
  `npm run docs:management-api`. `npm run check:management-api` fails when any of them is stale.

## Credentials

Create one in **Settings → API → Management credentials**. You need `site:settings` on the site.

- Give it a name, the scopes it may use and, optionally, the models it may touch.
- You can only grant what you hold now. A scope or model you do not have access to is refused with
  `422 grant_not_held`, which names them. The form disables them.
- The secret is shown once. Only its SHA-256 digest is stored. Copy it before you close the panel.
- Format: `dwm_` followed by 43 base64url characters.
- Revoke it on the same screen. A revoked secret stops working on its next request.
- No usage counter or last-used time is kept.

### Authority

A credential acts as the person who created it. On every request the API re-reads that person's
current permissions on the site and intersects them with the credential:

- **scopes** limit which commands it may call;
- **models** (if chosen) limit which content models it may read or write;
- the **creator's role** limits everything else, including `update:own` ownership rules, the
  permission each workflow transition names, and the role's field and language limits
  ([People and access](/guides/people-and-access/#limit-a-role-to-some-fields-or-languages)): entry
  lists and reads leave out languages and fields the role may not read, and writes outside the role’s permissions return `field_denied` or `locale_denied`.

If the creator is deactivated or loses access to the site, the API returns `creator_unauthorized`.
If the creator loses a permission, the credential loses it at the same moment. A superadmin creator
gets no bypass: the credential remains limited to its scopes and models.

| Scope               | Allows                                                                                                                                                                                         | Needs from the creator                                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content:read`      | Read site, models, entries, versions, dependents, proposals, pages, media. Always included.                                                                                                    | `read` on the model                                                                                                                                                                                           |
| `content:write`     | Create and update draft entries, add a language, restore an old version, change linked items (relate, related from).                                                                           | `create` / `update` on the model; a version restore also `content:restore`                                                                                                                                    |
| `content:propose`   | Propose field changes for an editor to review.                                                                                                                                                 | `read` on the model                                                                                                                                                                                           |
| `pages:write`       | Page editor save.                                                                                                                                                                              | `update` on the page model                                                                                                                                                                                    |
| `media:write`       | Upload media, edit a file's alt text, focal point, loading and fetch priority, delete unused files, and create, rename, move and delete library folders and move files between them.           | `media:upload` to upload, `media:update` to edit and for folders, `media:delete` to delete                                                                                                                    |
| `lifecycle:publish` | Publish and unpublish, with no second human confirmation.                                                                                                                                      | `update` and the transition's permission                                                                                                                                                                      |
| `content:trash`     | Move entries or single languages to Trash, and restore them.                                                                                                                                   | `delete` on the model                                                                                                                                                                                         |
| `content:purge`     | Delete a Trash item permanently.                                                                                                                                                               | `delete` on the model                                                                                                                                                                                         |
| `workflow:move`     | Workflow steps that neither publish nor unpublish (Submit for review).                                                                                                                         | `update` and the step's permission                                                                                                                                                                            |
| `workflow:assign`   | Name who acts next on an entry; list who could.                                                                                                                                                | `update` on the model                                                                                                                                                                                         |
| `settings:write`    | Read and change site settings: retention and review, missing-language fallback, media files, search, Site Chrome defaults, SEO, robots, redirects and menus.                                   | `site:settings`; search uses `site:infra` instead                                                                                                                                                             |
| `schema:propose`    | Propose a new model or a model change for a person to review; list and read those proposals.                                                                                                   | `model:apply`                                                                                                                                                                                                 |
| `schema:write`      | Create, change, replace and delete models directly.                                                                                                                                            | `model:apply`; a delete also `model:delete`                                                                                                                                                                   |
| `data:import`       | Run imports end to end: sources, jobs, upload, advance, mappings, pause, resume, cancel, undo, receipts and problem files. Each effect is still checked against the creator's own permissions. | `data:import`; the effects also need what the admin import needs (model and entry writes, `media:upload`, `model:apply`, `site:settings`, publication)                                                        |
| `data:export`       | Create exports, build them and read them in byte ranges.                                                                                                                                       | `data:export`                                                                                                                                                                                                 |
| `roles:write`       | Create, change and delete the site's roles, field and language limits included. A credential hands out only what it holds itself.                                                              | `role:manage`                                                                                                                                                                                                 |
| `plugins:use`       | List installed plugins, create one-time links that open a plugin view or entry action, and run declared plugin operations.                                                                     | What the same launch or run needs in the admin: `read` on the entry (`update` for a destructive operation), or a granted model the creator reads, own entries included; a site operation needs `site:plugins` |

## Roles

`/roles` lists the site's roles with their whole permission sets: `models`, `system` and the
optional field and language `limits` ([People and access](/guides/people-and-access/#limit-a-role-to-some-fields-or-languages)).
Writes go through the same checks as Settings → Roles: unknown permissions answer 400
`invalid_permissions` with every reason, and a permission set beyond the credential’s authority returns 403
`escalation_refused`. The ceiling is the credential's own narrowed permissions, not its person's
whole role: a credential without `content:write` cannot give `update`, and one without
`lifecycle:publish` cannot give `content:publish`. A model wildcard (`"*"`) is never within a
credential's ceiling. `PUT /roles/{id}` replaces only the fields it names; `permissions` replaces
the whole set. Deletion is refused for a seeded role, a role someone holds, a role a Cloudflare Access rule
names, and the last role that can grant access.

## Requests

- Base path: `/api/manage/v1`.
- Send `Authorization: Bearer <secret>`. The site comes from the credential. A request that sends
  `X-Site-Id` or names a database is refused.
- JSON bodies are closed: an unknown key is `invalid_request`.
- Every write needs `Idempotency-Key`: 1–128 visible ASCII characters (`0x21`–`0x7E`, no spaces).
  The exceptions take no key and their Key cell below is empty: plugin launches, the redirect review
  (it writes nothing) and the four editing routes under `/entries/{id}/editing`. Reuse the same key and body on a
  retry; the first result comes back with `replayed: true` (pages: `created: false`). A key reused for
  a different request is `idempotency_key_reused`. Publish, unpublish and move keys are kept 30 days;
  other keys 24 hours. Trash, restore, purge, assignment and new-language keys hold the exact first
  answer, so a retry of a purge replays even though the entry is gone.
- A command claims its key before it changes anything. A second request with the same key and body
  while the first still runs changes nothing and is `409 idempotency_in_progress` with
  `Retry-After`; retry it with the same key and body to get the first answer. A refused or failed
  command frees its key. Media metadata edits, media deletes, settings writes, proposals and every
  import and export step follow this rule; a replay answers the exact first response, never a fresh
  read.
- A command never becomes safe to repeat merely because its key claim has aged. When the request that holds a key stops
  answering, the next retry with that key settles the claim by what the command itself can prove:
  - Written in one batch with its answer: media upload, edit and delete, media folders, model and
    menu writes, Site Chrome and SEO settings, trash, restore, purge, assignment, a new language,
    creating an import, an export, an import source or a role, deleting a role, and importing a media
    source item. A claim with no answer proves nothing was written, so the retry runs the command.
    When the write committed and only its answer was lost, the retry answers from what it wrote, with
    `replayed: true`. A file a stopped upload stored is removed.
  - Kept in a record of its own, or safe to repeat: entry saves, publish, unpublish, move, proposals,
    page saves, settings, plugin operations, import parts, role updates, comment settings,
    moderation and deletes. The retry runs the command again. A moderation or delete repeated after
    the first one committed answers `conflict` (a delete: `not_found`) with the comment's state now.
  - Steps of a job: export and import steps, review choices, pause, cancel and upload completion.
    The claim records where the job stood before the step. When the job moved since, the retry
    answers its state now, with `replayed: true`, and runs nothing. When it did not move, an export
    step, a review choice, pause, cancel and upload completion run again: each is compare-and-set on
    that position or sets a target state. `advanceImport`, `resumeImport`, `advanceImportUndo` and
    `retryImportUndo` run again only after the first request ended with an error; when it stopped
    answering (a timeout, a lost connection), the claim stays pending.
- A claim that stays pending answers `409 idempotency_in_progress` without `Retry-After`: waiting
  does not settle it. Read the result (for an import, `getImportJob`), then send the command again
  with a new key if it is still needed. The claim expires with its key after 24 hours.
- Media upload takes a file whose kind and format the site accepts (Settings → Site → Media files): an
  image, a document, audio, video, or another file as a download. The same check runs for the admin,
  this API, plugins, imports and site copies. The type is checked against the bytes; a file whose
  bytes, extension or declared type say it is a program, a script or markup is refused
  (`executable_file`, or `unsupported_media_type` for markup). Every media item includes its `kind`:
  `image`, `document`, `audio`, `video` or `file`. An image's `width` and `height` come from its own
  header; the `width` and `height` fields are used only when the header provides neither value.
- `edited_from` uploads the bytes as an edited copy of a library file (for example a crop made in
  another tool). The original is kept. The copy answers `edited_from`, takes the original's tags, and
  takes its alt text and folder unless the request names them. An unknown id is `404`
  `media_edit_source_not_found`.
- A media upload through this API buffers the whole file, so it takes at most 32 MiB whatever a kind's
  cap says. The admin streams larger documents, audio, video and other files up to
  `limits.streamed_max_bytes`: 100 MB, or the larger plan limit the deployment declares in
  `MEDIA_REQUEST_BODY_LIMIT_BYTES` (at most 5 GB; see
  [Workers limits](https://developers.cloudflare.com/workers/platform/limits/)).
- Media upload is keyed on the file's bytes, name and type and its `alt_texts`, `width`, `height`,
  `aspectRatio`, `on_duplicate`, `folder_id` and `edited_from` fields, not on the multipart boundary. The key commits in the same
  batch as the media row, so an exact retry returns the recorded result.
- When the site already holds the same bytes, `on_duplicate` decides. `ask` (the default) answers
  `409` `media_duplicate` with the `existing` file and how many `copies` hold it, and stores and records
  nothing. `use_existing` answers `200` with the existing file and `reused: true`; a retry replays it
  as `200`. `copy` uploads a separate copy. Another site's files are never matched.
- The media library is site-wide: a credential limited to some models still lists and uploads all media.
- Every media item includes its `folder_id`, or `null` for Unfiled. Upload may name a `folder_id`; a
  reused duplicate stays where it is. Folders are logical: no stored file or address ever moves.
- `/media/folders` answers the whole tree depth first, each folder with its `revision`, `depth`,
  own `media_count`, `subtree_folder_count` and `subtree_media_count`, plus `unfiled`, `total` and the
  limits: 5 levels, 500 folders per site, names of 1–80 characters unique under their parent regardless of letter case. Rename and move send `expected_revision`; deleting sends `expected_revision`,
  `expected_folders` and `expected_media` as read. A stale value is `409` `media_folder_changed` with
  the current `folder`. Other refusals: `media_folder_exists` (with the `folder` holding the name),
  `media_folder_cycle`, `media_folder_too_deep`, `media_folder_limit`, `media_folder_not_found`.
  Deleting a folder deletes every folder below it and no file: each file becomes Unfiled.
  `/media/move` puts 1–200 files in one folder, or in Unfiled with `folder_id: null`.
- Every media item also includes `default_focal` (`{ x, y }` fractions, or `null`), `loading` and
  `fetch_priority`. `GET /media/{id}` answers one item in the list's shape.
- `GET /media/{id}/usage` answers where a file is used, as the media library shows it: `used_by` (at
  most 50 entries this credential may read), `hidden` (references in content it may not read:
  counted, never described), `at_least`, `total` (`null` when capped or unreadable), `more` and
  `unreadable`.
- `PUT /media/{id}` changes what the media library edits: `alt_texts` (language code to text; a
  language left out keeps its text, `""` clears it), `default_focal` (images only, `null` clears it;
  otherwise `400 media_framing_not_image`), `loading` (`eager`, `lazy`) and `fetch_priority` (`high`,
  `low`, `auto`). Send at least one. The file, its dimensions and its address never change here.
- `POST /media/{id}/replace` accepts a multipart `file`, with the same media kind as the
  existing file. It keeps the media id, references, folder, tags, credit and framing; omitted
  `alt_texts`, `default_focal`, `loading` and `fetchPriority` keep their current values.
  The verified replacement updates its name, type, size and dimensions. Its delivery URL may
  change: read the returned `url`, rather than relying on the old address. Published versions
  that pin the previous object keep those bytes until no version references them. Linked
  external media cannot be replaced. The same upload validation and atomic replacement used
  by the library applies. Reuse the same `Idempotency-Key` and file/fields to retry safely.
  The TypeScript operation is `replaceMedia`, the CLI command `replace-media`, and the MCP
  tool `replace_media` (remote MCP uses `content_base64`, `file_name` and `id`).
- `GET /media/{id}/originals` lists current originals by language (`content:read`), with object `id`, `lang`, `url`, MIME type, byte length and dimensions. Private URLs are `null`.
- `PUT /media/{id}/originals/{lang}` takes multipart `file` and `expected_object_id`; an empty string creates the first override, otherwise send the current object id. `DELETE` on the same path takes JSON `expected_object_id` (nonempty). Both need `media:write` and `Idempotency-Key`; stale pointers return `409 media_changed`. Only that language changes; the media id, references and other originals stay. Without an override, delivery follows the site's language fallback, then the default original. Published version pins retain their exact bytes. `POST /media/{id}/replace` still replaces the default original.
- TypeScript: `listMediaOriginals`, `replaceMediaOriginal`, `removeMediaOriginal`. CLI: `list-media-originals`, `replace-media-original`, `remove-media-original`. MCP: `list_media_originals`, `replace_media_original`, `remove_media_original`.
- `POST /media/{id}/remove` deletes a file nothing references. While anything does, it answers
  `409 media_in_use` with the same usage fields; `media_usage_unreadable` when usage could not be
  read. Nothing is deleted then. A success answers `storage_cleanup`: `complete`, or `pending` when
  the record is gone but a stored copy could not be removed yet. MCP clients see it as destructive.
- `GET /media/sources` lists the external media sources active plugins offer the site (a plugin granted
  `media:source`). `GET /media/sources/{installationId}/{sourceId}/items` answers one page of a source,
  at most 24 items, searched by `q`; send `next_cursor` back as `cursor` for the next page. Each item has
  its title, file name, type, size, a `thumbnail_url` on the plugin's origin (load it with no referrer)
  and its `attribution`. Each source lists its `modes`: `copy`, `reference` or both. Nothing is stored
  by browsing.
- `POST /media/sources/{installationId}/{sourceId}/import` with `item_id` and `mode` adds one item to the
  library. `mode` is required and is one of the source's `modes`; Dee Wan never infers it. With `copy`,
  Dee Wan fetches the file from the plugin and checks it like any upload: the site's kinds, formats and
  size limits, and the new file never depends on the source again. With `reference`, Dee Wan fetches
  nothing and keeps the plugin's delivery URL and the item's identity: the media answers `external:
true`, its `url` is the delivery URL, its bytes cannot be replaced or edited
  (`media_external_bytes_unavailable`, 409) and deleting it removes only the library row. `folder_id`
  and `on_duplicate` work as on upload (for `reference`, the same plugin, source and item is the
  duplicate); `use_existing` answers the existing file with `200`. The new file answers `attribution`
  (source name, author, license, links, and the plugin, source and item ids). Every media item includes
  `attribution`, `null` for files added any other way. Refusals: `media_source_unavailable` (404),
  `media_source_mode_unsupported` (422, the source does not declare that `mode`),
  `plugin_refused` (422, with the plugin's `refusal`), `plugin_unreachable`,
  `plugin_response_invalid` and `media_source_file_unreachable` (502), `plugin_timeout` (504), and the
  upload refusals such as `media_format_not_enabled`, `media_kind_not_enabled` and `media_too_large`. The audit records it as a
  media upload naming the source.
- Rate limit: 120 requests per minute per credential. Over it: `429` with `Retry-After`.

| Method | Path                                                                    | Scope               | Key      |
| ------ | ----------------------------------------------------------------------- | ------------------- | -------- |
| GET    | `/site`                                                                 | `content:read`      |          |
| GET    | `/models`                                                               | `content:read`      |          |
| GET    | `/entries?model_id=…`                                                   | `content:read`      |          |
| POST   | `/entries`                                                              | `content:write`     | required |
| GET    | `/entries/{id}`                                                         | `content:read`      |          |
| PUT    | `/entries/{id}`                                                         | `content:write`     | required |
| GET    | `/entries/{id}/versions`                                                | `content:read`      |          |
| GET    | `/entries/{id}/versions/{versionId}`                                    | `content:read`      |          |
| GET    | `/entries/{id}/dependents`                                              | `content:read`      |          |
| POST   | `/entries/{id}/publish`                                                 | `lifecycle:publish` | required |
| POST   | `/entries/{id}/unpublish`                                               | `lifecycle:publish` | required |
| POST   | `/entries/{id}/proposals`                                               | `content:propose`   | required |
| GET    | `/entries/{id}/proposals`                                               | `content:read`      |          |
| GET    | `/entries/{id}/editing?locale=…&kind=…`                                 | `content:read`      |          |
| POST   | `/entries/{id}/editing/takeover`                                        | `content:write`     |          |
| PUT    | `/entries/{id}/editing/draft`                                           | `content:write`     |          |
| POST   | `/entries/{id}/editing/draft/discard`                                   | `content:write`     |          |
| GET    | `/pages/{id}`                                                           | `content:read`      |          |
| POST   | `/pages/{id}/save`                                                      | `pages:write`       | required |
| POST   | `/pages/{id}/translations`                                              | `pages:write`       | required |
| GET    | `/media`                                                                | `content:read`      |          |
| POST   | `/media` (multipart, `file` part)                                       | `media:write`       | required |
| GET    | `/media/folders`                                                        | `content:read`      |          |
| POST   | `/media/folders`                                                        | `media:write`       | required |
| PUT    | `/media/folders/{id}`                                                   | `media:write`       | required |
| POST   | `/media/folders/{id}/remove`                                            | `media:write`       | required |
| POST   | `/media/move`                                                           | `media:write`       | required |
| GET    | `/media/sources`                                                        | `media:write`       |          |
| GET    | `/media/sources/{installationId}/{sourceId}/items`                      | `media:write`       |          |
| POST   | `/media/sources/{installationId}/{sourceId}/import`                     | `media:write`       | required |
| GET    | `/media/{id}`                                                           | `content:read`      |          |
| GET    | `/media/{id}/usage`                                                     | `content:read`      |          |
| PUT    | `/media/{id}`                                                           | `media:write`       | required |
| POST   | `/media/{id}/replace` (multipart `file`)                                | `media:write`       | required |
| GET    | `/media/{id}/originals`                                                 | `content:read`      |          |
| PUT    | `/media/{id}/originals/{lang}` (multipart `file`, `expected_object_id`) | `media:write`       | required |
| DELETE | `/media/{id}/originals/{lang}`                                          | `media:write`       | required |
| POST   | `/media/{id}/remove`                                                    | `media:write`       | required |
| GET    | `/languages`                                                            | `content:read`      |          |
| POST   | `/entries/{id}/locales`                                                 | `content:write`     | required |
| POST   | `/entries/{id}/versions/{versionId}/restore`                            | `content:write`     | required |
| POST   | `/entries/{id}/transition`                                              | `workflow:move`     | required |
| GET    | `/entries/{id}/assignees`                                               | `workflow:assign`   |          |
| PUT    | `/entries/{id}/assignment`                                              | `workflow:assign`   | required |
| GET    | `/trash?model_id=…`                                                     | `content:read`      |          |
| GET    | `/entries/{id}/trash`                                                   | `content:read`      |          |
| POST   | `/entries/{id}/trash`                                                   | `content:trash`     | required |
| POST   | `/entries/{id}/trash/restore`                                           | `content:trash`     | required |
| POST   | `/entries/{id}/trash/purge`                                             | `content:purge`     | required |
| POST   | `/entries/relate`                                                       | `content:write`     | required |
| GET    | `/entries/{id}/related-from`                                            | `content:read`      |          |
| PUT    | `/entries/{id}/related-from`                                            | `content:write`     | required |
| GET    | `/menus`                                                                | `settings:write`    |          |
| GET    | `/menus/{key}`                                                          | `settings:write`    |          |
| PUT    | `/menus/{key}`                                                          | `settings:write`    | required |
| POST   | `/menus/{key}/languages`                                                | `settings:write`    | required |
| GET    | `/models/{id}`                                                          | `content:read`      |          |
| GET    | `/models/proposals?state=…`                                             | `schema:propose`    |          |
| POST   | `/models/proposals`                                                     | `schema:propose`    | required |
| GET    | `/models/proposals/{id}`                                                | `schema:propose`    |          |
| POST   | `/models`                                                               | `schema:write`      | required |
| PUT    | `/models/{id}`                                                          | `schema:write`      | required |
| PUT    | `/models/{id}/folder`                                                   | `schema:write`      | required |
| PUT    | `/models/{id}/definition`                                               | `schema:write`      | required |
| POST   | `/models/{id}/remove`                                                   | `schema:write`      | required |
| GET    | `/settings/editorial`                                                   | `settings:write`    |          |
| PUT    | `/settings/editorial`                                                   | `settings:write`    | required |
| GET    | `/settings/language-fallback`                                           | `settings:write`    |          |
| PUT    | `/settings/language-fallback`                                           | `settings:write`    | required |
| GET    | `/settings/media-files`                                                 | `settings:write`    |          |
| PUT    | `/settings/media-files`                                                 | `settings:write`    | required |
| GET    | `/settings/search`                                                      | `settings:write`    |          |
| PUT    | `/settings/search`                                                      | `settings:write`    | required |
| GET    | `/settings/chrome`                                                      | `settings:write`    |          |
| PUT    | `/settings/chrome`                                                      | `settings:write`    | required |
| GET    | `/settings/seo`                                                         | `settings:write`    |          |
| POST   | `/settings/seo/redirect-review`                                         | `settings:write`    |          |
| PUT    | `/settings/seo`                                                         | `settings:write`    | required |
| GET    | `/imports/sources`                                                      | `data:import`       |          |
| POST   | `/imports/sources`                                                      | `data:import`       | required |
| GET    | `/imports?limit=…`                                                      | `data:import`       |          |
| POST   | `/imports`                                                              | `data:import`       | required |
| GET    | `/imports/{id}`                                                         | `data:import`       |          |
| PUT    | `/imports/{id}/archive/parts/{part}` (binary)                           | `data:import`       | required |
| POST   | `/imports/{id}/archive/complete`                                        | `data:import`       | required |
| POST   | `/imports/{id}/advance?recheck=…`                                       | `data:import`       | required |
| GET    | `/imports/{id}/findings`                                                | `data:import`       |          |
| GET    | `/imports/{id}/mapping`                                                 | `data:import`       |          |
| PUT    | `/imports/{id}/mapping`                                                 | `data:import`       | required |
| GET    | `/imports/{id}/wordpress`                                               | `data:import`       |          |
| PUT    | `/imports/{id}/wordpress`                                               | `data:import`       | required |
| GET    | `/imports/{id}/assignments`                                             | `data:import`       |          |
| PUT    | `/imports/{id}/assignments`                                             | `data:import`       | required |
| GET    | `/imports/{id}/principals`                                              | `data:import`       |          |
| PUT    | `/imports/{id}/principals`                                              | `data:import`       | required |
| POST   | `/imports/{id}/principals/accept-suggestions`                           | `data:import`       | required |
| POST   | `/imports/{id}/pause`                                                   | `data:import`       | required |
| POST   | `/imports/{id}/resume`                                                  | `data:import`       | required |
| POST   | `/imports/{id}/cancel`                                                  | `data:import`       | required |
| POST   | `/imports/{id}/undo`                                                    | `data:import`       | required |
| POST   | `/imports/{id}/undo/retry`                                              | `data:import`       | required |
| GET    | `/imports/{id}/artifacts/{name}`                                        | `data:import`       |          |
| POST   | `/exports`                                                              | `data:export`       | required |
| GET    | `/exports/{id}`                                                         | `data:export`       |          |
| POST   | `/exports/{id}/advance`                                                 | `data:export`       | required |
| GET    | `/exports/{id}/artifact?offset=…&length=…`                              | `data:export`       |          |
| GET    | `/roles`                                                                | `content:read`      |          |
| GET    | `/roles/{id}`                                                           | `content:read`      |          |
| POST   | `/roles`                                                                | `roles:write`       | required |
| PUT    | `/roles/{id}`                                                           | `roles:write`       | required |
| POST   | `/roles/{id}/remove`                                                    | `roles:write`       | required |
| GET    | `/plugins`                                                              | `plugins:use`       |          |
| GET    | `/plugins/manage-views`                                                 | `plugins:use`       |          |
| GET    | `/plugins/content-actions?instance_id=…`                                | `plugins:use`       |          |
| POST   | `/plugins/{id}/manage-views/{view}/launch`                              | `plugins:use`       |          |
| POST   | `/plugins/{id}/content-actions/{action}/entries/{instanceId}/launch`    | `plugins:use`       |          |
| GET    | `/plugins/operations?instance_id=…`                                     | `plugins:use`       |          |
| POST   | `/plugins/{id}/operations/{operation}/invoke`                           | `plugins:use`       | required |
| GET    | `/rich-blocks`                                                          | `content:read`      |          |

The four editing routes read and change the editing lease and the shared draft of one entry and
language (see **Editing lease** and **Shared draft** under [Conflicts](#conflicts)). They take no
`Idempotency-Key` and are not written to the audit history. They enforce the caller's ownership and
field read scope, and answer only the fields the credential may read.

Read and write are separate grants. A creator who may change the entry but not read that row or
language (an own-only read on another person's row, or no read grant in that language) can still
take over, write and discard. No answer carries the draft: `GET` is refused (`not_owner` or
`locale_denied`), takeover answers `draft: null`, `409 draft_conflict` answers `current: null`, and
a written draft echoes only the creator's own write. Such a creator cannot learn the draft's
revision: discard without `revision`, then write with `expected_revision: 0`. A creator with no read
grant on the model at all is refused with `403` on every editing route, and nothing changes.

- `GET /entries/{id}/editing`: query `locale` and `kind` (`content` or `page`).
- `POST /entries/{id}/editing/takeover`: body `{ locale }`.
- `PUT /entries/{id}/editing/draft`: body `{ locale, kind, baseline_version_id, expected_revision,
data }`. `baseline_version_id` is the version the draft starts from, or `null`; `data` is the
  draft's field values.
- `POST /entries/{id}/editing/draft/discard`: body `{ locale, kind }`, and optional `revision` to
  discard only that revision.

Refusals on these routes:

- `403 not_owner`: the creator may read or change only their own entries, and does not own the
  entry's row in that language (or the entry, when that language has no row yet).
- `403 locale_denied` with `locale`: reading needs read in that language. Takeover, draft write and
  discard need update there, or create when the entry has no row in that language yet.
- `403 field_denied` with `fields: ["slides"]`: a `page` draft for a creator who cannot read the
  page's sections. A creator who cannot read the page title gets `title` and `baseline.title` as
  `""`; their writes keep the stored title.
- `423 locked` with `holder` and `recovery`: another person holds that language. The lease is
  checked again inside the write or discard, so a takeover between those checks also causes the write or discard to be refused and
  nothing changes. A refused write is kept as the creator's own recovery draft (`recovery`). A
  refused discard keeps nothing: `recovery: null`.
- `409 draft_conflict` with `current`: the revision is stale. `current` and every other draft answer
  hold only the fields the creator may read. `current` is `null` when there is no draft, or when the
  creator may not read that row or language.

`/entries` lists translation-group primaries of one model: `model_id` (required), `published`,
`after`, `limit` (1–50). A creator who may read only their own entries of that model gets
`listing_owner_restricted`; read those entries by id.

`POST /entries` and `PUT /entries/{id}` take relation lists under `relations` (field → list). A
relation field with different links in each language takes them under `locale_relations` (language
→ field → list) instead; see [Different links in each language](/reference/models-and-fields/#different-links-in-each-language).
A relation field also takes `{ connect, disconnect, move }`. Operations run in this order: `disconnect`, then `connect`, then `move`. A `connect` item is
an id (added at the end) or `{ id, position }`; `move` is `[{ id, position }]` for items already related.
A `position` is exactly one of `{ before: id }`, `{ after: id }`, `{ start: true }`, `{ end: true }`; an
anchor is an id in the list at that step. Refusals (422): `relation_position_anchor_missing`,
`relation_write_invalid`, `relation_write_duplicate` (an id in both `connect` and `move`, in both
`disconnect` and `move`, or twice in `move`), `relation_move_target_missing`, and
`relation_position_not_ordered` (a position or `move` on a single-target field). Positions resolve
against the list stored when the save runs; `expected_current_version_id` still refuses a stale save.
Wherever a relation write takes an id it also takes `{ model, id }`, naming the target's model slug; see
[A relation to several models](/reference/models-and-fields/#a-relation-to-several-models).
**Relate** and **Related from** change the list of the language whose entry id is named.

`/trash` lists one model's Trash the same way (`model_id`, `after`, `limit`). Each item is a whole
entry (`scope: entry`, addressed by its primary) or one language moved there alone
(`scope: language`), with `deleted_at` and `purge_after` (30 days later).

`/menus` reads the menus of the accepted Site Chrome and `revision`, the accepted version they
come from (`null` when none is accepted). A menu is `key`, `name` and `variants`: language code to
that language's own `items`. `placed_in` maps a language to where the menu appears there.
`/menus/{key}` adds `languages`, `served` (per site language, the version it serves today under the
site's strict or fallback rule, or `null`) and `live` (per version, then item id, the languages it
shows in today). An item whose page, post or archive is not live is hidden on the site.
`PUT /menus/{key}` creates or replaces one menu with all its versions: `expected_revision`, `name`,
`variants` and optional `placements` (language code to `header`/`footer`; a language left out keeps
its placements). An item points at a `target`: `entry` (`model`, `entry` = `translation_group_id`),
`blog`, `archive` (`role` `category`/`tag`/`author`, `entry`), `url` (https), `email`, `phone` or
`path`, or `null` for a heading with items under it. Every item needs a label; item ids are unique
within one version. `POST /menus/{key}/languages` adds one version: `expected_revision`, `language`
(a site language) and `copy_from` (a language to copy, with new item ids, or `null` for blank). It
answers `menu_not_found` 404, `menu_language_exists` 409, `menu_language_missing` or
`menu_language_unknown` 422. Each save is a new Site Chrome version, accepted at once; unaccepted
Site Chrome changes are rebased onto the accepted version with the menu included (`draft: carried`), or left for a
person (`draft: needs_rebase`). A stale `expected_revision` is `409 stale_document` with
`revision`.

## Import and export

The same imports and exports as Settings → Data transfer, without the admin. Every step runs the
admin's own import or export code with the same refusals; nothing here is a second import engine.

**Import.** `POST /imports` with `format` (`tar`, `tar.gz`, `json`, `transfer`, `wxr`), a new `source`
(`label`, `system`) or an existing `source_id`, and optionally `destination`. One import per site
runs at a time (`409 import_already_active`). Then:

1. Upload the file in parts: `PUT /imports/{id}/archive/parts/{n}` with `Content-Type:
application/octet-stream`, 5 MiB per part, every part but the last exactly 5 MiB, numbered from 1.
   The format's size limit applies. A part number is bound to its bytes' SHA-256 before any byte is
   stored, here and in the admin upload alike: sending the same bytes again answers as before;
   different bytes for a bound part are `409 import_part_conflict`, whatever the key, and nothing of
   them is stored. No URL is ever fetched.
2. `POST /imports/{id}/archive/complete`, optionally with `client_sha256` of the whole file.
   Native `.deewan` uploads verify at most 32 MiB per call. While `outcome.more` is true,
   continue with `advance` or repeat completion with a fresh idempotency key. The saved
   checkpoint resumes by job ID. `client_sha256_matches` is answered only after sealing.
3. `POST /imports/{id}/advance` until no further action is required. Each call runs one bounded
   step on the server: preparing the file, reading it, producing the work list, checking or importing
   a batch. A step the Worker cannot finish in one request continues on the next call. The whole import never runs in a single call.
4. When `decision` names something, answer it and advance again: choose the Strapi mapping
   (`PUT /imports/{id}/mapping`), the WordPress choices (`PUT /imports/{id}/wordpress`), a site
   history's assignments (`PUT /imports/{id}/assignments`), or fix what `GET /imports/{id}/findings`
   lists. `?recheck=true` checks a finished check again.
   A history transfer or WordPress import may also map the people it credits to members here:
   `GET /imports/{id}/principals` lists each principal (`ref`, source `label`, `email`, `uses`,
   `suggestion`, `choice`, `mapped`, `problem`) and the active `members`;
   `PUT /imports/{id}/principals` with `{ "ref", "user_id" }` maps one (`user_id: null` leaves it a
   label). Native `.deewan` reviews page principals and assignments with an opaque
   `next_cursor`: pass it unchanged with `limit` (1–100, default 50); the active-member choice
   list accompanies each principals page. `POST /imports/{id}/principals/accept-suggestions`
   accepts exact-email suggestions only for the requested native-transfer page: use the same
   `cursor` and `limit` as its GET, then continue with the GET’s `next_cursor`. Legacy JSON and
   WordPress imports accept all undecided suggestions in one call. Existing choices stay. A member must be active on this site (`409 principal_user_ineligible`); an
   unknown `ref` is `404 principal_not_in_transfer`. Nothing creates or changes an account. The check
   blocks with `principal_mapping_invalid` when a mapped member lost access, and the run checks again
   before it writes. See [Import and migration](/guides/import-migration/).

A later import from the same source creates what is new and skips what it already imported; it never
changes content an earlier import wrote, and saving a new mapping changes nothing already imported.
The one exception is a WordPress menu still exactly as the last import wrote it, which gains the items
that now map ([Import and migration](/guides/import-migration/)). 5. A clean, current check imports on the next advance: advancing a checked job is the go-ahead.

Every import answer except artifacts is `{ "data": state }`:

- `job`: `id`, `status`, `stage` (`upload`, `prepare`, `review`, `check`, `import`, `undo`, `done`),
  `format`, `source`, `plan_revision`, `upload` (`state`, `parts_received`, `bytes_received`,
  `part_size`), `progress`, `dry_run_state`, `undo_state`, `final_status`, `error`, times.
- `findings`: counts of `blocking`, `warning` and `info`.
- `decision`: `null`, or `{ kind, message }` with `kind` one of `upload_needed`,
  `mapping_required`, `wordpress_mapping_required`, `findings_block`, `paused`, `blocked`,
  `cancel_pending`, `undo_refused`, `undo_failed`.
- `more`: another advance would run a step now.
- `next_actions`: the operations currently available.
- `step` and `outcome`: what this request ran, or `null`.

`pause` stops after the current batch; `resume` continues a paused job; `cancel` keeps what was
already imported and writes the cancelled receipt (`decision.kind: cancel_pending` while file
cleanup is still open). `POST /imports/{id}/undo` reverses one batch per call and is destructive;
`undo/retry` returns refused units to the queue where the admin allows it.
`GET /imports/{id}/findings?limit=&cursor=` reads at most 500 findings (default 100), worst first and
then in the order they were found; pass `next_cursor` as `cursor` to read on (`null` after the last).
`GET /imports/{id}/mapping`, `GET /imports/{id}/wordpress`, `GET /imports/{id}/assignments` and
`GET /imports/{id}/principals` take
the same `limit` (at most 500, default 200) and `cursor`. Their long lists hold one page in the
admin's order: Strapi `types`, `normalized.skipped_fields`, each list of `normalized.group_keys` and
`review.unresolved`; WordPress `posts`, `pages` and `entries`; history `assignments`; `principals`
and `members`. `totals` counts
the full list at that location in the response, and every other field, `mapping` included, comes whole on every
page.
`GET /imports/{id}/artifacts/{name}?offset=&length=` serves a byte range of `receipt`, `problems`
(`problem-rows.csv`), `entries`, `media` (the manifests), `partition` or `plugin_data` (the
WordPress plugin data file, see [Import and migration](/guides/import-migration/)), the same bytes the admin
downloads, at most 4 MiB a request, as `application/octet-stream` with the `X-Artifact-*` headers
below; `X-Artifact-Content-Type` names the file's own type. A missing job and another site's job both
answer `404 job_not_found`.

**Export.** `POST /exports` with `product` (`bundle`, `content`, `csv`, `xlsx`, `history`), optional `models` and `locale`. Then `POST /exports/{id}/advance` until `more` is `false`. Site copies and history use the resumable `.deewan` format; content uses JSON Lines. Each advance keeps the next immutable page or advances multipart assembly. Assembly can take several calls. The finished `artifact` records the file's size and complete SHA-256; only then are page objects removed. `pages` lists each built page's checksum, size, cursors and `readable` state. CSV and XLSX retain their own limits.

`GET /exports/{id}/artifact?offset=&length=` reads the finished file, at most 4 MiB a request; before
it is finished this is `409 export_not_final`. Add `page=<n>` to read one kept page while the export
runs; a page removed after finishing is `409 export_page_gone`. Every read answers
`application/octet-stream` with `X-Artifact-Offset`, `X-Artifact-Length`, `X-Artifact-Total`,
`X-Artifact-Sha256` and `X-Artifact-Content-Type` of the whole file, `X-Artifact-Next-Offset` (absent
at its end) and, for a page, `X-Artifact-Page` and `X-Artifact-Next-Page` (at the page's end, when the
next page is built). A stored file that is not the recorded one is `409 export_artifact_changed`;
past the end is `400 artifact_range_invalid`. Two advances at once never lose or duplicate a page: the
second answers the export as the first left it. Expired and failed exports are refused as in the admin.

Every write needs `Idempotency-Key`. History records the operation, job, format, phase and outcome;
never file contents, content values, mappings, findings text or downloaded bytes.

## Site settings

`settings:write` reads and changes one typed section per area. Each write names the revision it
read; a stale one writes nothing. Each write uses the same validator and the same stored value as
its Settings screen, and records `management.settings.update` beside that screen's own entry.
The creator must hold `site:settings` now; search needs `site:infra` instead.

| Section              | Read                                                                                                                                   | Write                                                                                                                                                                                               | Revision                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Retention and review | `versions_to_keep`, `review_flow`                                                                                                      | either, or both                                                                                                                                                                                     | `expected_revisions.versions_to_keep`, `.review_flow`         |
| Missing language     | `policy` (`strict` or `fallback_to_default`), `chains`, `languages`                                                                    | `policy`, `chains` (replaced whole)                                                                                                                                                                 | `expected_revisions.policy`, `.chains`                        |
| Media files          | `kinds` (each `enabled`, `max_bytes`, `formats`), `limits` (`min_bytes`, `buffered_max_bytes`, `streamed_max_bytes`, `kind_max_bytes`) | `kinds` (replaced whole; images stay on; a kind without `formats` takes its defaults)                                                                                                               | `expected_revision`                                           |
| Search               | `enabled`, `models`, `weights`, `modes`, what may be added or tuned                                                                    | `enabled`, `models`, optional `weights`, optional `modes` (`word`, `english_stem` or `substring` per model; absent is `word`; `english_stem` matches whole words in a language that is not English) | `expected_revision`                                           |
| Site Chrome defaults | `footer.note` per language, `routes`                                                                                                   | `footer`, `routes`                                                                                                                                                                                  | `expected_revision` (accepted Site Chrome version, or `null`) |
| SEO                  | `seo` defaults, `sitemap`, `robots`, `redirects`                                                                                       | any of them                                                                                                                                                                                         | `expected_revision` (accepted Site Chrome version, or `null`) |

- A stale settings revision is `409 settings_changed_concurrently` with `field`. A change that names
  a setting without its revision is `400 invalid_request`.
- Retention and review, missing language, media files and search keep their key with the setting, in
  one write. A retry with the same key and body gets the first answer, even after the revision moved.
  A write that was saved but not finished answers `503 temporary_failure`; the retry finishes it and
  replays the answer.
- The validators answer by name, for example `invalid_versions_to_keep`, `review_flow_items_in_progress`
  (entries wait in review; they are listed), `fallback_language_unknown`, `fallback_cycle`,
  `invalid_media_files`, `site_search_model_invalid`, `site_search_weights_invalid` and
  `site_search_mode_invalid`.
- Site Chrome defaults and SEO are saved as a new accepted Site Chrome version, like menus:
  unaccepted changes are carried (`draft`), and a stale revision is `409 stale_document`.
- A social image or logo is named by `og_image_media_id` / `logo_media_id` from this site's media
  library; the server records its address and size.
- Redirects are replaced whole. An exact source that is a live address, a reserved Blog address or a
  named route is refused. Changing a pattern rule needs `redirect_review_digest`: post the rules to
  `/settings/seo/redirect-review`, read which live pages each pattern covers, and send its `digest`.
  Without it the answer is `409 redirect_review_stale` with the review.
- Not here: secrets, passwords, sign-in methods, identity providers, plugin secrets and tokens,
  deployment, source providers, domains and other infrastructure.

## Visitor comments

Comment operations run the admin comments route with the credential's narrowed permissions, so its
rules, refusals and conflict answers are the admin's (see
[Visitor comments](/reference/models-and-fields/#visitor-comments)). Every write needs `Idempotency-Key` and
is recorded in History as `management.comment.moderate`, `management.comment.delete` or
`management.comment.settings`: the counts and target state, never a comment's text or email.

| Operation                                                    | Scope               | What it does                                                                                                                     |
| ------------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `GET /comments/settings` (`getCommentSettings`)              | `settings:write`    | Every model and whether its entries take comments.                                                                               |
| `PUT /comments/settings` (`updateCommentSettings`)           | `settings:write`    | `{ model, enabled }`: opens or closes one model. Closing hides comments; nothing is deleted.                                     |
| `GET /comments` (`listComments`)                             | `lifecycle:publish` | Newest first, 50 a page; `state` (default `pending`), `model`, `entry`, `lang`, `cursor`. No email.                              |
| `GET /comments/{id}` (`getComment`)                          | `lifecycle:publish` | One comment with its private email, parent and entry.                                                                            |
| `POST /comments/moderate` (`moderateComments`)               | `lifecycle:publish` | `{ to, comments: [{ id, expected }] }`, at most 25, each only if still in the state read.                                        |
| `POST /comments/publish-imported` (`publishImportedComment`) | `lifecycle:publish` | Shows one comment imported without consent. Consent stays false.                                                                 |
| `POST /comments/remove` (`deleteComments`)                   | `content:purge`     | Deletes at most 25 comments with their replies and reactions. Also needs `lifecycle:publish` and delete on each comment's model. |

- A comment whose state changed since it was read answers `conflict` with its current state; one imported without
  consent answers `consent_missing` to an approval.
- Reactions are visitor-facing and have no management write. A listed comment carries its reaction
  counts.

## Conflicts

Every write names the state it was made against. A stale value is refused and writes nothing.

- **Entry update:** `expected_current_version_id`. Stale: `409 version_conflict` with
  `current_version_id`. A create or update names addresses in `slugs`, one per language
  (`{ "fr": "bonjour" }`); a language left out keeps its address. A refused address names
  `field: "slug"` and its `locale`. A create in a language the site does not have is refused
  `400 unknown_locale` with `lang`. A language removed while the create runs gives
  `409 language_changed`, and nothing is written.
- **Publish:** `to`, `expected_workflow_revision`, `expected_current_version_id`. A newer draft is
  never published silently: `409 scheduled_target_stale`. A workflow state that has changed: `409 workflow_conflict`
  with `revision`.
- **Unpublish:** `to`, `expected_workflow_revision`, `expected_published_version_id`, and
  `acknowledged_dependents` equal to `ids` from `/entries/{id}/dependents` when other content
  references the entry.
- **One language:** add `locale` to a publish or unpublish to move that language only. `to` is
  checked against that language's own state in `workflow.locales`, and an unpublish pins that
  language's own published version. Without `locale` every language moves.
- **Page save:** `expected_current_version_id` and `expected_facts_digest` from `GET /pages/{id}`.
  A save carries one language (`locale`) and changes that language only; each language owns its
  sections.
- **Page language start:** `locale` (a language of the page with no page yet, or a site language
  the page does not have yet), `source` (another
  language of the page to copy, or `null` for blank) and `expected_current_version_id`. A copy keeps
  section order, appearance, values and shared-section links under new section ids. `409 translation_exists`,
  `422 translation_source_unavailable`.
- **Proposal:** `base_version_id` must be the entry's current version.
- **Editing lease:** while another person holds an entry and language open in the editor, a save,
  move, assignment, restore or Trash of that entry and language is refused `423 locked` with the
  `holder`. `GET /entries/{id}/editing?locale=&kind=` reads who holds it and the shared draft (`kind`: `content`
  for the entry editor, `page` for the page composer);
  `POST /entries/{id}/editing/takeover` ends that lease at once (the editor keeps its work as a
  recovery draft) and nobody holds it afterwards. Your own open editor never blocks your
  credential. An expired lease never blocks.
- **Shared draft:** `PUT /entries/{id}/editing/draft` names `kind` and `expected_revision` (`0` when there is
  none); stale: `409 draft_conflict` with `current`. `POST /entries/{id}/editing/draft/discard`
  removes it. A draft is never a version; an entry update clears it.
- **Move:** `to` and `expected_workflow_revision`, optional `note` and `locale`. A step that would
  publish or unpublish is `422 transition_kind_mismatch`: use publish or unpublish for it. A move
  without `locale` between two unpublished stages leaves a language that is already published where
  it is; unpublish that language by itself. A move clears the assignment, as it does in the admin.
- **Assignment:** `expected_workflow_revision`, `assignee_id` (a person from `/assignees`, or
  `null` to clear) and optional `due_date` (`YYYY-MM-DD`, today or later). Stale: `409
workflow_conflict` with `revision`. Someone who cannot act on the entry: `422
assignee_cannot_act`.
- **Version restore:** `expected_current_version_id`. The old version becomes a new current draft;
  what is live does not change. Stale: `409 version_conflict`. Optional `locale` restores that
  language only: its fields, its own relation lists and its address come from the version; shared
  fields, shared relations, media and every other language stay as they are. A language the version or the entry does not contain: `422 restore_locale_missing`. It needs `restore` for that language.
- **New language:** `lang` from `/languages`, optional `slug` (`null`: no address; omitted: the
  primary's address, suffixed when this language already holds it). It starts empty;
  the next entry update writes it. Already there: `409 locale_exists` with its `instance_id`.
- **Trash:** `scope: entry` moves every language; `scope: language` moves one non-owner language
  (`owner_language` for the owner). Live content is refused with `409 content_live` and
  `live_languages`: unpublish it first. A restored entry is a draft.
- **Restore from Trash:** `GET /entries/{id}/trash` names `conflicts` (blocking) and `references`
  (links that will not work). Restore is refused with `409 restore_conflict` while another item
  uses the address.
- **Purge:** `confirm` repeats the entry id from the path. It deletes the item, its history and its
  visitor comments, and cannot be undone. `GET /entries/{id}/trash` names the comments it will delete
  in `comments`; the answer names those deleted in `comments_deleted`.
- **Relate:** `ids` (1–25 entries), `field` (a many-to-many relation field they all have),
  `connect` and/or `disconnect` (1–10 linked entries in all, none in both) and `expected_versions`
  naming every entry's current version. Each entry is its own draft save and gets its own result:
  `done`, `unchanged` (already as asked; nothing written), `covered` (another language of the same
  entry did it; for a field with different links in each language the first selected language changes
  every selected language's own list in one save) or `refused` with `reason`, for example `version_conflict` or
  `batch_relation_exclusive` for a one-to-many field. A refusal stops nothing else. Nothing is
  published.
- **Related from:** `GET /entries/{id}/related-from` lists every relation field of any kind
  (one-to-one, many-to-one, one-to-many, many-to-many) whose target is this entry's model, as
  `groups` by source model and field with `relation_type`. Each source has its display `label`,
  `draft` / `live`, `version_id`, `can_change` and `readable`; a source the credential may not read
  has no `slug` or `label`. `PUT` takes `field_id`, `source_id`, `action` (`add` or `remove`) and
  `expected_source_version_id`. Both need `read` on this entry; a change also needs `update` on the
  source. It is the source's own draft save: the source's permissions, field rules, cardinality,
  one-owner rule, hierarchy rule and version check apply. It never publishes. Stale: `409
version_conflict`. A to-one source that already points elsewhere is refused with `409
related_from_replace_unconfirmed`, naming `current` and `next` (`instance_id`, `slug`, `label`;
  names the credential may not read are null). Send `replace_target_id` set to `current.instance_id`
  to confirm that exact replacement. The answer is `outcome` (`saved` or `unchanged`), the source's
  new `version_id` and the updated `related_from`.

`GET /entries/{id}` returns the workflow `state`, `revision` and the `transitions` this credential
may take: `kind: publish | unpublish` with `lifecycle:publish`, `kind: move` with `workflow:move`.
`to` must be one of them; publish and unpublish refuse a step of another kind with
`transition_kind_mismatch`, and so does a move.

## Proposals for editor review

An integration that should not write directly can propose field changes instead:

```json
{
  "base_version_id": "<current version id>",
  "fields": { "title": "A clearer title" },
  "note": "Why"
}
```

- Up to 50 value fields of the entry's model, at most 64 KiB of values, a note of at most 2,000
  characters. Relation and media fields cannot be proposed (`proposal_field_unsupported`).
- Nothing changes until a person applies it. The entry editor shows each open proposal above the
  fields and the proposed value beside each field it names, with **Apply** and **Dismiss**.
- **Apply** is the ordinary save, run as the person applying it and pinned to `base_version_id`.
  Their validation, permissions, ownership rules and workflow apply. If the entry changed after the
  proposal was made, Apply refuses with `proposal_stale` and writes nothing.
- The editor disables Apply while it has unsaved edits. Dismiss leaves the entry as it is.
- A proposal's `source` names who made it: `{ "kind": "management", "id", "label" }` for a credential,
  or `{ "kind": "plugin", "id", "label", "requested_by" }` for a plugin installation acting for a
  person (docs/plugins/protocol-v1.md). The editor shows a plugin proposal as `Proposed by <plugin> ·
requested by <person>`. Listing an entry's proposals also includes `{ "kind": "ai", "id", "label" }`, where `id` names the batch AI job. Each proposal includes `revision`; optional `original_fields` contains the readable baseline values for the proposed fields.

## Direct model changes

`schema:write` changes models without a review step. Each write runs the Content Builder's own
apply or delete: the same checks, breaking-change refusals, relation rules, grant moves and audit.

1. `GET /models/{id}` answers the whole `definition` and `revision`.
2. Write against that `revision`:

- `POST /models` with `{ "definition": { "model": …, "fields": [ … ] } }` creates a model. No field ids.
- `PUT /models/{id}` with `expected_revision` and `model` (`name`, `slug`, `description`,
  `settings`, `enableI18n`) changes the model and keeps its fields.
- `PUT /models/{id}/folder` with `{ "folder": "Blog" }` (1 to 40 characters, or `null`) puts the model in a
  content navigation folder or takes it out. It is display only: no `expected_revision`, the model
  `revision` does not move, and `listModels` shows it as `folder`. The answer is `model_id`, `slug`
  and `folder`.
- `PUT /models/{id}/definition` with `expected_revision` and the complete `definition` replaces it:
  keep a field by its `id`, add one without an id, leave one out to remove it.
- `POST /models/{id}/remove` with `expected_revision` and `confirm` (the model id again) deletes a
  model that holds no content.

- The answer is `model_id`, `slug`, `created_field_ids` and `renamed_from`. After a rename or a
  delete, `dependents.complete` says whether all role grants and token scopes naming the old slug were updated or removed; it is absent on a replay.
- `revision` changes with any change to the model or its fields. A stale one is `409 model_changed`
  and writes nothing.
- A change unsafe for existing content is refused with `409 model_change_blocked` and `changes`
  (`kind`, `field`, `affected_count`, `message`, `suggestion`). Nothing is overridden: migrate or
  clear the content first.
- Other refusals keep the Content Builder's reasons, for example `duplicate_field_key`,
  `field_not_found`, `unique_unsupported`, `model_name_collision`, `stale_role_grant`,
  `stale_token_scope`, `model_not_empty` and `model_has_bound_queries`.
- The creator must hold `model:apply` now, and `model:delete` for a delete; without it the answer is
  `403 missing_permission`.

## Schema proposals

Instead of changing a model, an agent can propose a new model or a changed definition; a person
reviews it in the Content Builder and applies it through the ordinary save, breaking-change check and apply process.

1. `GET /models/{id}` answers the model's whole `definition` (`model` and `fields`, each field with
   its `id`), `updated_at` and `revision`.
2. `POST /models/proposals` with the edited definition:

```json
{
  "mode": "update",
  "model_id": "<model id>",
  "base_updated_at": "<updated_at from getModel>",
  "definition": {
    "model": { "name": "Article", "slug": "article", "enableI18n": true },
    "fields": ["…"]
  },
  "note": "Why"
}
```

- `definition` is complete: keep each field by its `id`, add a field without one, leave a field out
  to remove it. Field order is array order. `config`, `derived`, `ui` and `validation` are JSON text,
  as the Content Builder stores them.
- A new model is `{ "mode": "create", "definition": { … }, "note": … }`, with no field ids.
- At most 200 fields and a note of at most 500 characters.
- The definition is read and checked by the same validation used when applying a model. What the apply refuses is refused here
  with the same reason, for example `duplicate_field_key`, `field_not_found`, `unique_unsupported`,
  `model_slug_taken` and `model_name_collision`. If the model changed since `getModel`, the answer is
  `409 model_changed` with `current_updated_at`.
- Changes that would break existing content are allowed, and listed in `changes` (`kind`, `field`,
  `affected_count`, `message`, `suggestion`). The person sees the same check again before applying.
- The creator must hold `model:apply` now; without it the answer is `403 missing_permission`.
- **Content Builder → Models** lists open proposals with **Review** and **Dismiss**. Review opens the
  editor with the proposed definition; Save applies it as an ordinary model change, as the person
  saving, and marks the proposal `applied` in the same write. They can edit it first.
- A proposal is pinned to `base_updated_at`. Once the model changes it is `stale: true`, its apply is
  refused with `409 schema_proposal_stale`, and it can only be dismissed.
- `GET /models/proposals` lists the site's proposals, newest first (`state` filters `open`,
  `applied`, `dismissed`). `GET /models/proposals/{id}` reads one.

## Plugin launches

An agent can create a launch link to open an installed plugin for a person. Creating the link does not run the plugin; invoking a declared [operation](#plugin-operations) does.

- `GET /plugins` lists installed plugins: `state` (`active` or `disabled`), `launchable`, and for an
  active plugin its `manage_views` and `content_actions`. They come from the manifest stored at
  install or upgrade. `GET /plugins/manage-views` and `GET /plugins/content-actions` list the same
  entries flat. `instance_id` keeps only the actions that entry offers.
- A content action lists `model_ids`: models granted to the plugin that this credential may read.
- `GET /rich-blocks` (`content:read`) lists each installed plugin's rich text block definitions:
  fields, rules, sample values, render tree and migrations, as `<plugin id>/<name>`. Write a block
  into a rich value as its canonical figure (see [Blog → Plugin blocks](/guides/blog/#plugin-blocks)).
  Only an active plugin's blocks can be added or changed.
- Only launches the credential could open now are listed, as entries and as tools. A view needs a
  granted model the creator reads, own entries included, inside the credential's models. An action
  needs at least one model in `model_ids`. A permission change shows on the next request. A launch
  sent anyway is still checked in full.
- `POST /plugins/{id}/manage-views/{view}/launch` and
  `POST /plugins/{id}/content-actions/{action}/entries/{instanceId}/launch` create one launch link.
  The answer is `201` with `outcome: launch_created`, `url`, `expires_at` and `single_use: true`.
- The link carries one launch code. It works once and expires 60 seconds after it is made. A person
  opens it in a browser and the plugin acts as the credential's creator, exactly as when that person
  opens the plugin in the admin. Nothing reaches the plugin until then, and the answer never says the
  plugin did anything.
- Once opened, the plugin works within its own grant and the creator's permissions, limited to the
  credential's models and capped by its scopes. The delegation carries only the plugin capabilities
  the scopes allow: `content:read` gives `content:read` and `workflow:read`; `lifecycle:publish`
  gives `workflow:publish`, `workflow:unpublish` and `workflow:locale`; `content:write` gives
  `content:write`, `content:create` and `draft:write`; `content:trash` gives `content:delete`;
  `media:write` gives `media:write`, `media:read`, `media:update` and `media:source`;
  `content:propose` gives the same name. A
  plugin command outside that is `capability_refused`.
- Each launch rechecks the creator's current permissions, the credential's models and the plugin
  grant, the same check the admin runs. A disabled plugin is `409 installation_not_active`; an
  uninstalled one, or one on another site, is `404 not_found`.
- No `Idempotency-Key`: each call makes a new link. Unused links expire.

## Plugin operations

A plugin manifest may declare operations: a small form and a result Dee Wan renders itself. An agent
runs one and gets the result back.

- `GET /plugins/operations` lists the operations this credential may run now: `scope` (`site` or
  `entry`), `destructive`, `input` (the declared fields), `input_schema` (JSON Schema of `input`),
  `result` (the result components) and `model_ids` (for an entry operation, the models it may run
  on). `instance_id` keeps only that entry's operations. `GET /plugins` carries the same list per
  plugin.
- An operation is listed only while the plugin is active and its grant holds every capability the
  operation requires, inside what the credential's scopes allow. An entry operation also needs a
  granted model the creator reads inside the credential's models; a destructive one needs `update`.
  A site operation needs `site:plugins`, and the plugin then acts for the creator on the granted
  models they read inside the credential's models, capped by its scopes. Scheduling's `releases`,
  `release-edit` and `release-run` are such operations. A grant or permission change shows on the
  next request.
- `POST /plugins/{id}/operations/{operation}/invoke` runs it. The body is
  `{ "instance_id"?: "…", "input"?: { … } }`; `instance_id` is required for an entry operation and
  refused for a site one. `input` is closed: an unknown key or a value outside the field's bounds
  is `400 input_invalid` with `issues`.
- The answer is `200` with `outcome: completed` and `result.blocks`: `text`, `rows`, `links`
  (https only) and `json`. The same `Idempotency-Key` and body return the first result with
  `replayed: true`; the key with another body is `409 idempotency_key_reused`. A replay is checked
  like a new run first: an operation no longer offered to this credential is
  `404 operation_unavailable`, not the old result.
- Refusals: `404 operation_unavailable` (unknown, or not offered to this credential now),
  `422 plugin_refused` (the plugin's own `refusal: { code, message }`), `504 plugin_timeout`,
  `502 plugin_unreachable`, `502 plugin_response_invalid`, `409 plugin_unavailable` (the plugin was
  disabled, narrowed or changed while it ran), `409 invocation_in_progress`.
- The plugin runs it as the credential's creator. It never receives a credential: core sends a
  one-time code, and the plugin exchanges it with its own installation token. The run is audited as
  `plugin.operation.run` with digests of the values and the result, not the values themselves.

## Plugin content policies

A plugin may declare content policies: checks Dee Wan asks before a save, a restore, a deletion, a
publication, an unpublication or a workflow move. An entry update, a page save, a version restore, a Trash command and a transition through this API invoke the same policy checks as their editor equivalents, with
`caller.via: management_credential`. `GET /plugins` lists each plugin's `policies` with their `kind`
and `mode`.

- The answer carries `policy_results`: a policy that warned, one set to warn that did not answer
  (`outcome: unavailable`, with `failure`), or one that transformed the saved content
  (`outcome: transformed`, `fields` naming what it changed). Each names `installation_id`,
  `plugin_name`, `policy_id`, `policy_label`, `locale`, `message` and `fields`. The write is done; do
  not send it again. After a transform, read the entry back for the stored values.
- `422 plugin_policy_transform_invalid`: a policy's transformed content broke a rule. `cause` holds
  the rule's `code`, `message` and `detail`. Nothing was written.
- `422 plugin_policy_transform_conflict`: two policies changed one field differently. Nothing was
  written.
- `422 plugin_policy_refused`: a policy said no. It names `plugin`, `policy`, `policy_label`,
  `locale`, the plugin's `code` and `message`, and `fields`. Nothing was written.
- `503 plugin_policy_unavailable`: a policy set to block did not answer. It names the policy and the
  `failure`. Nothing was written; try again later.
- `429 plugin_policy_budget_exhausted`: one request asked policies more often than it may. Send fewer
  entries at once.

## Command line and MCP

`dee-wan-manage.mjs` is one file with no dependencies. It needs Node 18 or newer. Download it from
**Settings → API**. The credential is `DEE_WAN_MANAGEMENT_TOKEN` when it is set, otherwise the saved
login for the origin (see [Sign in from the terminal](#sign-in-from-the-terminal)). The CMS origin is
`--url` or `DEE_WAN_URL`. The origin must use `https` (`http` only on `localhost`, `127.0.0.1` or
`[::1]`).

```bash
export DEE_WAN_MANAGEMENT_TOKEN=<credential>
node dee-wan-manage.mjs help
node dee-wan-manage.mjs list-entries --url https://cms.example --model-id <model id>
node dee-wan-manage.mjs create-entry --url https://cms.example --body-file entry.json
node dee-wan-manage.mjs upload-media --url https://cms.example --file photo.webp
node dee-wan-manage.mjs launch-plugin-manage-view --url https://cms.example --id <installation id> --view calendar
```

- Each command is one operation above, named in kebab case (`publishEntry` → `publish-entry`).
  There is no raw request mode.
- Writes always send an `Idempotency-Key`. The key is printed to stderr; pass it back with
  `--key <key>` to retry safely.
- Exit `0` on success, `1` when Dee Wan refused (the answer is printed), `2` for usage, network or
  credential problems.

### Sign in from the terminal

```bash
node dee-wan-manage.mjs login --url https://cms.example
node dee-wan-manage.mjs status --url https://cms.example
node dee-wan-manage.mjs logout --url https://cms.example
```

`login` signs you in with your own account, like [Connect an app](#connect-an-app):

1. It reads `/.well-known/oauth-authorization-server`. The issuer must be the origin, and the token,
   registration and revocation endpoints must live on it. PKCE `S256` must be supported.
2. It starts a listener on `127.0.0.1` only, on a port the system picks, and registers a client
   whose one redirect URI is `http://127.0.0.1:<port>/callback`.
3. It opens `/connect` in the browser with PKCE `S256` and a random `state`. `--no-open` prints the
   address instead. `--scope "content:read content:write"` asks for fewer scopes; without it every
   scope is asked for. You pick the site on the consent page.
4. The callback must be `GET /callback` with the same `state`, the issuer as `iss`, and exactly one
   `code`. Other paths answer `404`. **Cancel** ends the login with exit `1`. After 5 minutes it
   gives up with exit `2`.
5. It exchanges the code and saves the login.

A failed or cancelled login writes nothing. A saved login stays as it was.

The saved login:

- One per origin, in the operating-system config directory: `~/Library/Application Support/dee-wan`
  on macOS, `$XDG_CONFIG_HOME/dee-wan` or `~/.config/dee-wan` on Linux, `%APPDATA%\dee-wan` on
  Windows. The directory is `0700` and the file `0600` (on Windows the permissions are best effort).
- It holds the origin, client id, site, scopes and the current refresh token. Never an access
  token. No command prints a token.
- Every command renews it: it takes a lock for the origin, uses the refresh token, writes the new
  one to a temporary file in the same directory, flushes it and renames it over the old one. Two
  commands at once wait for each other, so a refresh token is never used twice. A lock left by a
  process that died, or older than 2 minutes, is cleared.
- When Dee Wan no longer accepts it (revoked, expired after 30 days unused, or the person lost the
  site), the command exits `2` and asks you to run `login` again. The file is kept.
- A new `login` for the same origin replaces it and revokes the old connection.
- `DEE_WAN_MANAGEMENT_TOKEN` always wins. It is never saved. `status` says when it overrides the
  saved login.

`status` shows the origin, the saved site and scopes, whether a client id is saved, and whether
`DEE_WAN_MANAGEMENT_TOKEN` is set. It exits `2` when there is neither. `logout` revokes the connection
at the revocation endpoint first and then deletes the file. When revocation fails the file is kept
and it exits non-zero; run it again.

`node dee-wan-manage.mjs mcp --url <origin>` runs an MCP server over stdio. Its tools are the same
operations, named in snake case (`publish_entry`), with the contract's input schemas. Like the
remote server, it lists only the tools the credential's scopes allow (read from `GET /site`), and
the plugin tools below. A write tool takes an optional `idempotency_key` and returns the key it
used. A call answers `structuredContent` `{ status, idempotency_key?, body }` and the same object as
JSON text. **Settings → API** shows a client configuration to copy:

```json
{
  "mcpServers": {
    "dee-wan": {
      "command": "node",
      "args": [
        "/path/to/dee-wan-manage.mjs",
        "mcp",
        "--url",
        "https://cms.example"
      ],
      "env": { "DEE_WAN_MANAGEMENT_TOKEN": "<your credential>" }
    }
  }
}
```

Without `env`, the MCP server uses the saved login for `--url` and renews it under the same lock
while the session runs.

The upload tool reads a local file path on the machine that runs the server.

Import and export on the command line:

```bash
node dee-wan-manage.mjs create-import --body '{"format":"wxr","source":{"label":"Old blog","system":"wordpress"}}'
node dee-wan-manage.mjs upload-import-part --id <job id> --file export.xml
node dee-wan-manage.mjs advance-import --id <job id> --follow
node dee-wan-manage.mjs create-export --body '{"product":"bundle"}'
node dee-wan-manage.mjs advance-export --id <export id>
node dee-wan-manage.mjs read-export-chunk --id <export id> --out site.json
```

- `upload-import-part --file` sends the whole file in 5 MiB parts, then completes the upload with
  the file's SHA-256. Each part's key comes from its bytes, so running it again replays; changed
  bytes are refused. `--part <n>` sends one part only. The stdio MCP tool takes `file_path` and an
  optional `part`.
- `advance-import --follow` advances step after step, one line per step on stderr, and stops on a
  decision, at the end or on a refusal; the last state is printed as JSON. Over MCP each call is one
  step.
- `read-export-chunk --out <file>` reads the finished export chunk by chunk, checks its SHA-256 and
  only then writes the file; with `--page <n>` it saves one kept page. `--finish` first advances the
  export until it is finished, each step under a key derived from the export and the step, so running
  it again after a lost answer replays instead of building twice.
- `read-import-artifact --out <file>` saves a whole import artifact the same way.
- `get-import-findings`, `get-import-mapping`, `get-word-press-review`, `get-history-assignments` and
  `get-import-principals --all` read every page into one answer.
- On `429`, and on `409 idempotency_in_progress` with `Retry-After`, the command waits for
  `Retry-After` and retries with the same key. Without `Retry-After` it stops and prints the answer.

### Remote MCP

Agents that connect over HTTPS need no download. Give the agent the address alone and it signs
you in (see [Connect an app](#connect-an-app)):

```
https://cms.example/api/manage/mcp
```

For automation, send a management credential instead. **Settings → API** shows both:

```json
{
  "mcpServers": {
    "dee-wan": {
      "type": "http",
      "url": "https://cms.example/api/manage/mcp",
      "headers": { "Authorization": "Bearer <your credential>" }
    }
  }
}
```

- One JSON-RPC message per `POST`, one JSON answer. No session, no stream: `GET` and `DELETE` are
  `405`. A notification is `202`. A batch is refused.
- Protocol versions `2025-06-18` and `2025-03-26`. Another `MCP-Protocol-Version` header is `400`.
- The credential is read again on every message. A revoked credential is `401` on the next one.
  Each `POST` counts once against the rate limit.
- `tools/list` lists only the tools the credential's scopes allow. A call runs through the same
  scope check, audit, conflicts and idempotency as the HTTP API, as the credential's creator.
- A request from a browser page on another origin is `403`.
- The remote upload tool takes the file as `content_base64` and `file_name`, at most 8 MiB decoded.
- `upload_import_part` takes one part as `content_base64` with `id` and `part`. `read_export_chunk`
  and `read_import_artifact` answer one byte range as
  `{ content_base64, content_type, offset, length, total, next_offset, sha256, page, next_page }`,
  never a whole large file; `content_type` and `sha256` describe the whole file, and `page` and
  `next_page` are `null` outside an export page. `get_import_findings` reads one page of findings.
- With `plugins:use`, each active plugin view and entry action is also a tool, such as
  `plugin_com_example_scheduler_view_calendar` (no arguments) or
  `plugin_com_example_scheduler_action_schedule` (`instance_id`). The name is `plugin_`, the plugin id,
  `view` or `action`, and its id, lowercased with other characters as `_`. Tools are read again on
  every message: a disabled or removed plugin has none on the next one. A name two launches share, a
  name a core tool has, or a name over 64 characters is listed for none of them; `GET /plugins` says
  why in `mcp_tool.omitted_because`. A view or action call only creates a launch link, as above. The
  stdio adapter lists the same tools.
- Each operation this credential may run is a tool too, such as
  `plugin_com_example_scheduler_op_status`. Its arguments are `instance_id` for an entry operation,
  `input` (the operation's `input_schema`) and an optional `idempotency_key`. A call runs the
  operation now and returns its result as `structuredContent` and text. Its annotations keep
  `destructive`. A tool the credential may no longer run is gone on the next message; calling it
  anyway is `Unknown tool`. An `automation` operation is never a tool.
- Both transports give the same tool names, schemas, annotations, results and refusals. Only the
  upload tool differs: base64 here, a local file path in the stdio adapter.
- A credential is created by a signed-in person in **Settings → API**, or by connecting an app.

### Connect an app

An MCP client that supports OAuth signs a person in with their own account. Nothing is installed.

1. The client calls the MCP address without a token and gets `401` with
   `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…"`.
2. It reads `/.well-known/oauth-protected-resource/api/manage/mcp` and
   `/.well-known/oauth-authorization-server`, registers itself at `POST /api/oauth/register`, and
   opens the admin's `/connect` page.
3. The person signs in if needed, picks a site, keeps or clears the permissions requested by the app, and
   presses **Connect**. **Cancel** returns `access_denied` to the app.
4. The client exchanges the code at `POST /api/oauth/token` and calls the MCP address with the
   access token.

Rules:

- OAuth 2.1 authorization code with PKCE `S256` only. Public clients only: no client secret.
- Redirect URIs are exact: `https`; `http` on `127.0.0.1` or `localhost` with any port; or a
  desktop app's private-use scheme (RFC 8252 7.1), such as `cursor://…` or `com.example.app:/cb`.
  A private scheme is lowercase, 2 to 64 characters, and is not `javascript`, `data`, `file`,
  `vbscript`, `blob`, `about`, `filesystem`, `ftp`, `ws`, `wss`, `mailto`, `tel`, `sms`, `intent`,
  `chrome`, `chrome-extension` or `view-source`. No fragment, no user info, at most 5. The consent
  page shows where the app returns to. A link naming an unknown app or an unregistered redirect URI
  shows an error on the page without redirecting.
- Codes live 60 seconds and work once. A second use revokes what the first one issued.
- Access tokens (`dwo_`) live 10 minutes. Refresh tokens (`dwr_`) live 30 days and rotate on every
  use. Every refresh token works once. Presenting any replaced one, however many rotations ago,
  revokes the connection. Only SHA-256 digests are stored.
- An app that asks for a scope this server does not know gets `invalid_scope`. An app that asks
  for no scope is offered every scope.
- `POST /api/oauth/revoke` (RFC 7009) revokes the whole connection from either token.
- A connection acts exactly like a credential its person created with the approved scopes, for
  every model. `content:read` is always included. The person's current permissions are re-read on
  every request: deactivation, removal of site membership or an inactive site stop the connection at once.
- Any member of the site may connect an app, as themselves. They can grant only what they hold.
- **Settings → API → Connected apps** lists connections: everyone's with `site:settings`, otherwise
  your own. **Revoke** stops it at once. "Last used" is the last token exchange.
- Dynamic registration, token and revocation are rate limited per IP. Connections, codes and
  clients nobody uses are removed by the daily prune after 30 days.
- In production the Worker answers `<host>/api/*` and `<host>/.well-known/oauth-*`.

## Answers

Success is `{ "data": … }` (version list: `{ "data": [...], "next_cursor": … }`). A refusal is
`{ "error": "…", "reason": "…" }` plus detail. Branch on `reason`; `error` is for a person.

| Status | Reason                     | Meaning                                                                                                                                                                                        |
| ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`          | Body, query or header does not match v1.                                                                                                                                                       |
| 400    | `idempotency_key_required` | The command needs `Idempotency-Key`.                                                                                                                                                           |
| 401    | `credential_invalid`       | Missing, unknown or revoked secret.                                                                                                                                                            |
| 403    | `creator_unauthorized`     | The creator is inactive or lost the site, or the site is inactive.                                                                                                                             |
| 403    | `scope_refused`            | The credential lacks the scope (`required` names it).                                                                                                                                          |
| 403    | `listing_owner_restricted` | The creator may read only their own entries of the model.                                                                                                                                      |
| 409    | `idempotency_in_progress`  | A request with the same key is still running. Retry after `Retry-After`. Without it the claim stays pending: check the result, then use a new key.                                             |
| 429    | `rate_limited`             | Wait for `Retry-After`.                                                                                                                                                                        |
| 503    | `audit_unavailable`        | The audit intent could not be written; nothing ran.                                                                                                                                            |
| 503    | `temporary_failure`        | The request did not finish. `error` says what is known: a settings write or a publish may already be saved with its result not recorded yet. Retry a keyed command with the same key and body. |

Lifecycle and page reasons pass through unchanged, for example `not_found`, `model_denied`,
`not_owner`, `field_denied`, `locale_denied`, `export_limited_role`, `forbidden`, `missing_permission`, `version_conflict`, `workflow_conflict`,
`idempotency_key_reused`, `scheduled_target_stale`, `transition_kind_mismatch`, `illegal_transition`,
`dependents_not_acknowledged`, `invalid_save_request`, `facts_conflict`, `no_changes`, `content_live`,
`plugin_policy_refused`, `plugin_policy_unavailable`, `plugin_policy_budget_exhausted`,
`plugin_policy_transform_invalid`, `plugin_policy_transform_conflict`,
`media_in_use`, `media_usage_unreadable`, `media_framing_not_image`,
`in_trash`, `not_in_trash`, `entry_in_trash`, `owner_language`, `restore_conflict`, `locale_exists`,
`unknown_locale`, `language_changed`, `locked`, `lock_lost`, `draft_conflict`, `assignee_cannot_act`, `due_date_past`, `batch_relation_terms_invalid`,
`batch_relation_field_invalid`, `batch_expected_versions_invalid`, `related_from_field_invalid`,
`related_from_source_invalid`, `related_from_replace_invalid` and `related_from_replace_unconfirmed`.

`field_validation_failed` (422) and `field_value_taken` (409) also carry `locale` and
`issues: [{ field, message, key?, params? }]`. `field` is a full path (`faqs[2].question`).
`message` is English. `key` and `params` name the admin message the sentence was written from, so
the admin shows it in its own language. Other callers can ignore them.

## Audit

Every write records an intent before it runs and a result after it in the site's administrative
history. The exceptions are plugin launches and the editing-lease and shared-draft routes; a shared
draft is unsaved work, never a version. The actor is the creator; `change.management_access` names the credential. Operations:
`management.content.save`, `management.content.transition`, `management.content.move`,
`management.content.assign`, `management.content.locale.add`, `management.content.version.restore`,
`management.content.trash`, `management.content.trash.restore`, `management.content.purge`,
`management.content.relate`, `management.content.related_from`, `management.menu.save`, `management.menu.language_add`, `management.page.save`, `management.page.translation.start`, `management.media.upload`, `management.role.create`, `management.role.update`, `management.role.delete`, `management.media.folder.create`,
`management.media.folder.update`, `management.media.folder.delete`, `management.media.move`,
`management.media.update`, `management.media.delete`, `management.import.source.create`,
`management.import.create`, `management.import.upload`, `management.import.advance`,
`management.import.mapping`, `management.import.assignment`, `management.import.pause`,
`management.import.resume`, `management.import.cancel`, `management.import.undo`,
`management.export.create`, `management.export.advance`, `management.proposal.create`,
`management.schema_proposal.create`, `management.model.apply`, `management.model.delete`,
`management.settings.update`, and
`management.credential.issue` /
`management.credential.revoke` for the credential itself, and `management.oauth.connect` /
`management.oauth.revoke` for a connected app. A connected app's writes also carry `change.via`,
the app's name, so the history reads "person via app". Versions and workflow events name the
creator, as they would for an edit in the admin. An applied proposal's version names the person who
applied it. An applied schema proposal is an ordinary `model.apply` by the person who saved it, with
`change.proposal` naming the proposal.

## Not in v1

- Workflow changes and publish override.
- Secrets, sign-in methods, identity providers, deployment, source providers and domains.
- Plugin administration and plugin commands. Install, grant, disable and the plugin's own work use
  the admin and the separate plugin protocol. The management API only lists plugins, creates
  launch links and runs declared operations.
- Generated-backend CRUD. It is never the CMS management surface.

## Example

```bash
curl -s https://cms.example/api/manage/v1/entries \
  -H "Authorization: Bearer $DEE_WAN_MANAGEMENT_TOKEN" \
  -H "Idempotency-Key: create-hello-1" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"<model id>","locales":{"en":{"title":"Hello"}}}'
```

## Next step

Your website is connected. To keep it running, set up [backup and restore](/guides/backup-restore/). To extend Dee Wan, start with [plugin authoring](/plugins/authoring/). The [standalone backend](/guides/standalone-backend/) stays optional.

<!-- dee-wan-docs page: /guides/docs-for-agents/ -->

# Documentation for AI agents

Source: https://dee-wan-docs.pages.dev/guides/docs-for-agents/

This site also serves AI agents. An agent can search and read these pages through a read-only MCP server, or read them as plain text files. Both are built from the same public pages you read here, at the same time.

## Documentation MCP server

The address is [`/mcp`](/mcp) on this documentation site. It takes JSON-RPC over HTTP `POST` (Streamable HTTP with JSON answers). It needs no sign-in, keeps no session and changes nothing.

```json
{
  "mcpServers": {
    "dee-wan-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}
```

Replace `docs.example.com` with the host of this site.

The server has three tools:

| Tool | What it does |
| --- | --- |
| `search_docs` | Finds sections that match `query`. Optional: `language` (`en`, `ru` or `th`), `section`, `limit` (default 5, at most 20) and `fallback_to_english`. |
| `read_doc` | Returns one page as Markdown, or one section of it when you pass `heading`. Takes a page `path`, such as `/reference/public-api/`, and an optional `language`. |
| `list_docs` | Lists sections and pages in reading order, with titles, paths, headings and languages. |

Answers come in the requested language only. To also get English results when the requested language has too few, pass `fallback_to_english: true` to `search_docs`. Matches in a page title rank above matches in a heading, and both rank above matches in the text.

Every answer names the documentation revision: a hash of the published text. The same text always gives the same revision.

The server reads only the public pages in this site's navigation. It refuses any other path.

## Plain text files

- [`/llms.txt`](/llms.txt) lists every page with a one-line description, in reading order.
- [`/llms-full.txt`](/llms-full.txt) holds every English page in one file, in reading order. A marker line with the page path starts each page.
- [`/agent/dee-wan/SKILL.md`](/agent/dee-wan/SKILL.md) is a skill for agents that load skills. It points the agent to the pages it needs to work with Dee Wan, and tells it not to guess behavior these pages do not describe.

## Documentation MCP and management MCP

The documentation MCP server answers questions about Dee Wan. It reads public documentation only, and gives everyone the same answers.

The [management MCP](/reference/management-api/#remote-mcp) runs on your own Dee Wan installation. It reads and changes the content of your sites, needs a credential or a sign-in, and can do only what that credential or account may do.

Use the documentation server to learn how a feature works. Use the management server to act on your sites.

<!-- dee-wan-docs page: /guides/standalone-backend/ -->

# Standalone backend: Overview

Source: https://dee-wan-docs.pages.dev/guides/standalone-backend/

A standalone backend is a repository for one site that you own. It holds an API Worker backed by its own D1 database, an Astro site, the published content, migrations and deployment scripts. The API reads only its own database. Statically built pages need nothing from Dee Wan. Blog routes, site search, Latest entries, visitor comments, forms and the optional preview reach Dee Wan on every request: see [What still depends on Dee Wan](/detachment-contract/#what-still-depends-on-dee-wan). This page describes generated source code, not a Cloudflare deployment that has passed acceptance.

The API and the statically built pages are a snapshot. They hold what was published when they were generated, and later publishes reach them only when you regenerate and deploy again. The CMS public API, and the website routes that read it, serve current content.

The generated API enforces declared text length and pattern rules. Changes to these rules require regeneration and redeployment; see the [API reference](/reference/standalone-backend-api/).

**You do not need to detach to customize it.** See [Extending your backend](/guides/extending-your-backend/) for the owned registry and the connected workflow. The [detachment contract](/detachment-contract/) describes stopping managed regeneration.

## Generate, deliver, deploy

These are different steps. Source is generated on your machine. The CMS never compiles it.

| Step | Path | What it does |
| --- | --- | --- |
| Generate standalone backend | `npm run backend:generate` (below) | Opens a local CMS SQLite copy read-only, generates and verifies the project against a disposable target database. It does not push or deploy. `--model <id>` limits it to one model. |
| Generate and deliver for the first time | `npm run backend:deliver` | Generates the project locally, delivers it to your repository, and starts the first deployment. `--media` transfers public media into your storage. |
| Deliver an existing generated commit | `npm run wire:github -- --managed` ([GitHub delivery](/guides/github-authentication/)) | Pushes a project you already generated, verifies the remote commit, and dispatches deployment of that exact commit. |
| Deploy from an existing repository | Settings → Source & delivery → Deploy | Calls the build webhook. The repository's own `dee-wan-build.yml` pulls definitions, runs the regeneration script already committed in that repository, commits, and deploys. Requires a repository that already contains generated source. |
| Hosted source generation | Settings → Source & delivery → Generate source with GitHub | Unavailable. The CMS Worker has no source build runtime and answers `source_build_runtime_unavailable`. |

```sh
npm run backend:generate -- --site <site-id> --source <cms.sqlite> --dest <output-directory> --db <scratch.sqlite>
```

A site with an active managed renderer release also needs `--template-artifacts <dir>`: a local copy of that release's template artifacts, with each file at its expected key (`managed/<site>/<candidate>/<role>.json`), in real directories and regular files. Symbolic links are not followed. Without it, generation refuses with `managed_release_custody_unavailable`. `npm run backend:deliver` accepts the same flag. `--model` output exports no managed renderer, and `npm run backend:generate:all` cannot pass the flag, so that command refuses generation for these sites.

Each path writes a directory or delivers a Git repository. There is no archive download. `npm run backend:deliver` uses GitHub device authorization, Cloudflare account credentials and a writer token, verifies the deployment, and offers detachment.

These commands run in the Dee Wan repository. The generated repository has its own commands, listed under [Snapshot, migrations, deployment and rollback](/reference/standalone-backend-api/#snapshot-migrations-deployment-and-rollback). [GitHub delivery](/guides/github-authentication/) separates the admin GitHub App from command-line device authorization.

## Keep connected or detach

A connected repository is regenerated through the managed workflow when you request it. `dee-wan-build.yml` retrieves site definitions with a build token, regenerates, validates, commits, and calls `deploy-from-repository.yml` for that exact commit. Developers may edit owned/shared files, commit them, and deploy them while connected.

A detached repository stops that managed update relationship. The repository-only workflow deploys committed source without fetching CMS definitions. Detachment does not enable extra extension points. Follow the [detachment runbook](/guides/detachment/). Keeping the repository does not by itself mean you store the media files yourself, or that a deployment succeeded.

## The site

Astro pre-renders page models from generated `pages.json` and serves them through a site Worker. Hero, rich text, media/text, feature-grid and call-to-action sections use accepted chrome and theme inputs. The repository emits navigation, footer, redirects, robots and an optional sitemap. Statically built pages use the committed page snapshot. Blog routes, search pages and pages with a Latest entries section, a Site search section or visitor comments are served on each request from Dee Wan's public API (`/v1` on the site's host), so these routes depend on a running Dee Wan installation; the generated API itself does not. See [what still depends on Dee Wan](/detachment-contract/#what-still-depends-on-dee-wan) and the [compatibility flag](/guides/detachment/#site-worker-compatibility-flag).

Owned head/body components, layout slots, section wrappers/overrides, Astro integrations, islands and `/owned/` pages extend it without detachment. Preview is disabled unless `previewApiOrigin` is configured. See the [page-document contract](/reference/page-contract/) for the generated page format.

## What is not included

The repository does not reproduce the CMS admin, user system, review workflow, plugin host, imports, AI generation, outgoing webhooks, drafts or history. It does not include media bytes, arbitrary business endpoints, or automatic provisioning for bindings you add yourself. Put your business logic and schema-validated routes in the owned extension files.

## Reference and details

- [API reference](/reference/standalone-backend-api/): routes, authentication, read tokens, guards, errors, OpenAPI, sign-in for the backend, deployment and rollback.
- [Implementation details](/reference/standalone-backend-internals/): files, dependencies, Cloudflare resources, table mappings, the exported managed renderer and the response cache.
- [Extending your backend](/guides/extending-your-backend/): where your own code goes.
- [Detach and verify](/guides/detachment/) and [standalone recovery](/guides/standalone-recovery/).

## Next step

Follow the four walkthroughs, starting with [edit and publish](/guides/walkthrough/edit-and-publish/).

<!-- dee-wan-docs page: /guides/walkthrough/edit-and-publish/ -->

# Walkthrough 1: edit and publish

Source: https://dee-wan-docs.pages.dev/guides/walkthrough/edit-and-publish/

Part 1 of 4 in the standalone walkthrough. Next: [generate and deliver](/guides/walkthrough/generate-and-deliver/).

Four states are easy to confuse. Keep them apart:

| State | Where it lives | Who can read it |
| --- | --- | --- |
| **Saved draft** | A version of the entry in the CMS | Editors, and a verified preview |
| **Published in CMS** | The entry's published version in the CMS | Anyone, through the CMS public API, at once |
| **Generated source** | A commit in your repository | Nobody. Source serves nothing |
| **Deployed website** | Your Worker, database and site, built from one commit | Your visitors |

## Save a draft

Edit an entry and save. Saving creates a new version. Nothing public changes. A preview renderer, if you configured one, can show the draft to a signed-in editor ([preview](/guides/preview-and-client/)).

## Publish

Publish the entry. The CMS public API serves the published version immediately. The toast says "Published. It is public now." The standalone API and statically built pages do **not** change: they serve what they were built from until you deploy again. Blog routes, search and pages with Latest entries read the CMS on each request, so the entry shows there at once.

Unpublishing is the same: the CMS public API and those routes stop serving the entry at once. The standalone API and statically built pages keep it until the next deployment.

## What decides the next deployment

Settings → Source & delivery shows **Out of date** when models, published content or the accepted theme changed since the last successful deployment. That is the only signal that publishing has not reached the standalone API and statically built pages yet.

Next: [generate and deliver](/guides/walkthrough/generate-and-deliver/).

<!-- dee-wan-docs page: /guides/walkthrough/generate-and-deliver/ -->

# Walkthrough 2: generate and deliver

Source: https://dee-wan-docs.pages.dev/guides/walkthrough/generate-and-deliver/

Part 2 of 4. Previous: [edit and publish](/guides/walkthrough/edit-and-publish/). Next: [the second deployment](/guides/walkthrough/second-deployment/).

## Generate on your machine

The CMS cannot compile source code. Attempting hosted generation in Settings → Source & delivery returns `source_build_runtime_unavailable`. Generate locally from a copy of the CMS database:

```sh
npm run backend:generate -- --site <site-id> --source <cms.sqlite> --dest <output-directory> --db <scratch.sqlite>
```

This writes and verifies the project. It pushes nothing and deploys nothing. `npm run backend:deliver` does the same generation, then pushes to your repository and starts the first deployment ([detachment runbook](/guides/detachment/)).

Before you generate, open **Settings → Source & delivery → Advanced — build webhook and deployment → Standalone backend**. It lists model configurations that generation cannot support, such as relation selection limits that no list of linked items can satisfy.

## What you now own

| Kind | Examples | On regeneration |
| --- | --- | --- |
| **Generated** | `prisma/schema.prisma`, `src/app.ts`, `scripts/*.mjs`, `data/published-snapshot.json`, `.github/workflows/dee-wan-build.yml` | Rewritten. If you edited one, the next regeneration refuses by name and changes nothing. |
| **Owned** | `src/owned/`, `apps/site/src/owned/`, `apps/site/src/pages/owned/` | Never overwritten during regeneration. |
| **Shared** | `package.json`, `wrangler.jsonc`, `README.md`, your own workflows | Written once. `package.json` gains missing required keys. Your values stay. |
| **CMS-owned rows** | Rows in generated content tables | Replaced from the published snapshot whenever it changes. A row the snapshot does not hold is deleted, whoever wrote it. |
| **Your tables and rows** | Tables your own migrations create | Kept. Put your data here, never in generated tables. |

The full zone rule is in [extending your backend](/guides/extending-your-backend/).

## Deliver an existing commit

To push a project you already generated and deploy exactly that commit, use managed delivery:

```sh
npm run wire:github -- --repo owner/site-source --project ./generated/site --managed --operation delivery-1
```

The CLI verifies the remote commit before it seals secrets or dispatches. Credentials are named in [GitHub authentication](/guides/github-authentication/). CLI success means GitHub accepted the run, not that deployment finished.

## Credentials by name

Secret values are not included in repository source or stored in the CMS.

| Name | Holder | Used for |
| --- | --- | --- |
| `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | Your repository secrets | Creating and deploying the Worker, database and site |
| `API_BEARER_TOKEN` | Your repository secrets and your environment | The generated API's writer token. `verify:deployment` uses it. |
| `DEE_WAN_URL`, `BUILD_TOKEN` | The managed workflow uses both values. The CMS mints `BUILD_TOKEN` per build. | Pulling definitions while connected |
| `ARTIFACT_*` | Your repository secrets | Optional sign-in for the generated backend |

Next: [the second deployment](/guides/walkthrough/second-deployment/).

<!-- dee-wan-docs page: /guides/walkthrough/second-deployment/ -->

# Walkthrough 3: the second deployment

Source: https://dee-wan-docs.pages.dev/guides/walkthrough/second-deployment/

Part 3 of 4. Previous: [generate and deliver](/guides/walkthrough/generate-and-deliver/). Next: [rollback and recovery](/guides/walkthrough/rollback-and-recovery/).

## Change content or a model, then deploy

Publish new content or change a model in the CMS. Settings → Source & delivery shows **Out of date**. Press **Deploy** on the Standalone backend card.

Deploy calls your build webhook. Your repository's own `dee-wan-build.yml` then:

1. pulls the site's definitions with a short-lived `BUILD_TOKEN`.
2. runs the regeneration script committed in your repository.
3. adds the next migration without rewriting existing migrations.
4. typechecks the backend, then installs, checks, builds and bundles the website.
5. commits, and deploys that exact commit through `deploy-from-repository.yml`.

## What the second deployment keeps

- Everything under the owned zone, byte for byte.
- Shared files, with missing required keys added.
- Your own tables and their rows.
- Every migration already applied. An applied migration is never rewritten.

## What it replaces

- Every generated file.
- The rows of generated content tables, from the new published snapshot. A row the snapshot does not hold is deleted, whoever wrote it.
- `ACCESS_CONFIG`: the CMS-issued read tokens from `access/read-tokens.json` together with `vars.ACCESS_CONFIG` in your `wrangler.jsonc`, or a valid empty token list (`tokens: []`) when there are none.

## When it refuses

If a check refuses the build, deployment stops before the new commit is deployed. The last deployed website keeps serving. Common refusals:

| Refusal | Meaning |
| --- | --- |
| An edited generated file, named | Move the change into `src/owned/`, then deploy again. |
| `site_check_unavailable` | The site's type checker could not load. Its dependency install is incomplete. |
| `site_check_failed`, `site_build_failed` | The website does not typecheck or build. |
| `site_bundle_failed` | Wrangler cannot bundle the website's Worker. |
| A generation refusal such as `relation_type_unsupported` | A model shape cannot be generated. Settings lists these before you deploy. |

Next: [rollback and recovery](/guides/walkthrough/rollback-and-recovery/).

<!-- dee-wan-docs page: /guides/walkthrough/rollback-and-recovery/ -->

# Walkthrough 4: roll back, restore or detach

Source: https://dee-wan-docs.pages.dev/guides/walkthrough/rollback-and-recovery/

Part 4 of 4. Previous: [the second deployment](/guides/walkthrough/second-deployment/).

## Roll back code

Settings → Source & delivery → Deployment history lists this site's deployments. **Latest deployment** marks the newest completed one. **Go back** on an earlier version needs `site:deploy`; its tooltip reads "Redeploy this version". Confirm "Redeploy this earlier version?" and the build deploys that revision's recorded commit against the **current** database. It never undoes a migration or a media change, and it never restores your own tables. If that commit contains different content, its snapshot replaces the generated content tables.

The CMS refuses a rollback when:

| Reason | Meaning |
| --- | --- |
| `destructive_since` | A later deployment ran a destructive migration. |
| `unreported_since` | A later deployment did not report whether its migration was destructive. |
| `different_database` | The revision ran against another database. |
| `no_git_sha` | The revision recorded no commit. |
| `build_in_progress` | Another build is already running for this site. |

The deployment script itself refuses with `rollback_database_missing` when the recorded database is gone. Recover the database using the restore procedure in that case.

## Restore data and media

Rollback moves code only. To bring back data or media, follow the [standalone recovery runbook](/guides/standalone-recovery/).

## Leave

Detaching stops CMS-managed regeneration. Remove the build webhook, stop pressing Deploy, and keep the repository. The deployed API, its database, statically built pages, your owned code and your own tables keep working. Blog routes, search, Latest entries, comments and forms still need the Dee Wan installation. See the [detachment contract](/detachment-contract/) and the [detachment runbook](/guides/detachment/).

Next: [extend your backend](/guides/extending-your-backend/) while it stays connected.

<!-- dee-wan-docs page: /guides/extending-your-backend/ -->

# Extending your backend

Source: https://dee-wan-docs.pages.dev/guides/extending-your-backend/

**You do not need to detach to customize the generated repository.** Owned and shared extension surfaces work while the repository stays connected to Dee Wan. Detach only when you want Dee Wan-managed regeneration to stop. [Standalone backend: Overview](/guides/standalone-backend/) describes the generated backend, and [Implementation details](/reference/standalone-backend-internals/) lists its dependencies.

## Connected workflow

1. Generate the project locally with `npm run backend:generate` or `npm run backend:deliver`. Settings → Source & delivery cannot compile source (`source_build_runtime_unavailable`).
2. Clone your generated repository.
3. Edit owned/shared files, starting with `src/owned/backend.ts` for API customization.
4. Run the artifact's checks, commit and push your changes.
5. Deploy that exact repository commit through `deploy-from-repository.yml`.
6. Later, regenerate from Dee Wan. Owned/shared work is preserved. The generator refuses to run if generated files have been edited.
7. Detach only if you want managed regeneration to stop.

The [GitHub authentication matrix](/guides/github-authentication/) explains the authority needed for delivery. The [detachment runbook](/guides/detachment/) covers independence checks. Customization is not a reason to detach.

## What can I change while connected?

| Change | Where | Regeneration behavior |
| --- | --- | --- |
| Generated-operation enable/disable, hooks, same-contract override | `src/owned/backend.ts` | Preserved. Validation or construction fails if operation IDs have been removed, settings conflict or group expansions have changed. Generated security remains outside owned policy. |
| Declarative custom API routes | Same registry, using `route()` | Preserved. Collisions with generated or custom routes are rejected after paths are normalized. Valid schemas enter OpenAPI and validate input/output. |
| Raw Hono escape hatch | `src/owned/routes.ts` | Preserved and mounted last. Cannot replace generated paths, including disabled operations. No collision guarantee or OpenAPI for raw routes. |
| Reusable business logic | Other files below `src/owned/` | Preserved byte-for-byte. Import it from the registry or raw routes. |
| Own database tables and migrations | Owned SQL or a runner below `src/owned/`, with your own workflow | Source and unrelated tables/rows survive. Run your migration explicitly. It is not automatically added to generated Prisma schema or the generated migration runner. Do not modify generated tables. |
| Dependencies and version ownership | Root and `apps/site/package.json` | Additive merge keeps your existing values. Missing required dependency/override keys are added. Your chosen version must still satisfy build/runtime contracts. |
| Wrangler bindings and secrets | Shared root/site `wrangler.jsonc`, own deployment workflow and secret store | Shared source is preserved. Extra local bindings are not automatically provisioned or copied into generated `wrangler.deploy.jsonc`. Generated build/deploy configs remain generated. Never commit secrets. |
| Own CI workflows | `.github/workflows/<your-name>.yml` | Preserved, except the two generated workflow names. |
| Astro head/body and layout slots | `apps/site/src/owned/Head.astro`, `BodyEnd.astro`, `slots/` | Preserved. Generated layouts import them. |
| Section wrappers and overrides | `apps/site/src/owned/sections/` | Preserved. Generated section contracts still typecheck against your implementation. |
| Integrations and islands | `apps/site/src/owned/config.mjs`, owned components, site dependencies | Preserved. Add the integration and its dependencies together, then run Astro checking/building. |
| Own pages | `apps/site/src/pages/owned/` | Preserved and served under `/owned/`. Generated pages and redirects cannot claim that namespace. |
| Generated files and content rows | Schema, generated clients/routers/security, snapshots, page data, generated content tables | Do not edit while connected. Source fingerprints, snapshot digests and row-set checks refuse drift. Change CMS models/content or use an owned surface. |

`README.md`, `.nvmrc`, `.npmrc`, `.gitignore` and existing shared Wrangler files are retained. `deploy-from-repository.yml` is generated, and `dee-wan-build.yml` with it in a whole-site artifact (a `--model` artifact has no CMS-managed site build). Your other workflows are shared. Existing SQL migration history is preserved. Do not rewrite an applied migration.

## Zone of sample paths

| Path | Zone |
| --- | --- |
| `prisma/schema.prisma` | generated |
| `graduation.manifest.json` | generated |
| `src/app.ts` | generated |
| `src/worker.ts` | generated |
| `src/security.ts` | generated |
| `src/owned/backend.ts` | owned |
| `src/owned/routes.ts` | owned |
| `src/backend-customization.ts` | generated |
| `.dee-wan-customization.json` | generated |
| `src/serve-cli.ts` | generated |
| `migrations/0002_graduation_ledger.sql` | generated |
| `scripts/regenerate.mjs` | generated |
| `scripts/emit-migration.mjs` | generated |
| `scripts/file-manifest.mjs` | generated |
| `scripts/portable-client.mjs` | generated |
| `scripts/configure-deployment.mjs` | generated |
| `tsconfig.json` | generated |
| `wrangler.example.jsonc` | generated |
| `wrangler.build.jsonc` | generated |
| `scripts/load-snapshot.mjs` | generated |
| `data/published-snapshot.json` | generated |
| `.github/workflows/dee-wan-build.yml` | generated |
| `.github/workflows/deploy-from-repository.yml` | generated |
| `.github/workflows/anything-else.yml` | shared |
| `package.json` | shared |
| `package-lock.json` | shared |
| `.npmrc` | shared |
| `.nvmrc` | shared |
| `wrangler.jsonc` | shared |
| `.gitignore` | shared |
| `README.md` | shared |
| `apps/site/src/owned/config.mjs` | owned |
| `apps/site/src/pages/owned/thanks.astro` | owned |
| `apps/site/package.json` | shared |
| `apps/site/package-lock.json` | shared |
| `apps/site/.npmrc` | shared |
| `apps/site/wrangler.jsonc` | shared |
| `apps/site/src/lib/pages.json` | generated |

## Typed operation registry

`src/owned/backend.ts` is scaffolded only when absent. Regeneration never rewrites an existing registry. `npm run customization:check` restores an absent registry as an empty customization and validates the generated catalogue. The generated app imports it. Route registration order does not determine which implementation runs.

Examples below assume the emitted model is `Article`. Use the actual IDs and Prisma fields from `src/backend-customization.ts`. Each example is a complete alternative registry. Combine its entries in one `defineBackend()` call when using several features.

### One request hook

```ts
import { defineBackend } from '../backend-customization'

export default defineBackend({
  operations: {
    'Article.findMany': {
      before: [(c) => { c.header('x-content-policy', 'owned') }],
    },
  },
})
```

`before` and `after` are request-execution hooks. They are not Prisma lifecycle hooks, transactions, `finally` blocks, or after-commit callbacks. A terminal response or thrown error stops the remaining phase. An `after` hook is not guaranteed to run after failure and is not evidence that a transaction committed.

### Wrap the generated implementation

```ts
import { defineBackend } from '../backend-customization'

export default defineBackend({
  operations: {
    'Article.findMany': {
      override: async ({ input, args, context, prisma, core }) => {
        void input
        void args
        void context
        void prisma
        return [...await core()].reverse()
      },
    },
  },
})
```

`input` and `args` name the same parsed Prisma arguments. `context` is the verified principal. `prisma` exposes only the target operation's guarded delegate. It does not expose raw SQL, a raw client, or other models/operations. Paginated reads expose guarded `findMany` and `count`. `core()` runs the generated implementation with the same request/guard state. It is not a transaction or retry boundary. Call it once unless repeated execution is intended.

### Replace one operation

```ts
import { defineBackend } from '../backend-customization'

export default defineBackend({
  operations: {
    'Article.findMany': {
      override: async () => [],
    },
  },
})
```

This replacement returns an empty array under the generated list contract and never calls `core()`. It still requires authentication, permission and resolved guards. Returning a different envelope, status contract or path requires a new declarative route. Types derive from emitted Prisma arguments/results. Changing or removing a model/operation exposes stale registry references during typechecking or construction.

### Disable an operation

```ts
import { defineBackend } from '../backend-customization'

export default defineBackend({
  operations: { 'Article.delete': { enabled: false } },
})
```

`enabled: true` retains an emitted operation. It cannot enable a route for which the platform emitted no security. Disabled paths remain reserved. An array of declarations for one ID may compose hooks. More than one override, contradictory enable settings, or combining disable with an override is rejected.

### Read and write groups

```ts
import { defineBackend } from '../backend-customization'

export default defineBackend({
  groups: [
    {
      name: 'content-reads',
      select: 'reads',
      accepted: ['Article.findMany', 'Article.findManyPaginated', 'Article.findUnique'],
      before: [(c) => { c.header('x-content-read', 'owned') }],
    },
    {
      name: 'content-writes',
      select: 'writes',
      accepted: ['Article.create', 'Article.update', 'Article.delete'],
      after: [(c) => { c.header('x-content-write', 'owned') }],
    },
  ],
})
```

This example assumes Article is the only emitted model and has no translations/junctions. `select: ['Article.findMany', 'Article.findUnique']` selects explicit IDs. Read/write selectors expand across the entire emitted catalogue, including read-only models. Group names are unique, and hook order follows group declaration order.

`accepted` pins the exact set. `customization:check` records expanded IDs in `.dee-wan-customization.json`. Adding or removing a model or operation causes validation to fail if the expansion changes. Review the exact proposed list in the error, update that group's `accepted` array in the owned registry, and regenerate/check again. Do not edit the generated state file or derive acceptance with a filter over the current catalogue: that would silently accept future changes.

A group may also carry typed `overrides: { 'Article.findMany': async ({ core }) => core() }` for an ID in its accepted expansion. A second override from another group or the operation settings is rejected. Declaration order never chooses a winner.

### Existing variants and ordering

Variant hooks use `operations['Article.findMany'].variants.reader.before/after` or the generated `editor` variant. They compose with the generator's existing variant mechanism. Unknown variants and attempts to supply shapes or router-level security settings from owned code are rejected. There is no second variant dispatcher.

Execution order is: platform authentication/permission, guard resolution, group before, operation before, variant before, then the generated or override handler. After the handler: variant after, operation after, group after, outer response/error protection. A terminal response/error preserves upstream short-circuit behavior. Hooks must preserve the documented request/result shape.

## Add a declarative custom route

```ts
import { defineBackend, route } from '../backend-customization'

export default defineBackend({
  routes: [route({
    method: 'POST',
    path: '/echo',
    access: { mode: 'service', operation: 'create' },
    request: {
      type: 'object',
      properties: { text: { type: 'string' } },
      required: ['text'],
      additionalProperties: false,
    },
    response: {
      type: 'object',
      properties: { text: { type: 'string' } },
      required: ['text'],
      additionalProperties: false,
    },
    handler: async ({ input }) => ({ text: input.text }),
  })],
})
```

The path is relative to `/api`. Supported methods are GET, POST, PUT, PATCH and DELETE. Declare `access.operation` as read/create/update/delete. Optional `access.model` names an emitted model. Without a model scope, a read token needs wildcard `*` scope. The handler receives validated typed input, the verified principal and path parameters. No raw client is provided.

Declare each custom route with `route()`. Construction rejects copied or manually assembled route descriptors. Request/response schemas are captured at declaration, so later mutation cannot change validation or OpenAPI.

Schemas support string/enum, finite number, safe integer, boolean, null, arrays, and closed objects with declared required fields. Unsupported schema keywords are rejected instead of appearing as enforced OpenAPI rules. GET query properties must be strings. Other methods parse a JSON body. Invalid input returns 400. A result violating the response schema returns 500.

Duplicate methods and normalized paths are rejected across generated/declarative routes, even if a generated operation is disabled. Repeated/trailing slashes normalize. Wildcard, encoded, query/fragment and traversal path syntax is rejected. Parameter-name aliases and static/parameter overlap are rejected as well. A generated collision must be an operation override. Valid declarative schemas appear in authenticated `/api/openapi.json`. Raw Hono routes do not.

## Raw Hono escape hatch

Keep imperative integrations in `src/owned/routes.ts`. It remains mounted after generated and declarative routes, with reserved generated paths ahead of it. Raw routes receive the outer authentication/error protection, but have no declarative collision guarantee, automatic request/result schema validation, or generated OpenAPI entry.

The compatibility mount still infers model scope by path prefix. A raw path matching no model needs wildcard read scope. Apply explicit `.guard(shape, variant)` to raw-route Prisma queries. An extended client alone does not guard arbitrary calls. Prefer declarative access metadata when the path does not represent a generated model.

### Access is checked before your code

Access policy decides whether a route accepts anonymous, session or service callers. Missing model policy is `service`. Read tokens are digests scoped by model in `ACCESS_CONFIG`. Unscoped routes and `/api/openapi.json` require wildcard scope. Service writes without a writer authenticator return `503 writes_unavailable`. Absent credentials return 401 and denied permission returns 403. Optional Better Auth supplies the artifact session for both local and Worker runtimes. Local serving and the Worker accept the same `API_BEARER_TOKEN` service bearer.

Errors remain normalized/redacted outside overrides and hooks. New response shapes use new routes. Extra authorization belongs in your business logic and cannot remove the platform checks.

## Add a site extension

Edit `apps/site/src/owned/Head.astro`:

```astro
<meta name="color-scheme" content="light dark" />
```

For a new page, add `apps/site/src/pages/owned/thanks.astro`. For an island, add its framework integration/dependencies and configure `apps/site/src/owned/config.mjs`. The generated Astro configuration imports that owned configuration. `Head.astro`, `BodyEnd.astro`, layout slots and section wrappers/overrides are independent extension surfaces. The preview bridge remains optional in `extensions.ts`.

## Dependencies, migrations and regeneration

Both package manifests preserve existing dependency/override values and add missing required entries. The root also adds missing script names. Existing commands remain yours. Generated build/deploy workflows run the customization check directly, even when an older owned typecheck command is retained. Package-manager and lifecycle-script decisions remain yours. An incompatible version fails checking/building. Root pins record the generating toolchain. Site ranges are fixed by the site's lockfile. The build rejects an unreadable manifest. Install through the verified installer after changes.

Keep business logic, own SQL and migration runners below `src/owned/`. Run application-owned migrations from an owned workflow. Generated Prisma models describe CMS content only. Adding an application table does not automatically add a generated model or endpoint. Preserve your migration order and rollback plan.

Regeneration compares generated fingerprints, preserves owned/shared files, appends required migrations and refreshes generated content. Regeneration rejects edited generated files and altered snapshots. When a changed snapshot is loaded, it replaces the rows of every generated content table: a row the snapshot does not hold is deleted, whoever wrote it. Your own tables are not part of the snapshot and keep their rows.

`npm run regenerate` needs the site definitions in `definitions.json` and `GENERATION_SOURCE_VERSION`. Managed CI gets the version from the CMS and pulls the definitions. [Regenerate locally](/reference/standalone-backend-api/#regenerate-locally) shows how to get them. With both in place:

```sh
node scripts/install-dependencies.mjs
GENERATION_SOURCE_VERSION=<version> npm run regenerate
npm run migrate:emit
npm run typecheck
node scripts/install-dependencies.mjs apps/site
npm run --prefix apps/site check
npm run --prefix apps/site build
npm run build
npm run files:manifest
```

## Deploy

Commit/push the reviewed repository and run `deploy-from-repository.yml` for its exact `git_sha`. Configure `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `API_BEARER_TOKEN` and `PUBLIC_HOSTNAME` as described in [Cloudflare resources and configuration](/reference/standalone-backend-internals/#cloudflare-resources-and-configuration). Managed regeneration calls this same deployment workflow after committing generated updates.

For local serving, use `db:init`, `build:serve` and `serve:local` with local access configuration and a writer bearer as shown in the emitted README. `npm run dev` runs Wrangler locally. Prove unauthenticated refusal, permitted reads/writes, guard refusals, override results and error redaction before deploying. An earlier code commit is not a database backup: rollback must also respect migration and media compatibility.

## Optional artifact authentication and access

In **Settings → Source & delivery → Standalone authentication, cache and exposure**, enable Better Auth once for the backend. Select Password, Magic link (Resend), Google or GitHub. Disabled is the default: no Better Auth dependency, runtime, routes, tables, migration, provider configuration or secrets are emitted. CMS accounts, sessions, invitations, password hashes and provider credentials never enter a standalone backend. Application content named `User` stays separate from the artifact identity tables.

| Access mode | Accepted caller |
| --- | --- |
| `public` | Accepts an explicit typed anonymous principal without a credential. |
| `session` | A current session from this artifact's Better Auth instance. |
| `service` | `API_BEARER_TOKEN`, or an eligible scoped token for a read. |
| `session_or_service` | Either the artifact session or service authentication. |

A missing model configuration explicitly uses `service`. Missing operation overrides inherit the model default. Overrides use exact generated IDs such as `User.findMany`, `User.findManyPaginated`, `User.findUnique`, `User.create`, `User.update` and `User.delete`. Validation fails for renamed or removed models or operations. Generated policy types also reject stale IDs. Operation availability remains in the owned backend registry. Access settings do not re-enable disabled operations. Policies name sessions, never particular login providers.

Authentication and permission checks run before hooks and overrides. Guard resolution, existing ownership boundaries and error protection remain mandatory. A public create rejects protected system, owner, tenant, role, administrator, password, verification and provider-link fields, including nested input. Public create makes application content. Signup happens only through Better Auth routes. Raw routes default to `service`. Declarative routes must state `access.mode` and `access.operation`, with optional model scope. OpenAPI shows each operation's access mode.

| Optional install root | Package | Block | Exact version |
| --- | --- | --- | --- |
| `root`, only when enabled | `better-auth` | `dependencies` | `1.6.25` |

Enabled artifacts emit `src/better-auth.ts`, provider verification and the existing auth limit/lockout rules, plus a separate migration for `_artifact_auth_*` infrastructure tables. These tables have no generated CRUD endpoints. Both the Node/SQLite server and Worker/D1 use the same selected methods, password bounds, verified OAuth identities, hashed verification tokens and database session revocation. Both also use the seven-day session limit and mutation-origin checks. Provider access, refresh and ID tokens are discarded. Auth responses suppress provider internals.

Run `npm run auth:init` to create a fresh random secret in ignored `.dev.vars`. It preserves an existing artifact secret. The Node server can load this file with `node --env-file=.dev.vars src/serve.local.mjs`. Wrangler loads it directly. Apply `db:init` first. Set `ARTIFACT_ORIGIN` to the API origin, for example `http://127.0.0.1:8787` locally. Remote origins must use HTTPS. Deployment derives the origin from the reviewed target hostname, never from the CMS origin.

| Selected method | Required runtime values | Target callback |
| --- | --- | --- |
| Password | `BETTER_AUTH_SECRET` | Password routes under `/api/auth` |
| Magic link | `BETTER_AUTH_SECRET`, `RESEND_API_KEY`, `MAIL_FROM` | `<ARTIFACT_ORIGIN>/api/auth/magic-link/verify` |
| Google | `BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | `<ARTIFACT_ORIGIN>/api/auth/callback/google` |
| GitHub | `BETTER_AUTH_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | `<ARTIFACT_ORIGIN>/api/auth/callback/github` |

Register callbacks in adopter-owned OAuth applications. Resend needs a verified sender domain. Only selected methods require credentials. Target preflight fails before deployment when a selected method lacks them. Repository Actions secrets prefix runtime names with `ARTIFACT_`. This also avoids GitHub's reserved `GITHUB_` prefix. Delivery generates a new artifact secret and seals it to the target public key. Existing target secret names are preserved without rotation. `npm run backend:deliver` reads provider inputs only from `ARTIFACT_*` environment variables. Secret values never enter source, manifests, generation inputs, digests, checked-in vars, logs or deployment ledgers.

Regeneration preserves owned/shared files. Enabling auth in an existing shared package or changing selected methods requires regeneration to update dependencies and caller workflow bindings. Disabling auth on an existing destination is rejected: use a new destination, preserving the old identities and migration history. Access-only changes participate in generation-source and manifest digests.

`verify:deployment` respects access policy: public reads are checked anonymously. Service reads use the bearer. Session-only reads require a current target session in `ARTIFACT_VERIFY_SESSION_COOKIE`. Without it, verification refuses with `verify_session_required`. It never reports an unperformed content check as passed. For first deployment, initialize the target, create an account through its auth routes, and rerun verification with that session. Keep the short-lived session out of source and evidence. Browser and live deployment acceptance remain separate gates.

## Next step

Define the queries your routes accept in [query variants and guards](/guides/query-builder-guards/).

<!-- dee-wan-docs page: /guides/query-builder-guards/ -->

# Declarative query variants and generated guards

Source: https://dee-wan-docs.pages.dev/guides/query-builder-guards/

This page describes the query-configuration direction for standalone backends. It is a pre-release contract and design reference, not proof that the current Dee Wan build already emits every feature below.

## The source of truth is a query

Dee Wan will configure guarded API access from concrete Prisma query templates. The user edits the query that a page or route needs. Dee Wan derives the prisma-guard shape from that accepted query.

The user does not edit generated guard JSON. Generated policy is a build artifact.

![The saved-query workspace with the nested query builder and Prisma query preview](/assets/screenshots/query-builder.webp)

The query editor keeps the nested Prisma structure:

- `select` and `include` fields
- nested relations
- `where` operators
- ordering
- pagination
- create, update and delete data
- named query usage.

The saved query is a declaration of an allowed request shape. A literal entered while building a query is a sample or default. It is not automatically a forced security value.

## Query identity

Queries are stored per model and operation. A query also has a stable usage key.

```text
model → operation → usage/variant → query template
```

Examples of usage keys:

```text
company-dashboard
public-profile
talent-search
assignment-autocomplete
```

Two pages may use the same query only when that reuse is explicit. Two pages that use the same model and operation may still need different projections, filters, ordering, pagination or mutation data. They must have separate query variants.

Dee Wan does not union all queries for a model. A union would grant fields and operators from one page to another.

Each saved query has, at minimum:

- a stable ID
- a model and operation
- a human name
- a stable usage/variant key
- the Prisma query payload
- an accepted/enabled state
- a schema revision or identity for stale-query detection.

Validation rejects duplicate or ambiguous usage mappings. A stale query must be reviewed before generation.

## What the compiler derives

The compiler is pure and deterministic. It receives an accepted query and any explicitly declared trusted constraints, then emits the guard artifact used by the generated backend.

The first conservative rules are:

| Query part | Derived meaning |
| --- | --- |
| `select`/`include` | The accepted structural projection |
| `where` | Allowed field and operator structure. Ordinary sample values are erased to typed leaves |
| `orderBy` | The represented ordering structure |
| `skip` | Allowed only when the template includes it |
| `take` | A conservative default and maximum based on the accepted positive value |
| `data` | The represented writable fields and nested operations |
| scalar literal | A sample/default, never an implicit forced security value |

Unsupported or ambiguous constructs fail closed. The compiler does not widen a query to make it pass.

The generated guard remains internal. It may be available as an advanced diagnostic or build artifact for developers, but it is not the normal editing interface.

## Trusted constraints are separate

Some security rules cannot be learned from a query example:

- current user or tenant scope
- company ownership
- hidden/deleted predicates
- server-controlled fields
- identity and role restrictions
- hook-added conditions.

These rules are declared as trusted server constraints or hooks. They are not inferred from a value typed into the query editor. A query template may request `companyId`, but that does not authorize a caller to choose another company.

The generated backend applies authentication, permissions, trusted constraints and guards before returning a result. Hooks remain server code. They do not become arbitrary query policy through the editor.

## Same model, different pages

One Prisma model can safely have many variants. For example, a talent profile model may need:

- a small autocomplete projection
- a company search projection with filters and pagination
- a profile-summary projection
- a dashboard projection
- a grouped dashboard query
- an account update shape
- a separate boost mutation shape.

These are separate usages even when they share a model and operation. Each trusted usage becomes a fixed
generated HTTP method and path whose handler captures one query identity. A caller cannot select another
variant with a header, body field or query parameter. Route paths use the same grammar and collision
checks as generated and owned routes.

Path parameters supply declared unique selectors. Query parameters supply declared filters, ordering and
pagination. Mutation bodies supply declared data fields. Every value is checked against the derived guard
shape. The saved projection is fixed, and saved literals remain examples rather than forced values.

If two usages are intentionally identical, link them to the same saved query explicitly. Do not rely on name matching or automatic structural union.

## Generated backend and customization

The generated backend still uses the `prisma-generator-express` route and hook contracts and `prisma-guard` at the Prisma boundary. See [Extending your backend](/guides/extending-your-backend/) for owned hooks, operation overrides, groups and custom routes.

The query editor does not replace those extension points:

- query variants describe allowed request shapes
- trusted constraints protect ownership and tenant boundaries
- hooks add server behavior around the generated operation
- operation overrides replace or wrap an operation under the existing authentication, permission, guard and error contracts.

Do not edit generated route files or generated guard files in a connected backend. Put application code in the documented owned files. See [Implementation details](/reference/standalone-backend-internals/) for the generated stack, dependencies and ownership zones, and [Guard settings](/reference/standalone-backend-api/#guard-settings) for the fixed guard policy.

## Review before generation

Before a query becomes generation input, review:

1. the model and Prisma operation
2. the usage key and trusted route mapping
3. the projection and relation depth
4. allowed filters, operators, ordering and bounds
5. writable fields and nested writes
6. trusted constraints and hooks
7. stale schema or removed-field errors
8. the negative case: a query from another usage must fail.

Changing a model field, relation, selector or operation can make a saved query stale. Generation must refuse until the query is repaired or deliberately removed.

## Current status

The saved-query contract is defined in the canonical `SPEC.md` and `SPEC-ACCESS.md` contracts. Production
storage, the model-builder workspace, the route editor's method and path, generation-time validation and
the fixed runtime endpoints are implemented. A standalone backend serves each bound trusted route at its
own method and path from `src/trusted-routes.ts`. The manifest those handlers read is `src/query-manifest.ts`.
Query edits still take effect only after regeneration and redeployment. Check the generated artifact's own
README before using it in a deployment.

## Next step

When the backend is ready to run without managed regeneration, follow [Detach and verify](/guides/detachment/).

<!-- dee-wan-docs page: /guides/detachment/ -->

# Detach and verify your standalone site

Source: https://dee-wan-docs.pages.dev/guides/detachment/

Detachment stops CMS-managed updates. It is not deleting the CMS or its data. Keep the original installation until the owner accepts the standalone result. The [detachment contract](/detachment-contract/) defines what is exported, and the [standalone backend API reference](/reference/standalone-backend-api/) is the only generated-backend API reference.

## Preconditions

Use a reviewed source snapshot and identify the intended site, repository, published snapshot and destination database. Read the [GitHub authentication matrix](/guides/github-authentication/). Managed delivery of a locally generated commit uses a configured App, `npm run backend:deliver` uses device flow, and the admin cannot generate source (`source_build_runtime_unavailable`). `npm run backend:generate` does not need GitHub credentials and does not deploy.

Before any deployment, address the known standalone boundaries. Every deployment, managed or repository-only, writes `ACCESS_CONFIG` as the union of the CMS-issued read-token digests committed in `access/read-tokens.json` and `vars.ACCESS_CONFIG` in your `wrangler.jsonc`. When there are none, it writes a valid empty list (`{ version: 1, siteId, tokens: [] }`). Routes that require a read token refuse until one is delivered, and the deploy refuses a value the Worker could not boot with. A revoked CMS token stays accepted until you regenerate and deploy. Detaching does not remove the committed digests: see [Stop the CMS connection](#stop-the-cms-connection). The emitted README can describe an older one-model/read-only contract. Edge compatibility is not a blanket guarantee for added Prisma extensions or generated routes. Follow the current [API reference](/reference/standalone-backend-api/), not the stale emitted README, and retain a verified backup.

## Generate and review

For the integrated CLI, the source repository's invocation shape is:

```sh
npm run backend:deliver -- --site <site-id> --repo <owner/name> --source <cms.db> --dest <output-directory> --db <target.db>
```

This is an operator-authorized write/deploy operation, not a verification-only command. Supply its required environment and confirm repository ownership before running. Review generated, owned and shared files, model coverage, translations, relations and the published snapshot. Preserve `src/owned/` and shared dependency configuration. Media transfer is a separate explicitly selected operation requiring source and destination access. A site that references private files also needs a private source group and a private destination bucket of its own (the `EXIT_MEDIA_SOURCE_PRIVATE_` and `EXIT_MEDIA_DESTINATION_PRIVATE_` names in `exit --help`); without them the run is refused before anything is copied, and a private file is never written to the public bucket. Bind that bucket to the Worker as `PRIVATE_FILES`. To serve with `npm run serve:local` instead, set `EXIT_MEDIA_DESTINATION_PRIVATE_DIRECTORY` (an existing absolute directory, used instead of the bucket) and start the server with `PRIVATE_FILES_DIRECTORY` pointing at it; the server answers `503 private_files_unavailable` while that is unset. Generation alone does not move media into your custody.

## Verify the exact generated commit

From the generated repository, use its verified dependency installer and existing checks. After an authorized deployment, keep `API_BEARER_TOKEN` in the environment and run:

```sh
node scripts/install-dependencies.mjs
npm run typecheck
npm run build
npm run verify:media
npm run verify:deployment -- --origin 'https://site.example.com' --expect-commit <full-commit-sha>
```

`verify:media` checks committed snapshot/page projections for CMS-owned media references. It is not a remote byte-availability test. `verify:deployment` uses the bearer token and compares the deployed content with the committed snapshot across routed tables, including the expected commit. It must pass for the repository revision you intend to own, not merely return a healthy status.

For an emitted `apps/site`, also use `node scripts/install-dependencies.mjs apps/site`, `npm run --prefix apps/site check` and `npm run --prefix apps/site build`. Open representative deployed pages in each required locale and verify media availability separately. A passed backend check does not verify the website visually.

### Site Worker compatibility flag

Blog routes, search pages, and pages with a Latest entries section, a Site search section or visitor comments read published content from `/v1` on the site's own host at request time. Cloudflare sends that same-host request to the Dee Wan public Worker only when the site Worker enables `global_fetch_strictly_public`. New projects get it in `apps/site/wrangler.jsonc`. That file is yours: Dee Wan writes it only when it is absent and never rewrites it. Latest entries in a shared section shown in a region are pinned at generation and read nothing at request time. They read public models only: a private model shows `collection_model_missing`. Their summaries frame the embed origins accepted at generation. Changing a model's visibility or an embed origin needs a new generation.

When the generated site performs these reads (recorded in the generated `apps/site/public-reads.json`), generation and deployment check your existing `apps/site/wrangler.jsonc`. If `compatibility_flags` is missing the flag, or is not a list of strings, both refuse with `public_fetch_compatibility_flag_required`, name the file and the flag, and change nothing. Add `"global_fetch_strictly_public"` to `compatibility_flags` yourself and run again. Generation in the CMS and the deployment both read this file as JSONC, so comments and trailing commas are accepted. A file that is not valid JSONC refuses the same way. A site with no Blog, site search turned off and no page served at request time has no such requirement.

## Stop the CMS connection

Only after acceptance, remove the CMS build webhook and stop requesting CMS-managed deployments. Review or disable the repository workflow that fetches CMS definitions so it cannot regenerate unexpectedly. Set the generated site's `previewApiOrigin` to `null` when no longer using CMS draft preview. The standalone API and statically built pages should continue with the CMS unavailable. The routes in [What still depends on Dee Wan](/detachment-contract/#what-still-depends-on-dee-wan) do not. Without the Dee Wan public Worker, Blog routes and search pages answer 503 and a Latest entries section shows its error. Without the intake Worker, comments and forms cannot be sent.

CMS-issued read tokens survive detachment. Their digests stay in the committed `access/read-tokens.json`, and every repository-only deployment still adds them to `ACCESS_CONFIG`. Revoking a token in the CMS no longer reaches this repository. Review the file after detaching. To stop accepting a token, delete its entry, or the whole file, then commit and deploy. Without the file, deployment uses only `vars.ACCESS_CONFIG`, or the empty list. The file is in the `generated` zone, so while you are still connected, revoke in the CMS and regenerate instead.

`npm run backend:deliver` offers the detachment plan after verification. It does not perform this final disconnection automatically. Do not delete source data, buckets or credentials as part of this runbook. For rollback, retain the previous accepted commit and matching database/media state. An old code commit alone does not reconstruct later data changes.

Authorities: `scripts/exit-start.ts`, `backend/src/lib/graduate/regenerate-template.ts`, `backend/src/lib/graduate/deployment-files.ts` and `backend/src/lib/graduate/media-custody.ts`. Real deployment and visual acceptance remain the operator's responsibility.

## Before you retire the CMS

Detaching keeps the Dee Wan installation running. Retiring it is a separate step. Check each item first:

- **Generated API.** `npm run verify:deployment` passes for the commit you will keep. The API reads only its own D1 database.
- **Static pages.** They are built from the committed `pages.json` and read nothing at request time.
- **Blog, site search, Latest entries and comments.** When the site has any of them, `apps/site/public-reads.json` holds `"requestTimePublicReads": true`. They read `/v1` from the Dee Wan public Worker on every request and stop working when it is gone.
- **Forms and comment submissions.** They post to `/v1/interactions/*` on your host, which the Dee Wan intake Worker answers. The Dee Wan admin Worker delivers form submissions.
- **Preview.** `previewApiOrigin` is `null`, or you accept that `/preview` stops.
- **Managed renderer.** If you deployed `managed-renderer/`, it reads `/v1` on every request.
- **Public and intake Workers.** Know which routes on your host point at Dee Wan Workers: `/v1/*` and `/v1/interactions/*`.
- **Media custody.** `npm run verify:media` passes, so no committed projection still points at Dee Wan media. Without a `--media` transfer, Dee Wan still serves the media.
- **Plugins.** The generated backend has no plugin host. Plugin rich blocks on request-time routes read their definitions from `/v1/_rich-blocks`.
- **Read tokens.** You reviewed `access/read-tokens.json`, as above.
- **Definitions.** To regenerate later, pull and keep a `definitions.json` while the CMS still runs. See [Regenerate locally](/reference/standalone-backend-api/#regenerate-locally).

## Artifact authentication during delivery

Before delivery, review backend-wide Better Auth methods and exact access policies. A missing model policy is `service`. Supply selected provider inputs through target secret storage or local `ARTIFACT_*` environment variables. Delivery creates a fresh `BETTER_AUTH_SECRET` for the artifact and seals repository values with the `ARTIFACT_` prefix. Existing target secrets are preserved. Unselected providers require no credentials. The reviewed target hostname determines OAuth and magic-link callbacks. Never copy CMS credentials or accounts.

Keep the artifact auth tables and their migration history with its database backup. They have no generated CRUD API. Disabling auth requires a new destination. Regenerate for dependency or method-binding changes. Public reads are verified anonymously. Session-only reads require a real target session supplied as `ARTIFACT_VERIFY_SESSION_COOKIE`. A missing session produces `verify_session_required`, not successful verification. On first deployment, initialize the target, sign up through its auth routes and rerun verification with that session. Do not save session values in source, reports or ledgers. Provider callbacks, email and live deployment acceptance require the adopter's own authorized environment.

## Next step

Plan how to restore the database and media with [standalone recovery](/guides/standalone-recovery/).

<!-- dee-wan-docs page: /guides/standalone-recovery/ -->

# Standalone recovery runbook

Source: https://dee-wan-docs.pages.dev/guides/standalone-recovery/

How to recover a standalone website's data and media with your provider's own tools. Dee Wan has no backup service. Nothing on this page has been run against a live deployment by this project. Rehearse it on a disposable copy before you rely on it.

The Wrangler commands below are Cloudflare's. They are checked against Cloudflare's D1 and R2 Wrangler command references, D1 import and export guide and D1 Time Travel reference on 2026-09-23. This repository runs only `wrangler d1 export` itself (`scripts/d1.ts`).

## What to recover

| Part | Where it lives | Recovered by |
| --- | --- | --- |
| Code | Your repository | Git. A commit identifies it. |
| Generated content rows | Generated tables in your D1 database | Reloading the committed snapshot (`npm run data:load`), or a database restore |
| Your own rows | Your own tables in the same D1 database | A database restore only |
| Media | Your R2 bucket, if you moved media into your custody | Your own copy of the objects |
| Secrets | Your repository secrets and Worker secrets | Your secret store. Never in a backup file. |

A code rollback in Settings restores none of the rows or media above.

## Capture

First pause processes that write data: your own jobs and CMS deployments to this site.

Export the database to a file:

```sh
npx wrangler d1 export <database-name> --remote --output backup-<date>.sql
```

An export blocks other requests to the database while it runs, and Cloudflare does not export databases that contain virtual tables. Numeric values pass through JavaScript numbers, so integers beyond 52 bits of precision can change.

Record the repository commit that was deployed, the export time and a checksum of the file. For media, copy every object key listed in `data/media-manifest.json` out of your bucket, for example with `npx wrangler r2 object get <bucket>/<key> --remote --file <path>`. Keep the copies outside the bucket.

## Restore into isolation first

Create a new database and load the export into it:

```sh
npx wrangler d1 create <restore-database-name>
npx wrangler d1 execute <restore-database-name> --remote --file backup-<date>.sql
```

The generated deployment resolves its own database from its configuration, and this project has no command that targets a restored copy. Point a separate, non-production Worker configuration at the restored database yourself, deploy the recorded commit to it, then verify it with `API_BEARER_TOKEN` in the environment:

```sh
npm run verify:deployment -- --origin 'https://restore.example.com' --expect-commit <full-commit-sha>
npm run verify:media
```

`verify:deployment` compares the deployed content with the committed snapshot. `verify:media` checks media references in the committed projections. It does not download bytes. Open representative pages and media yourself.

## Point-in-time restore of a D1 database

Cloudflare D1 Time Travel restores a database in place to an earlier point in time. It reaches up to 30 days back on the Workers Paid plan and 7 days on the Workers Free plan. `--timestamp` takes a Unix timestamp or an RFC 3339 time with a timezone. `--bookmark` takes a bookmark that `info` prints.

```sh
npx wrangler d1 time-travel info <database-name>
npx wrangler d1 time-travel restore <database-name> --timestamp <time>
```

This overwrites the live database, including your own tables, and cancels queries in flight. Export first. The restored schema may be older than the deployed code. Check that the deployed commit's migrations match the restored database before you serve traffic from it.

## Restore media

Put the copied objects back under the same keys with `npx wrangler r2 object put <bucket>/<key> --remote --file <path>`. While the CMS still holds the media, `npm run backend:deliver` with `--media` transfers its current public media as part of a full generation and delivery. It cannot bring back media the CMS no longer holds.

## Cut over

After the isolated copy passes verification, point production at it or repeat the restore in production. Keep the old database until the owner accepts the result. Re-enable processes that write data last.

Related: [rollback and recovery](/guides/walkthrough/rollback-and-recovery/), [CMS backup and restore](/guides/backup-restore/), [detachment runbook](/guides/detachment/).

## Next step

Look up routes, authentication and deployment behavior in the [API reference](/reference/standalone-backend-api/).

<!-- dee-wan-docs page: /reference/standalone-backend-api/ -->

# Standalone backend: API reference

Source: https://dee-wan-docs.pages.dev/reference/standalone-backend-api/

This page covers the API, authentication, deployment and rollback of a generated standalone backend. It describes emitted source, not a Cloudflare deployment that has passed acceptance. For what a standalone backend is and how to generate one, see the [overview](/guides/standalone-backend/). For files, dependencies and table mappings, see [Implementation details](/reference/standalone-backend-internals/).

## Routes

Generated IDs such as `Article.findMany` identify operations. HTTP routes use the lower-case model name, for example `/api/blogpost`. The customizable catalogue includes only operations that have generated security.

| Method/path below `/api/<model>` | Operation | Result |
| --- | --- | --- |
| `GET /` | `findMany` | Array of rows |
| `GET /paginated` | `findManyPaginated` | `{ data, total, hasMore }` |
| `GET /unique` | `findUnique` | Row or `null` |
| `POST /` | `create` | Row, status 201 |
| `PUT /` | `update` | Row |
| `DELETE /` | `delete` | Row |

Junctions expose only the three reads; a list relation is written through its owner (below). Translation tables also allow create, update and delete operations for editors. Bulk operations, aggregate/count/groupBy, upsert, updateEach and other unconfigured operations are absent. Disabling an emitted operation removes it from execution and OpenAPI while keeping its path reserved against the raw owned mount. Reads have no POST alias.

Read arguments use query parameters, with JSON for structured values. Writes use Prisma argument objects in JSON bodies. URL-encode structured query values.

```text
GET /api/blogpost?take=25&skip=25
GET /api/blogpost/unique?where={"id":"item-id"}
POST /api/blogpost {"data":{"id":"new-post","featured":false}}
PUT /api/blogpost {"where":{"id":"new-post"},"data":{"featured":true}}
DELETE /api/blogpost {"where":{"id":"new-post"}}
```

This is not the CMS `/v1` public API: consumers receive Prisma-shaped results, not the CMS `{ data, page }` response contract.

### Relation and translation writes

A to-one id is written on the row, like any column. A missing target returns `422 relation_target_missing`.

A hierarchical parent link (a to-one relation to its own model marked **Hierarchy (parent/child)**) never loops. A create or update that makes a row its own parent, or puts it under one of its own descendants, returns `422 relation_hierarchy_cycle` with `field` (the `<field>_id` column) and `targets`. Generated create and update routes and trusted routes check it before writing. SQLite triggers in `migrations/` refuse the same write inside the database, so two concurrent writes cannot both succeed; the refused one gets the same answer. Every migration drops and re-creates these triggers around its changes. Roots, reparenting and clearing the parent (`null`) are ordinary writes. An id from another model or site, or one that identifies no row, returns `relation_target_missing`. Locale rows never carry the parent.

A list relation has one route per field on its owner: `PUT /api/<owner>/relations/<field>`. The body names the owner row and either the whole ordered list or the changes to it.

```text
PUT /api/article/relations/tags {"where":{"id":"post-1"},"set":["tag-2","tag-1"]}
PUT /api/article/relations/tags {"where":{"id":"post-1"},"connect":["tag-3"],"disconnect":["tag-1"]}
POST /api/articletranslation {"data":{"article_id":"post-1","lang":"fr","title":"Bonjour"}}
```

- `set` replaces the list in the given order. `connect` appends; `disconnect` removes, and disconnecting an id that is not linked is treated as already complete. `set` cannot be combined with the other two.
- The resulting list is validated against the CMS rules: no duplicates (`relation_duplicate_target`), required and `minItems` (`relation_too_few`), `maxItems` (`relation_too_many`), existing targets (`relation_target_missing`). Item counts are checked on every request. Deleting a target removes its link, so a list can fall below `minItems`; it then answers `relation_too_few` until a write brings it back within its limits. A list equal to the stored one writes nothing and answers with the stored list.
- A one-to-many target already held by another owner is refused with `409 relation_target_taken`.
- The links are rewritten in one database batch. If the list changed after it was read, nothing is written and the answer is `409 relation_changed_concurrently`.
- The route inherits `<Owner>.update`: its access mode, permission, operation and group hooks. Disabling `<Owner>.update` disables the route; its path stays reserved.

A locale row is created with its row key and language. The language must be one the site was generated with (`422 unknown_locale`): a Blog's configured languages, or a language used by published content. A Website pins no language list, so a language with no published content yet needs a regeneration. The base row must exist (`422 translation_row_missing`), and a row has one locale row per language (`409 locale_exists`). An update changes only the translated values. Translation writes inherit `<Model>.update`, and deletes `<Model>.delete`.

### A field that allows several models

A relation field can allow more than one model. Such a field is stored in one join table per allowed model, for example `ArticleRelatedTag` and `ArticleRelatedPerson`, each with a foreign key to its model that deletes the link with the target. The rows of all these tables share one list order through `position`, so the list can mix models freely. A mixed to-one field (`manyToOne`, `oneToOne`) is stored the same way, not in a column. A parent link (hierarchy) allows one model only.

- A reference is `{"model":"<model slug>","id":"<row id>"}`. In `set`, `connect`, `disconnect` and `relations` of the atomic create, a bare id is refused with `422 relation_target_model_required` on a field that allows several models. A model the field does not allow answers `422 relation_target_model_not_allowed`, and an id that identifies no row of the named model, or no row at all, answers `422 relation_target_missing`. A field that allows one model still takes bare ids and also takes `{ model, id }` with its own model.
- The answer lists `{ "model", "id" }` references in order. In `targets` of an error, a reference of such a field is written `model:id`.
- The same rules as for any list apply to the whole mixed list: no duplicates, `minItems` and `maxItems`, a one-to-many target held by one owner (`409 relation_target_taken`), one write in one batch. A to-one field holds one reference across all its models, also against a racing write: the write that read an older list answers `409 relation_changed_concurrently`.
- `GET /api/<model>/files/<field>/<row id>` serves a private file when the row's `<field>_url` holds a `private-file:` marker. The Worker reads it from the `PRIVATE_FILES` R2 binding; the Node server (`npm run serve:local`) reads it from the absolute directory named by `PRIVATE_FILES_DIRECTORY`, which must exist, in which a file's content type is kept in a `<key>.meta.json` beside it. It inherits `<Model>.findUnique`: its access mode, permission, hooks and availability, and the caller's own guarded read of the row. It answers `404` for a row without a marker, an object the bucket lacks, or a row the caller cannot read. With neither the binding nor the directory it answers `503 private_files_unavailable`, and never falls back to public storage. A response is `private, no-store`; images and PDFs are displayed inline, anything else downloads.
- Rich-text media use the same protected route with `?media=<media id>`. It selects a `private-file:` marker actually held by the row’s rich field, not a storage key supplied by the caller. `&variant=thumb` and `&variant=preview` read that parent’s private WebP variants; a missing preview falls back to its original. The exported `privateRichText(html, endpoint, rowId)` helper maps canonical rich HTML to these same-origin file URLs for display. Use it after reading the row; the file route still checks live row access on every request.

- `GET /api/<owner>/relations/<field>?id=<owner id>` reads the ordered list with each reference's model (add `&locale=` for a list with links in each language). It inherits `<Owner>.findUnique`, and a private field answers editors only. Reading one join table, for example `GET /api/articlerelatedtag`, returns only that model's rows; `position` is the place in the whole list.
- A published item that links to a model the field does not allow blocks generation (`invalid_reference`), and a model that is not on the site blocks it (`relation_target_absent`).

### Create a row with its lists in one write

An owner with at least one list relation also has `POST /api/<owner>/with-relations`. It creates the row and its list memberships together. The ordinary `POST /api/<owner>` still creates a row without lists, and `PUT /api/<owner>/relations/<field>` still changes a list later.

```text
POST /api/article/with-relations {"data":{"id":"post-1","title":"Hello","author_id":"person-1"},"relations":{"tags":["tag-2","tag-1"],"topics":["topic-1","topic-2"]}}
POST /api/note/with-relations {"data":{"id":"note-1"},"relations":{"related":{"en":["tag-1"],"fr":["tag-2","tag-3"]}}}
```

- `data` is the body of the ordinary create, validated against the same create guard shape and hooks as `POST /api/<owner>`. A missing `id` is generated. `relations` names list fields; a shared list is an array of ids in order, a list with its own links in each language is an object from language to array. Anything else in the body answers `400 invalid_request`.
- Every list field of the owner is checked, and a field you leave out counts as empty. A required list (`minItems`) must be given, or the answer is `422 relation_too_few`. For a list with links in each language only the languages you name are checked.
- Before anything is written the route checks the CMS rules: no duplicates (`relation_duplicate_target`), `minItems` and `maxItems` (`relation_too_few`, `relation_too_many`), existing targets (`relation_target_missing`), a one-to-many target held by another owner (`409 relation_target_taken`), a parent link that names the new row (`relation_hierarchy_cycle`), an id that is already a row (`409 record_exists`), and to-one ids in `data` (`relation_target_missing`).
- The row and all its links are written in one database batch on D1 and in one transaction on SQLite. If any statement fails, none of them is kept: there is no row without its links and no link without its row. Two creates that claim the same one-to-many target at the same time cannot both succeed. One answers `201`; the others answer `409 relation_target_taken` and leave nothing behind. A failure the preliminary checks could not detect, such as a unique value another write took first, answers `409 write_conflict`.
- A success answers `201` with `{ "id", <columns>, <field>: [ids] }`. Private fields are left out, as in every write answer.
- The route inherits `<Owner>.create`: its access mode, permission, and operation and group hooks. It answers `403 forbidden` to a caller that may not create. Disabling `<Owner>.create` removes the route. If the owner's `create` has an operation override, the route answers `501 atomic_create_unavailable`, because the override replaces the write this route performs. Without a batch runner it answers `503 relation_writes_unavailable`. OpenAPI marks the route `x-atomic-create`.
- It does not write translation rows. Create those with `POST /api/<model>translation`.

Deployment runs `scripts/check-relation-ids.mjs` before it applies migrations. A database migrated by an earlier generator can hold relation ids that name no row, and the migration that adds their foreign keys would fail as a whole. The check lists each one (model, column, row id, missing target) with the remedy and refuses with `relation_ids_dangling` before anything is migrated. `npm run db:init` and `npm run data:load -- --database <file>` run the same check, with the same database, before local migrations. Generating the standalone backend locally into an existing target database refuses the same way.

Readiness refuses relation shapes no generated write can satisfy: limits no list can meet (`relation_bounds_unsatisfiable`), a target model the site does not have (`relation_target_absent`), and required to-one fields that lead back to their own model (`relation_required_cycle`). Published items whose parent links already loop are refused with `relation_hierarchy_cycle`, naming the items. Model Builder shows the same note on the relation field.

### Text validation

Generated text fields retain the declared `minLength`, `maxLength` and `pattern` rules. Patterns support Unicode property escapes such as `\p{L}` and `\p{N}`; an intentionally ASCII-only pattern keeps its restriction. Regenerate and redeploy after changing these rules. Generation refuses executable custom text validation with `unsupported_text_validation` instead of running or discarding it. Malformed text rules, including invalid patterns or a minimum above the maximum, refuse generation with `invalid_field_validation`.

### Point queries

Generated list and paginated-list routes accept `filter[location][within_radius]=13.75,100.5,1000` (latitude, longitude, metres) and `filter[location][within_bbox]=13,100,14,101` (south, west, north, east). Bounds are inclusive; west greater than east crosses the antimeridian. Nearest order uses `sort=location&origin=13.75,100.5`; `sort=-location` reverses distance. Missing points sort last, followed by stable row ID order. Radius uses Haversine distance in metres.

These options pass through the existing generated route, authentication, row guard and effective field-query permissions. A disabled point field is refused with `403 spatial_field_denied`. They do not enable a field or operation removed by an owned customization or saved query. `sort` cannot be combined with `orderBy`; invalid coordinates or syntax are refused with `400 spatial_query_invalid`.

The emitted local SQLite and D1 runtimes supply a driver adapter. A spatial request without an adapter returns `501 spatial_adapter_required`. SQL translation also covers PostgreSQL and MySQL; those providers require their own runtime acceptance before deployment. Spatial filtering and ordering run before SQL pagination and use the same predicates for counts.

Live shared references require source-site grant custody. Generation returns `shared_references_require_live_delivery` for effective shared slots; remove or replace them before generating a detached backend. Ordinary same-site relations remain supported.

### Retained locale originals

Media identity remains `<field>_id`; `<field>_url` remains the default transferred address. Media-bearing fields also carry `<field>_originals`, a JSON map from served locale to media ID to the exact retained original's facts and transferred URL. Shared component and rich fields keep one authored value and retain originals for each served language. Private fields and components with private nested fields keep this metadata private.

Import `mediaOriginal` from `src/media-original.ts`. `mediaOriginal(row, 'cover', 'fr')` reads the original for the row's `cover_id`; pass a fourth media ID for a component or rich field. An absent locale or asset returns `null`. Generation uses the published version's recorded fallback result; it does not choose a newer library file. Exit transfers each retained object independently and rewrites its address while preserving the asset identity.

## Authentication, guards and errors

Access policy decides whether a route accepts anonymous, session or service callers. Missing model policy is `service`. Read tokens are digests scoped by model in `ACCESS_CONFIG`. Unscoped routes and `/api/openapi.json` require wildcard scope. Service writes without a writer authenticator return `503 writes_unavailable`. Absent credentials return 401 and denied permission returns 403. Optional Better Auth supplies the artifact session for both local and Worker runtimes. Local serving and the Worker accept the same `API_BEARER_TOKEN` service bearer.

Managed deployment builds `ACCESS_CONFIG` on every deploy from two sources: the CMS-issued tokens in the generated file `access/read-tokens.json`, and your own `vars.ACCESS_CONFIG` in `wrangler.jsonc`. It deploys their union. With neither, it deploys a valid empty list (`tokens: []`). Both are checked by one rule module, `src/access-config-rules.js`, which the Worker also uses at startup. The rule requires version 1, this site, every token naming this site, and lowercase SHA-256 hex digests. It also requires model scopes, no write capability, no duplicate token id and no duplicate digest. An invalid owned value is rejected with `owned_access_config_invalid`, and an invalid generated file is rejected with `generated_access_tokens_invalid`. The same id in both is rejected with `access_token_id_conflict`, and the same digest in both with `access_config_union_invalid`, all before any database or Worker changes. Your own entries are never removed. A value set only in the Cloudflare dashboard is replaced by the next deploy, so keep yours in `wrangler.jsonc`. Commit digests of long random secrets only, never the secrets. Outside the generated deployment flow, missing or invalid `ACCESS_CONFIG` refuses boot.

## Read tokens issued from the CMS

Settings → Source & delivery → Deployed API read tokens, with the `site:infra` permission.

- **Issue.** Give a name and one or more models. The secret, `dw_art_` and 43 base64url characters, is shown once and stored nowhere. The CMS keeps its SHA-256 digest. Callers send `Authorization: Bearer <secret>`. The CMS never issues a `*` token. A wildcard token stays in your own `vars.ACCESS_CONFIG`.
- **Deliver.** Nothing reaches a deployed backend until you regenerate and deploy. Issuing or revoking marks the site out of date. Regeneration writes the active tokens, digests only, to `access/read-tokens.json` with each scope mapped to the model's generated name (and its translation table).
- **Revoke.** Revoking does not deploy. The deployed backend accepts a revoked token until the next regeneration and deploy. A detached backend is out of the CMS's reach.
- **Rotate.** Issue a replacement, deploy, move the caller to the new secret, revoke the old token, deploy again. There is no in-place swap.
- **Models.** Scopes are model ids, so renaming a model changes nothing. Deleting a model, or undoing the import that created it, removes it from every token. A token left with no model is revoked, never widened.
- CMS site API tokens (`site_api_token`) are never copied into a generated backend.
- Generation refuses a token whose scope no longer maps to a generated model (`token_scope_not_emitted`), and single-model generation refuses while active tokens exist (`read_tokens_need_site_graduation`).

Generated reader shapes permit id equality. Editor shapes permit equality on the generated row columns. A model's private fields are left out of reader selects (anonymous reads and read tokens) and of every write response; a component column holding a private field anywhere below is left out whole, and a private list relation's join table responds only to editors. A single-entry model's table holds one row: a unique index refuses a second, and the create route answers `409 single_entry_exists`. Normal lists order by id and use default 25/max 100. Translation lists order by language then id. Junction lists order by position then id with default 100/max 200. Unsupported selectors/operators are refused. D1 is isolated per site. The artifact refuses a mismatched `SITE_ID` rather than claiming row-level tenancy.

In the generated backend, a component field is one embedded JSON value, nested up to 3 levels below a root component, the same limit the CMS enforces when you build the definition. A chain deeper than that is refused before generation with `component_nesting_too_deep`, naming the component and the path of components that reaches it. Media references inside nested components are found at every level.

Customization cannot remove generated authentication, permissions, variant selection, guards or error protection. The generated composition layer resolves guards before hooks, validates resolved shapes and disables the environment guard bypass regardless of owned settings. The installation's other supported guard choices remain generation inputs. `allowE2EGuardBypass` is still deprecated upstream, but is not an override escape hatch here.

Generated router errors retain upstream normalization. Errors disclosing SQL, Prisma calls or local paths are replaced by `request_refused` while preserving status. Unhandled owned failures return `request_failed`. A configured commit is returned in `x-artifact-commit`.

## Guard settings

Settings → Source & delivery → Generated API guards remains the installation input for generator policy. The owned composition layer fixes the following security settings. Owned declarations cannot weaken them. The existing reader/editor variants remain the only variant dispatcher.

| Setting | Generated customization pipeline |
| --- | --- |
| `requireGuardShape` | `true` |
| `validateGuardShapes` | `true` |
| `requireDefaultVariantOptIn` | Retains the installation's selected policy |
| `enableUpdateEach` | `false` |
| `guardResolutionOrder` | `before-hooks` |
| `allowE2EGuardBypass` | `false` |
| `validateResolvedShapes` | `true` |

## OpenAPI

Authenticated `GET /api/openapi.json` combines upstream generated schemas and enabled operations with schema-validated declarative routes. Same-contract overrides retain the generated request/result schema. Custom routes declare their access operation and optional model scope. Their supported schema subset is enforced for input and output. Raw Hono routes have no generated OpenAPI contract. Documentation does not make an anonymous route public.

## Optional artifact authentication and access

![Source and delivery settings with standalone authentication, cache and model exposure](/assets/screenshots/source-delivery.webp)

In **Settings → Source & delivery → Standalone authentication, cache and exposure**, enable Better Auth once for the backend. Then select Password, Magic link (Resend), Google or GitHub. Disabled is the default: no Better Auth dependency, runtime, routes, tables, migration, provider configuration or secrets are emitted. CMS accounts, sessions, invitations, password hashes and provider credentials never enter a standalone backend. Application content named `User` stays separate from the artifact identity tables.

| Access mode | Accepted caller |
| --- | --- |
| `public` | Accepts an explicit typed anonymous principal without a credential. |
| `session` | A current session from this artifact's Better Auth instance. |
| `service` | `API_BEARER_TOKEN`, or an eligible scoped token for a read. |
| `session_or_service` | Either the artifact session or service authentication. |

Each model's access mode and operation overrides are set on its model page → **Standalone API**. Saving needs `site:infra`. The policy is stored against the model id, so it follows a slug rename and is deleted with the model. A save names the revision it replaces. A stale screen gets `409 policy_changed_concurrently`. Slugs that generate the same model name (`blog-post` and `blog_post`) are refused when a model is created or renamed. A missing model configuration explicitly uses `service`. Missing operation overrides inherit the model default. Overrides use exact generated IDs such as `User.findMany`, `User.findManyPaginated`, `User.findUnique`, `User.create`, `User.update` and `User.delete`. Validation rejects removed operations. Generated policy types also reject stale IDs. Operation availability remains in the owned backend registry. Access settings do not re-enable disabled operations. Policies name sessions, never particular login providers.

![A model's standalone API page with default and per-operation access modes](/assets/screenshots/model-standalone-api.webp)

Authentication and permission checks run before hooks and overrides. Guard resolution, existing ownership boundaries and error protection remain mandatory. A public create rejects protected system, owner, tenant, role, administrator, password, verification and provider-link fields, including nested input. Public create makes application content. Signup happens only through Better Auth routes. Raw routes default to `service`. Declarative routes must state `access.mode` and `access.operation`, with optional model scope. OpenAPI shows each operation's access mode.

| Optional install root | Package | Block | Exact version |
| --- | --- | --- | --- |
| `root`, only when enabled | `better-auth` | `dependencies` | `1.6.25` |

Enabled artifacts emit `src/better-auth.ts`, provider verification and the existing auth limit/lockout rules, plus a separate migration for `_artifact_auth_*` infrastructure tables. These tables have no generated CRUD endpoints. Both the Node/SQLite server and Worker/D1 use the same selected methods, password bounds, verified OAuth identities and hashed verification tokens. They also use the same database session revocation, seven-day session limit and mutation-origin checks. Provider access, refresh and ID tokens are discarded. Auth responses suppress provider internals.

Run `npm run auth:init` to create a fresh random secret in ignored `.dev.vars`. It preserves an existing artifact secret. The Node server can load this file with `node --env-file=.dev.vars src/serve.local.mjs`. Wrangler loads it directly. Apply `db:init` first. Set `ARTIFACT_ORIGIN` to the API origin, for example `http://127.0.0.1:8787` locally. Remote origins must use HTTPS. Deployment derives the origin from the reviewed target hostname, never from the CMS origin.

| Selected method | Required runtime values | Target callback |
| --- | --- | --- |
| Password | `BETTER_AUTH_SECRET` | Password routes under `/api/auth` |
| Magic link | `BETTER_AUTH_SECRET`, `RESEND_API_KEY`, `MAIL_FROM` | `<ARTIFACT_ORIGIN>/api/auth/magic-link/verify` |
| Google | `BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | `<ARTIFACT_ORIGIN>/api/auth/callback/google` |
| GitHub | `BETTER_AUTH_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | `<ARTIFACT_ORIGIN>/api/auth/callback/github` |

Register callbacks in adopter-owned OAuth applications. Resend needs a verified sender domain. Only selected methods require credentials. Target preflight fails before deployment when a selected method lacks them. Repository Actions secrets prefix runtime names with `ARTIFACT_`. This also avoids GitHub's reserved `GITHUB_` prefix. Delivery generates a new artifact secret and seals it to the target public key. Existing target secret names are preserved without rotation. `npm run backend:deliver` reads provider inputs only from `ARTIFACT_*` environment variables. Secret values never enter source, manifests, generation inputs, digests, checked-in vars, logs or deployment ledgers.

Regeneration preserves owned/shared files. Enabling auth in an existing shared package or changing selected methods requires regeneration to update dependencies and caller workflow bindings. Disabling auth on an existing destination is rejected: use a new destination, preserving the old identities and migration history. Access-only changes participate in generation-source and manifest digests.

`verify:deployment` respects access policy. Public reads are checked anonymously. Service reads use the bearer. Session-only reads require a current target session in `ARTIFACT_VERIFY_SESSION_COOKIE`. Without it, verification refuses with `verify_session_required`. It never reports an unperformed content check as passed. For first deployment, initialize the target, create an account through its auth routes, and rerun verification with that session. Keep the short-lived session out of source and evidence. Browser and live deployment acceptance remain separate gates.

## Application-account administration

Off by default. When Better Auth is enabled, the artifact can also expose the Better Auth admin plugin for the application's own accounts. Accounts, roles and sessions stay in the application's database, and only an application administrator can use these operations. The Dee Wan CMS holds no copy of the accounts, takes no part in a request, and need not be running. With the integration off, no plugin, route, migration, column or binding is emitted.

**Turn it on.** Add `"accountAdmin": true` to the authentication setting of the site, then regenerate and deploy: `PATCH /api/sites/<site-id>/standalone-auth` with `{"authentication":{"enabled":true,"methods":["password"],"accountAdmin":true}}` and the `site:infra` permission. A save that leaves `accountAdmin` out keeps its current value. In the admin it is the switch "Account administration in the generated application" under Settings → Source & delivery → Standalone authentication, cache and exposure; it is disabled while Better Auth is off. The setting adds the migration `migrations/<number>_artifact_auth_admin.sql`: it adds the `role`, `banned`, `banReason` and `banExpires` columns to `_artifact_auth_user` and `impersonatedBy` to `_artifact_auth_session`. The number is the next free one in the migration lineage the artifact already has when the setting is first enabled (`0004` on a new artifact). Regeneration keeps that file and number, and an applied migration is never renumbered. Turning the setting off later removes the routes and the page and leaves the columns and the migration file; turning it on again reuses the same file.

**Who is an administrator.** A user whose `role` is `admin`, or whose id is in the optional runtime binding `ARTIFACT_ADMIN_USER_IDS` (comma-separated, at most 50 ids). New accounts use the configured default application role unless an administrator selects another role. `list-users` and `get-user` add `access` (`admin` or `user`) and `adminSource` (`role`, `configuration`, `both` or `null`) to each account, computed on every request from the stored role and the current binding. The binding never changes the stored role; the account page shows both. To create the first administrator, sign up through `/api/auth/sign-up/email`, read your id from `GET /api/auth/get-session`, set the binding as a Worker secret of the target (or in the environment of the Node server) and restart. Later administrators are promoted with `set-role`. The database refuses deletion, demotion or banning of the last active administrator. Keep the binding as an independent recovery path. The generated deployment workflow does not manage this binding.

All calls use the administrator's own session cookie, and mutations must come from `ARTIFACT_ORIGIN` like every other auth call. The paths are under `/api/auth/admin/`.

| Operation | Method and path | Body or query | Effect |
| --- | --- | --- | --- |
| List accounts | `GET /api/auth/admin/list-users` | `limit` (at most 100, default 100), `offset`, `searchValue`, `searchField`, `sortBy` | `{ users, total }` |
| Create an account | `POST /api/auth/admin/create-user` | `{ name, email, role?, password? }`; a configured role; password 12–128 characters | Creates the account without public sign-up or mail delivery |
| Delete an account | `POST /api/auth/admin/remove-user` | `{ userId }` | Ends sessions and removes credentials; self-deletion, last-administrator deletion and linked application records are refused |
| Read one account | `GET /api/auth/admin/get-user` | `id` | The account |
| Edit a profile | `POST /api/auth/admin/update-user` | `{ userId, data }`, `data` holds `name`, `image` or `email` only | The updated account |
| Set application access | `POST /api/auth/admin/set-role` | `{ userId, role }`, `role` is a configured application role (default: `admin` or `user`) | The updated account |
| Ban | `POST /api/auth/admin/ban-user` | `{ userId, banReason?, banExpiresIn? }` (seconds) | Marks the account banned and ends all its sessions |
| Unban | `POST /api/auth/admin/unban-user` | `{ userId }` | Clears the ban |
| List an account's sessions | `POST /api/auth/admin/list-user-sessions` | `{ userId }` | `{ sessions }` |
| Revoke one session | `POST /api/auth/admin/revoke-user-session` | `{ sessionToken }` | `{ success: true }` |
| Revoke all sessions | `POST /api/auth/admin/revoke-user-sessions` | `{ userId }` | `{ success: true }` |

**Create or delete.** Open `/admin/accounts`, choose **New account**, enter a name, email, initial role and password when password sign-in is enabled. Creation uses the same Better Auth service and hashes credentials; no sign-up request or email transport is needed. Open an account and choose **Delete account** to confirm irreversible deletion and session revocation. A `409 ACCOUNT_ADMIN_LINKED_RECORDS` response lists the model/table and field to reassign or remove first. Application foreign keys are checked at deletion; related application records are never silently cascaded. `400 YOU_CANNOT_REMOVE_YOURSELF` and `409 ACCOUNT_ADMIN_LAST_ADMINISTRATOR` protect administrator access.

A banned account cannot sign in until it is unbanned or the ban duration specified by `banExpiresIn` expires; its sign-in answers `403 authentication_failed`.

**Refusals.** Every refusal answers `{ "error": "account_admin_refused", "code": "<code>" }` with the status below.

| Status | `code` | When |
| --- | --- | --- |
| 401 | no code, or Better Auth's | No valid session |
| 403 | `YOU_ARE_NOT_ALLOWED_TO_…` | The signed-in user is not an administrator; or the origin is foreign |
| 404 | `USER_NOT_FOUND` | No such account |
| 404 | `ACCOUNT_ADMIN_OPERATION_UNSUPPORTED` | Any other path or method under `/api/auth/admin/`: set password, impersonate, stop impersonating, has permission |
| 400 | `ACCOUNT_ADMIN_PROFILE_FIELD_UNSUPPORTED` | `update-user` with a field other than `name`, `image`, `email`, or with no field |
| 400 | `YOU_CANNOT_BAN_YOURSELF` | An administrator bans their own account |
| 400 | `YOU_ARE_NOT_ALLOWED_TO_SET_NON_EXISTENT_VALUE` | `set-role` with an unknown application role |

The administrator role carries only the permissions these operations use, so an operation outside the table is unavailable even if a request reached the plugin. The integration never writes the `_artifact_auth_*` tables itself and adds no generic CRUD over them.

**Account page.** The artifact serves a page for these operations at `/admin/accounts` on its own origin. It uses the application's own administrator session, in the browser, with the page's own cookie, and calls only the operations in the table plus the artifact's own `get-session`, `sign-in/email` and `sign-out`. Signed out, it shows a sign-in form when the password method is selected; with another method, sign in through the application first. A signed-in user who is not an administrator sees a refusal. Each account shows its stored role and, separately, "Administrator (role)", "Administrator (configured)" or "Administrator (role and configured)" when it has administrator access. An administrator can search accounts by email, edit a profile, set the role, ban and unban an account, and list and revoke its sessions. The page holds no account data of its own and names no CMS address, so it works with the CMS offline. With the integration off the route does not exist. In the Dee Wan admin, once the switch is saved on and the deployment has recorded a hostname (Settings → Source & delivery → Advanced — build webhook and deployment → Standalone backend), "Open account administration" under the switch opens `https://<hostname>/admin/accounts` in a new tab; until a hostname is recorded the admin shows "Deploy the application to record its address." The CMS never proxies the application's cookies: a page served by the CMS cannot call these operations, because the artifact's session cookie belongs to the artifact origin and its trusted origin list holds only that origin. `curl` or a client of your own on the artifact origin also works.

### Application roles

In **Settings → Source & delivery**, enable application sign-in and account administration.
**Application roles** lets you add roles such as `customer` or `staff`, choose the signup role,
and select each role's generated API operations by model. Save, then regenerate and deploy the
application. `/admin/accounts` offers those roles when an administrator changes an account.

Up to 32 roles, including `admin` and `user`, are supported. Names use 1–64 lowercase Latin letters,
digits, hyphens or underscores and start with a letter. The signup role must exist and cannot be
`admin`. The administrator role retains all operations. **All operations** is explicit; otherwise
only the selected operation IDs are permitted. Empty grants permit none. Without this optional
configuration, the existing `admin`/`user` behavior is unchanged.

The stored `backend_policy.authentication.roles` configuration is:

```json
{"default":"customer","grants":{"admin":["*"],"user":[],"customer":["Article.findMany","Article.findUnique"]}}
```

This constrains application sessions on generated API operations. Public operations remain public;
service credentials keep their existing scopes. Trusted reads and translation writes inherit the
operation they already name. CMS roles and accounts remain separate. Assignment changes are checked
on subsequent requests; they do not depend on the CMS being online. A configured recovery
administrator retains access. Removed or unknown role assignments grant no application operations.
The existing regeneration and deployment process carries the policy without overwriting owned code.

## Snapshot, migrations, deployment and rollback

`data/published-snapshot.json` is generated and digest-checked. `db:init` applies local migrations before loading it. `data:load` loads a declared local SQLite or D1 target. Loading the same snapshot again changes nothing. Loading is rejected for a database that holds another site's or artifact's snapshot, for edited snapshot bytes or for an incomplete load. A snapshot with different content replaces every table it owns: the load deletes each table's rows and writes the snapshot's rows. A row the snapshot does not hold is gone, whoever wrote it, and the load does not refuse. Tables the generator did not create are not touched. Store application-owned rows in application-owned tables. The `observed_row_set_mismatch` refusal belongs to local generation into its own disposable `--db` database, not to `data:load`.

```sh
npm run db:init -- --database ./standalone.db
```

Regeneration validates source ownership, emits schema/app/security/site files, regenerates Prisma and guard/router output, removes generation-machine paths, and checks customization. Migration emission appends changes and preserves history. Destructive or incompatible shape changes require their explicit review path. The final ownership manifest must describe the completed tree.

### Regenerate locally

`npm run regenerate` runs `scripts/regenerate.mjs`, then `prisma:generate`, `portable` and `customization:check`. A whole-site artifact needs two inputs:

- `definitions.json` in the repository root: the site definitions as the CMS serves them. Git ignores the file, and the managed build deletes it before it commits. Without it, regeneration refuses with `definitions_missing`.
- `GENERATION_SOURCE_VERSION`: the version those definitions describe. Without it, regeneration refuses with `generation_source_absent`. A value that differs from `data.generationSourceVersion` in the file refuses with `generation_source_version_mismatch`.

**Connected.** The CMS serves definitions only to a build token. Signed in to the admin with `site:deploy`, call `POST /api/sites/<site-id>/build/token`. It answers `build_token` and `generation_source_version`. The token is short-lived and reads that one version's definitions. `DEE_WAN_URL` is the same CMS origin the managed workflow uses. A change to the site after you mint the token makes the pull answer `409 source_moved`.

```sh
curl -sS -o definitions.json -H "Authorization: Bearer <build_token>" "$DEE_WAN_URL/api/sites/<site-id>/definitions"
export GENERATION_SOURCE_VERSION=<generation_source_version>
node scripts/install-dependencies.mjs
npm run regenerate
npm run migrate:emit
npm run typecheck
npm run build
npm run files:manifest
rm definitions.json
```

**Detached.** Without the CMS, regeneration works only from a `definitions.json` you pulled earlier, for example with the connected steps before retirement. Keep that copy outside the repository: it is the site's whole content model. Regenerating from it rebuilds the generated files for that same version. It brings no newer content.

```sh
cp <kept-definitions.json> definitions.json
export GENERATION_SOURCE_VERSION="$(node -p "require('./definitions.json').data.generationSourceVersion")"
node scripts/install-dependencies.mjs
npm run regenerate
npm run migrate:emit
npm run typecheck
npm run build
npm run files:manifest
rm definitions.json
```

Regeneration refuses an edited generated file. If you edit generated files after detaching, stop regenerating.

A `--model` artifact needs `MODEL_VERSION_ID` and that model's definitions instead. Without the variable it refuses with `model_version_absent`. The CMS `/definitions` route serves site definitions only. The single-model manifest reader reads the payload, and records and re-checks the artifact's own generator guard choices.

`deploy-from-repository.yml` checks out an exact commit, installs verified dependencies, checks/builds, resolves D1, and applies `migrations/` with `wrangler d1 migrations apply`. It then deploys the API, sets its writer secret, loads the committed snapshot and invalidates the response cache, verifies content/media, and deploys the site. `verify:deployment` compares served rows and commit identity. `verify:media` checks custody. An older `git_sha` selects an earlier code revision. It is not automatic database or media restoration: retain compatible migration history, backups and adopter objects before rollback.

The response cache and its invalidation are described in [Response cache](/reference/standalone-backend-internals/#response-cache).

## Known gaps

D1 does not support the interactive-transaction path. Paginated rows and totals use separate reads and can differ during concurrent writes. Raw Hono handlers must apply explicit guard shapes to their own Prisma queries. Merely using an extended client does not constrain every query, and raw SQL is not guarded. Local Worker acceptance and deployment acceptance are separate gates. Source code and authored checks alone do not prove either has passed.

## Next step

For the files, dependencies and table mappings behind this API, see [Implementation details](/reference/standalone-backend-internals/).

<!-- dee-wan-docs page: /reference/standalone-backend-internals/ -->

# Standalone backend: Implementation details

Source: https://dee-wan-docs.pages.dev/reference/standalone-backend-internals/

How a generated standalone backend is built: the files it contains, its dependencies, the Cloudflare resources it uses, how content maps to tables, the exported managed renderer and the response cache. For routes, authentication and deployment, see the [API reference](/reference/standalone-backend-api/).

## Emitted directory tree

The tree is abridged. It shows the main files, not every emitted file.

```text
.
├── package.json
├── .nvmrc / .npmrc
├── wrangler.jsonc / wrangler.example.jsonc / wrangler.build.jsonc
├── graduation.manifest.json / graduation.generator.json
├── .dee-wan-files.json / .dee-wan-customization.json
├── prisma/schema.prisma
├── migrations/
├── access/read-tokens.json
├── data/published-snapshot.json
│   (data/media-manifest.json after a media transfer)
├── src/
│   ├── app.ts / worker.ts / access.ts / access-policy.ts / auth.ts / security.ts / db.ts
│   ├── access-config-rules.js / access-config-rules.d.ts / credential-digest.ts
│   ├── response-cache.ts / query-manifest.ts / trusted-routes.ts / relation-routes.ts
│   ├── sqlite-batch.ts / d1-column-types.ts / d1-schema-columns.ts
│   ├── backend-customization.ts / backend-config.ts / customization-runtime.ts
│   ├── local.ts / serve.ts / serve-cli.ts / migrate.ts
│   ├── generated/prisma/ / generated/guard/ / generated/routes/
│   └── owned/backend.ts / owned/routes.ts
├── scripts/
│   ├── dee-wan-generator.mjs / regenerate.mjs / check-customization.mjs
│   ├── install-dependencies.mjs / emit-migration.mjs / portable-client.mjs
│   ├── load-snapshot.mjs / configure-deployment.mjs / file-manifest.mjs
│   ├── check-relation-ids.mjs / deploy-from-repository.mjs
│   └── verify-deployment.mjs / verify-media.mjs
├── .github/workflows/deploy-from-repository.yml
│   (site artifacts additionally carry dee-wan-build.yml, the managed
│    build contract; a `--model` artifact has no CMS-managed site build)
├── managed-renderer/
│   (only when the site had an active managed renderer release)
│   ├── package.json / package-lock.json / astro.config.mjs / tsconfig.json
│   ├── wrangler.jsonc / public/ / worker/ / src/
│   └── release/release.json / template.json / route-map.json / site-chrome.json
│       / managed-renderer.mjs / evidence/
└── apps/site/
    ├── package.json / wrangler.jsonc / astro.config.mjs / public-reads.json
    ├── public/.assetsignore
    └── src/
        ├── lib/ / pages/ / components/
        ├── lib/image-endpoint.ts
        ├── owned/
        └── pages/owned/
```

`generated` files are fingerprinted and regenerated. The next regeneration rejects edited generated files. `owned` files are scaffolded only when absent and preserved byte-for-byte. `shared` files are preserved, with an additive merge for package manifests. Migration history is append-only. The [customization guide](/guides/extending-your-backend/) gives the precise path matrix.

New package names are `graduated-site-` plus the UTF-8 site ID encoded as lowercase hexadecimal. They remain stable when models are reordered, added or removed. Existing adopter package names and README files are preserved.

## Stack and dependency inventory

Hono handles HTTP. Prisma uses its query compiler and D1 adapter in the API Worker. `prisma-generator-express` emits the Hono CRUD pipeline and OpenAPI, and `prisma-guard` enforces query shapes. Local serving uses the better-sqlite3 adapter. `eav-to-prisma` converts accepted CMS models during generation. The generator is also carried as a digest-pinned build script. It is not a runtime CMS service.

The following inventory is checked against `ARTIFACT_TOOLCHAIN_PACKAGES`, `SITE_MANIFEST`, and the installer constants. Root versions come from the actual generating installation and `graduation.manifest.json.toolchain`. Installed versions are taken from these sources. Every root entry is an exact pin. The site accepts the listed ranges and resolves them in its own lockfile.

| Install root | Package | Package block | Version authority |
| --- | --- | --- | --- |
| `root` | `@dee-wan/cache` | `dependencies` | `toolchain.responseCache (exact)` |
| `root` | `@prisma/adapter-d1` | `dependencies` | `toolchain.prismaAdapterD1 (exact)` |
| `root` | `@prisma/client` | `dependencies` | `toolchain.prismaClient (exact)` |
| `root` | `hono` | `dependencies` | `toolchain.hono (exact)` |
| `root` | `yaml` | `dependencies` | `toolchain.yaml (exact)` |
| `root` | `prisma-generator-express` | `dependencies` | `toolchain.prismaGeneratorExpress (exact)` |
| `root` | `prisma-guard` | `dependencies` | `toolchain.prismaGuard (exact)` |
| `root` | `jsonc-parser` | `dependencies` | `toolchain.jsoncParser (exact)` |
| `root` | `@cloudflare/workers-types` | `devDependencies` | `toolchain.workersTypes (exact)` |
| `root` | `eav-to-prisma` | `devDependencies` | `toolchain.eavToPrisma (exact)` |
| `root` | `@prisma/adapter-better-sqlite3` | `devDependencies` | `toolchain.prismaAdapterBetterSqlite3 (exact)` |
| `root` | `@types/node` | `devDependencies` | `toolchain.nodeTypes (exact)` |
| `root` | `better-sqlite3` | `devDependencies` | `toolchain.betterSqlite3 (exact)` |
| `root` | `esbuild` | `devDependencies` | `toolchain.esbuild (exact)` |
| `root` | `prisma` | `devDependencies` | `toolchain.prisma (exact)` |
| `root` | `typescript` | `devDependencies` | `toolchain.typescript (exact)` |
| `root` | `wrangler` | `devDependencies` | `toolchain.wrangler (exact)` |
| `apps/site` | `@astrojs/cloudflare` | `dependencies` | `^12.6.3` |
| `apps/site` | `@tailwindcss/vite` | `dependencies` | `^4.1.14` |
| `apps/site` | `astro` | `dependencies` | `^5.14.1` |
| `apps/site` | `tailwindcss` | `dependencies` | `^4.1.14` |
| `apps/site` | `@astrojs/check` | `devDependencies` | `^0.9.5` |
| `apps/site` | `@emnapi/runtime` | `devDependencies` | `^1.11.3` |
| `apps/site` | `typescript` | `devDependencies` | `^5.9.3` |

Runtime root packages provide the D1 adapter/client, Hono, guard support, generated-route helpers, and YAML OpenAPI serialization. Root development packages provide Worker/Node types, model conversion, local SQLite serving, Prisma generation/migration, TypeScript checking, esbuild bundling, and Wrangler. Local SQLite packages are development dependencies even though the local server uses them at runtime. The site dependency block contains Astro, its Cloudflare adapter, Tailwind, and the Vite integration. Its development block contains Astro checking and TypeScript.

The root declares Node `>=22`. Emitted `.nvmrc` selects `24.18.1` and `packageManager` selects `npm@11.16.0`. Existing `.nvmrc` and package-manager choices are preserved, so the verified installer still checks that the selected npm matches the declaration. Prisma CLI and client must use the supported major 6. Do not infer compatibility from Node's broad engine range alone.

```sh
node scripts/install-dependencies.mjs
node scripts/install-dependencies.mjs apps/site
```

The verified installer extracts dependencies with scripts disabled, audits lifecycle scripts including native builds, and rebuilds only approved packages. `allowScripts` approvals name exact versions. Denials can name a package. Root approvals derive from pinned Prisma engines/CLI, better-sqlite3, esbuild, and the recognized Wrangler/workerd pair. Automatic Prisma-client generation and fsevents are denied. The site has its own reviewed allowlist. An unknown lifecycle version requires review. Changing a dependency does not grant script permission. No Git hook is installed.

## D1 result types

The Worker reads D1 result types through `src/d1-column-types.ts` and the site's `src/d1-schema-columns.ts`. The D1 adapter guesses a column's type from its first value, so text that looks like a date can turn a whole column into dates. A raw query (`$queryRaw*`) gets such a column back as text only when its SQL text proves the column is `String`:

- Every row source is a table the schema declares. Sources are read after `FROM`, every `JOIN` kind, `UPDATE`, `INTO` and each comma of a `FROM` list, including after `ON` or `USING`, at any depth. A table may be quoted, prefixed with `main.` and aliased. A subquery counts through the tables inside it.
- At least one source declares the column, and every source that declares it declares `String`.
- No select or `RETURNING` list gives that name to anything except the same column (`x`, `t.x`, `x AS x`).
- The statement has no `UNION`, `INTERSECT` or `EXCEPT`.

Anything else keeps the adapter's guess. This happens for a table the schema does not declare, a CTE, a table-valued function and another schema. It also happens for a `VALUES` list, an alias, an expression, a compound select and a statement with no table. The check reads table and column names from the SQL text. It does not infer the types of SQL expressions.

## Cloudflare resources and configuration

| Item | Source or purpose |
| --- | --- |
| API Worker | The build uses `nodejs_compat`. Deployment uses the selected repository commit. |
| D1 database and `DB` binding | Deployment resolves it by site identity and creates it if absent. Migrations and snapshot loading target this database. |
| `SITE_ID`, `ACCESS_CONFIG`, `GIT_SHA` | Worker variables for site identity, read-token digests/scopes, and deployed commit. `ACCESS_CONFIG` is the union of CMS-issued tokens (`access/read-tokens.json`) and `vars.ACCESS_CONFIG` from your `wrangler.jsonc`, or a valid empty token list when there are none. |
| `API_BEARER_TOKEN` | Must have at least 32 characters. Store it as the API Worker writer secret in the repository secrets. Never commit it. |
| `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | GitHub Actions secrets used by deployment, not CMS runtime credentials. |
| `PUBLIC_HOSTNAME` | Repository variable naming the bare hostname used for deployment verification. |
| Astro site Worker/assets | Built from `apps/site`, bundled with `wrangler deploy --dry-run` before generation adopts it and before the first provider change, and deployed after API verification. No `nodejs_compat`: images pass through unchanged (`imageService: 'passthrough'`), so the Worker does not include `sharp`. `/_image` answers 404 (`src/lib/image-endpoint.ts`). The site has no image service. Sessions use the `null` driver, so the Worker needs no `SESSION` KV binding. `public/.assetsignore` keeps `_worker.js` and `_routes.json` out of the public assets. |
| Adopter media storage | R2/storage declarations and transfer manifest are required when moving media. `MEDIA_PUBLIC_ORIGIN` identifies the destination origin. Media bytes are not source files. |
| Managed build authority | `DEE_WAN_URL` and a site/version-bound build token belong to managed CI. Repository-only deployment does not fetch CMS definitions. |

`wrangler.jsonc` is a shared local configuration. `wrangler.build.jsonc` is generated for bundling. Deployment derives `wrangler.deploy.jsonc` from verified site/database/media inputs. An extra binding in the shared local file is not automatically provisioned or copied into that deployment configuration. Define the required provisioning/deployment step explicitly in an additional workflow. The generator ships no account credentials, active database identifier, or production route in its example configuration.

## Content, tables and mappings

Published versions become rows. Drafts, unpublished changes, history, users, roles, sessions, credentials and review/audit records stay in Dee Wan. A model slug produces a PascalCase Prisma model and mapped SQL tables/columns. Item identity is preserved in `id`.

Translatable fields live in a translation table keyed to the base row and language. A to-one relation (`oneToOne`, `manyToOne`) keeps target identity in a scalar `<field>_id` column. A list relation (`manyToMany`, `oneToMany`) uses an explicit junction table with ordered positions, owned by the model that declares the field. A one-to-many junction makes its target column unique: each target belongs to one owner through that field. A field that allows several models has one junction per allowed model, each with a foreign key to its model, and they share the owner's list order through `position`; a mixed to-one field is stored the same way. The target model gets no column and no write for the field. Single-model output does not invent target models or SQL foreign-key constraints, and it refuses list relations. A hierarchical parent link points at its own model, so it gets a foreign key on both paths. Text/rich text, numbers, booleans and dates become matching scalar columns. JSON, multi-select and components use JSON columns. Select options remain manifest constraints rather than database enums.

In whole-site output every relation id is a foreign key, and deletes follow the CMS:

| Reference | When the target row is deleted |
| --- | --- |
| Optional to-one `<field>_id` | The column becomes null. |
| Required to-one `<field>_id` | The delete is refused with `409 relation_target_referenced`, naming the model and column. |
| Junction link | The link row is removed. The list may then hold fewer items than its minimum until it is written again. |
| Translation row | Removed with its base row. |

A relation id inside a component JSON value is not a foreign key. Readers treat an id that resolves to no row as absent, as the CMS does.

Media keeps an identity column and adds a URL column. Moving the repository does not move media bytes. Media transfer rewrites addresses to adopter storage, and deployment verification refuses remaining Dee Wan-owned URLs. Page models produce Astro routes from their title and page document. Ordinary data models receive API routes without invented site pages.

## The exported managed renderer

`managed-renderer/` exists only when whole-site generation ran for a site with an active managed renderer release. It is export format 2, in the generated zone: generation writes it, fingerprints it and pins it in `graduation.manifest.json` under `managedRenderer`. Managed regeneration never rewrites it. The pin's `exportDigest` is the SHA-256 of `release/release.json`, which is canonical JSON followed by one newline. Generation inspects the export from its bytes before it adopts the tree. It refuses an identity that does not match the recomputed value, a `release/managed-renderer.mjs` that is not byte for byte the command this product emits (`managed_renderer_export_cli_mismatch`), an unreadable pin (`managed_renderer_export_pin_invalid`) and a `managed-renderer` directory spelled in another case. There is no compatibility path for older export shapes. See [managed templates](/guides/managed-templates/).

Generation adds three root scripts. It adds each only when it is absent and never overwrites one.

| Script | What it does |
| --- | --- |
| `managed-renderer:verify` | Checks the manifest pin and the closed release record; every file under `managed-renderer/` except build output at its root, by length and digest, below the per-file limit, at a safe path, once even ignoring case; the compiled chunks; the input, source, contract and release digests; the gate report, bound to the release with every required gate passed in order; `template.json`, `route-map.json`, `site-chrome.json` and `wrangler.jsonc`; and no custody key or local path in the metadata. It does not re-parse the template manifest, its provenance or the route map grammar. Generation's inspector does. |
| `managed-renderer:build` | Verifies, then runs `npm ci --ignore-scripts`, the type check and the build inside `managed-renderer/`, on this machine and with network for `npm ci`. It refuses a changed lockfile or another toolchain. It does not re-run the contract, accessibility or viewport gates. Their evidence is `release/evidence/report.json`. |
| `managed-renderer:prepare` | Builds, then runs `wrangler deploy --dry-run` into `managed-renderer/.wrangler/deploy`. Deploys nothing. |

Run them from the repository root. `managed-renderer/` and `managed-renderer/release/` must be real directories. `build` and `prepare` first remove `node_modules`, `dist`, `.astro` and `.wrangler` at the top of `managed-renderer/`, and unlink a link there without following it. The commands set `ASTRO_TELEMETRY_DISABLED=1` and `WRANGLER_SEND_METRICS=false`. None of them contacts the CMS.

Script edits keep every other byte of `package.json`: line endings, indentation, a byte order mark and the final newline. When the previous manifest pinned an export and a later generation no longer writes one, it removes only scripts whose value is still exactly the canonical one, so your own command under one of those names stays. Adding refuses with `managed_renderer_scripts_unwritable`, and removing with `managed_renderer_scripts_unremovable`, when `package.json` is not UTF-8 or strict JSON, its root or `scripts` is not an object, or it names `scripts` or one of these scripts twice. Adding also refuses when `package.json` is missing. A removal from a `package.json` that never names one of these scripts changes nothing.

The generated workflows, `deploy-from-repository.yml` and the `dee-wan-build.yml` that calls it, deploy the API Worker and `apps/site` only. They never build or deploy `managed-renderer/`. Its `wrangler.jsonc` names no route. Whoever deploys it must serve it at `https://` plus the site's active binding host, because the release is pinned to that origin. The renderer reads published content from `/v1` at that origin on every request, so publishing needs no rebuild, and it answers HTML with `Cache-Control: no-store`. It has no service binding: its `wrangler.jsonc` sets `PUBLIC_API_TRANSPORT` to `"public"` and enables the `global_fetch_strictly_public` compatibility flag, so each read uses public HTTPS and reaches the public Worker by its `/v1/*` route.

## Response cache

Standalone backend Workers use the registry package `@dee-wan/cache@1.0.1`. Every generated model defaults to cached reads. The global switch is in Settings → Source & delivery → Standalone authentication, cache and exposure. Each model's choice is on its model page → Standalone API, stored against the model id like its access policy. Reading and saving the global switch require `site:infra`. The model page opens with read access to that model, `site:settings` or `site:infra`. Saving it requires `site:infra`. Individual model choices and the global choice are recorded in generation input and manifests. Changing only cache settings makes the artifact out of date. Regenerate and deploy to apply them. Invalid stored settings refuse generation until reviewed and saved.

An opted-out model, its translations and its relation tables are excluded from cached reads. Queries reaching any excluded model also bypass caching. Writes still fence caches when caching is enabled. `CACHE_ENABLED=false` disables both cached reads and write fences. Any value other than `true` or `false` refuses every request with `cache_switch_invalid`. Local SQLite serving is uncached.

The Worker exports `CacheCoordinator`. Example, build and deployment Wrangler configurations declare the `CACHE_COORDINATOR` binding and a SQLite Durable Object migration. Exactly one coordinator name must serve each artifact D1 across every writer and code version. Names must never be shared by different D1 databases. The repository deploy script binds `CACHE_COORDINATOR_NAME` to the artifact identity plus its resolved D1 identity, preserving compatible owned bindings, migrations and variables. When deploying manually, keep that name stable and explicitly change it when cloning to a different D1. A second coordinator serving the same D1 under a different name would miss writes made through the first coordinator.

On Prisma 6.19.3 the client applies guards before caching. Guards run even on cache hits, and rewritten query arguments enter the cache key. A client is scoped after authorization to the principal, access variant, request URL, method and result-affecting headers, including locale and tenant context. Volatile request identifiers are excluded. Scope values are digests, not stored raw credentials. Auth lookups use uncached reads. Cache integration does not grant any model or operation access and has no Dee Wan runtime callback.

D1 `data:load` requires the artifact service writer token and `PUBLIC_HOSTNAME` before it writes. After a verified committed load, it calls the service-only invalidation endpoint, which verifies the committed snapshot ledger and calls `$cacheInvalidate({ all: true })`. Failure is a failed command, even if data already committed. Replaying the same load retries invalidation. A local D1 load also needs a loopback `CACHE_INVALIDATION_ORIGIN`. Local SQLite file loads need no coordinator. Raw writes made by other tools must use `$cacheRawWrite` or explicit post-commit invalidation. Post-commit invalidation has a window where older cached data may be read, so keep traffic stopped during bulk loads.

Generation is tied to the artifact manifest and an optional operator `CACHE_GENERATION` epoch. Different enabled generations sharing a coordinator remain correct but repeatedly invalidate each other’s caches and serve requests without cached data. Enabled and disabled versions must never serve together: disabled writes are unfenced. Stop and drain traffic, deploy all writers together, and invalidate or change `CACHE_GENERATION` before re-enabling after uncached writes. Do not use a gradual rollout to change the global mode.

Defaults are a one-hour fresh TTL and a 1 GiB storage budget. Stale-while-revalidate uses request `ctx.waitUntil`. Without request context it does not refresh in the background. A cache hit costs one Durable Object call. A miss adds a database read and a fill call. Writes normally use two coordinator calls. One coordinator has a soft limit of about 1,000 requests per second and one location, so network distance may make hits slower than D1 reads. Read-cache failures fall back to D1. Failure to acquire a write lease refuses the write. Loss of the final write fence can leave an entry until its TTL after the lease expires. Review the package contract when handling an outage.

Durable Object storage migrations are forward-only. Older code refuses newer storage, including Prisma writes. Roll forward across storage format changes. A code rollback is not a database, cache-storage or media rollback. Keep compatible migration history and adopter backups.

## Next step

Return to [Standalone backend: Overview](/guides/standalone-backend/), or continue with the [product vocabulary](/reference/vocabulary/) and the rest of the reference pages.

<!-- dee-wan-docs page: /guides/import-migration/ -->

# Import and migration

Source: https://dee-wan-docs.pages.dev/guides/import-migration/

Strapi v4/v5 import is the first migration boundary. It is a **supervised pilot**, not a promise that every production archive or deployment limit has been accepted. The [product boundary](/boundary/) separates local evidence from real-site migration acceptance.

## Before importing

Keep an untouched export and a verified backup of the destination. Record source identity, export time, expected counts, languages, published/draft expectations and media ownership. Use a disposable destination first. Decide explicitly which source partition belongs to each destination site. Never infer ownership from matching slugs or copy one site's data into another because they share a database.

## Inspect and map

Open Settings → Data transfer, then **Start import** on the **Import data** card. Select the supported Strapi source and supply the archive the UI requests. Inspection is not acceptance. Review every discovered content type, field, relation, locale and media source. Choose a new model, an existing model or skip for each type. Match field types and primary language deliberately. Unresolved or ambiguous mapping must block the run. Creating models and adding languages need the corresponding permissions.

A new field in an existing model cannot reuse a key that the model's kept versions still hold values under. The import's model step is then refused with `model_change_blocked`, each such key is listed as `retained_key_reuse`, and no field is added. Otherwise an old value could come back under the new field. Put that source field into another field, or leave it out.

![The import wizard source-selection step](/assets/screenshots/import-source.webp)

The import screens proceed through source, review/mapping, check, run and done. The review screen is where source-to-destination identity is chosen, not a place to accept guessed ownership.

**Cancel this import** is on the upload, review, WordPress review, check and run screens. It asks first, stops the work on the page, cancels the job and opens the result. A cancelled job frees the site for another import. Committed changes stay. Ordinary create-only imports can be undone separately; selected-content refresh has no automatic Undo. **Start a new import** on an import that is still open asks first (**Cancel and start again**), cancels it, then starts over. If the job cannot be cancelled in its current state, the screen says so and sends nothing. If the cancel is refused, the wizard stays where it is and shows why.

An archive whose reading stopped part-way (during extraction or inspection) opens on the upload step with a note. **Continue** reads on from where it stopped. **Cancel this import** frees the site instead.

![The import review and mapping step](/assets/screenshots/import-review.webp)

### Strapi components, dynamic zones and single types

- **Component definitions.** Each Strapi component a mapped type uses becomes a component this site owns. Its slug is the category and name: `shared.seo` becomes `shared-seo`, named "seo (shared)". A component inside a component comes along. Components may nest up to 3 levels below the component a field names, the same limit components built here follow. A deeper chain, a chain that contains itself, or a component value with more than 5,000 values or more than 256 KiB blocks the types that use it (`component_nesting_too_deep`, `component_cycle`, `normalize_component_too_large`) and names the chain or the field's path. Nothing is cut off.
- **Fields.** A component attribute becomes a component field allowing that component, a list when Strapi made it repeatable. A dynamic zone becomes a block list allowing the zone's components: each block keeps its source position, names its component and the definition version, and is shown.
- **Values inside components.** Rich text becomes rich text. Files become the imported media and are pinned per version like any component media. A relation inside a component points at the imported entry. A relation to a type the mapping skips is left out of the component (`component_relation_not_imported`). A relation inside a component shows its target by the target's title field, else its `title`, `name` or `label` field; a target with none blocks (`component_relation_display_unknown`).
- **Field keys inside components.** A component field key is lowercase letters, digits, hyphens and underscores. A Strapi attribute that does not follow this format is kept under a deterministic key: lowercase, each run of other characters as `_` (`SKU` becomes `sku`). The review lists each change (`component_field_key_normalized`) and the stored values move with it. Two attributes that become one key, or an attribute with no usable key left, block the types that use the component (`component_field_unmappable`), naming the source path.
- **One-to-many relations inside components.** A component value stores a relation’s order and targets, but cannot enforce a single owner for a target, so a one-to-many relation is kept as many-to-many. The review lists it (`component_relation_remapped`). The check refuses a source where two entries hold the same target through the same component field (`component_relation_target_shared`), naming the field. Choose which entry owns the target and exclude the others.
- **Languages.** A localized component or zone keeps each language's own value. A component that is not localized keeps the primary language's value.
- **The site's own components.** A component this site already owns under the same slug with the same fields is reused, so a second import from the same source writes nothing new. Different fields under that slug (`component_slug_taken`), a shared component with that slug (`component_shadows_shared`), or another component with the same name (`component_name_taken`) block the check.
- **Adding to an existing model.** Its fields for the source's components must be component fields allowing the same components with the same list shape (`component_field_mismatch`).
- **Single types.** A Strapi single type becomes a single-entry model: one entry, with its languages. The review screen marks it **single**. The check blocks when the selection or an existing single model would hold a second entry (`single_entry_many`, `single_entry_exists`).
- **Private fields.** A Strapi attribute marked `private` becomes a private field: kept for editors, never served publicly. Password attributes are never imported.
- **Media folders.** A Strapi 4 or 5 archive's folders are recreated in the media library from its folder entities and their parent and file links, never from file paths. Only folders that selected files sit in, with their ancestors, are created. A folder already at the same path in the site is reused. A file with a folder path but no folder link imports Unfiled and is reported (`media_folder_link_missing`). The dry run blocks a folder the library cannot hold: unusable name, missing parent, cycle, more than 5 levels, a sibling differing only by case, or past 500 folders. Nothing is renamed. Undo removes only folders this job created that are empty.
- **File type recorded wrongly.** Strapi can record one image type, such as WebP, for a file whose bytes are another, such as JPEG or PNG. A Strapi import stores the file using its real type and keeps the file name when both the recorded and real types are JPEG, PNG, WebP, GIF or AVIF and the site accepts the real type. Each such file is a warning (`media_type_corrected`) naming the file, the recorded type and the stored type; the import result shows them in their own block and the receipt download lists every one. Any other disagreement still blocks the file: SVG, a non-image, or a type this site does not accept. Uploads in the admin are not changed by this.
- **Permissions.** Strapi's end-user roles (Public, Authenticated) and their API permissions are listed and not imported (`strapi_permissions_not_imported`). Imported models are public, as new models are; set each model's visibility after import. An export carries no admin roles.
- **Review.** The type card names each component field by its component, and a dynamic zone by its blocks. **Components** lists every definition the import writes, its fields and the types that use it. The management mapping read (`getImportMapping`) returns the same `components` list, paged like `types`.
- **Undo and site copy.** Undo removes the component definitions the import wrote once no field uses them; a definition another model now uses, or one edited since, stays. A site copy carries the definitions and remaps every relation inside component values to the copied entries.
- **Not proven yet.** The recorded archives have no repeatable component attribute and no non-password private attribute. Both follow the rules above but are not tested against a real export.

## Check, run and resume

Save the mapping and run the check before starting writes. The check writes no site content, only the job's check state. While it runs, **Run the check** becomes **Stop**. **Stop** only stops this page: a request already in progress may still finish. A stopped or unfinished check says so, and **Check again** runs it again. Resolve blocking findings. Retain the accepted mapping with the source archive. Each entry's address is the source's slug or chosen URL field, normalized by the [item address](/reference/models-and-fields/) rules. One with no letters or digits blocks the check (`slug_invalid`). A chosen URL field that names a different address from the entry's `slug` field blocks it too (`slug_conflict`). Read the URL from `slug`, or make them match. The check judges every entry by the destination's field rules, required relations and media and their item counts included. This holds whether or not the entry has links. Start only the intended job and site. On interruption, resume that job rather than creating another with a new source identity. A repeatable rerun is not permission to discard refusal details or overwrite another site's rows.

The check reviews the destination's content types and components as they stand when it starts. If a field is added later, or renamed onto a key, or a component field starts allowing another component, the run refuses each entry or carried version that holds a value under the key the change claimed: `409 import_definition_changed`, naming the key. Running again does not change this, because the archive and its values stay the same. Nothing of that entry or version is written, and what already landed stays. Give the new field another key, then continue the run. Entries and versions without a value there continue. A field the import adds itself does not count as a change. While a component change holds a content type, writes to it wait (`component_migration_in_progress`) and continue once it finishes.

A site copy or history file carries private files too, with their bytes, checksums and visibility. The check blocks with `private_storage_unavailable` when this installation has no private file storage, before anything is written. The run stores each private file in that storage and never in the public bucket, and undo removes it from there. A model that is private in the file arrives private. If a model with the same key already exists here as public, the check blocks with `model_visibility_public`, so private entries are never shown publicly. Building that file needs `data:export` and read access to the media library; a content-only export (CSV, JSON, XLSX) never depends on a private library file. See [Media](/guides/media/#private-files).

A site copy or history file also carries the source's own field definitions. A carried value keeps the key its source field had, even when the source has since removed that field. A field here with the same key is not that field. If this site's content type or component has a field under a key such a value sits under, and the source did not define that key, the check blocks with `unmapped_source_key`, naming the key (`component.key` inside a component). This holds whether the field was here before the check or was added later. It covers carried versions, a language's live version in a site copy, and published or current values. A run refuses the same value with `409 unmapped_source_key` on every attempt and writes nothing of it. Give this site's field another key, then choose **Check again**. A field added after the check is first refused as `import_definition_changed`. Fields under keys no carried value uses, and fields the import adds itself, are not affected.

The source's privacy travels too. When the source keeps a field private, and this site's field under that key is public, the check blocks with `source_private_value`. This covers a private component attribute and a private component field around it. A run refuses the same value with `409 source_private_value`. Findings and refusals name keys, never values. Make this site's field private in the model or component editor, then choose **Check again**. A public source field imported into a private field here is fine.

The check also refuses a value that no save here could write. If a published, current or language version holds a key the destination content type will not have, the run would fail with `unknown_fields`. The check blocks it first with `unsupported_source_key` and writes nothing. If the source no longer defines the key, save and publish the entry in the source without that value, export a new file and import that file. The rejected file stays with its job. If the source still defines the key and this site's content type lacks it, add the field here, private where the source's is private, then choose **Check again**. Older carried versions may keep a retired key, because nothing here reads it.

![The import check with its readiness verdict](/assets/screenshots/import-check.webp)

![The import run before writes start](/assets/screenshots/import-run.webp)

Keep the source, mapping and completion/refusal result together. Verify primary entries, translations, relations, referenced media and publication state against the expected source partition. Reconcile counts by site and model, not only a global total. Confirm that destination A cannot read destination B's imported records.

![The completed import with per-source result counts](/assets/screenshots/import-done.webp)

## Undo and stuck files

For ordinary create-only imports, Undo on the done screen reverses what the job created and nothing else. Selected-content refresh has no automatic Undo. A file can get stuck when an earlier import write or undo delete never reported back. Undo then waits on it and cannot finish by itself. The undo section shows **A file is stuck** for each such file.

The screen shows the site, job, item, old storage key, expected digest, what undo is waiting on, when undo last checked the key, and a live check of the key made when the screen loaded. **Still used here** says whether a media row in this site still uses those bytes.

To finish, tick the acknowledgement and choose **Abandon old key and finish**. This needs the `data:import` permission. The outstanding write or delete may still land on the old key later, and nothing cleans that key up afterwards. The old key stays reserved forever and is never used again. A receipt records the decision: who, when, the evidence shown and the acknowledgement. If the key changed after the screen loaded, the action is refused. Choose **Check again** and decide on the new evidence.

If bytes came back at the old key and no media row uses them, the action is blocked. Choose **Continue the undo** first: it removes those bytes. A later import of the same asset writes to a new key.

## Native site files

A **site copy** carries current content and any differing published versions, models, fields, languages and media. It excludes edit history, accounts and credentials. Settings, workflow definitions and generation-context documents are included for comparison only; importing does not apply them. Choose **Transfer with history** for all retained content versions and workflow events. Neither product is a full installation backup; see [backup and restore](/guides/backup-restore/).

New site copies and history transfers download as `.deewan` files. Use the same import wizard to upload them. Building, uploading, verifying the completed upload, preparing and applying the file resume from stored progress; reopen the stored export job to continue a failed download. In Brave, saving to a chosen file writes verified chunks directly to disk. The browser download remains available when the file picker is unavailable.

History transfers carry all retained history without the earlier 20,000-row or 64 MiB archive limit. The archive upload limit is 52,428,800,000 bytes (about 48.8 GiB, including transport overhead). Verification reads at most 32 MiB per request and resumes by job ID after an interruption; you do not have to upload the file again. Individual media files follow the destination installation's normal file limits, up to 5 GB where enabled; they are copied in chunks and checked against their full checksum. Private originals and their previews stay private. The destination must allow the file's type and size. Nothing silently drops an oversized record or a missing file: preparation or the check names the refusal, and the job remains resumable.

A record may be up to 8 MiB. One model configuration or component dependency graph may be up to 16 MiB; one import work item may load up to 32 MiB. A source item that cannot fit a bounded processing pass is refused with a named reason. Splitting the archive does not bypass these per-item limits. Large groups of workflow events are split without discarding notes. Each stored event, including its note and identifiers, must fit the 1,900,000-byte row limit (`workflow_event_too_large`).

People and assignment reviews are paged. Suggestions apply to the current people page; saved choices remain when you change pages. CSV and XLSX exports keep their separate row and size limits. Earlier JSON site files remain readable with their existing 64 MiB archive, 32 MiB embedded-file and 10,000-character workflow-note limits.

<a id="refresh-selected-content"></a>

## Schema promotion

Switch to the destination site and open **Content Builder → Compare models**. Choose an accessible source site and model. Models match by their stable API slug, fields by key; translated labels do not determine identity.

Choose **Compare**, select the model details and field additions, changes or removals to carry over, then compare the selected changes. Removals start unselected. **Review changes** creates a proposal and opens the normal model editor; **Save** applies it only after the existing compatibility checks pass. Creating a model requires explicitly selected fields. No content, permissions, workflows or credentials are copied.

Both source and destination definitions are pinned to the comparison. Changed definitions or lost source access require a fresh comparison. Stored destination values, retained definitions, relation targets, components and uniqueness rules keep their normal guards; promotion cannot force an incompatible overwrite. A field kept by key keeps its destination ID, and a new field receives a new destination identity.

The admin endpoints are `POST /api/models/promotions/check` and `POST /api/models/promotions/propose`. Their request names `source_site_id`, `source_model_id`, `target_model_id` (or `null` for a new model), and `selection: { metadata, fields, remove }`. Propose also names the check's `source_revision` and `target_revision`. The resulting schema proposal follows the ordinary review/apply flow; revision mismatches return `schema_promotion_stale`.

## Refresh selected content

Use **Refresh selected content** on the **Check this import** screen to update a populated CMS staging site from a new native site copy. Ordinary import still adds missing records and skips records already imported. History files and WordPress imports use their own workflows.

1. Upload and prepare the latest site copy in the destination's import wizard.
2. Choose **Refresh selected content**, then select up to 50 models. The source and destination field definitions must agree.
3. Choose **Review changes**. Review the counts and every page of additions, updates, entries to move to Trash and retained entries. A destination entry missing from the source is a removal within the selected models, including entries created locally. Matching uses the source identity, never a guessed match by title or address.
4. Resolve blockers. An entry outside the selected models may still refer to a removal. Include the relevant model or choose **Keep this entry** for the target, then review again. At most 200 individual targets can be retained. Retention choices persist across pages and reloads.
5. Acknowledge replacement without Undo, then choose **Use refresh plan**. Continue through the ordinary **Run the check**, **Continue to run** and **Start importing** actions. Confirming the plan does not apply the content.

The refresh coordinates selected content relationships and required media. Other models, application accounts, roles and site configuration stay unchanged. Source deletions move entries to Trash; they are not permanently purged. The review and run refuse destination changes after review instead of overwriting newer work. Before importing starts, review the changes again. After any batch has committed, cancel this job and upload the current source copy as a new job to review the remaining changes; committed work stays in place.

A refresh has **no automatic Undo**. Keep a destination backup before running it. **Cancel this import** stops future batches; it leaves committed changes in place. Stored progress and receipts support reopening and resuming the same job. The operation does not promise one atomic replacement across database rows and files.

A provider-hosted link cannot return to a URL already recorded as a retained immutable version or change that URL’s recorded file facts. The check refuses it with `refresh_linked_media_retained`; existing versions stay unchanged.

For a single-entry model, refresh can update the entry already linked to the same source identity. A different source identity cannot replace an occupied single-entry model, even if its existing entry is in Trash. The review blocks this with `single_entry_taken`; it does not match entries by address or permanently delete the existing entry.

## Transfer a site with its history

Settings → Data transfer → Transfer with history moves one site into another site that has no entries yet. It carries every kept version and the workflow history. It is its own file, not a larger site copy. **Download history file** builds it on the source site. **Import a history file** on the destination opens the same wizard, check, run, undo and receipt as a site copy.

The file (transfer format 1, with history payload 3.1) carries models, content, languages, images and files, rich-text snippets, every kept version of each entry, the image copies those versions show, each entry's workflow steps, the items in Trash, current assignments and who each entry, file and signed-in comment is credited to. People travel as name or email labels only, never as accounts. It leaves out accounts, sessions, passwords, passkeys, API tokens, management credentials, AI keys, deployment settings and secrets, the admin audit log, plugin installs, planner plans, runs and queue, and import jobs and receipts. The check states this list.

Items in Trash arrive in Trash. They stay out of public pages and normal lists, keep their versions, links, files and comments, and are kept 30 days from when the import finishes. An assignment keeps its source person's email and due date. During the check, **Assignments** suggests the active member of this site with that exact email who can act on the entry. Keep the suggestion, choose another member who can act, or leave it **Unassigned**. Nobody gets an account or access from this. If nobody matches, or the person can no longer act when the import runs, the entry comes in unassigned with a warning. A carried assignment never sends a notification. An import is quiet by default; to have its own workflow moves notify, tick **Notify reviewers about review changes in this import** on the run screen. The choice is stored on the job, so every chunk, unattended run, resume and retry keeps it, and it can be changed while the job runs with the same `data:import` permission. See [feedback and notifications](/guides/content-editing/#feedback-and-notifications).

### Map people to members here

A history file and a WordPress export name the people behind the content: the author of each version, the person behind each workflow step, the entry's creator, the file's uploader and the writer of each signed-in comment. A WordPress author is listed by display name; the login and email are never stored. During the check, **People** lists each one with what they are credited with.

- **Map to** picks an active member of this site. Search when the site has many members.
- A member whose email is exactly the source email is suggested. A suggestion does nothing until you accept it. **Use page suggestions ({count})** accepts suggestions for undecided people on the current native-transfer page. In earlier JSON files and WordPress imports, **Accept {count} suggestions** applies all undecided suggestions. Choices you made stay.
- **Not mapped** keeps the source name or email as a label.

A mapped row shows **Mapped to {email} (source: {label})**. The import then credits the member and keeps the source label beside it: on carried versions and workflow steps, on each entry (the member owns it), on each file and on signed-in comments. An assignment uses the mapped member as its suggestion. Unmapped people stay labels; their entries stay owned by the person who runs the import. Visitor comments keep their visitor name, website and email.

Mapping never creates an account or a membership and copies no password, session, sign-in method or account. The check blocks the run when a mapped member is no longer an active member here. The run checks every mapping again before it writes and stops with `principal_mapping_invalid` if access changed since the check. Give the member access again, or undo the import. Exporting the site again carries the source labels, never account IDs. A member who owns mapped entries is the owner for "own content" permissions; an operator with only "own content" rights cannot undo entries handed to someone else. A Strapi export carries no people this import reads.

The check blocks the run when the destination already holds entries, counting the Trash. It also blocks when **Versions kept per item** (Settings → Workflow → Version history) is lower than the longest carried history needs, or when a carried version uses a language or shows an image the file does not carry. It blocks a carried value under a key that a field here uses but the source did not define there (`unmapped_source_key`, see [Check, run and resume](#check-run-and-resume)). An old version that links to an entry the file does not carry is carried without that link, and the check lists the removed links. The current and published versions follow the site-copy rules, so an unresolved link there still blocks. Carried versions keep their source numbers, times and author labels, and the history view marks them **Imported**. The import's own versions come after them and hold the published and current state again, so that content appears twice in the history: once as an **Imported** version and once as the import's own. Carried workflow steps are listed under **Imported workflow history ({count})** and never move an entry's workflow. Undo removes everything the job created, history included, also when the imported entries link to each other. Undo leaves alone what was edited after the import, and what such an edited entry still links to. Put the edit back, then choose **Try the remaining items again**. A history transfer is not a restore: IDs change and accounts do not travel.

## Import from WordPress

In WordPress, open Tools → Export, choose All content and download the .xml file. In Settings → Data transfer, use **Start import** on the **Import data** card, choose **WordPress export file**, name the WordPress site, choose the destination and upload the file. Use the same name for every later export from that site, so a second import skips what is already here. Only a WordPress export of format 1.2 in UTF-8 is read, at most 8 MiB. An export that holds the same post or attachment ID twice is refused (`wxr_item_duplicate`).

The media files the export names are copied once, before review: at most 5,000, from https addresses on public hosts only, and only file types Dee Wan accepts, with bytes that prove their type. Review counts a file that could not be copied under **Files not copied**, and the check report names it.

Posts, categories, tags, authors (as credited people), comments and media go onto the site's Blog. Pages go to a page type. The check blocks until the site has the Blog with categories, tags and people added (`wordpress_blog_taxonomy_missing`). On review, choose the **Language of the content** from this site's languages, and under **Where pages go** the page type for WordPress pages, or **Leave pages out**. A site with exactly one page type has it chosen already; a site with none leaves pages out. Published posts and pages are published; drafts come in as drafts. A featured image becomes the post's `cover`.

Pending-review (`pending`), private and password-protected content stays draft. Private visibility and passwords are not reconstructed; passwords are never stored. Scheduled (`future`) content requires an explicit **Keep schedules** or **Import as drafts** choice. Review shows the original `wp:post_date_gmt` instant; the source local timezone is never guessed. **Keep schedules** uses the installed, active and granted Scheduling plugin and its current publish workflow. Missing/invalid UTC time, a passed date or unavailable Scheduling blocks the check with an actionable finding. The schedule pins this import's final saved version; intervening edits refuse scheduling. **Import as drafts** keeps original UTC and local timestamps in review and `wordpress-plugin-data.json` without scheduling. Resume replays the same schedule request. Undo first cancels the unchanged schedule this job owns; if it cannot, its content is kept. Other statuses are not imported (`wordpress_status_not_imported`). Excerpt, menu order, parent, template, custom-type author and page featured-image values without a reviewed destination are reported.

**Custom fields**, in review, lists the post custom fields whose names do not start with `_`. A field with one plain value per post can go into a Blog post field whose type takes every value (text, a single choice with the value as an option, number, yes/no, or date), or be left out. Nothing is chosen for you and no field is created. A custom field with several values on one post, or a serialized or structured value, is listed and cannot be mapped. The section is hidden when the export has none. The choices save with **Save and continue**. A field removed or changed after saving blocks the check (`wordpress_metadata_mapping_invalid`). A post an earlier import already created keeps its values: changing the custom field choices does not update it on a later import.

**Custom content**, in review, lists each custom post type and each custom taxonomy in the export (for example an `event` type with `venue` and `event_tag` taxonomies). For each one, choose **New model “{name}”** (the default; the model is created in the import’s model step), a model this site already has, or **Leave out**. A site that already has a model under the WordPress name has that model chosen, filled field by field where the field key matches. Open **Fields** to choose, per source field, the field it goes into or **Leave out**. A new model gets the title, content (rich text), excerpt, featured image, publication date, every Advanced Custom Fields (ACF) field the export's field groups define, plain public values as text, and one link field per custom taxonomy. A custom taxonomy keeps its name, description, parent (hierarchical taxonomies) and ACF term fields. In a model this site already has, a source field goes into a field that can hold every value, or becomes **New field ({type})** under its own key when the model has none by that key; nothing else in that model changes. ACF fields and custom taxonomies on Blog posts are offered the same way under **Posts**: each can become a new Blog post field, go into an existing one, or be left out (the default). A choice that no longer holds blocks the check (`wordpress_model_choice_invalid`); a left-out type or taxonomy is a warning (`wordpress_type_left_out`, `wordpress_taxonomy_left_out`). Custom items follow create-or-skip like posts: a second import of the same source skips items, terms and models it already created and does not update them. When a custom type's items have comments, **Bring {count} comments** is on: they come in held for moderation like Blog comments, and the model is opened to comments (a new model is created with comments on; an existing one has comments turned on in the import's model step, which undo does not turn off). Untick it to leave them out (`wordpress_comment_type_left_out`).

**Excerpts and featured images** are kept only through a mapping you review; nothing is mapped by default. In **Custom content**, **Posts** lists the excerpt: it goes into an existing Blog post field that can hold text, or becomes a new field, or is left out. A post's featured image always becomes its `cover`, and can also go into a second image field. **Pages** lists the excerpt and the featured image once the export has a page with one and a page type is chosen: each goes into a text or image field of that page type, becomes a new field under its own key, or is left out. Changing the page type clears the page choices. A value left unmapped is counted in the check report (`wordpress_excerpt_not_kept`, `wordpress_featured_image_not_kept`) and named on each item; a featured image whose attachment is not an imported image is named on its item.

ACF field types map by the settings the export carries: text, email, URL, oEmbed, color and time become text; textarea becomes multi-line text; WYSIWYG becomes rich text; number and range become number; true/false becomes yes/no; select, radio and button group become a choice; checkbox becomes a multiple choice; date picker becomes a date; link becomes its URL as text (link text and target are named as not kept); image and file become media, pointing at the copied attachment; relationship and post object become a link to the imported item, only when every allowed post type goes into one model. Source-defined ACF groups and repeaters become editable JSON fields. Nested objects and repeater row order stay intact. Definitions must be present in the export; no field tree is inferred from raw meta keys. Unsupported subfields, mismatched definitions and nested media/relation references that have not been resolved are named in mapping review and remain in the plugin data file, rather than being presented as reconstructed native content. Password fields are never imported. Anything else is named and left out.

Yoast SEO values go into each post's, page's and custom item's search and sharing settings: the SEO title, meta description, canonical address (https or a path on the site only), the Open Graph or Twitter image, and noindex. Open Graph and Twitter titles and descriptions fill only what Yoast left empty. A title template is resolved only when every variable is one the export answers (`%%title%%`, `%%sitename%%`, `%%sitedesc%%`, `%%excerpt%%`); a template with `%%sep%%` or another Yoast setting is not kept and is named. Focus keyword, breadcrumb title, cornerstone, nofollow, advanced robots, schema type and primary category are named and kept in the plugin data file.

When the WXR carries Rank Math metadata and no Yoast metadata, the supported Rank Math title, description and canonical address fill the same settings. Only `%title%`, `%sitename%`, `%sitedesc%` and `%excerpt%` variables are resolved from the export. Unresolved variables and unsupported settings remain in the plugin data file. Missing source values are never invented. When both SEO plugins have values, Yoast takes precedence and Rank Math data stays in the plugin data file.

**Plugin data** in review downloads `wordpress-plugin-data.json`: everything the import does not read in — ACF field groups, post types and taxonomies, synced patterns and block navigation, every unmapped meta value of an item or term (Yoast settings, oEmbed caches, unmapped ACF values), plugin blocks, custom HTML and shortcodes with no equivalent, and comment meta keys. It is built from the export and the saved choices, so it changes when the choices change. Management clients read it as the `plugin_data` import artifact.

An image in a post or page body whose address is exactly an attachment's file address or GUID in the same export points at the copied file. A resized copy such as `photo-300x200.jpg`, an image on another host, and an image whose file was not copied are losses, each with its reason. A classic (pre-block) body is read the way WordPress shows it, with blank lines as paragraph breaks; markup between blocks of a block body is kept. Blocks with an equivalent are converted: galleries, tables (footer rows become the last rows), YouTube and Vimeo embeds (titled from the export's oEmbed cache), file blocks, quotes and pull quotes (a citation becomes the last line), details (a bold line over its text), buttons (links), images with captions (a paragraph under the image), the `[caption]` and `[gallery]` shortcodes, and synced patterns (copied in). Columns, groups, covers, media and text, colours, spacing and the "more" marker keep their words, images and links; the layout is dropped and named as not kept. Plugin blocks, dynamic blocks and custom HTML remain losses. A link whose address is exactly an attachment's file address points at the copied file. On pages, an embedded video becomes a video in a media section, a details block an FAQ section, a cover with text a hero section, and a quote or pull quote with a citation a testimonial; a link to a copied attachment file is kept as a rich-text file block. A post, page or comment that cannot be kept exactly, for example because of such an image, a shortcode or markup in its title, is left out unless you choose **Import them with the losses** under **Items that cannot be kept exactly**. The check report lists what each one loses.

A page becomes a structured page document. Heading levels, code blocks, tables, quotes, lists, links, supported formatting and copied media stay in its rich text. Long bodies use complete rich-document sections instead of losing content after the old 24-section conversion; each rich document holds up to 256 KiB, and one page holds up to 24 sections. A block or complete page beyond those bounds is refused, never truncated, even when you accept other losses. Simple pages keep their text and media sections. The host rich-text editor edits imported rich documents. A page keeps its title, address and draft or published state. In **Custom content**, map page custom and ACF fields to compatible fields of the selected page type; unmapped and unsupported values remain in the plugin data file. A page's parent, theme template, menu order and author are reported rather than guessed. Excerpts and featured images need reviewed mapping (see **Excerpts and featured images**).

Comments come in held for moderation. A WordPress export does not record that a commenter accepted this site's comment form, so every imported comment is stored with no consent, stays pending (or spam, when WordPress marked it so) and is not shown to visitors. In Posts → Comments it shows **No consent**. To show one, choose **Publish imported comment…**, one comment at a time. That is your decision to republish it, not a record of consent: the comment keeps **No consent**, and Settings → History records who published it. Approving a selection skips these comments. Refuse or delete the ones you do not keep. Each comment keeps its post, its reply parent, name, optional private email, optional website, text and date. Pingbacks, trackbacks, comments in WordPress Trash, comments on pages or on posts that are not imported, replies to replies (a Blog thread holds one reply level), replies whose parent is missing and parent chains that loop are left out and listed. A comment with markup keeps its text only once you accept the losses; its replies follow it.

Items with any other status than published, draft, pending review, scheduled, private or password-protected, the post types and taxonomies you leave out in review, and unsupported SEO plugin data are listed in the check report and are not imported; plugin data that is not read is kept in the plugin data file.

Importing menus needs the `site:settings` permission. Each menu of the export becomes a Site Chrome menu in its own accepted version, in export order. The menu, its Site Chrome version and the import's record of it are saved together or not at all. An item maps when it points at a post, page, category or tag that was imported, or at an https address. Item order is kept, with one level of items under a top-level item. An item that points at something not imported, a non-https address, and anything nested deeper are left out and listed per item. An item with no address stays as a heading over the items under it that map. Opening in a new tab, CSS classes, link relationships, title attributes and descriptions are not kept. A later import from the same source updates a menu only while it is still exactly as the last import wrote it: it adds the items that now map, in export order, and never doubles one. Where the menu is placed stays as it is. A menu someone changed, or a menu with that key that no import from this source wrote, is kept as it is and listed in the check report and the receipt. Importing the same export again changes nothing. Undo goes newest first: undoing the latest import returns the menu to the version before it, and an earlier import cannot be undone while a later one still owns the menu. The menus are not placed: choose where they appear in [Site Chrome](/guides/page-builder/#site-context).

Undo removes the menus first, then comments (replies before the comment they answer), then posts, pages, terms, people and media. A menu that is placed, was changed after the import, or was updated by a later import that is not undone is kept and listed.

## Cut over or stop

On the disposable destination, verify representative public pages in every required locale, access to private models, media bytes and URLs, and explicit withdrawals. Agree a final source-edit freeze and final export with the operator before a production cutover. Route traffic only after the complete verification set passes. Keep the source service and destination backup intact until the owner accepts the result.

A failed or partial migration is not a successful cutover. Rollback requires the retained deployment/database/media state, not a second import that guesses the prior state. Follow [backup and restore](/guides/backup-restore/). Native site-bundle copy and CSV/XLSX transfer are different workflows. A site copy uses new IDs and is not a full restore. Neither a site copy nor a history file carries planner plans, runs or queue items; drafts the planner saved travel as ordinary entries.

Authorities: `backend/src/lib/import/`, `backend/src/lib/import/bundle-handlers.ts` and `frontend/src/routes/settings/components/data-transfer/`. No command here modifies a provider or production system automatically.

## Connected WordPress acquisition

Choose WordPress, name the source and select the destination. On **Import from WordPress**, choose **Upload export file** or **Connect to WordPress**. To connect, enter the HTTPS site address, WordPress username and application password. Failed attempts show the reason and keep credentials for retry; successful acquisition clears the password. Credentials stay in browser memory and never enter WXR or migration artifacts. Each request reads one page of the WordPress API, at most 50 rows. Cross-origin redirects are refused.

Acquisition reads REST-exposed posts, pages, custom types, taxonomies, users, comments, media and available menu endpoints. Original editable post content goes into WXR, then follows ordinary upload, preparation, review, mapping, check, import, receipt and undo. Limits: 8 MiB snapshot, 200 requests, 100 pages per resource, 64 resources, 2 MiB per REST response. Missing pagination or required logo/icon media stops acquisition. REST-hidden data is not acquired; review lists omissions.

**Site configuration** review shows title, tagline/SEO description, logo, icon and supplied indexing preference. Replacement is off by default. Select the explicit replacement option to apply the reviewed values; the destination configuration revision guards against concurrent changes. Theme files, arbitrary WordPress options and unavailable plugin settings are outside supported configuration.

Configuration application requires both import authority and `site:settings`. It creates an accepted Site Chrome version with the import receipt in the same guarded write. Re-import changes only configuration still owned by the source receipt; a concurrent destination edit blocks replacement. Undo follows receipt ownership and restores the previous configuration rather than overwriting later edits. Logo/icon references resolve to imported destination media; the managed and generated renderers use the accepted branding and favicon. If WordPress supplies no indexing preference, the destination preference stays in place. Time zone, theme code, arbitrary options and plugin settings are not transferred by this configuration choice.

Native bundle format 1.16 carries entry-folder trees and current placements; history format 3.1 also carries separate placement history with source actor labels. IDs are remapped to destination entries/folders. Receipt-owned undo removes imported placement effects and keeps later local changes. Current readers require these formats, including `entry-folders.json`; older files must be exported again from a matching source.

## Reusable links inside rich blocks

Site-copy format 1.16 and history format 3.1 require `rich-relations.json`. The counted, checksummed
inventory identifies source reference positions inside nested and repeatable rich blocks and private
snippets. Import creates the destination entries first, then remaps those references to destination IDs.
Missing current targets block Check or Apply. Excluded older-history targets use the existing named
dropped-relation finding. Plugin installations, grants and credentials are not copied.

`export_rich_relation_schema_unavailable` means a stored block has no matching source declaration.
Restore the matching declaration on the source and export again. The stored block stays untouched.
The destination's declaration never decides which source strings are references.

<!-- dee-wan-docs page: /guides/backup-restore/ -->

# Backup and restore runbook

Source: https://dee-wan-docs.pages.dev/guides/backup-restore/

This is an operator runbook, not a built-in disaster-recovery service. The repository does **not** provide a one-command full CMS backup/restore. A native site-bundle copy is not a restore: it copies supported current content with new IDs, not the installation's complete historical and account state. A [history transfer](/guides/import-migration/) adds kept versions and workflow events, but it also uses new IDs and carries no accounts, credentials or audit log, so it is not a restore either.

## Define the recovery set

Record the exact CMS source revision, migration history, deployment bindings and a mapping from every site ID to its content database and media storage. Include the control database and every assigned content database, not only the currently selected site. Keep configuration and secret recovery material under the deployment owner's existing secure process, separate from content exports.

A database backup alone does not preserve the media files. Retain the referenced R2 objects or Cloudflare Images assets and the identifiers needed to serve them. Include generated repositories and owned code when recovering detached backends. A published snapshot intentionally omits drafts, CMS accounts and version history and cannot replace a CMS backup.

## Capture a consistent backup

Arrange a pause in writes with the operator, including scheduled publishing, imports and other processes that write data. Capture each database using the provider's supported consistent export/backup facility, or a SQLite backup operation for local databases. Do not copy a live SQLite file while ignoring its WAL. Record when each part was captured and protect the matching media and configuration set before resuming writes.

Verify that exports are readable and nonempty, that every expected database/site is represented, and that media references resolve to retained bytes. Store a protected inventory with checksums. Retention periods and provider-specific export/restore commands are not established by this source snapshot. The deployment owner must verify those against the actual account before relying on a backup.

## Restore into isolation first

Use a separate, explicitly authorized environment. Restore matching database, migration, configuration and media state without binding the restored installation to another site's live database. Keep cron jobs, outbound webhooks and build delivery disabled until review: restored pending work may otherwise repeat effects in external systems. Do not assume old sessions or old external credentials should be reactivated.

Start the matching source revision and verify database migrations before any upgrade. Then check administrator access, site ownership, roles, private-model refusals, model definitions, drafts, published versions, translations, relations and media. Compare per-site/per-model counts and representative records to the retained inventory. A successful SQL import alone is not successful recovery.

## Cutover and rollback

Obtain owner acceptance before routing production traffic. Keep the previous environment and recovery set intact until the restore is accepted. Re-enable background processes that write data and delivery to external systems only after reviewing pending jobs and checking how they handle repeated requests. For detached deployments, also run the [deployment and media verification steps](/guides/detachment/).

Authorities and boundaries: `backend/src/lib/import/bundle-handlers.ts` explicitly implements copy, not native restore. `backend/src/lib/graduate/source-db.ts` uses a SQLite backup operation. `scripts/d1.ts` contains guarded D1 export behavior. Do not use a destructive teardown command merely to obtain a backup. See [migration](/guides/import-migration/) for source-system cutover.

<!-- dee-wan-docs page: /guides/managed-templates/ -->

# Site templates

Source: https://dee-wan-docs.pages.dev/guides/managed-templates/

A managed template is the design used to render a managed site. You make candidates, preview them
privately, and accept one. Settings → Source & delivery → **Site template** provides these controls. It is
part of the admin: there is no separate frontend setup. Making, uploading and previewing a candidate
need an operator-run build host and a private R2 bucket. Delivering a release needs an operator-run
deployment service (see [Delivering releases](#delivering-releases)).

## Make a candidate

- **Generate with AI.** Describe the look. The model writes a template from the site's accepted
  brief, theme and chrome.
- **Upload template source (developers).** A JSON file `{ "manifest": …, "source": [ … ] }`.

Both go through the same checks: source rules, offline install from the pinned lockfile, type
check, build, page-contract fixtures, accessibility, and 390- and 1440-pixel viewport widths. The source rules
also refuse what generating the standalone backend could not export later: two file paths that differ only in letter case,
a file under a `dist` or `node_modules` directory, and text with an unpaired surrogate. A candidate is
stored only when every check passes. Its source, compiled output and check report go to template
storage, each under a key for this site and candidate, written once.

A candidate never serves public traffic.

## Preview privately

Choose a page: one of your saved pages, or a fixture (ordinary, long, sparse, no images, error).

- The preview service receives exactly the chosen page and its title and locale, plus the published
  entries below. It receives no other site content. A build request carries no customer content at all.
- A page with **Latest entries** sections also carries their published entries. The admin reads
  each section's list through the public published projection, with the section's exact mapping and
  limit, before it sends the request. The preview service serves only those answers to the
  candidate, at the exact public list path the candidate requests; any other request gets 404. The candidate
  has no network access or credentials. A refused list stays refused: the candidate draws that
  section's error, never an empty list. Fixtures and pages without such a section carry no entries.
- One request carries at most 24 lists, each at most 256 KiB and all together at most 1 MiB. A
  larger request is rejected before anything is rendered.
- The page and its entries are used for that request only. They are not stored, logged, cached,
  put in a URL or repeated in an error, and the service removes its workspace after every result.
- The admin applies a strict display policy to the candidate's HTML: no scripts, frames, forms or
  base links, images only from the page's own recorded media origins and the recorded cover origins
  of the carried entries, no referrer. The preview frame is fully sandboxed.

A candidate built against a page contract different from the one embedded in this admin is not previewed
(`template_contract_outdated`): build a new candidate.

## Accept

Accepting re-reads the candidate's three stored files and checks their keys, lengths and digests,
re-runs the source rules, and requires a report bound to this site, candidate and build with every
check passed. The candidate must be built against the page contract this admin embeds; otherwise acceptance is
refused: rebuild it. If another template was accepted since the screen loaded, accepting refuses with
`stale_document`: reload first. Then it chooses the candidate for a later managed release.

Accepting is not activating. It deploys nothing and changes no public page.

## Registered sections

A developer can register typed page sections in an uploaded template. The
manifest lists them under `registered_sections`:

```json
"registered_sections": [
  {
    "definition": {
      "key": "team-grid",
      "label": "Team",
      "description": "People with a photo, a name and a role.",
      "variants": ["grid", "list"],
      "props": [
        { "name": "intro", "kind": "multiline", "label": "Introduction", "required": false },
        { "name": "members", "kind": "list", "label": "Members", "noun": "Member", "min": 1, "max": 12,
          "item": [{ "name": "name", "kind": "text", "label": "Name", "required": true, "max": 80 }] }
      ]
    },
    "component": "src/template/registered/Team.astro"
  }
]
```

- A prop is `text`, `multiline`, `link`, `media`, `toggle`, `choice` (2–12 options) or a `list` of
  those. The editor builds its fields from this; `heading` is reserved for each section's own heading.
- The component lives under `src/template/registered/` and imports nothing but the page contract
  (`../../lib/page-contract/…`), so an exported site can carry it alone. It receives
  `{ props, variant, layout, level, appearance }`, where `props` is `{ heading, fields }`.
- It goes through every check a template does: source rules, offline build, type check and
  accessibility. A form inside a section uses the platform form component, never `<form>`.
- Each registered section is identified by the SHA-256 of `{ definition, source }`. The managed worker
  renders a section only for the exact identifier its page pins; any other pin is a page error.

**Before you accept**, `GET /api/managed-templates/candidates/:versionId/sections` (`site:infra`)
lists, for each key, the version accepting would give it, how it differs from the newest promoted
version (`new`, `unchanged`, `compatible` or `breaking`, with reasons), and how many saved or
published pages still pin an older version.

**Accepting** (`site:deploy`, nothing else) promotes every registered section to an immutable
version: a new address gets the next version number of its key, and an address the site already
holds keeps its version. Accepting refuses with `section_pins_stranded` when a saved or published page
pins a version the candidate no longer includes: keep that component in the template until those
pages move to a newer version (the editor's **Update section**). Activating or rolling back a release
refuses with `published_pages_pin_missing_sections` for the same reason, and publishing a page whose
pin the active template does not draw refuses with `renderer_capability_exceeded`.

Promoted versions are never rewritten or deleted: a registered section's record stays. The template
manifest may list one definition twice when the component files differ, which is how a component
keeps an older version beside its newer one. A component made from a page section is a candidate of
this kind; its builds are cleaned up after 90 days when nothing references them (see
[Reusable components](/guides/page-builder/#reusable-components)). Nothing else is removed by a clean-up.

## Images in a template

A template draws every recorded image through the platform component
`src/runtime/Image.astro` (`<Image media={props.media} alt={…} />`), never its own `<img>`. It
applies the slot's crop and focal point, the image sizes the published read carries, and the
release's transform hosts, with the same rule a generated site uses. The theme keeps its own box
shape: the component sets only width, height, `srcset`, `sizes` and the focal `object-position`.
An image whose size is unknown gets no dimensions and no `srcset`.

Transform hosts are an installation setting: `MANAGED_IMAGE_TRANSFORM_ORIGINS`, a comma-separated
list of https origins whose Cloudflare zone has Image Transformations enabled. Every release
prepared after it is set names them in its `MANAGED_RELEASE` variable. Without it every image keeps
its original URL. A portable export leaves the hosts out; add them to your own deployment.

## Files in a template

A media item that may be a document, audio or video is drawn through the platform component
`src/runtime/MediaAsset.astro` (`<MediaAsset media={item} />`). Audio and video play with their own
controls and a download link; a document is a link naming its type and size, for example
"Menu (PDF, 1.2 MB)"; an image is a plain `<img>`. The kind comes from the item's `mime_type`. Pages
allow audio and video from the same hosts as images (`media-src`). A generated site carries the same
component at `src/components/MediaAsset.astro`.

## Forms in a template

A template maps the `form` section type like any other. Its component
places the platform component `src/runtime/Form.astro` with the props it receives and the `form` view
the runtime passes (`<RuntimeForm fields={props} view={Astro.props.form} />`). The platform component
draws the fields and every state, and posts to the site's intake at `/v1/interactions/form.submit`
as an ordinary form. The managed worker's policy allows `form-action 'self'` for this; it still
allows no script. Previews and unsaved working-document renders draw forms disabled.

## Menus in a template

A template's shell places the platform components `src/runtime/SiteNav.astro` (the menu placed at
the top of every page) and `src/runtime/SiteFooter.astro` (the menu placed at the bottom, and the
footer note). They take no props: the page reads `/v1/_chrome` for its language on every request
and they render the returned menu data, so a menu change or a moved page needs no new release. One isolate
reuses an answer for at most 30 seconds. When the read fails, or nothing is placed, they draw
nothing and the page still renders. An item whose page is not live is left out; an item whose own
page is not live but has items under it is a heading. Each language has its own menu items; a
language without its own version shows the one the site's fallback rule serves, and the components
mark it with that language's `lang`. The built-in shell places both. Working document renders draw
no menus.

## Regions in a template

A manifest may declare regions: `"regions": [{ "key": "sidebar", "label": "Sidebar" }]`. It declares
1 to 8, each with a unique key (letters, digits, `_` and `-`, up to 64 characters) and a plain label
of up to 60 characters; anything else is refused with `invalid_template_manifest`. The shell places
the platform component `src/runtime/SiteRegion.astro` (`<SiteRegion region="sidebar" />`) where each
region belongs. The CMS invents no positions. The page reads `/v1/_chrome` on every request, so a
region change needs no new release. Items draw in order: a shared section (through the template's
own section components, never with an `h1`), a menu, a search form, recent posts, categories, tags
or **Posts by month**. A shared section's Latest entries render the entries `/v1/_chrome` contains for
them, using the same read rules as the public list; one that could not be read draws its refusal. **Posts by
month** links the 30 newest posts at most, in 12 months at most, and never a month address. A
region that shows nothing draws nothing. The built-in template declares `page_start` and
`page_end`. Saving a changed region the accepted template does not declare is refused with
`unknown_region`. **Preview** of a candidate draws a saved page with the candidate's own declared
regions over the accepted Site Chrome; the accepted template and the live regions do not change.
A synthetic preview page carries no regions.

## Use the built-in template

**Use built-in template** makes the platform's released built-in template live in one action. Nothing is built
and nothing needs review: the platform release pipeline already built it in the pinned sandbox and
recorded every check (see [Releasing the built-in template](#releasing-the-built-in-template)).

1. **Accept.** The admin re-reads the released source, compiled output and check report from template
   storage and checks their lengths, digests, the exact built-in source and the report. It copies them
   byte for byte under a new candidate of this site and accepts that version. Using it again reuses
   the site's copy.
2. **Prepare and activate.** When the site can be delivered (see
   [What delivery needs](#what-delivery-needs)), the same action prepares a release for the site's
   address and activates it, through the ordinary **Prepare release** and **Activate** actions with all their
   checks. A release that already pins exactly this is reused; one already live is left alone.

When delivery is not set up, or the site has no active address, it stops after step 1 and names what
is missing. When prepare or activate fails, the built-in stays accepted, the live site keeps its
release (or, when the outcome is unknown, **Check deployment** settles it), and the screen says which
step failed. Continue with **Prepare release** or **Activate**.

Before anything changes, it refuses with `platform_template_unavailable` when no built-in is released
in this admin, the release was made for another page contract, toolchain or built-in source, or its
files are not in template storage as released; with `stale_document` when another template was
accepted since the screen loaded; and with `section_pins_stranded` when saved or published pages pin
a custom section the built-in does not draw.

## What each action needs

| Action | Permission | Settings |
| --- | --- | --- |
| Review | `site:infra` | none; without `TEMPLATE_ARTIFACTS`, files show as unchecked |
| Preview | `site:infra` | `TEMPLATE_PREVIEW_SERVICE_URL`, `TEMPLATE_PREVIEW_SERVICE_KEY`, `TEMPLATE_SANDBOX_IMAGE`, `TEMPLATE_ARTIFACTS` |
| Upload | `site:deploy` | `TEMPLATE_BUILD_SERVICE_URL`, `TEMPLATE_BUILD_SERVICE_KEY`, `TEMPLATE_SANDBOX_IMAGE`, `TEMPLATE_ARTIFACTS` |
| Generate | `site:deploy` and `ai:generate` | everything Upload needs, plus a configured inference connection ([Inference provider](/guides/local-development/#inference-provider)) |
| Accept | `site:deploy` | `TEMPLATE_ARTIFACTS` |
| Use built-in template | `site:deploy` | `TEMPLATE_ARTIFACTS` holding the released built-in; going live also needs everything in [What delivery needs](#what-delivery-needs) |

A setting counts as unset when:

- a service key is shorter than 32 characters;
- a service URL is not a bare `https` origin (no path, query, fragment or credentials); `http` is
  accepted only on `localhost`, `127.0.0.1` or `[::1]`;
- the sandbox image is not pinned by digest.

A missing dependency disables only the actions that need it, and the card names what is missing
beside each one. Such an action refuses with `503 template_operation_unavailable` and
`{ operation, missing }`, naming what is missing and never a value, before anything is read or
written. A build or preview service outage never blocks accepting.

Generating also needs the site's generation model: generation is refused if the provider no longer offers that model
(choose another in Settings → Generation). An unreadable model list does not block generating: the
site's model is used unchecked, and the candidate's provenance records that it was not checked.

## When the answer is lost

If generating, uploading or accepting gets no answer, or an answer the screen cannot read, the
action may have happened. The card says so, keeps what you see, and offers **Reload**. It never
repeats the action by itself. Switching sites or closing a review drops any answer still on its
way.

## Releases

A release pins an accepted template, the route map, theme and chrome, and the site's canonical
origin. Its states are `proven`, `active` and `retired`.

The pinned chrome's SEO defaults (title template, site description, default social image, who runs
the site and the search-engine verification codes) reach the renderer in `MANAGED_RELEASE` as `seo`,
only when they differ from the defaults. The Worker adds the page's search and sharing tags
(description, Open Graph, Twitter card, robots, verification codes and one `application/ld+json`
structured data block) to the template shell's `<head>`; the shell still draws the title and
canonical link it is given. The data block is never executed, so the release's content security
policy neither blocks nor reports it. A page's own overrides come from its published version at
request time.

Redirects are not pinned: when an address a route template (or the Blog post address) resolves has
no published item, the renderer reads the accepted rules from `GET /v1/_redirects`. A move answers
301, 302, 307 or 308 with its location; 410 and 451 answer the error page with that status. So does
a well-formed path no route template matches, such as an old URL from a previous site. Exact rules
win over patterns, and the pattern with the most fixed parts wins over the others. A malformed path
(one that does not decode, or holds an encoded slash, backslash, control character or dot segment)
gets no lookup. Each Worker instance keeps the list for up to 30 seconds.

`/robots.txt`, `/sitemap.xml` and `/sitemap-<model>-<number>.xml` are answered from
`GET /v1/_sitemap` and its chunks at request time, so a publication reaches the sitemap without a
release. A portable export carries the pinned Site Chrome as `release/site-chrome.json`;
both verifiers check it against the release pin and rebuild `MANAGED_RELEASE.seo` from it.

Site template prepares, activates and rolls back releases. See
[Delivering releases](#delivering-releases).

`GET /api/sites/:siteId/managed-renderer/releases` lists releases and their history. It needs
`site:infra`.

Accepting a template deploys nothing. Publishing content never rebuilds the renderer.

### Canonical origin

A release's origin is `https://` plus the host of the site's **active** control-plane binding. The
site's domain setting, the request `Host` header and request bodies are not authorities. A site
without an active binding (shared mode) has no canonical origin, so it cannot have a production
release. The release digest covers that origin, so a host change needs a new release.

The product flow is **Change address**. It proves a candidate host before moving traffic, switches
the binding, route and release atomically, and keeps the prior binding for seven-day one-action rollback.
A failure leaves the old address active. A change is refused with `provider_state_conflict` when the provider
state no longer matches the recorded live site; do not tear down the working site.

### Change address

Settings → Source & delivery → **Site template** → Releases shows the site address. A live site (one
release active) offers **Change address**. Each step needs `site:deploy`; reading needs `site:infra`.

1. **Enter the new address.** A bare host (`shop.example.com`) or `https://shop.example.com`. It must be
   a public host that no other site uses as its domain, binding or previous address.
2. **Check address** (`POST /api/sites/:siteId/managed-renderer/address/prove`, `{ "host": … }`). The
   deployment service reads the host's routes; a foreign `<host>/*` or `<host>/v1/*` route refuses
   (`provider_route_conflict`), and so does a host outside the allowed zones
   (`host_outside_allowed_zones`). Then the accepted template is uploaded as a new version whose
   release is pinned to `https://<new host>`, and the identity its Version URL serves is proven. The
   result is a prepared release for the new address. No route is created and the live host keeps its
   release.
3. **Switch address** (`POST …/releases/:number/switch-address`, `{ "observed_active_number": … }`).
   The deployment service (`move-host`) checks the current host still serves the live version on its
   own catch-all, creates `<new host>/v1/*` and `<new host>/*` when absent, gives the new version 100%
   and reads the identity at `https://<new host>`. Dee Wan proves it, then writes one control-plane
   batch: `site.domain`, `site_binding.host`, the router's completion marker and the renderer record
   (new host, zone, routes, live version) with the old host kept as the previous address. Then the
   release transition commits. A wrong identity, a lost race, or another site taking the host first
   puts the old version back, removes a catch-all the switch created, and keeps the old host active.
4. **Go back** (`POST …/address/rollback`, `{ "observed_active_number": … }`) for seven days after the
   switch. The old host's routes were kept, so it is the same move in reverse: the old release on the
   old host, one control-plane batch, one release transition. After seven days it refuses with
   `address_rollback_expired` and its deadline; nothing changes.
5. **Remove address** (`POST …/address/remove-previous`) deletes the previous host's recorded
   `<host>/*` route through the deployment service, confirms none is left, and forgets the previous
   address. Its `/v1/*` route is the shared public Worker's and stays. Use it after going back, after
   the seven days, or earlier to give up going back. A new Change address waits until the previous
   address is removed (`address_change_retained`).

During the seven days the old host still reaches the renderer. It serves the new release, whose
canonical links name the new host; its own `/v1/*` reads stop, because the public router follows the
binding.

A lost answer leaves the step unresolved, like any release change: **Check deployment** finishes it
from what the provider shows. Once the control-plane batch has committed, Check deployment only goes
forward (release transition, then the site row in the site's own database); it never moves traffic
back.

The site's general settings no longer rename a site whose managed renderer serves or keeps a host:
`PATCH /api/sites/:id` with a new domain answers `409 managed_address_change_required`.

## Delivering releases

Site template prepares, activates and rolls back a site's managed renderer. A separate,
product-owned Node service does the Cloudflare work: the managed renderer deployment service. It
holds the Cloudflare API token. The admin Worker never does.

### What delivery needs

All of the following settings are required. Without any one, **Prepare release**, **Activate** and **Roll back** stay unavailable,
and Settings lists what is missing.

- `MANAGED_RENDER_DEPLOY_SERVICE_URL` (var): the service's `https` origin, no path. `http` only on
  `localhost`, `127.0.0.1` or `[::1]`.
- `MANAGED_RENDER_DEPLOY_SERVICE_KEY` (secret, 32+ characters): signs every request to the service
  and checks every receipt. The service holds the same value.
- `MANAGED_RENDER_INSTALLATION_ID` (var, not secret): lower-case letters, digits and hyphens, 3 to 63
  characters. Each site's renderer Worker name (`dee-wan-r-<32 hex>`) is derived from it and the site
  id. Never change it after a first release.
- `MANAGED_RENDER_HMAC_KEY` (secret): the admin derives a per-site key from it and sends the service
  only that site's derived key with each prepare. The service never receives this master key.
- `TEMPLATE_ARTIFACTS`: the compiled artifact is read from here.
- An active site binding (per-site database host) for the site.
- The admin Worker's `global_fetch_strictly_public` compatibility flag. The editor's exact preview
  goes from the admin Worker to a `*.workers.dev` Version URL on the same account. Without the flag
  Cloudflare answers that request with error 1042. Setup adds the flag to `backend/wrangler.jsonc`
  beside `nodejs_compat` and keeps any other flags. The public Worker does not get it: its config is
  derived without it, because it makes no such request.

Do not set `CLOUDFLARE_API_TOKEN` on the admin Worker.

### The deployment service

```
npm run managed-deploy-service
```

Run it on a trusted host. It refuses to start when any required setting is missing or invalid. It
reads its secrets once and removes them from its environment. It never logs request bodies,
artifacts, keys, tokens or receipts.

| Setting | What |
| --- | --- |
| `CLOUDFLARE_API_TOKEN` | Secret. Permissions below |
| `CLOUDFLARE_ACCOUNT_ID` | The Cloudflare account id |
| `MANAGED_RENDER_ALLOWED_ZONE_IDS` | Comma-separated zone IDs, 32 lower-case hex each, that the service may create routes in |
| `MANAGED_RENDER_PUBLIC_WORKER_SCRIPT` | Name of the shared public read Worker, e.g. `dee-wan-cms-public`. It must own `https://<host>/v1/*` |
| `MANAGED_RENDER_INTAKE_WORKER_SCRIPT` | Optional. Name of the form intake Worker, e.g. `dee-wan-cms-intake`. When set, activation also attaches `https://<host>/v1/interactions/*` to it; a route there owned by another script is refused (`intake_route_conflict`). Unset, website forms on managed sites take no submissions |
| `CLOUDFLARE_WORKERS_SUBDOMAIN` | The account's workers.dev subdomain (`<sub>` in `<sub>.workers.dev`). A Version URL Cloudflare returns must sit under it, or the version is refused |
| `MANAGED_RENDER_DEPLOY_SERVICE_KEY` | Secret, 32+ characters. The same value as the admin's |
| `MANAGED_RENDER_DEPLOY_SERVICE_AUDIENCE` | This service's own origin, exactly as the admin's `MANAGED_RENDER_DEPLOY_SERVICE_URL` names it |
| `MANAGED_RENDER_INSTALLATION_ID` | The same value as the admin's |
| `MANAGED_RENDER_DEPLOY_SERVICE_HOST`, `MANAGED_RENDER_DEPLOY_SERVICE_PORT` | Optional. Default `127.0.0.1`:`8791` |

The service reads each allowed zone's real name from Cloudflare. It picks the one zone whose name
equals the site host or is a dot-suffix of it (`example.com` for `www.example.com`). The operation is refused if no zone or
more than one zone matches.

Minimum token permissions:

- Account → Workers Scripts: Edit (covers Read);
- Zone → Workers Routes: Edit, for each allowed zone;
- Zone → Zone: Read, for each allowed zone.

The service must reach each site's `https://<host>` and the `*.workers.dev` Version URLs over the
public internet. It reads renderer identities there itself.

A prepare can take up to 4 minutes and an activation up to 2. Do not put the service behind a proxy
that ends requests sooner (Cloudflare's own proxy ends them at 100 seconds).

### Cloudflare API it uses

The service uploads with Cloudflare's **beta Workers API**. Cloudflare's direct-upload guide for
static-asset Workers uses it. Only `cloudflare-provider.ts` calls it.

- Beta Worker and version paths take the Worker's immutable **id**, never its name. The service
  finds or creates the Worker by name once, checks the name is the site's `dee-wan-r-<32 hex>`
  script, and from then on uses the id. Dee Wan stores the id in the control-plane provisioning
  record and with each release. Any mismatch between the stored id, the id Cloudflare answers, the
  script name and the site causes the operation to be refused.
- Script settings, asset upload sessions, deployments, routes and deletion use the script name.
- Each upload is tagged with its operation id in the `workers/tag` annotation, so a retried
  operation finds its version instead of uploading again.
- Static assets are hashed as Cloudflare documents: SHA-256 of base64(file bytes) plus the file
  extension, first 32 hex characters.
- Each version gets a `PUBLIC_API` service binding to `MANAGED_RENDER_PUBLIC_WORKER_SCRIPT`.
  The target comes only from the service's own setting. The version gets no public-transport
  variable and no compatibility flag.
- An operation-version lookup and a Worker lookup page through Cloudflare's lists. Each answers,
  found or absent, only after an empty page. Reaching the page bound first (5 pages of versions,
  50 of Workers) answers unknown, so a Worker with more versions than that cannot prove absence and
  reconciliation remains unresolved. Two matches are unknown too.

### Version URLs

Dee Wan never builds a Version URL. Cloudflare returns a version's routable URLs; the service takes
exactly one that is `https`, has no credentials, port, path, query or fragment, sits under
`CLOUDFLARE_WORKERS_SUBDOMAIN`, and names the site's script in its host. None or more than one
refuses the version.

The service names the account subdomain in its signed prepare answer. The admin stores it in the
control-plane provisioning record (`provider_workers_subdomain`). An existing record must name the
same subdomain, or the prepare stays unresolved. At render time the stored Version URL must be a
bare `https` origin that names the release's script under exactly that recorded subdomain. A
subdomain read from the site's release row alone is never trusted.

The URL is stored with the release as internal provider state. It is never shown in the browser,
never in a release summary, and never used as the site's public address.

### Where identities are read

A Worker cannot call another Worker routed on its own zone with a plain `fetch`. So:

- **The deployment service reads renderer identities.** It fetches
  `/.well-known/managed-release.json` from the version's Version URL (prepare) or the site's
  canonical address (activate, roll back, reconcile). Fixed path, `https`, no redirects, 5 s
  timeout, at most 64 KiB, exactly HTTP 200, exactly one JSON object. It retries for about half a
  minute while a new version or deployment reaches the edge, then answers the raw identity inside
  its signed, receipted answer. It does not decide whether the identity is right.
- **No answer is not a wrong answer.** When no identity could be read, the operation stays
  unresolved for **Check deployment**; nothing is rolled back for it. A wrong identity during
  activate or roll back is rolled back. A prepare whose version reports a wrong identity closes as
  refused (`renderer_proof_failed`); that version stays uploaded and serves no traffic.
- **The admin decides.** It compares the observed identity with the site, release digest and
  renderer-contract digest it derived from its own records. The proof always names the canonical
  address. The browser never supplies identity or proof.
- **The renderer reads content through `PUBLIC_API`.** Published pages, previews and preview
  attestations go through the service binding to the public Worker. The request URL is still the
  canonical `https://<host>/v1/...`, so host and site routing do not change. Plain `fetch` is used
  only for a local loopback build, or for a generated standalone backend that selects public transport (see
  [Exported Worker configuration](#exported-worker-configuration)). A managed version without the
  binding never falls back to `fetch`: those reads answer 503.
- **Identity and the exact preview need no `PUBLIC_API`.** `/.well-known/managed-release.json`, the
  renderer contract and the signed working-page render answer from `MANAGED_RELEASE` alone. The
  signed render still checks audience, release digest, body digest, expiry, site, page, locale and
  baseline, persists nothing and calls no public API.
- **The editor's exact preview goes to the Version URL.** The admin sends the signed render request
  to the active release's stored Version URL. The envelope's audience, the frame's base and the
  release identity stay the canonical address. It also checks that the release, the provisioning
  record and the installation name the same script, Worker id and live version, and that the URL
  sits under the recorded workers.dev subdomain. This request needs the admin Worker's
  `global_fetch_strictly_public` flag. A release prepared before Version URLs were stored has no
  exact preview until a new release is prepared.

### Routes on the site host

```
https://<host>/v1/interactions/*  -> shared form intake Worker (MANAGED_RENDER_INTAKE_WORKER_SCRIPT, when set)
https://<host>/v1/*               -> shared public Worker (MANAGED_RENDER_PUBLIC_WORKER_SCRIPT)
https://<host>/*                  -> the site's renderer Worker (dee-wan-r-<32 hex>)
```

These are Workers routes, not a Custom Domain. The more specific `/v1/*` route wins. The service
creates the `/v1/*` route when it is absent and refuses when it belongs to another script. It never
overwrites or deletes a route it does not own.

A host that the public Worker serves as a Custom Domain cannot also carry these routes. For a
managed site, attach the public Worker to the host by the `/v1/*` route instead. See the `routes`
comment in `backend/wrangler.public.example.jsonc`.

Every renderer Worker has workers.dev disabled and Version URLs (preview URLs) enabled.

After a Change address the previous host keeps its two routes until **Remove address**; the control
plane records its catch-all as the previous address.

### Prepare, activate, roll back

- **Prepare release** uploads the accepted compiled template as a new Worker version with no
  traffic. The service reads the identity its Version URL serves; the admin checks it and stores a
  prepared release.
- **Activate** gives that version 100% of traffic. The first activation also creates the catch-all
  route. The service reads the identity at the site's own address; the admin checks it, marks the
  release live, then records the live version in the control plane.
- **Roll back** re-deploys an earlier release's existing version. Nothing is rebuilt.

Only one release operation runs per site at a time.

### When the outcome is unknown

If the identity check or the site database update fails after traffic moved, Dee Wan moves traffic
back, or removes a route it just created, and verifies that.

Marking the release live and recording it in the control plane require writes to two databases. The site database
commits first and the operation stays open (`tenant_committed`). It closes only after the control
plane record reads back exactly the live version, deployment and routes. If that write fails, the
operation stays unresolved and release actions stay blocked. **Check deployment** then confirms the
release is active, the provider serves it on the owned routes and the site reports its identity,
repairs the control-plane record and closes the operation. It never moves the release again and
never moves traffic back for an operation in this state.

Every provisioning record write is read back. A write that changed nothing does not count.

If the outcome cannot be established, the operation stays unresolved and every release action for
that site is blocked. Settings then offers **Check deployment**. It finishes the operation, closes
it, repairs the record, or moves traffic back, as the provider state shows.

**A signed prepare answer means a version exists.** After the service answers a prepare, a script or
Worker mismatch, a bad Version URL or subdomain, a failed provisioning-record write or read-back, a
missing identity, or a failed release write leaves it unresolved. That keeps the next prepare from
uploading another version beside it. A version whose identity was read and is not this release closes
the operation as refused (`renderer_proof_failed`): the version stays uploaded, serves no traffic and
never becomes a release. **Check deployment** closes a prepare as refused when the service's lookup
reached an empty page and found no version tagged with the operation (or no renderer Worker), or when
the version exists and reports a wrong identity. When the version exists but its identity, ownership
or storage cannot be confirmed, the operation stays unresolved. Dee Wan never deletes a single version
by itself.

### Removing renderers

**Installation teardown** (`npm run teardown`) removes every recorded renderer before it deletes
the control database, using the operator's own Cloudflare token:

1. It reads `managed_renderer_provision` from the configured control database (the `DB` binding,
   only after the D1 identity check proved it). If managed delivery is configured
   (`MANAGED_RENDER_DEPLOY_SERVICE_URL` or `MANAGED_RENDER_INSTALLATION_ID` set) and the table cannot
   be read, `--apply` refuses.
2. For each record it re-derives the Worker name from the installation id and site id, checks the
   Worker id still names that script, and checks the recorded route's pattern and script. A name
   prefix alone never counts. Any mismatch or unreadable answer refuses `--apply`.
3. The dry run lists each recorded renderer route and Worker.
4. `--apply` deletes each recorded catch-all route (the live host's and a previous address's) and
   confirms it is gone, then each renderer Worker and confirms it is gone. Only then are the remaining
   resources deleted, with D1 last. A failed or unconfirmed renderer deletion stops the run before any D1 database
   is deleted.

It never deletes the shared public Worker or any `/v1/*` route.

**Per-site removal.** The admin API has no hard site deletion. The per-site renderer teardown
(`teardownManagedRenderer`, through the deployment service) is ready for that future caller: it
removes a previous address's catch-all first, then deletes only the recorded catch-all route and the
recorded Worker, and keeps the provisioning record when a deletion fails or its result is unknown.

## Admin settings

All optional. Keys are secrets (`wrangler secret put`); the rest are `vars` or bindings.

| Setting | What |
| --- | --- |
| `TEMPLATE_ARTIFACTS` | Private R2 bucket for template storage |
| `TEMPLATE_BUILD_SERVICE_URL`, `TEMPLATE_BUILD_SERVICE_KEY` | Build service origin and its key (32+ characters) |
| `TEMPLATE_PREVIEW_SERVICE_URL`, `TEMPLATE_PREVIEW_SERVICE_KEY` | Preview service origin and its key (32+ characters) |
| `TEMPLATE_SANDBOX_IMAGE` | The sandbox image, `repository@sha256:<64 hex>` only |
| Inference connection | Needed only to generate: DeepInfra with `DEEPINFRA_API_KEY`, or the configured OpenAI-compatible connection with `AI_API_KEY`. See [Inference provider](/guides/local-development/#inference-provider). |
| `MANAGED_RENDER_DEPLOY_SERVICE_URL`, `MANAGED_RENDER_DEPLOY_SERVICE_KEY` | Deployment service origin and its key (32+ characters) |
| `MANAGED_RENDER_INSTALLATION_ID` | Stable installation id; see [What delivery needs](#what-delivery-needs) |
| `MANAGED_RENDER_HMAC_KEY` | Master render key (32+ characters); see [Secrets and the exact working-page render](#secrets-and-the-exact-working-page-render) |

Every build and preview request names the sandbox image; a service running another image refuses
it. Use different keys for build and preview.

## Build and preview service

```
npm run template-build-service
```

One host can serve builds, previews or both: each operation runs only when its key is set
(`TEMPLATE_BUILD_SERVICE_KEY`, `TEMPLATE_PREVIEW_SERVICE_KEY`, 32+ characters). With neither key it
does not start. `TEMPLATE_SERVICE_AUDIENCE` is the host's own origin, the one the admin is
configured with. The host holds no deployment credential.

The service listens on plain HTTP at `TEMPLATE_SERVICE_HOST`:`TEMPLATE_SERVICE_PORT` (default
`127.0.0.1:8790`). The admin calls only `https` origins (except loopback), so put a TLS proxy at the
configured origin. The host runs one operation at a time; another request meanwhile is refused with
`503 service_busy`, not queued.

The host never runs generated code itself. Every build and every preview runs in a fresh container,
and the service refuses to start without all of these:

| Setting | What |
| --- | --- |
| `TEMPLATE_SANDBOX_IMAGE` | Image by digest; a tag is refused |
| `TEMPLATE_SANDBOX_RUNTIME` | Absolute path to `docker` or `podman` |
| `TEMPLATE_SANDBOX_MEMORY_MB` | 512 to 65536 |
| `TEMPLATE_SANDBOX_CPUS` | 0.5 to 64 |
| `TEMPLATE_SANDBOX_PIDS` | 64 to 65536 |
| `TEMPLATE_SANDBOX_TIMEOUT_SECONDS` | 30 to 3600 |
| `TEMPLATE_SANDBOX_WORKSPACE_ROOT` | Absolute, writable directory for per-request workspaces |

Each container runs with:

- the service's own non-root user (the service refuses to run as root);
- a read-only root filesystem, every Linux capability dropped, `no-new-privileges`;
- no network: install, type check, build, fixtures, browser checks and preview all talk over the
  container's own loopback;
- bounded memory, CPU, processes, time and output;
- one fresh workspace directory and a bounded `/tmp`; no home directory, repository or container
  socket mounted;
- no host environment: the host sets only `HOME` and `TMPDIR`;
- no container log; the answer comes back on stdout.

The runtime is started with an argument list, never a shell. After every run the host removes the
container (`rm --force`), confirms with a listing that no container of that name is left, and
deletes the workspace. Each cleanup call has a time limit. When a run times out or overflows its
output, the host kills the runtime client and waits for a limited grace period for it to close; a client that
does not close in time is not counted as stopped. A result, success or failure, is returned only
when the client has been observed closing, the container is confirmed gone and the workspace is deleted;
otherwise the request fails with `sandbox_cleanup_failed`.

### The sandbox image

```
npm run template-sandbox:context -- --out <new dir> --node-image <node@sha256:…>
docker build -t <registry>/<name> <new dir>
docker push <registry>/<name>
```

The context pins the base image by digest, the npm, wrangler, playwright-core and axe-core versions
this checkout uses, the headless Chromium those versions install, and an npm cache holding exactly
the managed worker lockfile. Builds install offline from that cache with install scripts disabled.
The image's cache is read-only, and npm treats a cached package record as missing if it cannot write back to the cache, so
each build first copies the cache into its own workspace and installs from the copy. The copy is
deleted with the workspace. An image built before this change fails every build at `install` with
`ENOTCACHED`; build the image again from a fresh context.
Configure the service and the admin with the pushed digest, never the tag.

**Proving an image on one machine.** No provider is contacted. A local registry gives the image
a digest:

```
docker run -d --rm --name dw-local-registry -p 127.0.0.1:5055:5000 registry:2
docker tag <image> 127.0.0.1:5055/dee-wan-template-sandbox:local
docker push 127.0.0.1:5055/dee-wan-template-sandbox:local
docker inspect --format '{{json .RepoDigests}}' <image>
cd backend
DEEWAN_SANDBOX_IMAGE=127.0.0.1:5055/dee-wan-template-sandbox@sha256:<digest> \
DEEWAN_SANDBOX_RUNTIME=$(command -v docker) \
npx vitest run test/managed-sandbox-real.test.ts
docker stop dw-local-registry
```

The test runs the real service with the real runtime. It builds the built-in template in a
container and requires all seven checks passed and a stored bundle. Then it draws a saved page
whose Latest entries sections are populated, empty and refused. After each run no container may
be left and the workspace must be deleted. Without `DEEWAN_SANDBOX_IMAGE` the test is skipped. A
skipped run proves nothing.

Production does not rebuild the built-in from an admin route. The platform release pipeline runs the
same pinned offline sandbox and checks, stores the immutable artifacts and evidence, and promotes that
exact digest. A new site activates the preaccepted platform version in one action.

### Releasing the built-in template

```
TEMPLATE_SANDBOX_IMAGE=… TEMPLATE_SANDBOX_RUNTIME=… TEMPLATE_SANDBOX_MEMORY_MB=… \
TEMPLATE_SANDBOX_CPUS=… TEMPLATE_SANDBOX_PIDS=… TEMPLATE_SANDBOX_TIMEOUT_SECONDS=… \
TEMPLATE_SANDBOX_WORKSPACE_ROOT=… \
npm run platform-template:release -- --out <new or empty directory>
```

It takes the same sandbox settings as the build service and runs the build service in-process on
loopback, with a key made for this one build. The built-in goes through the candidate build: source
rules, the signed build request, the sandboxed build with every check, and the answer's receipt and
frame checks. Every sandboxed check must name the configured image.

On success it writes the three files once under `<out>/managed/_platform/<candidate>/<role>.json`,
reads them back verified, writes the release record to `<out>/platform-template-release.json`, and
promotes the build by rewriting `backend/src/lib/managed-renderer/platform-template-release.ts`.
Review and commit that file with the release; the admin embeds it. Then copy the three files into the
`TEMPLATE_ARTIFACTS` bucket at exactly their keys; the command prints them. It uploads and deploys
nothing itself.

`_platform` is a reserved partition: site ids never start with `_`. Until a build is promoted the
file holds `null`, and **Use built-in template** stays unavailable.

### The build answer

A build answers one binary frame: small closed metadata (sandbox, toolchain, check results), then
the compiled bundle exactly as template storage keeps it. The admin checks the receipt, the
metadata and the bundle's canonical form, then stores those bytes. Compiled files are not decoded
and encoded again on the way.

The check results are an exact prefix of `install`, `typecheck`, `build`, `contract_fixtures`,
`accessibility`, `viewport_390x844`, `viewport_1440x900`: no repeat, no reorder, no gap, nothing
after a failed check. A shorter list must end on its failed check and carries an empty bundle. A
passed build has all seven at exit code 0 and a non-empty canonical bundle. A passed build with an
empty bundle (compiled output over its limit) is refused as `compiled_too_large`; anything else is
`sandbox_output_invalid`. Nothing is stored in either case. `source_validation` is the admin's own check; the
sandbox never reports it.

## Generating the standalone backend with an active managed release

A site with no active managed release generates its standalone backend exactly as before.

Only whole-site generation for a site with an active release writes `managed-renderer/` (format 2).
Generation reads that release from the CMS copy, re-verifies it, and refuses generation if anything is missing or unreadable, has changed, or belongs to another site:

- the release record, every pin, and the release digest;
- the pinned route map and template version;
- the template's source, compiled output and check report, from template storage, by key, length
  and digest, with every check passed;
- the worker files, emitted again from that source, must match the build's recorded input digest.
  A template built before input digests were recorded, or with another page contract or toolchain
  than this build pins, refuses: rebuild, accept and release it again.

Generation has no access to the R2 bucket. Copy the release's three objects into one directory, each
at its key (`managed/<site>/<candidate>/<role>.json`), and pass it:

```
npm run backend:generate -- --site <id> --source <cms.sqlite> --dest <dir> --db <scratch.sqlite> --template-artifacts <copy>
npm run backend:deliver -- … --template-artifacts <copy>
```

Without it, generation refuses with `managed_release_custody_unavailable` and names the three keys.
The directory and every directory on the way to an object must be real directories, and each object
a regular file; links are not followed.

Limits:

- A `--model` run exports no managed renderer. It still exports the selected model backend.
- `npm run backend:generate:all` cannot pass `--template-artifacts`, so generation for a site with an active release is refused
  by that command. Generate that site alone.
- A verified managed-renderer export has its own 32 MiB total budget. It does not consume the ordinary
  32 MiB GitHub source budget. Every exported file still stays below 4 MiB.

### Exported files

Export format 2 only. There is no compatibility for older export shapes. Every file is stored as raw
bytes, and every file is below the 4 MiB per-file limit of GitHub source delivery.

| Path under `managed-renderer/` | What |
| --- | --- |
| `package.json`, `package-lock.json` | The pinned package manifest and lockfile |
| `astro.config.mjs`, `tsconfig.json`, `public/`, `worker/`, `src/env.d.ts`, `src/runtime/`, `src/pages/` | The managed runtime |
| `src/lib/page-contract/` | The page contract it was built against |
| `src/template/` | The template source and assets |
| `wrangler.jsonc` | The release's portable deploy configuration: the release as `MANAGED_RELEASE`, public transport and `global_fetch_strictly_public` |
| `release/release.json` | Closed record: release number, digest, origin, pins, template identity, chunk list, every other file's length and digest |
| `release/route-map.json` | The complete route map, as pinned |
| `release/site-chrome.json` | The pinned Site Chrome, canonical; the source of `MANAGED_RELEASE.seo` |
| `release/template.json` | The pinned template version without storage keys: manifest, candidate and build identity, provenance, artifact digests and lengths |
| `release/evidence/compiled/NNNN.part` | The compiled artifact as evidence, in chunks |
| `release/evidence/report.json` | The check report, as stored |
| `release/managed-renderer.mjs` | The commands below |

The compiled artifact can be 24 MiB, so it is split in order into raw chunks of exactly 3 MiB (the
last one shorter), with no base64. `release/release.json` records each chunk's order, length and
SHA-256, and the whole artifact's length and digest. Joined in order, the chunks are the exact bytes
template storage holds.

`release/template.json` is not the stored template version: that version also holds storage keys,
which never leave the CMS. The release pins keep the stored version's id and digest as recorded
identity; the repository cannot recompute that digest.

`graduation.manifest.json` pins the export: release number and digest, contract digest, and
`exportDigest`. `release/release.json` is canonical JSON followed by one newline, and its SHA-256 is
`exportDigest`. Every file is in the generated zone and the ownership file.

Never exported: storage keys, render or signing keys, service keys, tokens, environment values,
preview or unpublished content, local paths in the release metadata. The check report goes out byte
for byte as template storage holds it, so its check commands and outputs can name build-sandbox
paths.

### The CMS inspector

The CMS checks an export from its bytes with one inspector. Generation runs it on the export it
composed, and on the staged tree (or, when a replay changes nothing, the destination) before any
database or destination write. On disk it skips only `node_modules`, `dist`, `.astro` and
`.wrangler` directly under `managed-renderer/`, like `managed-renderer:verify`; any other unlisted
file there, such as `.dev.vars`, causes rejection. Source assembly uses the same inspector. It checks format, manifest pin, exact file set with each
length and digest, chunk order, lengths and joined digest, input, source and contract digests, the
check report with exactly the eight checks in order and all passed, the template projection, the
route map, the release digest, `wrangler.jsonc`, and no storage key or local path anywhere in the
release metadata.

Among its refusals:

- `managed_renderer_export_cli_mismatch`: `release/managed-renderer.mjs` is not byte for byte the
  command this product emits. A repository cannot replace its verifier and update the pin to accept that replacement;
- `managed_renderer_export_pin_invalid`: the manifest pin is open (not exactly the closed pin keys);
- `managed_renderer_export_path_invalid`: a `managed-renderer` root spelled in another case, or a
  path that is not a managed renderer path;
- `managed_renderer_export_unpinned`: files under `managed-renderer/` with no pin.

### Regeneration and source delivery

Ordinary managed regeneration keeps the export. It carries the manifest pin into the new manifest
and never writes or deletes a file under `managed-renderer/`; a generator that returned one there
is refused.

In 1.0, source reaches your repository through local CLI generation and ordinary Git. Hosted source
preparation is not available: the CMS's source-delivery build intents refuse with
`source_build_runtime_unavailable` before any provider write. No 1.0 command or screen calls source
assembly.

Source assembly (`assembleSourceArtifact`) takes the export as an explicit input with three states:

- omitted: a verified existing export and its pin are kept, or nothing when there is neither. It is
  kept only when it passes the inspector against the manifest pin and the ownership file records
  each file unedited. Anything else refuses;
- an export: it is installed after the inspector re-derives every identity it claims, in place of
  the old one; old files it does not list are removed. The root `package.json` gains the scripts
  below;
- `null`: the export and its pin are removed, and only the canonical scripts below. On a repository
  that never had an export, `null` changes nothing. Pass `null` only when the site has no active
  managed release.

Source assembly delivers the edited `package.json`.

### Package scripts

The root `package.json` carries three scripts: `managed-renderer:verify`, `managed-renderer:build`
and `managed-renderer:prepare`, each `node managed-renderer/release/managed-renderer.mjs <command>`.

- Adding writes only the scripts that are absent. A present script is never overwritten; one that
  holds another command refuses the add.
- Removing deletes a script only while its value is exactly the canonical one. A script you changed
  is kept.
- Edits are in place. Every other byte is kept: line endings, indentation, a byte order mark and the
  final newline.

The edit refuses with `managed_renderer_scripts_unwritable` (add) or
`managed_renderer_scripts_unremovable` (remove) when `package.json` is missing (add only), is not
UTF-8, is not strict JSON, its root is not an object, `scripts` is not an object, or it names
`"scripts"` or a `managed-renderer:*` script twice. Adding also refuses when one of the three
scripts holds another command; another `managed-renderer:*` script of yours is kept. A removal from
a `package.json` that never names a `managed-renderer:` script changes nothing.

Generation adds the scripts when it writes an export. It removes the canonical ones only when the
previous manifest pinned an export that this run no longer writes. A project that never had an
export keeps its `package.json` byte for byte.

### Commands in the repository

```
npm run managed-renderer:verify
npm run managed-renderer:build
npm run managed-renderer:prepare
```

Run them from the repository root. `managed-renderer/` and `managed-renderer/release/` must be real
directories, not links. None of them contacts the CMS.

- **verify** checks: the manifest format and pin; a closed, canonical `release/release.json` with
  typed fields; that every file under `managed-renderer/`, except build output at its root, is a
  regular file the record lists, and every listed file is present at its length and digest, below the per-file limit,
  at a safe path, once even ignoring case; the chunks rejoining to the compiled digest; the input,
  source and contract digests; a closed check report bound to the release with every required check
  passed in order; `release/template.json` closed, canonical and agreeing; `release/route-map.json`
  canonical, shaped and pinned; `release/site-chrome.json` canonical and pinned; the release digest;
  `wrangler.jsonc` byte for byte; and no storage
  key or local path in the metadata. An export in another format refuses.

  Website or Blog comes from `graduation.manifest.json`, never from `wrangler.jsonc`. verify reads
  only site manifest format 9 and refuses any other format. `"blog": null` accepts only the Website
  config (no `blog` in `MANAGED_RELEASE`). `"blog": {"locales": [...]}` (non-empty, sorted, unique)
  accepts only the Blog config, at the address the route map gives. Any other `blog` value refuses.
  The CMS export inspector applies the same rule against the manifest it writes or keeps, and refuses
  a pinned export under a manifest that records neither.

  verify is narrower than the CMS inspector. It does not re-parse the template manifest, its
  provenance, the route map grammar, the Blog language spelling or the manifest digest; the CMS does
  that when it writes or keeps the export.
- **build**: verify, then clear only `node_modules`, `dist`, `.astro` and `.wrangler` directly
  under `managed-renderer/` (a link there is unlinked, never followed). Then it re-runs install
  (`npm ci --ignore-scripts`), type check and build only, on this machine, with network for `npm ci`.
  It refuses a changed lockfile or another toolchain. It does not re-run the contract, accessibility
  or viewport checks; their evidence is `release/evidence/report.json`. The compiled evidence is
  never unpacked or run.
- **prepare**: build, then package the worker with `wrangler deploy --dry-run` into
  `.wrangler/deploy`. Nothing is deployed.

build and prepare run with `ASTRO_TELEMETRY_DISABLED=1` and `WRANGLER_SEND_METRICS=false`.

### Exported Worker configuration

An export has no product-managed `PUBLIC_API` binding. Its `wrangler.jsonc` therefore selects public
transport explicitly:

- `"PUBLIC_API_TRANSPORT": "public"` in `vars`. The runtime accepts exactly this value. Any other
  value, or none, without a binding answers 503.
- `"global_fetch_strictly_public"` in `compatibility_flags`. The renderer's fetch to
  `https://<host>/v1/...` then leaves through the public internet and reaches the public Worker by
  its `/v1/*` route. Without the flag a same-zone fetch can skip that route.

The target is the canonical origin inside `MANAGED_RELEASE`. There is no other URL setting. The CMS
inspector and verify both check this file byte for byte, so edit neither setting by hand.

The exported `wrangler.jsonc` names no route. Whoever deploys it must serve it at
`https://<the site's active binding host>`, the origin the release was made for. The deploy
workflows still deploy `apps/site`, the detached renderer. They do not deploy, activate or roll back
the managed renderer. In the CMS, that is [Delivering releases](#delivering-releases).

### Publishing and freshness

The renderer reads the site's public API on each request. Publishing needs no rebuild. Renderer
HTML is sent with `cache-control: no-store`.

### Secrets and the exact working-page render

Public pages need no secret. The renderer reads its release from `MANAGED_RELEASE` in
`wrangler.jsonc` (not secret) and its content from the site's public API. Deploying needs your own
Cloudflare credentials, as for the rest of the repository.

The editor's **Site design** draws an unsaved working page through the release. It is offered only
when all of these hold:

- the site has an active managed release;
- the CMS has `MANAGED_RENDER_HMAC_KEY` of 32+ characters;
- the site's active binding host, as `https://<host>`, is the origin the release was made for.

When any of these is missing, the editor shows the Structure preview.

The CMS's `MANAGED_RENDER_HMAC_KEY` is a master key and never goes to a renderer. The CMS signs each
render with a per-site key: HMAC-SHA256, keyed by the master key, over
`dee-wan:managed-render-site-key:1`, a newline and the site id, encoded as unpadded base64url. A site
renderer's `MANAGED_RENDER_HMAC_KEY` must hold that derived key, never the master. Without it the
renderer refuses the working-page render. With each prepare, the admin sends the deployment service
only that site's derived key, never the master.

<!-- dee-wan-docs page: /guides/github-authentication/ -->

# GitHub delivery

Source: https://dee-wan-docs.pages.dev/guides/github-authentication/

Choose credentials for the operation you need to run. The authentication methods in these workflows are not interchangeable. This matrix describes repository behavior, not a hosted GitHub App service supplied by Dee Wan.

## Workflow matrix

| Workflow | Authentication and prerequisites | What persists |
| --- | --- | --- |
| Admin sign-in and first-admin claim | Operator-configured GitHub OAuth app. Backend needs `GITHUB_CLIENT_ID` and secret `GITHUB_CLIENT_SECRET`. The callback is `BACKEND_URL` + `/api/auth/callback/github`. GitHub must return an exact primary, verified email matching an existing account or the bound first-admin address. | The GitHub account id links to the one CMS account with that normalized email. Provider access, refresh and ID tokens are not retained. |
| Admin **Settings → Source & delivery** | Operator-configured GitHub App. Backend needs `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_PRIVATE_KEY`, plus valid `BACKEND_URL` and `FRONTEND_URL`. App callback: `BACKEND_URL` + `/api/source/github/callback`. The signed-in user needs `site:infra` and model read access. | The installation/repository binding persists. Repository-scoped installation tokens are short-lived and revoked after use. Do not replace this flow with a personal token. |
| `npm run wire:github` | GitHub OAuth device flow using `DEEWAN_GITHUB_CLIENT_ID`. Cloudflare wiring needs `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` and `DEE_WAN_URL`. `--project` is required. Secrets are sealed only after exact-commit read-back. | Repository secrets/variables are written by the authorized CLI. Device credentials stay in the process. Webhook configuration is printed, not silently saved in the CMS. |
| `npm run backend:deliver` | Device flow using `DEEWAN_GITHUB_CLIENT_ID`, not the admin App. Also requires the target repository, source database and output paths, Cloudflare account/token, `API_BEARER_TOKEN` and `PUBLIC_HOSTNAME`. Media transfer adds its own source/destination credentials when selected. | Generated repository and deployment remain. Device credentials are not written into git configuration or the CMS ledger. Successful verification offers a detachment plan. It does not automatically detach. |
| Installer's optional GitHub connection | `DEEWAN_GITHUB_APP_SLUG` only enables a link to an App installation. | This is not the five-variable backend App configuration and does not replace either CLI device flow. |

## Permissions and refusals

The GitHub OAuth app used for CMS sign-in is separate from the GitHub App used for source delivery and from the CLI device-flow app. Its client id and secret do not authorize repository delivery.

Admin source tokens require repository `contents:write`, `workflows:write`, `metadata:read`. Deployment also requires `actions:write`, `secrets:write`, `variables:write`. Selection is checked against the installed repository. If the backend App configuration is missing, the request is refused with `github_app_not_configured`. There is no device-flow fallback in this UI.

The separate build-webhook credential printed by `wire:github` is a fine-grained token for that repository with **Contents: read** and **Actions: write**. Do not reuse the device token as the stored webhook secret. Review and save the printed configuration under **Source & delivery → Advanced — build webhook and deployment** with an authorized CMS session.

![Settings, Source and delivery before a repository is connected](/assets/screenshots/source-delivery.webp)

## Managed delivery of a local commit

Generate the Astro website and backend locally first. Hosted generation still refuses with `source_build_runtime_unavailable`. Connect the source GitHub App to the intended private adopter repository, then run:

```sh
npm run wire:github -- --repo owner/site-source --project ./generated/site --managed --operation delivery-20260920-1
```

Use a new stable operation id for a new delivery. The signed-in person needs `site:infra`, `site:deploy` and read access to every generated model. Supply `DEE_WAN_SESSION_COOKIE` in the CLI environment and `DEE_WAN_SESSION_ORIGIN` as the CMS frontend origin. `DEE_WAN_URL` is the backend origin. The CLI sends the session only to that CMS origin. These values do not go into the generated project.

Before changing the repository, determine `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`, `API_BEARER_TOKEN`, `DEE_WAN_HOSTNAME` (the deployed backend hostname), `ASTRO_ORIGIN` (the expected public HTTPS Astro origin), and the selected artifact authentication credentials described below. GitHub authorization does not grant Cloudflare access. The generated site must have its preview bridge configured for the intended CMS public API before committing.

The CLI commits and pushes through Git, reads back the full remote commit, and verifies its manifest. Only then can it seal secrets to the adopter repository. The CMS records the site, operation, attempt, source version and exact commit, with only the build token's identifier and HMAC. Cloudflare credentials never enter a CMS request, ledger, manifest or generated file. The deployment dispatch carries the exact commit. The workflow checks out and verifies that commit before running its deployment script.

Keep the operation id after an interruption. Add `--resume` only after the previous CLI process has stopped, while the operation is still preparing secrets. This rotates and revokes its previous build credential before continuing. Once dispatch has begun, use `--reconcile` with the same operation id. Reconciliation reads the matching GitHub run and never dispatches. A missing, duplicate or unreadable run stays locked as an unknown outcome. Do not invent another operation to bypass that lock. CLI success means GitHub confirmed the run. It does not mean deployment or preview activation finished.

Only the managed workflow reports completion, using its existing build token and the bound operation, attempt, commit and deployed Astro origin. The repository-only workflow has no CMS callback. Completion stores the origin as unverified. A conflicting completion replay is refused, while an exact replay can return the recorded result. Under Source & delivery, a signed-in person with `site:settings` chooses a readable saved item and runs preview verification. Only the reported candidate may be activated through this action. A failed completion or proof keeps the previous active renderer target.

Real GitHub installation/callback authority, private repository adoption, secret sealing and revocation, Actions reconciliation, Cloudflare deployment, DNS, deployed callbacks and preview proofs remain external acceptance gates.

## Evidence and next task

The authorities are `backend/src/api/source-delivery.ts`, `backend/src/lib/github/credentials.ts`, `scripts/github-start.ts`, `scripts/github.ts`, `scripts/exit-start.ts` and `scripts/install-web.ts`. Before using the CLI, read its actual usage output. This page does not supply or create credentials. Continue with [installation](/guides/installation/) or [detachment](/guides/detachment/).

## Disconnect GitHub sign-in

Choose **Account security** from your identity menu to inspect and unlink your own GitHub sign-in connection. Confirmation names GitHub and warns that every CMS session will end, including the current one. The operation is atomic and refuses removal if no active superadmin would retain an enabled, configured, usable sign-in method. It does not change the separate source-delivery GitHub App installation or CLI credentials.

See [account security](/guides/first-administrator/#disconnect-a-sign-in-provider) and the lead-owned [real-provider acceptance procedure](/guides/authentication-acceptance/). Local fixtures are not evidence of a successful GitHub callback.

## Artifact sign-in credentials

Optional Better Auth in generated backends is a separate identity system. The artifact GitHub OAuth application uses `<ARTIFACT_ORIGIN>/api/auth/callback/github`. It is separate from the CMS OAuth application, source-delivery GitHub App and CLI device authorization. Select methods under Source & delivery. Supply credentials explicitly for the target, and only for the selected providers. Actions secret names prefix runtime names with `ARTIFACT_`, including `ARTIFACT_GITHUB_CLIENT_ID` and `ARTIFACT_GITHUB_CLIENT_SECRET`. Delivery creates a fresh artifact auth secret, seals values to the target public key and preserves existing target secrets without rotating them. No CMS identity, password or provider credential is copied.

<!-- dee-wan-docs page: /guides/authentication-acceptance/ -->

# Verify sign-in

Source: https://dee-wan-docs.pages.dev/guides/authentication-acceptance/

This is a procedure for the lead, not a record of completed acceptance. Local SQLite checks and stubbed frontend/Cypress responses prove local behavior only. They do not prove real email delivery, provider callback success or Cloudflare configuration. Do not run these steps without authority for the selected deployment and test identities.

## Before starting

- Use an authorized acceptance deployment and provisioned test identities. Keep an independently verified superadmin recovery method available.
- Confirm required Worker bindings are present using the deployment's approved secret-presence process. Record only presence, never values. Confirm enabled methods on the Installation page, under Sign-in methods.
- Confirm frontend/backend origins and provider callback registrations match the deployment: `BACKEND_URL` + `/api/auth/callback/google` or `/api/auth/callback/github`.
- Use separate browser profiles for two sessions of the target user, a second active superadmin, and an unknown identity. Remove Access cookies from the session-only revocation profiles so Access cannot independently authenticate a revoked session.
- Run `frontend/cypress/e2e/journey-account-security.cy.ts` in the existing local rig. The lead owns execution and live visual review at 390×844 and 1440×900: loading, empty, linked, error, long email, confirmation, refusal, pending, success and focus return. Passing assertions alone are not visual acceptance.

## Real-provider gates

| Gate | Procedure | Required result |
| --- | --- | --- |
| Resend delivery | Request a magic link for a known active identity with magic link enabled. Receive it at the authorized mailbox and follow it. | The email arrives, the user signs in to the expected CMS account, and a protected request succeeds. A provider HTTP acknowledgment alone does not prove delivery. |
| Invitation delivery and address proof | From Settings → People, invite an authorized mailbox. Open the emailed link, type that address, and enter the emailed code. Separately, forward the link to a second authorized mailbox and try to accept it there. Retry a used, resent and cancelled link. | Both emails arrive, acceptance grants exactly the invited role on that site, and the new password signs in. The forwarded link cannot accept without the code from the invited mailbox. Used, replaced and cancelled links are refused alike. |
| Magic-link replay and expiry | Reopen the consumed link. Request two links, then try the older one. Separately retain an unused link beyond its 15-minute lifetime and try it. | Consumed, replaced and expired links cannot create another session. Requesting for an unknown address has the same public response and creates no account. |
| Google callback | Sign in with a real Google identity whose verified email matches a provisioned CMS account. Try a different unknown email and an unverified address if the provider permits an authorized fixture. | The user signs in to the matching existing CMS account, with no duplicate account or signup for an unknown email. Unverified proof is refused. If a real unverified fixture is unavailable, leave that subcase unverified. Do not substitute a stub and mark it accepted. |
| GitHub callback | Use a real GitHub identity whose primary verified email matches a provisioned CMS account. Exercise hidden-public-email behavior and a primary-email mismatch using authorized identities. | Primary verified address from GitHub is used. A secondary matching address alone cannot claim the CMS identity. Unknown/mismatched identity is refused. |
| OAuth replay/invalid state | Revisit a consumed callback and an expired or invalid state through the browser, without saving callback URLs or authorization codes in evidence. | No session or provider link is created from reused, invalid or expired proof. |
| Link-time revocation and token discard | Sign in through a newly linked provider while an older CMS session exists in another profile. Verify the older session against a protected API. Perform an approved boolean-only database check for provider token presence. | Older session is refused. Provider access, refresh and ID token columns remain null. Never export those columns or their values. |
| Unlink and session revocation | Establish two CMS sessions for the same user. Open Account security, cancel once, then confirm Google unlink. Repeat independently for GitHub. Verify both old sessions with a protected request. | Cancel changes nothing. Confirmation removes only the selected connection owned by that user, signs the user out in the initiating UI, and makes both old sessions fail. Other users' links/sessions remain valid. Use a fresh sign-in to inspect remaining links. |
| Ordinary last-provider unlink | Use an ordinary user with only one OAuth connection while a separate active superadmin retains a usable method. | Unlink succeeds and all target-user sessions end. Recovery or later same-email provider sign-in is a separate step. |
| Last usable superadmin | In an authorized isolated acceptance deployment, make the target provider the only usable method across all active superadmins, retaining an approved operator recovery path. Attempt unlink. Then establish another active superadmin with a verified usable method and repeat. | First attempt returns 409 `would_lock_out_superadmins`. Account and sessions stay intact. Second attempt can succeed even if the target retains no personal method. Disabled, incomplete or unlinked alternatives do not count. |
| Passkey on a real device | With passkeys switched on, sign in another way and add a passkey under Account security on a laptop (Touch ID or Windows Hello) and on a phone. Sign out, then use **Sign in with a passkey** on each. Rename one and remove one. Try adding again from a session older than 24 hours. | Each device signs in the expected CMS identity with no address typed. A removed passkey no longer signs in. The old session is asked to sign in again before adding. |
| Passkey lost-device recovery | Using an account whose only other method is a password, remove access to the device holding its passkey. Sign in with the password, remove the lost passkey, then try it again. With mail and email links on, repeat with a passkey-only account using an email sign-in link instead of the password. Separately, deactivate an account that has a passkey and try to sign in with it. | Password sign-in still works and the removed passkey is refused. The last remaining method cannot be removed. The deactivated account gets no session. |
| First-admin claim, when accepting a fresh install | On separately authorized fresh instances, use a bound claim with each opted-in method. Try wrong-email, consumed and expired claims. Never reset an existing deployment for this check. | Only the bound email can create the first superadmin. Replay/expiry fails. Ordinary sign-in never creates users. |

## Safe evidence

Record deployment label/version, date, method, scenario, expected/observed outcome, response status/reason, and pass/fail/unverified. Screenshots may show UI state with personal addresses redacted. Record boolean/count comparisons for account/session invariants only through authorized access.

Do not retain cookies, session tokens, passwords, claim links, email links, OAuth codes/state, provider identity ids, provider tokens or secret values. Do not retain full database dumps or unredacted HAR/network exports. Browser profiles holding acceptance sessions are credential-bearing and should be closed or signed out after the exercise.

## Gates that remain open

- Lead-run focused Cypress and live visual review at both viewports.
- Actual Resend (magic link and invitation), Google, GitHub and real-device passkey acceptance, including the applicable negative/replay/expiry cases above.
- Live Cloudflare secret-presence confirmation.
- Docs-site deployment after the normal owner gate.

Record results separately when performed. This procedure makes no deployment or provider-success claim.

<!-- dee-wan-docs page: /guides/database-migrations/ -->

# Database migrations

Source: https://dee-wan-docs.pages.dev/guides/database-migrations/

This guide covers the CMS's own database: where its schema history lives, how to change it, and how
to apply a change to a local database, a deployed one and any per-site databases. Run every command
from the repository root.

## Where things live

| Path | What it is |
| --- | --- |
| `backend/prisma/migrations/` | Prisma SQL migrations, one directory per migration. `20260908000000_init` is the fresh-install baseline: the whole schema and its seed rows. **The source of truth** for the schema history, including custom constraints and required seed rows. |
| `backend/migrations-wrangler/` | The D1 mirror of those migrations (`0001_init.sql` for the baseline, then one file per later migration). Generated — never edit it by hand. Wrangler applies these files to D1. |
| `backend/prisma/prod.prisma`, `local.prisma`, `site.prisma`, `eav.prisma`, `tables.prisma` | The schema **fragments**. Edit these. |
| `backend/prisma/schema.prisma` | Assembled from `prod.prisma` + `site.prisma` + `eav.prisma` + `tables.prisma` by `scripts/build-prisma-schema.mjs`. It is checked in, but it is output: an edit made directly to it is overwritten on the next build. |
| `backend/prisma/schema.local.prisma` | The same assembly on top of `local.prisma`, used when authoring a migration. Gitignored. |
| `backend/tenant-migrations/` | The schema a new per-site database starts from (`0001_tenant_schema.sql`), plus the deltas under `deltas/` that bring existing per-site databases forward. There are no deltas yet. This applies only if you use `npm run provision:site`. |

After the first release, migrations are append-only. Never edit or delete a released migration.
Correct it with a new one.

## Before the first release

Dee Wan is unreleased, so no installation has to be carried forward yet. Until the first release,
schema changes edit the baseline instead of adding a migration: the fragment, `20260908000000_init`,
its `0001_init.sql` mirror and the tenant baseline `0001_tenant_schema.sql` change together, and
`npm run migrate:check`, `npm run prisma:drift` and `npm run tenant:schema:check` must pass.

The first release starts from fresh databases. It ships no upgrade SQL for databases an earlier
build created, and no tenant delta. A baseline edit changes the tenant schema with no new delta, so
`npm run tenant:schema` refuses it. Regenerate with `npm run tenant:schema -- --allow-no-delta`. After
the first release, every schema change is a new migration, made with the steps below.

A local database built from an older baseline does not pick up such a change. Recreate it: stop the
local rig, delete `backend/.wrangler/state`, then run `npm run local:migrate` and `npm run local:seed`
again. This deletes every local site, entry and upload.

## Change the schema

Before first release, update the baseline as described above. The steps below apply after release.

1. Edit the fragment that holds the model (`site.prisma`, `eav.prisma` or `tables.prisma`).
2. Rebuild `schema.prisma` and the Prisma client:

   ```bash
   npm run prisma:generate
   ```

3. Apply everything that already exists to your local database, then write the new migration:

   ```bash
   npm run local:migrate
   npm run local:migrate -- initial --create-migration
   ```

   Authoring is off unless you pass `--create-migration`, so an ordinary apply never writes a
   migration from a drifting schema. With it, and only when nothing is left to apply locally, the
   command runs `prisma migrate dev --create-only`, which writes a new directory under
   `backend/prisma/migrations/`, and then applies that migration to the local database. It uses the
   tracked local config (`backend/wrangler.dev.jsonc`), so it works on a clone that has never been
   installed.

   Keep the word `initial` in that command. `--create-migration` given alone is currently rejected
   with a usage message.

4. **Read the generated SQL before you commit it.** A migration authored from a schema that has
   drifted from the database can contain `DROP TABLE` statements nobody intended.
5. Regenerate the D1 mirror and check the result:

   ```bash
   npm run migrate:sync          # writes backend/migrations-wrangler/ from the Prisma migrations
   npm run migrate:check         # fails if the mirror and the migrations disagree
   npm run prisma:drift          # fails if schema.prisma no longer describes what the migrations build
   ```

6. If you use per-site databases, regenerate their schema too:

   ```bash
   npm run tenant:schema         # rewrites the per-site bootstrap schema
   npm run tenant:schema:check   # fails until every new table has a placement
   ```

   A migration that adds a table fails `tenant:schema:check` until the table is placed in
   `backend/src/lib/tenancy/placement.ts`.

   A migration that changes what existing per-site databases hold also needs a delta. Write the SQL
   that brings such a database forward as `backend/tenant-migrations/deltas/NNNN_<name>.sql`, with
   the next number, before you run `npm run tenant:schema`. For an added column or index this is the
   migration's own SQL. `npm run tenant:schema` refuses a changed tenant schema with no new delta and
   names the file to write. Pass `--allow-no-delta` only when the change needs none.

7. Commit the Prisma migration, its mirror file, any delta and any tenant schema change together.

## Apply migrations

| Where | Command | Notes |
| --- | --- | --- |
| The local rig (no Cloudflare account) | `npm run local:migrate` | Uses `backend/wrangler.dev.jsonc`, which every clone has. Needs no credential. |
| The local mirror of an installed configuration | `npm run migrate:d1:local` | Reads `backend/wrangler.jsonc`, which `setup` writes and git ignores, so it fails on a clone that has not been installed. Use it with `npm run dev:install --workspace backend`. |
| The deployed control database | `npm run migrate:d1` | Needs `CLOUDFLARE_API_TOKEN`. Prints the config and database it is about to migrate before it runs. Add `-- --config <file>` for an installation that is not `backend/wrangler.jsonc`. |
| Existing per-site databases | `npm run tenant:upgrade` | Only if you ran `npm run provision:site`. `-- --plan` shows what each site is missing without writing. |

A fresh installation needs none of these: `npm run setup` applies the schema itself.

`npm run deploy` refuses to deploy the admin Worker while the control database has pending
migrations, or when it cannot tell. Apply them first. `--skip-migration-check` overrides the check.
Use it only when you know the new code does not depend on the pending migrations.

## When a migration fails

- Migrations are applied in order, and each one is recorded as applied only after it succeeds. A
  failure stops the run and says the migration was not recorded. The migrations after it are not
  applied. Fix the cause and run the same command again: it retries the failed migration.
- If a migration stopped part-way, the retry runs it statement by statement and skips only the
  statements whose table, index, trigger or column already exists, so it can finish. A migration
  that contains a `BEGIN … END` block other than a trigger cannot be split that way. The run refuses
  and names it, and you resolve the schema by hand before running again.
- Do not fix a failed migration by editing one that has already been applied somewhere. Add a new
  migration that corrects it, run `migrate:sync`, and apply again.
- Before applying a risky migration to a deployed database, take an export:
  `npx wrangler d1 export <database-name> --remote --output backup.sql` from `backend/`. Cloudflare
  D1 also keeps its own point-in-time history (Time Travel), which can restore a database to a
  moment before the migration.
- If `npm run deploy` refuses because of pending migrations, apply them with `npm run migrate:d1`
  rather than bypassing the check.

<!-- dee-wan-docs page: /guides/web-installer-preview/ -->

# Web installer preview

Source: https://dee-wan-docs.pages.dev/guides/web-installer-preview/

The web installer is a four-step wizard served from your own machine. It needs a Cloudflare OAuth
application that you register and own. Dee Wan 1.0 does not ship one, so the web installer is not a
supported way to install Dee Wan. Install with the command-line installer in
[Installing Dee Wan](/guides/installation/).

Without an OAuth application you can still walk through the wizard with
`npm run install:web:dry-run`, which touches nothing. See
[Preview the wizard without touching Cloudflare](#preview-the-wizard-without-touching-cloudflare).

## How it differs from the command-line installer

Both use the same installer engine, configuration file (`backend/wrangler.jsonc`) and step ledger.

| | Web installer | Command-line installer |
| --- | --- | --- |
| Start with | `npm run install:web` | `npm run setup` or `npm run install:cms -- <verb>` |
| Interface | A browser page on `127.0.0.1`, served from your machine | Terminal prompts, or no prompts with `--yes` |
| Cloudflare credential | Cloudflare sign-in (OAuth), held in memory for the session | An API token you create, from the environment, `.env` or the prompt |
| Needs | A Cloudflare OAuth application (`DEEWAN_CF_OAUTH_CLIENT_ID`) | A Cloudflare API token with the [listed permissions](/guides/installation/#credentials) |
| Rate-limit rules | Not installed (the sign-in asks for no WAF access) | Installed when the token has Zone · Zone WAF · Edit |
| Planning and scripting | Shows what will be created before you install | `plan`, `--json` output and fixed exit codes |
| Resume after a stop | **Resume** button | `npm run install:cms -- resume`, or run `setup` again |

The installer reads the OAuth client id from `DEEWAN_CF_OAUTH_CLIENT_ID`. Without it, the Cloudflare
step shows "Cloudflare sign-in needs setup." and tells you to use the command-line installer.

## Start it

```bash
npm run install:web
```

The server listens on `127.0.0.1` only, on port 8976 unless `DEEWAN_INSTALL_PORT` is set. It
prints one link:

```
Dee Wan installer
Open this link. It is bound to this session and is not written to disk:

  http://127.0.0.1:8976/?t=<session-token>
```

The token in the link is generated for this run. Every request must carry it, so another page or
program on the same machine cannot drive the installer. A request without it gets "This installer
is bound to one session. Open the link printed in the terminal." Press Ctrl-C in the terminal when
you are done.

Cloudflare sends the browser back to `http://127.0.0.1:<port>/oauth/cloudflare` after sign-in, and
that address must match the one registered with the OAuth application exactly.
`DEEWAN_CF_OAUTH_REDIRECT` overrides it.

The page has a **Language** selector with English, Thai, Russian, Spanish, French and German. The
language you install in also becomes the default language of the first site.

The wizard has four steps: **Site**, **Cloudflare**, **Administrator** and **Install**. **Continue**
saves the current step before moving on, and **Back** returns to the previous one.

## Step 1: Site

![Web installer, Site step: the installation will live on its own domain](/assets/screenshots/installer-site.webp)

**Where will this live?** has two answers:

- **On my own domain**: enter it in **Your domain**, for example `example.com`.
- **On addresses Cloudflare provides**: leave the domain empty.

Nothing else is asked here. Infrastructure names and optional features have working defaults and
are on the Install step.

## Step 2: Cloudflare

![Web installer, Cloudflare step: connected for this session, D1 plan chosen](/assets/screenshots/installer-cloudflare.webp)

1. Under **Connect Cloudflare**, choose **Authorise Cloudflare**. It opens Cloudflare in a new tab.
   The link is disabled while you have unsaved changes ("Save your settings before connecting.").
2. Approve the request. The tab then shows **Connected** and says the installer holds a Cloudflare
   credential for this session only. Close it and return to the installer, where the card shows
   **Connected for this session only**.
3. Choose the account under **Which Cloudflare account** and select **Use this account**. If your
   sign-in reaches only one account, it is chosen for you. Everything the installation creates is
   billed to this account.
4. Choose the **D1 database plan**: **Free** or **Paid**. Cloudflare publishes no way to read which
   plan an account is on, and the two plans allow different amounts of stored content, so the
   installer asks instead of guessing.

**What access is requested?** lists the exact Cloudflare scopes the sign-in asks for. They depend
on your answers:

| When | Scopes |
| --- | --- |
| Always | `account-settings.read`, `d1.write`, `workers-scripts.write`, `page.write`, `workers-r2.write` |
| With your own domain | `zone.read`, `workers-routes.write` |
| With your own domain and DNS setup on | `dns.write` |
| With Cloudflare Access on | `access.write`, `access-acct.read` |

No WAF scope is ever requested. See the visitor limit under [Step 4](#step-4-install).

If you later change a setting that changes the access needed, the installer drops the old
authorization and says "Saved. This changes what access is needed, so connect Cloudflare again."

You cannot continue until Cloudflare is connected and an account is chosen.

The credential is held in the installer's memory, not written to disk. If it expires, the page says
"Your connection expired. Connect again to continue." Authorising again does not affect anything
already created.

## Step 3: Administrator

Enter one **Administrator email**. The first sign-in link (the claim link) is bound to this
address, and only this address can claim the installation.

## Step 4: Install

![Web installer, Install step: the review of planned addresses and everything that will be created](/assets/screenshots/installer-review.webp)

**Review** lists what you decided: the address, the **Planned sign-in address**, the **Planned
website address**, the Cloudflare account, the D1 database plan and the administrator. **Will be
created** lists every step that will create something and has not been done yet.

**Customize infrastructure** opens the remaining settings:

| Setting | Default |
| --- | --- |
| **Where you sign in** (admin subdomain) | `cms` |
| **Where your website reads from** (public API subdomain) | `content` |
| **Point your domain at this installation** | On. Needs your own domain. |
| **Ask for a Cloudflare sign-in before the admin** (Cloudflare Access) | Off. Needs your own domain. |
| **Limit how often one visitor can read your content** | Off. Needs your own domain. See the note below. |
| **Service name** (admin Worker) | `dee-wan-cms-backend` |
| **Project name** (Pages project) | `dee-wan-cms` |
| **Your workers.dev subdomain** | Empty. Used for the public API address when you have no domain. |
| **Seconds to keep website answers** | `0`, which shows every reader the newest content |
| **Also prepare the archive bucket for importing from another system** | Off |

The admin and the website need different subdomains. If you turn on Access, note the two warnings
the page shows: every person you invite also needs an entry in the Cloudflare Access policy, and if
the Access application is deleted or misconfigured, everyone is locked out.
With Access on, a site administrator can map an email domain or an Access group to a role instead
of inviting each person. Someone Access lets in with that domain or group then gets an account on
first sign-in. See [People and access](/guides/people-and-access/).

The web installer does not install the visitor limit. The setting is saved
(`SETUP_PUBLIC_RATE_LIMIT` in `backend/wrangler.jsonc`), but the rule is a Cloudflare WAF
rate-limiting rule and the web installer's sign-in has no WAF access. The run reports that the rule
could not be installed and continues. The same happens to the sign-in rate-limit rule. To install
them, run `npm run setup` afterwards with an API token that includes Zone · Zone WAF · Edit (see
[Credentials](/guides/installation/#credentials)). When the rule is installed, it also limits private
reads, including a site build that reads from one IP address.

The review also says that error reports go to the Dee Wan Sentry project when the deployment has its
address, built in or set as the `DEEWAN_SENTRY_DSN` secret, and that without one nothing is sent. In
this build no Dee Wan Sentry address is built in, so nothing is sent to Dee Wan unless
`DEEWAN_SENTRY_DSN` is set. Until then, Installation → Error reports says "No Dee Wan
destination in this build. Nothing is sent." Reports never include content, form values, emails or
credentials. To send them to your own Sentry project, set the `OPERATOR_SENTRY_DSN` secret. Secrets
belong to one Worker: set either address on the public read Worker too
(`npx wrangler secret put <NAME> --config wrangler.public.jsonc`) for its errors to be reported. See
[Secrets](/guides/local-development/#secrets).

If you edit a setting on this step, the primary button becomes **Save changes**. Once everything is
saved, choose **Install**.

The installer refuses to start a run against settings you have not reviewed. If the configuration
file changed while the page was open, it says "The settings changed while this was open. Nothing
was started. Review them and try again."

## What the web installer writes

Each save writes your answers into `backend/wrangler.jsonc` (or the file named with `--config`)
and keeps any comments in it. If the file does not exist, a fresh one is created. Choosing an
account writes `account_id`. The file is gitignored because it holds your real values. The web
installer cannot edit a `wrangler.toml` configuration. Convert it to `wrangler.jsonc` or use the
command-line installer.

The install run itself is the command-line engine: the page starts `install:cms apply` (or
`resume`) with `--yes`, passing the Cloudflare credential from your sign-in. It does everything
`npm run setup` does that the sign-in's access allows, including writing
`backend/wrangler.public.jsonc` for the public read Worker and `backend/wrangler.intake.jsonc` for
the form intake Worker.

## Following the run, retrying and resuming

The panel beside the wizard shows **What will happen** before a run, **Progress** during it, and
**What was done** when it finishes. **Technical details** shows the installer's log, with
credentials removed.

The page keeps polling while a run is going. If you reload it, it returns to the run. If it loses
contact with the installer, it says "Lost contact with the installer. It may still be running —
reload this page."

If a run stops, the panel says where ("Stopped at: …") and what to do next:

- If some steps were completed: "Your progress is saved. Resume when you are ready." Choose
  **Resume**. Completed steps are not repeated.
- If nothing was created: "Nothing was created. Install again when you are ready." Choose
  **Install**.

A run that ends with unfinished work (exit code 4, **incomplete**) is reported as "Not finished" and
not as a success. Check the log, fix what it names, and resume.

## When it finishes

![Web installer, finished: every step done and the Create administrator button](/assets/screenshots/installer-done.webp)

The panel lists the Worker, the admin address and the public API address that answered, and the
page shows **Create administrator**. It opens the claim link in a new tab, where you choose any
configured sign-in method. See [Claim the installation](/guides/installation/#claim-the-installation).

The claim link is never shown in the log. The page offers it through that button, only while the
link is valid, and only once. If it expires before anyone uses it, choose **Resume** to mint a new
one while the installation is unclaimed.

## Preview the wizard without touching Cloudflare

```bash
npm run install:web:dry-run
```

This serves the same page for review, with every external effect replaced. The configuration and
ledger live in a temporary folder that is removed on Ctrl-C. Account discovery and the install run
are simulated, and nothing reaches Cloudflare. It listens on port 8978 unless `DEEWAN_INSTALL_PORT`
is set. Sign-in completes when you open the sign-in link printed at start. Do not press
**Authorise Cloudflare**, which opens Cloudflare with a placeholder client id.

## Troubleshooting

**The web installer says the port is in use.** Another process, often a second installer, is
listening on the port. Close it, or set `DEEWAN_INSTALL_PORT` to a free port. Nothing was created
in any account. The OAuth application's registered redirect address must match the new port.

**The page says "This installer is bound to one session."** Open the exact link printed in the
terminal. A restarted installer prints a new link.

**The Cloudflare step says "Cloudflare sign-in needs setup."** `DEEWAN_CF_OAUTH_CLIENT_ID` is not
set. Use the [command-line installer](/guides/installation/#command-line-installer) with an API token.

**The web installer cannot read or edit the configuration.** It edits only `wrangler.jsonc`. Fix
`backend/wrangler.jsonc` if it is malformed, or convert a `wrangler.toml` to `wrangler.jsonc`, then
reload the page.

For problems the command-line installer shares, such as `DOMAIN` set without `DOMAIN_MODE` or an
unresolved step, see [Troubleshooting](/guides/installation/#troubleshooting).

## Next step

Install with the [command-line installer](/guides/installation/#command-line-installer).

<!-- dee-wan-docs page: /guides/plugins-for-site-admins/ -->

# Plugins for site administrators

Source: https://dee-wan-docs.pages.dev/guides/plugins-for-site-admins/

A plugin is a remote service. It runs on its own server, with its own data. Reviewed embedded UI
runs in an isolated frame. Server operations use HTTPS. It works on one site, within the access grant you choose. This guide is for the person who installs
and manages plugins. To build one, see [Writing a plugin](/plugins/authoring/).

## Where plugins live

Open **Settings → Plugins**. You need the `site:plugins` permission. The built-in `admin` role has
it, and so does a superadmin. The section has three cards:

- **Installed plugins**: each plugin on this site, its state, grant and actions.
- **Discover plugins**: plugins listed by this server's catalogues.
- **Install a plugin**: install from a manifest URL.

Each site has its own installations. Installing a plugin on one site gives it nothing on another.

## Install a plugin

1. Get the plugin's manifest URL and a one-time activation code from the plugin's operator.
2. Either press **Review** on a listing under **Discover plugins**, or type the **Manifest URL** under
   **Install a plugin** and press **Review**. The URL must start with `https://`.
3. Read the review: name, version, plugin id and the server it runs on. **Adds to the editor** lists
   the cards and field editors it adds.
4. Under **Capabilities**, tick only what this plugin needs. You can choose only what it asks for.
5. Under **Models**, tick the content types it may work on. **No model selected means no content
   access.**
6. Enter the **Activation code** and press **Install**.

**Discover plugins** says **No plugin catalogue is set up on this server. Install by manifest URL
below.** when the operator configured no catalogue. A listing grants nothing. Install fetches and
checks the manifest again, exactly as for a typed URL.

Install fails when the deployment has no public address set, because the plugin could not reach
Dee Wan. It also fails when the plugin refuses the activation code. Nothing is installed in either
case.

## What each capability allows

A plugin acts only on the models you granted. Every write is made on behalf of the person who started it from
Dee Wan, and that person's current permissions still apply. If the person loses access, or you
narrow the grant, the plugin loses that power too.

| Capability | Shown as | What the plugin can do |
| --- | --- | --- |
| `content:read` | Read content summaries | Read summaries; with a live delegation, read saved values and retained revisions within the person’s current grants. |
| `workflow:read` | Read workflow state | Read the workflow state and the available workflow transitions. |
| `workflow:publish` | Publish | Publish a pinned version. |
| `workflow:unpublish` | Unpublish | Take a published version offline. |
| `workflow:locale` | Publish or unpublish one language | Move one language instead of the whole translation group. A move notifies people exactly as the same move made in the editor does, see [feedback and notifications](/guides/content-editing/#feedback-and-notifications). |
| `content:write` | Save existing entries | Save values, relations and media on existing entries through the delegating person’s lifecycle checks. |
| `content:create` | Create entries | Create entries through the delegating person’s normal create checks. |
| `content:delete` | Move entries to Trash | Trash existing entries through the delegating person’s normal delete checks. |
| `draft:write` | Read and change that person’s unsaved drafts | Read, write and discard that person's working drafts. |
| `media:write` | Upload files | Upload files within the person’s current upload authority. |
| `media:read` | Read existing media | Read metadata and bytes within the person’s current media read authority. |
| `media:update` | Edit media metadata | Edit existing metadata within the person’s current media update authority. |
| `content:propose` | Propose changes for an editor to review | Create proposals. An editor applies or dismisses them in the entry. |
| `media:source` | Offer its files in the media picker | List its own files in the media picker. |

Creation, deletion, existing-media reads and metadata edits each need their own reviewed capability. Existing `content:write` and `media:write` grants do not gain these powers. Changed relation targets, including links inside components, must fit both the installation’s model grant and the launch delegation’s model list. An unchanged opaque link can remain during another edit.

A plugin cannot read users, roles, sessions, settings or the audit log. Embedded code runs inside an isolated frame; it cannot execute in the parent admin document or reach the database directly. Details: [Plugin security](/plugins/security/).

## Content checks

A plugin can declare content checks. They appear under **Content checks** on its row, along with when they
run: **On save**, **On publish**, **On restore**, **On delete**, **On unpublish** or
**On workflow move**. A check runs on each matching write to a model in the plugin's grant, from
every path: the editor, bulk actions, spreadsheets, imports, the management API and other plugins.

Be aware of what a check can do:

- It sees the facts of the write it is asked about, including the new values, even without
  `content:read`.
- It can warn, or refuse the write.
- An **On save** or **On restore** check can also change the content being saved: values, links,
  media and search settings. Dee Wan saves the result through the same rules that apply to a person's edit.
  The editor then shows which fields changed, and the version history names the plugin.

Each check has a switch **Block changes if it does not answer**. Off (the default): a timeout or an
outage lets the change through with a warning. On: the change is refused. A real refusal always
stops the change. A check shows **Needs more access** when the grant lacks a capability it needs,
and **Plugin is off** while the plugin is disabled.

Install only plugins you trust with the content of the models you grant.

## Checks before accepting

A plugin can declare checks that run before Dee Wan accepts something. They appear under **Checks
before accepting** on its row, each with **Use this check**, and every one is off until you turn it on.
Declaring a check sends nothing.

- **Before a file is uploaded** asks the plugin about each new library file. It sees the file's name, type,
  size, folder and alt texts. It never sees the file itself or who uploads it. It can approve the file,
  tidy its name (the file type stays the same) and alt texts, or refuse it with its own reason, which the
  uploader reads.
- **Before a comment is stored** asks the plugin about each visitor comment. It sees the entry, the
  author's name and website, and the text. It never sees the email address. It can approve the comment,
  leave it for a moderator, or reject it.

A check that does not answer never approves. If it times out (5 seconds), cannot be reached, or answers
something Dee Wan does not accept, the upload is refused with "The upload check did not answer" and
nothing is saved, and the comment waits for a moderator as it does when no check is on. The same file
sent again with the same details gets the check's first answer back for 24 hours, so a retry does not
ask twice. After a failed attempt it asks again.

Turning a check on or off needs the same permission as changing the grant (`site:plugins`) and is
recorded in the history as **Plugin check setting changed**. A check shows **Needs more access** when the
grant lacks a capability it needs, and **Plugin is off** while the plugin is disabled. Media that an import
brings in does not pass through upload checks, so a check never sees imported files. Every other way a new file arrives does: the library upload, the management API, a plugin, AI-generated images, files copied from an external source and the content planner.

## Media from a plugin

A plugin with `media:source` adds files to the media picker. In the picker, **Where to pick from**
offers **Library** and **Sources**. The person needs `media:upload`.

- **Add** copies the file into the site's library. It becomes an ordinary site file and keeps working
  if the plugin goes away.
- **Link without copying** keeps the file on the plugin's server. Pages use its address as it is.
  Dee Wan cannot edit or replace the file. If the plugin is disabled or removed, existing pages keep
  the address and the media details say **The source is not available now.**

Disabling the plugin or removing `media:source` from the grant hides its sources at once.

## Columns and actions in the content list

A plugin can add a **column** to the content list of a model in its grant, and **actions** for the
entries you select. Dee Wan renders both. The plugin supplies only text and, for a link, an `https://`
address.

- **Columns.** A cell is plain text, a coloured label or a link. The plugin is asked about the rows
  on the current page only, at most 50 at a time, and it is sent the model and the ids of the rows you
  can read, never their values. A row with nothing to show has a dash. When the plugin does not
  answer, its column shows a dash and **{plugin} could not fill this column.**, and the rest of the
  list works as usual. Opening the list writes nothing to the audit log.
- **Actions.** Select entries and open **Plugin actions**. The menu lists what plugins offer for this
  model, each marked **From {plugin}**. Choose one, fill in its form if it has one, and press **Run**.
  It runs once for each selected entry, at most 25. Dee Wan then shows how many were done and how
  many were not, with a result for each entry. A refusal on one entry does not stop the others. Each
  entry is checked against your permissions at that moment, and an action that can change data asks
  you to confirm first.
- A column or action appears only while the plugin is active, the model is in its grant and the grant
  holds every capability it needs. Disabling the plugin removes both at once.

## Structured fields

A plugin can offer an editor that shows one JSON field as a small form of named values: text,
number, switch and choice. In the model builder, open the field's **UI** tab and choose it under
**Plugin editor**. Choosing it writes the allowed values onto the field: which values are required,
their limits and the allowed choices. Dee Wan checks every save against them, like any other field
rule. If the plugin is disabled or uninstalled, the field keeps those rules and its values, and the
standard JSON editor shows them.

## Plugin workspaces

A reviewed plugin may add navigation pages and Dashboard views. Their isolated frames use the same declared operations as plugin cards. A view appears only while the installation is active, its reviewed capabilities are granted, and your current model and system permissions allow them. Opening its URL directly grants no access. New capabilities requested by an upgrade remain ungranted.

## Approved email templates

An administrator with `site:plugins` configures **Email templates** on a plugin row. **Recipient** selects **Approved addresses**, **Entry author** or **Assigned reviewer**. Fixed addresses accept 1–8 recipients; contextual choices use the account that created the selected CMS entry (`created_by_id`) or its current workflow assignee. **Entry author** does not mean a public Blog author/profile relation or the last editor. The account must be active, have current site access and still be able to read the entry; an active superadministrator may qualify without an explicit site membership. An absent or ineligible recipient refuses the send.

Review the recipient rule, subject and message before saving. A plugin with `mail:send` chooses a declared template and supplies its declared substitutions. For contextual mail it also names an entry inside its granted models and delegated item scope. It cannot choose an email address, account, recipient rule or arbitrary message. Sending requires the person’s current `site:plugins` permission; fixed mail uses a manage delegation, while contextual mail also accepts a matching content-action delegation.

Retries with the same key keep the accepted recipient and message, even after reassignment. They recheck the actor’s access and the original recipient’s active account, site/entry access and unchanged address. If that account is no longer eligible, delivery is refused rather than redirected. Provider acceptance is not proof of inbox arrival; an interrupted send is not proof that nothing was delivered.

The reviewed grant can also allow comment reads or moderation, redirect reads or writes, restoring entries from Trash, and deleting unused media. Each operation retains the owning CMS service's permission, validation and concurrency checks. Redirect patterns require the ordinary reviewed digest before saving. Media deletion still refuses files in use.

## Change the grant

Press **Grant** on the plugin's row. Tick capabilities and models, then **Save grant**. You can pick
only what the plugin's manifest asks for, and at least one capability. A narrower grant applies at
once, including to work the plugin queued earlier.

## Disable or enable

**Disable** stops the plugin at once: Dee Wan refuses its requests, and its cards, operations, media
sources and content checks stop. Its content checks no longer run on writes while it is off.
**Enable** turns it back on with the same token and grant.

Work the plugin scheduled may fail while it is off. For example, a schedule in the Scheduling plugin that comes due
while the plugin is disabled is refused and not retried.

## Rotate the token

Use this when the plugin's credential may have leaked, or when its operator asks.

1. Get a new activation code from the plugin's operator.
2. Press **Rotate** on the plugin's row, enter the **New activation code** and press
   **Rotate token**.

Rotation works only on an active plugin. If the plugin refuses or cannot be reached, nothing changes
and the old token keeps working. After a successful rotation, the old token works for at most 10
more minutes, and stops as soon as the plugin uses the new one.

## Accept a new release

A new release published by the plugin changes nothing on your site until you accept it. Settings →
Plugins offers **Check for updates**. Review the installed and proposed versions, feature changes,
permissions and embedded origins. Press **Confirm upgrade** to accept the reviewed version.
The server rechecks that version through `POST /api/plugins/:id/upgrade`; see
[Shipping a new release](/plugins/authoring/#shipping-a-new-release).

- Accepting never widens the grant. It can narrow it, when the release stops asking for a
  capability.
- When a release asks for a new capability, add it afterwards with **Grant**.
- A release that changes the plugin id, its server or its protocol version cannot be accepted.
  Uninstall and install it again.

## Uninstall

**Uninstall** asks first: **Access is revoked now. Data the plugin keeps is deleted only by the
plugin.** The token stops working for good, and the plugin leaves the list.

What stays in Dee Wan:

- versions it saved, publications it made, and their history entries
- files it uploaded or that people copied from it
- proposals still open on entries, which editors can still apply or dismiss
- rich text blocks from the plugin. They stay stored, but public pages do not show them while no
  active plugin defines them. See [Plugin blocks](/guides/blog/#plugin-blocks).
- fields that used its field editor. They fall back to the standard editor and keep their values.

What stays on the plugin's side: everything it stores. Ask its operator to delete it. For
Scheduling, see [Data, retention, uninstall](/plugins/scheduling/#data-retention-uninstall).

Installing the same plugin again creates a new installation. Choose its grant again and get a new
activation code. Content-check switches start at their defaults.

## Scheduling releases

The Scheduling interface is in English. A release sends up to 25 items as one atomic CMS command. `Done` confirms the whole command. `Failed` means a definite refusal left every publication unchanged. `Outcome unknown` requires recovery of the same recorded command and key; it does not mean partial publication.

A release blocked at its scheduled time stays scheduled and lists the blocking items. Fix or remove them, then press **Run now**, or set a new time. **Retry unfinished items** checks a definite refusal again or recovers an uncertain command without inventing item successes. **Stop remaining items** cancels unsent work. Completed changes remain; an in-flight command cannot be undone. Schedules due after the plugin is disabled or uninstalled are refused.

Choose **Version → Independent future version** when adding an entry to a release to prepare separate campaign content. Edit it in the entry’s **Future versions** panel. Ordinary items use the latest ordinary saved draft; future items use their own exact revision when the command starts. Set different times for releases that change the same entry and overlapping languages. See [future versions](/guides/content-editing/#future-versions).

Full rules: [Releases](/plugins/scheduling/#releases) and [Scheduling, end to end](/plugins/scheduling-end-to-end/).

## Next step

Developers: [Writing a plugin](/plugins/authoring/), [Protocol v1](/plugins/protocol-v1/) and
[Plugin security](/plugins/security/).

## Check and accept a release

Open Settings → Plugins → Check for updates. The host reads the installed manifest URL; it does not use a registry service. Review the installed and proposed versions, declared features, added or removed permissions, and embedded origins. Choose Confirm upgrade. The server fetches the manifest again and refuses the upgrade if the reviewed version has changed. New permissions remain ungranted; update the grant explicitly after the upgrade when needed. A failed upgrade keeps the current installation. After correcting the reported cause, check again.

Installed integrations can read saved content and history, create entries, save relations and media, move entries to Trash, read existing media and edit descriptions. The person’s current grants still apply. Embedded views run in an isolated frame. Field changes use the ordinary Save action. Vendor snippet scripts run inside isolated preview/site frames. The provider controls booking and form behavior; do not store provider secrets.

<!-- dee-wan-docs page: /plugins/authoring/ -->

# Writing a plugin

Source: https://dee-wan-docs.pages.dev/plugins/authoring/

A plugin is a separately deployed service. Core grants no database binding. Backend commands use
HTTPS; reviewed embedded UI runs in an isolated frame with host-authorized actions. This guide builds a plugin end to end: manifest, install, grant, launch, a conditional
publish command, and uninstall.

You need somewhere to run an HTTPS service and somewhere to keep its state. A Cloudflare Worker with
a D1 database is what the reference plugin uses (the Scheduling plugin source, `plugins/scheduling`
in the Dee Wan repository), and this document assumes that shape, but nothing in protocol v1
requires it.

Every request and response below is replayed against the real routes by Dee Wan's own test suite,
so what you read is what the server answers. The ids and secrets are synthetic and deliberately
invalid.

- [Protocol v1](/plugins/protocol-v1/) — every route, header, body, outcome and retry rule.
- [Plugin security](/plugins/security/) — tokens, delegation, scope and the threat model.
- [Testing a plugin](/plugins/testing/) — the contract checklist and a local two-service setup.
- Machine-readable: [`schemas/manifest-v1.schema.json`](/schemas/plugins/manifest-v1.schema.json),
  [`schemas/protocol-v1.schema.json`](/schemas/plugins/protocol-v1.schema.json).

## What you are responsible for

| You own | Dee Wan owns |
| --- | --- |
| Your service, its database, its clock and its retries | Content, versions, workflow rules, permissions, audit |
| Your own browser sessions and your own UI | Whether a transition is legal, and applying it atomically |
| Deciding when to ask | Deciding whether the answer is yes |
| Deleting your own data | Revoking your access |

Dee Wan never trusts a plugin's claim that a transition is allowed, that a version is current, or
that an unpublish is safe. Those are re-checked inside the mutation.

## 1. Serve a manifest

The manifest is one HTTPS document describing your plugin and what it wants. Dee Wan fetches it at
three moments, and never on ordinary requests:

- **Review** fetches and validates it, shows it to the administrator, and stores nothing.
- **Install** fetches it again, validates it again, and stores that copy. The stored copy is what
  every later check uses, so serve the same manifest at install that you served at review.
- **Upgrade** fetches it again from the stored manifest URL when an administrator accepts a new
  release (see [Shipping a new release](#shipping-a-new-release)).


```json
{
  "manifest_version": 1,
  "id": "com.example.myplugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "protocol_versions": [1],
  "base_url": "https://plugin.example",
  "activation_url": "https://plugin.example/dee-wan/activate",
  "management_url": "https://plugin.example/installations/{installation_id}",
  "requested_capabilities": [
    "content:read",
    "workflow:read",
    "workflow:publish",
    "workflow:unpublish"
  ],
  "content_actions": [{ "id": "schedule", "label": "Schedule" }]
}
```

Rules worth knowing before you write it, all enforced:

- `id` is a stable reverse-domain identifier: lowercase, starting with a letter, at least three
  dot-separated labels, at most 128 characters. It never changes across releases. `version` is your
  release and moves freely.
- `name` is 1 to 64 characters, with no control characters and no `<` or `>`.
- `version` is semantic versioning, `MAJOR.MINOR.PATCH` with an optional `-prerelease` suffix (no
  `+build` suffix), at most 64 characters.
- `manifest_version`, `protocol_versions` and `version` are three different things.
  `manifest_version` is `1`. `protocol_versions` lists 1 to 8 protocol versions you speak, and at
  least one must be a version this core speaks, or the manifest is `protocol_unsupported`.
- `requested_capabilities` lists at least one capability, with no duplicates.
- Every URL is HTTPS, carries no credentials and no fragment, and all of them — plus the manifest
  URL itself — must share ONE origin. A second origin is `manifest_origin_mismatch`.
- Unknown top-level keys are refused. A manifest cannot rely on a field this core ignores, so you
  cannot ship a key today and hope it is honoured later.
- Redirects are refused on the manifest fetch and on activation. Serve both directly.
- Private, loopback, link-local and reserved destinations are refused. For local development, see
  [Testing a plugin](/plugins/testing/#a-local-two-service-setup).
- `content_actions` is optional, and at most four `{ id, label }` pairs with unique ids. An `id`
  matches `^[a-z][a-z0-9_-]{0,31}$`. A `label` is 1 to 24 characters with no control characters and
  no `<` or `>`. No markup, no script, no CSS, no icon URL: core renders its own button with its own
  styling, and only on items whose model is in the installation's grant.
- `manage_views` is optional: a list of direct management pages from a closed vocabulary:
  `calendar` and `releases`. Core renders its own labelled link for each one on the installation in
  Settings → Plugins, and offers each beside the editorial calendar on the Dashboard and the Content
  list. The plugin supplies no label.
- `management_url` may contain `{installation_id}`, and is navigation only. It never receives a
  long-lived credential in a URL.
- `ui_extensions` is optional: 1 to 16 declarative additions to the Dee Wan screens. See
  [Cards and field editors](#cards-and-field-editors).

The full schema, generated from the object core validates with, is
[`schemas/manifest-v1.schema.json`](/schemas/plugins/manifest-v1.schema.json).

### Cards and field editors

`ui_extensions` adds cards and field editors to Dee Wan. Declarative controls use core components.
An optional reviewed `frame` loads an isolated editor or management view from the plugin origin.
The frame receives a bounded field value and a MessageChannel. It receives no admin session or
installation token. Field changes use ordinary Save; declared operations use the host authorization
and confirmation path. A field editor does not change its field's stored type.

```json
"ui_extensions": [
  {
    "id": "schedule-card",
    "placement": "entry_sidebar",
    "title": "Schedule",
    "description": "Plan when this goes live.",
    "launch": { "kind": "content_action", "action": "schedule" }
  },
  {
    "id": "calendar-row",
    "placement": "settings_row",
    "title": "Calendar",
    "launch": { "kind": "manage_view", "view": "calendar" }
  },
  {
    "id": "priority",
    "placement": "field_editor",
    "control": "select",
    "label": "Priority",
    "help_text": "How soon this should go out.",
    "options": [
      { "value": "low", "label": "Low" },
      { "value": "high", "label": "High" }
    ]
  }
]
```

- Each entry has an `id` that matches `^[a-z][a-z0-9_-]{0,31}$`, is unique in the manifest, and stays
  the same across releases. Model fields refer to it. `manage`, `core`, `dee-wan`, `workflow`,
  `history`, `seo`, `preview` and `settings` are reserved.
- `placement` is `entry_sidebar`, `page_sidebar`, `settings_row` or `field_editor`. Anything else is
  refused.
- A card has a `title` (1 to 40 characters), an optional `description` (1 to 160) and one `launch`.
  `{ "kind": "content_action", "action": "<id>" }` opens one of your `content_actions` for the item on
  screen. `{ "kind": "manage_view", "view": "calendar" }` opens one of your `manage_views`. A launch
  that names something the manifest does not declare is refused. A `settings_row` card launches a
  manage view only. Every launch goes through the delegated launch in section 5.
- A field editor draws an ordinary field. `control` is `text`, `textarea` or `url` for a text field,
  and `number`, `boolean`, `date` or `select` for a field of that type. The stored value stays a value
  of that type. `label` (1 to 40) names the editor, and `help_text` (1 to 200) is shown under it.
- A `select` editor lists 1 to 50 `options`, each `{ "value", "label" }` with a unique value. Text and
  textarea editors may set `validation.min_length` and `max_length`. A URL editor may set
  `max_length`, and Dee Wan adds its own `http(s)` rule. Number editors may set `min` and `max`. Date
  editors may set `min_date` and `max_date` as `YYYY-MM-DD`. Nothing else is accepted, so every rule
  is one the Dee Wan save path enforces.
- A `group` editor draws one JSON field as a small form. It lists 1 to 8 `members`, each with a
  unique `key` (`^[a-z][a-z0-9_]{0,31}$`), a `label` and a `control`: `text` (with a required
  `max_length` up to 500), `number` (`min`, `max`, `integer`), `boolean` or `select` (up to 12
  `options`). `required` makes a text, number or select member mandatory. The value is one JSON object
  of at most 8192 bytes. Dee Wan writes the closed schema onto the field when a site builder chooses
  your editor. By default, draft saves may leave required members empty; strict models require them
  on every save. Supplied values with invalid types or outside their bounds or choices, unknown
  member keys and non-object values are still refused. Publication always validates required members in the exact saved snapshot.
- A site builder chooses your editor on a model field. Dee Wan copies its rules and options into the
  field, so the field keeps them if your plugin goes away. When your installation is disabled or
  uninstalled, or a release drops the editor, the field keeps its value and Dee Wan draws its own
  editor with a note that names your plugin.
- Text is printable, with no control characters and no `<` or `>`. Unknown keys are refused.

### Operations and policies

`operations` are actions Dee Wan runs on your service and shows with its own form and result. A
person runs one from **Settings → Plugins** (`scope: "site"`) or from an entry (`scope: "entry"`). An
agent runs one through the management API or MCP. `policies` are checks Dee Wan asks before a save, a
restore, a deletion, a publication, an unpublication or a workflow move. A `save` or `restore` policy
may also tidy the content it is asked about.

```json
"operations": [
  {
    "id": "schedule-status",
    "label": "Schedule status",
    "description": "Pending scheduled changes for this entry.",
    "endpoint": "https://plugin.example/dee-wan/operations/schedule-status",
    "scope": "entry",
    "audience": "interactive",
    "requires": ["content:read"],
    "result": ["rows"]
  }
]
```

- `audience` is required. `interactive` operations appear in the admin, the management API, the CLI
  and MCP. `automation` operations never appear there and their run routes refuse them; only a named
  Dee Wan workflow calls one, such as the content planner calling Scheduling's `schedule-draft`.
- `endpoint` is on your manifest's one origin. `requires` names capabilities you also request. While
  the grant lacks one, the operation is not offered.
- `input` lists at most 8 fields: `text`, `number`, `boolean` or `select`. Dee Wan draws the form and
  checks the values. `result` names the components your answer may use: `text`, `rows`, `links`
  (https only) and `json`. Add `"destructive": true` only when the operation changes or removes data;
  Dee Wan then asks the person to confirm.
- Dee Wan POSTs a small envelope to `endpoint`. Exchange its `code` at
  `POST /api/plugin/v1/invocations/exchange` with your token, then answer the POST with
  `{ "status": "completed", "result": { "blocks": [...] } }` or
  `{ "status": "refused", "code", "message" }`. Answer only after the exchange. The protocol reference
  has the shapes and limits: [Operations and policies](/plugins/protocol-v1/#operations-and-policies).
- An `entry` operation's exchange also returns `delegation_id`: a delegation bound to the person who
  ran it, your installation, the entry and its model. Keep it when the operation starts later work,
  such as a schedule, and use it like a launch delegation. Dee Wan re-reads that person's authority
  on every use. A `site` operation's exchange returns a delegation like a `manage` launch: no entry,
  and the granted models the person reads. Scheduling's release operations run each item under it. A
  policy gets `null`.

```json
"policies": [
  {
    "id": "tone",
    "label": "Tone check",
    "kind": "save",
    "endpoint": "https://plugin.example/dee-wan/policies/tone",
    "requires": []
  }
]
```

- `kind` is one of:
  - `save`: each language whose values, links, media or search settings a save changes. You get the
    changed keys in `changed_fields` and the new parts in `values`, `links` (relation field → entry
    ids), `media` (media field → media ids) and `seo`. Shared links and media come with the primary
    language. A change to only links, media or SEO is asked about too (`seo` is the key for search
    settings).
  - `restore`: an old version restored (`action: "version"`, the same facts as a save) or an entry
    leaving Trash (`action: "trash"`). A version restore asks `save` policies as well.
  - `delete`: an entry or a language moved to Trash (`action: "trash"`) or deleted permanently
    (`action: "purge"`). You get the whole draft of each language.
  - `publish`: each language going live, the whole version. `unpublish`: each language going offline,
    the version that stops being served.
  - `transition`: every workflow move, with `transition: { from, to }`. Scheduled releases and other
    plugins' moves are asked too; `caller.via` says who moves it.
- Answer `{ "decision": "allow" }`, `{ "decision": "warning", "message", "fields"? }` or
  `{ "decision": "refuse", "code", "message", "fields"? }`. `fields` are field keys; the editor shows
  your message on them. A warning lets the write through; nobody submits twice.
- A `save` or `restore` policy may answer `{ "decision": "transform", "message"?, "values"?, "links"?,
  "media"?, "seo"? }` instead. It replaces those parts of the entry and language you were asked
  about, by field key. A list replaces the whole list. Shared links and media are taken only from the
  primary language's answer; a restore takes `values` and `seo` only. Dee Wan saves the result through
  every rule a person's input meets. If a rule refuses it, the write is refused as
  `plugin_policy_transform_invalid` with the reason; two policies changing one field differently refuse
  it as `plugin_policy_transform_conflict`. The editor then shows which fields your policy changed,
  with your message, and reloads the saved values. Nobody confirms a second time.

```json
{
  "decision": "transform",
  "message": "Trimmed spaces and normalized the title.",
  "values": { "title": "Harbour tours" }
}
```

- A refusal always stops the write. A timeout, an outage or an answer Dee Wan does not accept follows
  the site's choice in **Settings → Plugins**: by default the write goes through with a warning; with
  **Block changes if it does not answer** it is refused.
- Every path asks: the editor, page saves, restores, Trash, bulk actions, spreadsheets, imports, the
  management API and other plugins' writes. A transform changes only the entry being written; you
  never move a workflow.
- One path asks nothing: the scheduled purge that deletes items left in Trash past the retention
  window. Nobody acts there, so there is no one to refuse. A `delete` policy has already been asked
  when the item moved to Trash, and again if someone deletes it permanently by hand.
- The version history shows `Changed by <plugin> · <policy>` on a version your transform changed.

### Content-list columns and list actions

A `page` operation adds a column to the content list of a model in your grant. A flagged `entry`
operation becomes an action on the rows a person selects. Both use the invocation described above,
and Dee Wan draws every cell and every result.

```json
"operations": [
  {
    "id": "schedule-column",
    "label": "Scheduled",
    "endpoint": "https://plugin.example/dee-wan/operations/schedule-column",
    "scope": "page",
    "audience": "column",
    "requires": ["content:read"],
    "result": ["cells"],
    "cell": "badge"
  },
  {
    "id": "schedule-status",
    "label": "Schedule status",
    "endpoint": "https://plugin.example/dee-wan/operations/schedule-status",
    "scope": "entry",
    "audience": "interactive",
    "requires": ["content:read"],
    "result": ["rows"],
    "list_action": true
  }
]
```

- A column has `scope: "page"`, `audience: "column"`, one `cell` kind (`text`, `badge` or `link`),
  `result: ["cells"]`, no `input` and no `destructive`. Its label is the column header.
- The exchange returns `$defs/column_request`: the model and at most 50 ids of rows the person may read.
  No values; read what you need through your grant. Answer one `cells` block with at most one cell per
  id you were asked about: `{ "id", "text" }`, plus `tone` for a badge or an https `url` for a link.
  Text is at most 80 characters. A cell for another id, a repeated id, a link without an https `url` or a
  `url` on a badge makes the whole answer invalid. An empty list is a valid answer.
- A column binds no delegation, is never listed or run as an ordinary operation, writes no audit row
  and keeps no replayed answer. Do not store anything when you answer it.
- A list action is an interactive `entry` operation with `list_action: true`. Dee Wan runs it once for
  each of at most 25 selected rows, each with its own invocation, delegation, idempotency key and audit
  entry, so answer each as the entry operation it is.

### Rich text blocks

`rich_blocks` declares block types authors can insert into rich text. You send data only. Dee Wan
draws the fields, previews the block and renders it on the site from your declarative render tree.
This tree contains no executable script or remote calls. Vendor HTML/CSS/JS belongs in the separate
snippet block, whose preview and public output run inside an isolated frame.

```json
"rich_blocks": [
  {
    "name": "callout",
    "version": 2,
    "label": "Callout",
    "description": "A boxed note",
    "fields": [
      { "key": "tone", "control": "select", "label": "Tone", "required": true, "default": "info",
        "options": [{ "value": "info", "label": "Info" }, { "value": "warning", "label": "Warning" }] },
      { "key": "title", "control": "text", "label": "Title", "required": true, "validation": { "max_length": 80 } },
      { "key": "image", "control": "media", "label": "Image", "media_kind": "image" }
    ],
    "preview": { "tone": "info", "title": "Heads up" },
    "render": {
      "tone": "tone",
      "nodes": [
        { "element": "strong", "children": [{ "field": "title" }] },
        { "element": "img", "src": "image", "alt": "title" }
      ]
    },
    "migrations": [{ "from": 1, "to": 2, "steps": [{ "op": "rename", "from": "heading", "to": "title" }] }]
  }
]
```

- A block is stored as `<your plugin id>/<name>`, with the version it was saved with and its values.
- Controls: `text`, `textarea`, `number`, `boolean`, `select`, `url` and `media` (`media_kind`:
  `image`, `document`, `audio`, `video` or `file`; a `file` is a download the site's media
  settings let in). Rules: `required`, `min_length`/`max_length`,
  `min`/`max`/`integer`, select options. No patterns. A `url` value is an `http(s)` address or a site
  path. At most 24 fields.
- `rich_text` draws the host rich editor. Its value is `{ "richText": "<p>Formatted text</p>" }`, with canonical host HTML up to 10,000 characters. Bind `{ "field": "body" }` directly inside a block element to render paragraphs, lists, links, emphasis, images and files. The stored plugin figure carries a `<div data-rich-field="body">` child; host media traversal, pinning, import and export read its ordinary markup. Rich children cannot contain plugin blocks, snippets or embeds; inline plugin definitions cannot declare rich children. The same private-model media rules apply.
- `relation` uses `models` and optional `multiple`, with the ordinary relation picker and live actor
  read checks. `group` uses `fields`, optional `repeatable` and `max_items`; at most three nested
  group levels and fifty items per group. Nested media keep ordinary media pins. Render bindings
  scope children through `{ "group", "children" }` and `{ "each", "children" }`.
- `render.nodes` is a tree of: `{ "element", "children" }` from `div section aside p span strong em
  small h2 h3 h4 blockquote ul ol li figure figcaption hr br`; `{ "element": "a", "href": <url or
  media field> }`; `{ "element": "img", "src": <image field>, "alt"?: <text field> }`; `{ "text" }`;
  `{ "field" }` (a select shows its option label); and `{ "when", "equals"?, "children" }`. At most
  64 nodes, 8 levels deep. `render.tone` names a select field whose value (`neutral`, `info`,
  `success`, `warning`, `danger`) tints the block. Every value is escaped; an unsafe address renders
  its children without the link.
- Without `render`, the block can still be edited and stored, but renderers show it as unsupported:
  nothing on a public page, a placeholder in a preview.
- Raise `version` when the fields change and add one migration per step (`to` is `from + 1`):
  `rename`, `set_default` and `drop`. Stored blocks keep their version. Renderers and the editor
  migrate in memory; the stored block changes when an author updates it.
- Disabling or uninstalling your plugin never removes blocks. They stay stored with their version
  and values, and your next release may migrate them.
- Content is checked on save against active plugins only. See
  [the save rules](/guides/blog/#plugin-blocks). The management API lists definitions with
  `GET /api/manage/v1/rich-blocks` (`listRichBlockDefinitions`); the admin reads
  `GET /api/plugins/rich-blocks`; renderers read `GET /v1/_rich-blocks`.

### Media sources

`media_sources` turns your service into a library people browse inside Dee Wan's media picker, under
**Sources**, next to the site's own library. Request `media:source` and declare at most four sources:

```json
"requested_capabilities": ["media:source"],
"media_sources": [
  {
    "id": "library",
    "label": "Reference images",
    "description": "Seven self-made CC0 files.",
    "endpoint": "https://media-source.example/dee-wan/sources/library",
    "modes": ["copy", "reference"],
    "delivery_origins": ["https://media-source.example"]
  }
]
```

`modes` is required. `copy` lets people copy a file into the site's own library; `reference` lets them
link it instead, with your service keeping the bytes. A source declares one or both, and Dee Wan never
guesses the mode from a URL or a name. `delivery_origins` (one to four bare origins, your manifest's origin
may be one) is required with `reference` and absent without it.

- Core calls `endpoint` through the same invocation exchange as an operation: it POSTs the envelope,
  you exchange the code with your token, and the binding has `kind: "media_source"`, your source `id`
  and no delegation. The bound input is `$defs/media_source_request`: `{ "action": "browse", "query",
  "cursor", "limit" }` or `{ "action": "item", "item_id" }`.
- Answer a browse with `{ "status": "completed", "items": [...], "next_cursor": "..." | null }` and an
  item with `{ "status": "completed", "item": {...} }`. Each item has `id`, `title`, `file_name`,
  `mime_type`, `thumbnail_url`, `download_url` (required when the source declares `copy`),
  `delivery_url` (required when it declares `reference`) and `attribution` (`source_name`, `license`,
  and optional `author`, `author_url`, `license_url`, `source_url`). Add `width`, `height` and
  `byte_size` when you know them. An image's `description` (125 characters at most) becomes its alt
  text in the site's default language. Refuse with `{ "status": "refused", "code", "message" }`; the
  picker shows your message.
- `thumbnail_url` and `download_url` must be on your manifest's origin, and `delivery_url` on one of
  the source's `delivery_origins`. The picker loads previews
  straight from you with no referrer and no Dee Wan credential. When a person adds an item, core asks
  `item` again and GETs `download_url` itself: no credential, no redirect, 20 seconds, the media file
  limit. Sign `download_url` if your files are not public.
- Core checks the bytes like any upload: the site's kinds, formats and size limits, then its duplicate
  check. The copy is an ordinary media file owned by the site. It keeps your `attribution` and your
  plugin, source and item ids, which the media details show as its credit and site copies carry.
  Published pages get only `credit` (`author`, `source`, `license`, `url`), shown under the image.
  Nothing on the site loads from you again after a copy, so pages keep working if you go away.
- **Reference mode** links the file instead of copying it. Core fetches nothing: the library row keeps
  your `delivery_url` as its address, your plugin, source and item ids as its identity and the metadata
  and credit you declared, and the same item added again follows `on_duplicate`. Published pages, site
  copies and generated sites use the `delivery_url` as it is, so keep it served, and stable, for as long as
  sites use it. Dee Wan does not proxy it, cannot replace or edit its bytes (`media_external_bytes_unavailable`),
  and never calls you when a person deletes the library row. If your plugin is uninstalled or disabled,
  existing pages keep the stored address, the media details say the source is not available, and new
  links from it are refused. Add the mode with the request's required `mode`; a mode the source does not
  declare is refused with 422 `media_source_mode_unsupported`.
- Browsing changes nothing and is not audited. The person needs `media:upload`. Disabling the
  installation or removing `media:source` from the grant hides the source at once.
- The management API offers the same: `listMediaSources`, `browseMediaSource` and
  `importMediaSourceItem` (scope `media:write`, body `item_id` and `mode`). See [the management API](/reference/management-api/).
- `plugins/media-source-reference` is a complete, tiny example with tests. The conformance suite
  checks a source with its `mediaSource` subject (see [Testing a plugin](/plugins/testing/)).

### Pre-operation hooks

`hooks` let your service decide BEFORE Dee Wan accepts something. Declare at most one hook per kind:
`upload_metadata` is asked before a new library file is stored, `comment_moderation` before a visitor
comment is stored.

```json
"hooks": [
  {
    "id": "upload-check",
    "label": "Upload check",
    "kind": "upload_metadata",
    "endpoint": "https://plugin.example/dee-wan/hooks/upload",
    "requires": []
  },
  {
    "id": "comment-check",
    "label": "Comment check",
    "kind": "comment_moderation",
    "endpoint": "https://plugin.example/dee-wan/hooks/comment",
    "requires": []
  }
]
```

A hook is off until a site administrator turns it on for the installation in **Settings → Plugins**.
Declaring one asks for nothing and runs nothing. An unsupported `kind` is refused when the manifest is
validated.

- Core calls `endpoint` through the same invocation exchange as an operation. The binding has
  `kind: "hook"`, your hook `id`, `caller: null` and no delegation. The input is only what the decision needs: for
  an upload, `$defs/hook_upload_facts` (file name, MIME type, size, folder and alt texts, never the
  bytes); for a comment, `$defs/hook_comment_facts` (the entry, the comment's id, parent, author name,
  website and body, never the email). The person who initiated the operation is not identified.
- Answer an upload with `$defs/hook_upload_reply`: `{ "decision": "accept" }`, optionally with
  `normalized` (a new `filename` that keeps the extension, and alt texts only in languages the
  upload already named), or `{ "decision": "refuse", "code", "message" }`. The uploader sees your
  message (422 `upload_hook_refused`).
- Answer a comment with `$defs/hook_comment_reply`: `{ "decision": "approve" }`, `{ "decision": "hold" }`
  (the comment waits for a moderator) or `{ "decision": "reject" }` (stored as spam, or as refused with
  `"as": "refused"`).
- Answer within 5 seconds. A hook that times out, cannot be reached, answers something outside the closed
  replies, or is disabled while it runs never approves: the upload is refused (503
  `upload_hook_unavailable`, nothing stored) and the comment stays pending.
- A question has a stable retry identity. A retried upload or a re-sent comment gets your first
  accepted answer back for 24 hours without a new call; a failed question is asked again.

## 2. Accept the activation hand-off

Installation is a two-party hand-off, so your service needs one route before anybody can install it:
`activation_url`. Mint a one-time activation code, hand it to the administrator out of band, and
wait. The code must match `^[A-Za-z0-9_-]{16,128}$`. Anything else is refused by Dee Wan as
`invalid_activation_code` before your service is called. When they install, Dee Wan `POST`s this to
`activation_url`:


```json
{
  "kind": "activate",
  "installation_id": "plg_0000000000000000000000000000d1ee",
  "site_id": "cdocssite00000000000000001",
  "dee_wan_base_url": "https://cms.example",
  "protocol_version": 1,
  "token": "dwp_ExampleTokenNotRealExampleTokenNotRealExamp",
  "activation_code": "activation-code-0123456789"
}
```

What your handler must do:

1. Consume the `activation_code` exactly once, and refuse an unknown, used or expired one. This is
   the only thing proving the caller is the administrator you gave the code to.
2. Check `protocol_version` is one you speak and `dee_wan_base_url` is an origin you accept.
3. Store `token` as your secret for this installation — encrypted at rest, never logged, never in a
   URL or an error body.
4. Answer 2xx, within 5 seconds, with a body of at most 32 KB. Core marks the installation `active`
   only then, and stores only the token's SHA-256 hash. It can never show the token again.

Until your handler has returned, the installation is still `pending`, and a pending installation's
token answers `plugin_unauthorized`. So do not call `/api/plugin/v1` from inside the activation
handler — store the token, answer, and make your first call afterwards.

Where to call back: every protocol request goes to `dee_wan_base_url` followed by `/api/plugin/v1`,
for example `<dee_wan_base_url>/api/plugin/v1/context`. Store the base URL with the token, and accept
only origins you expect.

A `kind` of `rotate` is the same hand-off for an existing installation: replace the stored token.
Both kinds carry a code, because rotation is a hand-off and not a reset.

**When activation fails.** A non-2xx answer, a redirect, a body over 32 KB, or no answer within 5
seconds all make the install fail: core deletes its pending installation and shows the
administrator why. Core cannot see what your side did, though. If your handler stored the token and
then answered too late, you now hold a token for an installation that no longer exists, and your
activation code is already consumed. Plan for that:

- Keep the handler short, well inside the timeout.
- Treat a stored installation as unconfirmed until your first successful call with its token, and
  remove one whose token has never worked and now answers `plugin_unauthorized`.
- Tell the administrator to mint a fresh activation code for the retry. The retry is a new install
  with a new `installation_id`, not a second attempt at the old one.

## 3. Review, then install

An administrator with `site:plugins` reviews the manifest first. Nothing is stored by a review — it
exists so that approval is informed.

![Settings → Plugins after Review: requested capabilities and the site's models, each a checkbox, above the activation code](/assets/screenshots/plugins-review.webp)


**Review the manifest**

```sh
curl -X POST "https://cms.example/api/plugins/review" \
  -H "X-Site-Id: cdocssite00000000000000001" \
  -H "Content-Type: application/json" \
  -b "__Secure-better-auth.session_token=$SESSION" \
  --data '{"manifest_url":"https://plugin.example/dee-wan/manifest.json"}'
```

```json
{
  "data": {
    "manifest": {
      "manifest_version": 1,
      "id": "com.example.myplugin",
      "name": "My Plugin",
      "version": "0.1.0",
      "protocol_versions": [1],
      "base_url": "https://plugin.example",
      "activation_url": "https://plugin.example/dee-wan/activate",
      "management_url": "https://plugin.example/installations/{installation_id}",
      "requested_capabilities": [
        "content:read",
        "workflow:read",
        "workflow:publish",
        "workflow:unpublish"
      ],
      "content_actions": [{ "id": "schedule", "label": "Schedule" }]
    },
    "protocol_version": 1
  }
}
```

Then they install: the approved capabilities, the approved model ids, and your one-time code. Install
fetches and validates the manifest again, and that second copy is the one stored. The approved set
must be a subset of what that manifest requested. An empty `model_ids` means no content access at
all — not every model.


**Install, which activates**

```sh
curl -X POST "https://cms.example/api/plugins" \
  -H "X-Site-Id: cdocssite00000000000000001" \
  -H "Content-Type: application/json" \
  -b "__Secure-better-auth.session_token=$SESSION" \
  --data '{"manifest_url":"https://plugin.example/dee-wan/manifest.json","activation_code":"activation-code-0123456789","capabilities":["content:read","workflow:read","workflow:publish","workflow:unpublish"],"model_ids":["cdocsmodel0000000000000001"]}'
```

```json
{
  "data": {
    "id": "plg_0000000000000000000000000000d1ee",
    "plugin_id": "com.example.myplugin",
    "plugin_name": "My Plugin",
    "plugin_version": "0.1.0",
    "protocol_version": 1,
    "state": "active",
    "capabilities": [
      "content:read",
      "workflow:read",
      "workflow:publish",
      "workflow:unpublish"
    ],
    "requested_capabilities": [
      "content:read",
      "workflow:read",
      "workflow:publish",
      "workflow:unpublish"
    ],
    "model_ids": ["cdocsmodel0000000000000001"],
    "content_actions": [{ "id": "schedule", "label": "Schedule" }],
    "manage_views": [],
    "ui_extensions": [],
    "operations": [],
    "policies": [],
    "policy_modes": {},
    "hooks": [],
    "hook_modes": {},
    "manifest_url": "https://plugin.example/dee-wan/manifest.json",
    "management_origin": "https://plugin.example",
    "created_by_email": "admin@example.com",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}
```

No token and no hash appear in that response, in any later read, or in the audit entry the install
writes. Your service holds the only copy.

## 4. Narrow the grant

A grant can be changed at any time, and only within what the stored manifest requested. Removing a
capability or a model takes effect on your next request — there is no cache to wait for.


**Take away a capability this plugin turned out not to need**

```sh
curl -X PUT "https://cms.example/api/plugins/plg_0000000000000000000000000000d1ee/grant" \
  -H "X-Site-Id: cdocssite00000000000000001" \
  -H "Content-Type: application/json" \
  -b "__Secure-better-auth.session_token=$SESSION" \
  --data '{"capabilities":["content:read","workflow:read","workflow:publish"],"model_ids":["cdocsmodel0000000000000001"]}'
```

```json
{
  "data": {
    "id": "plg_0000000000000000000000000000d1ee",
    "plugin_id": "com.example.myplugin",
    "plugin_name": "My Plugin",
    "plugin_version": "0.1.0",
    "protocol_version": 1,
    "state": "active",
    "capabilities": ["content:read", "workflow:read", "workflow:publish"],
    "requested_capabilities": [
      "content:read",
      "workflow:read",
      "workflow:publish",
      "workflow:unpublish"
    ],
    "model_ids": ["cdocsmodel0000000000000001"],
    "content_actions": [{ "id": "schedule", "label": "Schedule" }],
    "manage_views": [],
    "ui_extensions": [],
    "operations": [],
    "policies": [],
    "policy_modes": {},
    "hooks": [],
    "hook_modes": {},
    "manifest_url": "https://plugin.example/dee-wan/manifest.json",
    "management_origin": "https://plugin.example",
    "created_by_email": "admin@example.com",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}
```

Asking for a capability outside the stored manifest is `400 invalid_capabilities`. A grant can
widen again later, but never past what the stored manifest requested.

### Shipping a new release

Publishing a new manifest at your URL changes nothing in an existing installation. Two explicit acts
by an administrator do:

1. **Accept the release** with `POST /api/plugins/:id/upgrade` and a body of
   `{"expected_version": "<the version they reviewed>"}`. Core fetches the manifest again from the
   stored manifest URL and refuses it as `manifest_changed_since_review` if its `version` is not the
   one named, as `manifest_identity_changed` if its `id` or its `base_url` origin changed, and as
   `protocol_changed` if the protocol version it would negotiate changed. On success it stores the
   new manifest, and keeps only the granted capabilities the new manifest still requests. Accepting
   a release can narrow a grant. It never widens one.
2. **Widen the grant**, if the release requests a new capability, with
   `PUT /api/plugins/:id/grant` as above. That is now allowed because the stored manifest requests
   it.

So a release that needs a new capability must say so in its own release notes: until an
administrator does both steps, your service keeps running with the old grant, and a command that
needs the new capability answers `capability_refused`.

## 5. Open your UI through a delegated launch

An ordinary delegated launch opens your management page in a new top-level tab. A declared,
reviewed `frame` opens an isolated editor or management view inside the admin and uses host-authorized
actions. Frames receive no admin session or launch code. Dee Wan session cookies stay in Dee Wan.
A delegated launch mints a one-time code, valid for 60 seconds,
stored hashed, bound to installation, site, user, action and — for a content action — one instance.

There are two kinds of launch. `manage` (no `instance_id`) opens your UI for the whole installation
and needs `site:plugins`. A `manage` launch that names a declared view is editorial: it needs no
`site:plugins`, only one granted model the person reads, all entries or only their own. A content action — one of your manifest's `content_actions` ids, with an
`instance_id` — needs read access to that item, and is refused as `model_not_granted` when the
item's model is not in the installation's grant. The admin UI only shows your action on items of
granted models in the first place.

A `manage` launch may also carry `"view"`, one of your manifest's `manage_views`. The launch URL then
adds `dee_wan_view=<view>` next to `dee_wan_launch`. It is a landing hint only: exchange the code as
usual, then send the session to that page. It grants nothing, so treat an unknown value as no hint.
A view your manifest does not declare is refused as `invalid_launch_action`.

A launch can also start from an agent. A management credential or connected app with the
`plugins:use` scope creates the same link through the management API or MCP (see
[Plugin launches](/reference/management-api/#plugin-launches)). Core runs the same checks, and a person
still opens the link. Your page sees an ordinary launch.


**Ask for a launch URL**

```sh
curl -X POST "https://cms.example/api/plugins/plg_0000000000000000000000000000d1ee/launch" \
  -H "X-Site-Id: cdocssite00000000000000001" \
  -H "Content-Type: application/json" \
  -b "__Secure-better-auth.session_token=$SESSION" \
  --data '{"action":"schedule","instance_id":"cdocsinstance00000000000001"}'
```

```json
{
  "data": {
    "url": "https://plugin.example/installations/plg_0000000000000000000000000000d1ee?dee_wan_launch=dwl_ExampleLaunchCodeExampleLaunchCodeExampleLa"
  }
}
```

The browser navigates there. The launch response from Dee Wan carries
`Referrer-Policy: no-referrer`, but the page the browser lands on is yours, and so is the rest of
the job:

- Send `Referrer-Policy: no-referrer` on your management page yourself, so the code in its URL
  cannot leak through a referrer.
- Load no third-party resource before the exchange.
- Once the exchange succeeds, redirect to the same page without `dee_wan_launch` in the URL, so the
  code does not stay in the address bar or the browser history. The reference plugin answers
  `303 See Other` to the clean URL.

Your BACKEND exchanges the code, with your installation token:


**Exchange the code for a delegation**

```sh
curl -X POST "https://cms.example/api/plugin/v1/launch/exchange" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  --data '{"code":"dwl_ExampleLaunchCodeExampleLaunchCodeExampleLa"}'
```

```json
{
  "data": {
    "delegation_id": "pld_0000000000000000000000000000d1ee",
    "installation_id": "plg_0000000000000000000000000000d1ee",
    "site_id": "cdocssite00000000000000001",
    "action": "schedule",
    "instance_id": "cdocsinstance00000000000001",
    "model_ids": ["cdocsmodel0000000000000001"],
    "user": { "id": "cdocsuser00000000000000001", "email": "admin@example.com" }
  }
}
```

Now create your OWN session cookie for that browser, and store `delegation_id` against it. The
delegation is not a credential and grants nothing by itself: it names the person who asked, and
every command you later send carries it so that core can re-read their authority at execution time.

What a delegation can be used for:

- A **content-action** delegation (one with an `instance_id`) acts only on items in the same
  translation group as that instance. Naming it for any other item is `requester_unauthorized`.
- A **manage** delegation (`instance_id` is `null`) acts on items of the models in its `model_ids`.
- Every delegation carries `model_ids`: the granted models its person could read at launch, all
  entries or only their own (for a content action, the item's model). Show and act only inside them.
  An item of another model, or one the person can no longer read, is `requester_unauthorized`.
- `GET /api/plugin/v1/delegations/<delegation_id>` says what the delegation reaches now: each model,
  the transition kinds the person may take there, and `entries`. Ask before each page. Offer moving or
  cancelling planned work only for a listed kind.
- `entries: "all"`: the person reads every item of that model and the kinds hold for each.
  `entries: "checked"`: the person reads or updates only their own items there (`read:own`,
  `update:own`). Ask `GET /api/plugin/v1/delegations/<delegation_id>/entries?instance_id=…` (up to
  100 ids) which items to show and what each allows. Show nothing it leaves out. Do not copy who owns
  what into your own store; ask again on each request.
- A delegation a management credential opened carries a capability ceiling: only the installation
  capabilities that credential's scopes allow. A command outside it is `capability_refused`.
- Core does not check the delegation's `action` when you send a command. It is there so your own UI
  knows which screen to show.
- A delegation has no time limit, because scheduled work may run long after the person launched
  your UI. It stops working when that person no longer holds the authority the command needs — they
  lost the permission, their role on the site, or their account — and when the installation is
  disabled, uninstalled, or its token is no longer valid. Their current authority is re-read on
  every command.

See [Plugin security](/plugins/security/#launch-delegation-and-the-delegation_id).

## 6. Read content, and pin exactly what you intend to move

Before you record any intent, read the item with the delegation. The `workflow` block tells you
what that person may actually do now, and gives you the values to pin.

Reading an item needs `content:read`. The `workflow` block — and with it `workflow.revision`, which
every transition command must send — is only returned when the installation also holds `workflow:read`.
Without it you get the summary alone, and have no revision to pin. A plugin that sends commands
therefore requests both.


A delegated read also returns `saved`, projected to the current person’s field/locale grants.
The response below shows summary keys.

**Read one item as the person who asked**

```sh
curl "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001?delegation_id=pld_0000000000000000000000000000d1ee" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "translation_group_id": "cdocsgroup0000000000000001",
    "model_id": "cdocsmodel0000000000000001",
    "model_slug": "article",
    "lang": "en",
    "label": "Hello",
    "slug": "hello",
    "current_version_id": "cdocsversion00000000000001",
    "published_version_id": null,
    "workflow": {
      "state": "draft",
      "revision": 0,
      "transitions": [{ "to": "published", "kind": "publish" }]
    }
  }
}
```

Store, against your own record:

- `primary_instance_id` — the instance a transition addresses. Publication applies to the whole
  translation group, and the primary is the group's handle.
- `current_version_id` for an ordinary draft publish, or `published_version_id` for an unpublish. That is the pin.
- `workflow.revision`.
- The `to` and `kind` you chose, which must be one of the offered `transitions`.

Independent future versions use `POST /api/plugin/v1/content/:instanceId/futures` to create a branch
and `GET /api/plugin/v1/content/:instanceId/futures/:futureId` to read it. Pin that branch’s saved
`current_version_id` for publication, together with `future_draft_id` and `expected_future_revision`.
Core binds it to the installation, release and entry, then freezes the exact revision when its
publication command starts. Current authority, workflow, required fields and review tasks are checked
against that snapshot; the ordinary draft stays unchanged. Retry an uncertain result with the same
command, version and idempotency key. The command below publishes an ordinary draft.

## 7. Send the command

One mutation, conditional on everything you pinned, with an idempotency key you can derive again.


**Publish the pinned version**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0001:r1" \
  --data '{"kind":"publish","expected_current_version_id":"cdocsversion00000000000001","expected_workflow_revision":0,"delegation_id":"pld_0000000000000000000000000000d1ee"}'
```

```json
{
  "outcome": {
    "code": "transition_applied",
    "message": "The transition was applied.",
    "retry": false
  },
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "from": "draft",
    "to": "published",
    "published": true,
    "published_changed": true,
    "published_version_id": "cdocsversion00000000000001",
    "revision": 1,
    "redirect": {
      "status": "none",
      "reason": "no_public_address"
    },
    "policy_results": []
  }
}
```

`redirect` is present when the transition publishes. It reports the automatic redirect core made for a
changed address, or why it made none. A replay of the same command returns this same body.

Derive the key from your own record and its revision, never from the clock. The reference plugin
uses `sched:<installation_id>:<record_id>:r<revision>`, which is the shape of the key above. Core
accepts any 1 to 128 printable ASCII characters with no spaces. Then:

- An exact replay returns the first result as `idempotent_replay`. A retry after a timeout is safe.
- A publish that moves an address writes its redirect after the transition commits. Until that
  outcome is recorded, the command and its replays answer `temporary_failure` saying the transition
  was applied. Retry with the same key and body. You never get a result without its `redirect`.
- The same key with different input is `idempotency_key_reused`. Rescheduling is a new revision, so
  a new key.
- Every refusal is named and terminal except `rate_limited` and `temporary_failure`. Read the table
  in [Protocol v1](/plugins/protocol-v1/#outcomes) and handle each one. Do not turn an unknown failure
  into success, and do not retry forever.

The audit trail records this as the plugin acting, not as a user: the workflow event names the
installation, your plugin id, name and accepted version, the protocol version, a digest of the
idempotency key, and the person whose delegation authorised it. The admin UI shows your plugin's
name as the actor.

## 8. Uninstall

Uninstall revokes first. The state becomes `revoked`, both token hashes are dropped, and that token
can never be valid again.


**Uninstall**

```sh
curl -X DELETE "https://cms.example/api/plugins/plg_0000000000000000000000000000d1ee" \
  -H "X-Site-Id: cdocssite00000000000000001" \
  -b "__Secure-better-auth.session_token=$SESSION"
```

```json
{ "data": { "id": "plg_0000000000000000000000000000d1ee", "state": "revoked" } }
```


**Every later request, including one already in flight in your queue**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "plugin_unauthorized",
    "message": "The installation token is missing, unknown, disabled or revoked.",
    "retry": false
  }
}
```

Two things follow, and both belong in your own documentation:

- Audit attribution survives. The workflow event stored a snapshot of your installation rather than
  a foreign key, so uninstall cannot erase who published what.
- Dee Wan does not claim to have deleted anything you hold. Remote deletion is your action, and your
  documentation has to say what you keep, for how long, and how an operator removes it. The
  reference plugin's answer is in
  [Scheduling, end to end](/plugins/scheduling-end-to-end/).

## What to build next

Protocol v1 deliberately gives you no scheduler, no queue and no event stream. If your plugin acts
later, you own:

- a lease, so two of your workers cannot execute one record at once — `Idempotency-Key` is core's
  second guard, not your first.
- bounded retries with jitter, an attempt cap and an age cap, and `Retry-After` honoured within a
  maximum you choose.
- a terminal-failure table your users can read, because every conditional refusal means a person has
  to decide something.
- your own authorisation for your own UI. Core checks the launch. After that, the session is yours.

The Scheduling plugin source (`plugins/scheduling` in the Dee Wan repository) is a complete worked
example of all four. Its behaviour is described in the [Scheduling plugin](/plugins/scheduling/)
page.

## Reusable relation values

Relation controls store entry IDs. Public reads resolve them through ordinary published relation
authority and locale selection. `{ "field": "target" }` renders the current published title/name.
`{ "field": "target", "property": "address" }` renders a projected scalar field from that target.
An anchor with `href: "target"` uses the shared live Page/Blog/managed-route address, or the target's public `url` field.
An entry with no public address renders its link children without an anchor. Missing, draft,
withdrawn, trashed or unreadable targets contribute no labels or addresses. Private fields stay out.
Resolved labels are read output; normal saves accept IDs, not supplied label/URL objects.

Site copies and history carry `rich-relations.json`: source version, rich-value pointer, typed
reference pointer, target ID and allowed models. The file is counted and checksummed. Apply remaps
nested and repeatable IDs after entries exist. Missing current targets block; omitted older-history
targets use the existing named dropped-relation finding. Snippets use `snippet:<source id>` as owner.
A missing or unsupported source declaration refuses export by name. Restore the matching source
declaration and export again. Destination declarations never decide which source strings are IDs.

### Structured inline declarations

Set `inline: true` on a `rich_blocks` declaration to offer it inside rich-text paragraphs. Fields,
values, media and relation references, declared versions and migrations use the existing block
contract. The stored element is `<span data-inline="plugin">` with `data-type`, `data-version` and
`data-values`; declared media remain empty reference links inside it. Do not send rendered HTML.

Inline render trees allow only `span`, `strong`, `em`, `small`, `a`, `img` and `br`, including inside
conditional and group nodes. Block tone and block elements are refused. An inline item is not a link
wrapper: the host refuses nesting it inside an existing link. Its dialog uses the same host fields
and its published output uses the same escaped renderer as the block form.

### Renderer metadata contributions

Declare bounded contributions in `renderer_metadata` and request `renderer:metadata`. Each declaration
has `key`, `label`, `meta_names`, `link_rels` and `schema_types`. Installation review grants them; new
capabilities on an upgrade remain off until reviewed. A contribution may send only declared metadata
names, link relations (`alternate`, `related`, `author`, `license`) and JSON-LD schema types.

Use delegated `POST /content/:instanceId/renderer-metadata` with an `Idempotency-Key` header and
`{ delegation_id, locale, expected_version_id, contributions }`. Each contribution has its declared
`key` and optional `meta`, `links` and `json_ld`. The write replaces only this plugin's contributions
in the named locale. It creates an ordinary content version and stays a draft until publication.
A stale version, missing grant or field/locale restriction refuses the whole write.

The accepted content version carries the data. Public delivery never calls the plugin. Existing
SEO titles, descriptions, canonical/robots settings, site verification and published locale alternates
win. Contributions merge by plugin ID and key; duplicate names and locale links resolve deterministically.
Markup, executable addresses, arbitrary contexts and invalid links are refused. Shared SEO serialization
is used by managed output, generated output and signed preview; previews remain unindexable.

## Contextual email recipients

Declare `mail_templates` and request `mail:send`. A site administrator reviews the text and recipient policy under **Settings → Plugins → Email templates**. Plugins never submit raw recipients or message text.

For a reviewed `entry_author` or `entry_assignee` template, send `POST /api/plugin/v1/mail/send` with `Idempotency-Key` and `{delegation_id, template, instance_id, variables}`. The entry must be inside the installation and delegation’s model/item grants, and the actor must still read it and hold `site:plugins`. A matching content-action delegation works; fixed-address templates continue to require a manage delegation and omit `instance_id`.

`entry_author` resolves the account that created the selected CMS entry (`content_instance.created_by_id`), not a public Blog author/profile relation or the last editor. `entry_assignee` resolves its current workflow assignee (`content_workflow.assigned_to_id`). The account must be active and have current site and entry read access; an active superadministrator may qualify without an explicit site membership. Missing assignment, missing author or ineligible account gives `validation_failed`; the response never returns an address. Keep the same key and input after an uncertain result. Core reuses the accepted recipient/message and checks the original account again rather than redirecting a retry after reassignment. See [approved mail commands](/plugins/protocol-v1/#post-apipluginv1mailsend) for bounds and outcomes.

<!-- dee-wan-docs page: /plugins/testing/ -->

# Testing a plugin

Source: https://dee-wan-docs.pages.dev/plugins/testing/

This guide explains what to prove before using a plugin with real content, how to test it against a fake core in your own suite, how to run both services on one machine, and how to produce each failure deliberately.

See [Protocol v1](/plugins/protocol-v1/) for the surface under test and [Plugin security](/plugins/security/) for
the invariants the cases below exist to protect.

## The contract

These are the test cases a plugin must cover. Each one is a property of the protocol rather than of any
particular plugin, so each one belongs in your suite whatever your plugin does.

| Case | What must happen |
| --- | --- |
| Activation | A one-time code is consumed exactly once. An unknown, used or expired code is refused. The raw token is stored encrypted and never logged. The handler answers well inside 5 seconds and makes no protocol call of its own |
| Rotation | `kind: rotate` replaces the stored token. The old one stops being used by every worker. A refused rotation leaves the old token in place |
| Launch | A code is exchanged once, through the plugin's backend. A second exchange fails. A code minted for another installation fails. The management page sends `Referrer-Policy: no-referrer` and drops `dee_wan_launch` from the URL after the exchange |
| Session | The plugin's own browser session is created at exchange, is its own cookie, and carries no Dee Wan credential |
| Pinning | Publish pins `current_version_id`, unpublish pins `published_version_id`, both pin `workflow.revision`, and the chosen `(kind, to)` came from the delegated read |
| Idempotency | The key is derived from the record and its revision, is identical on every retry, and changes when the record is rescheduled |
| At most once | Only the current lease owner may start a delivery. Its request deadline must precede lease expiry. Recovery may repeat the request with the same key and body. Core must apply the effect at most once within retention. A timeout does not prove a remote request stopped |
| Replay | `idempotent_replay` settles as success, not as a new effect |
| Terminal refusals | `invalid_request`, `plugin_unauthorized`, `capability_refused`, `requester_unauthorized`, `content_not_found`, `scheduled_target_stale`, `workflow_conflict`, `dependent_content`, `idempotency_key_reused`, `transition_unavailable` and `transition_refused` each settle without a retry, under their own name |
| Retries | Valid structured `rate_limited`/429 and `temporary_failure`/503, bare 429/500/502/503/504 without an outcome, and network/timeouts retry within attempt AND age caps. Honour valid bounded `Retry-After`. Otherwise back off with jitter |
| Untrusted responses | A present but malformed outcome, unknown code, incorrect retry flag or status/code mismatch is terminal even on a retryable status. A body without an outcome is terminal outside the listed fallback statuses. Redirects are never followed |
| Isolation | Every table and every query is scoped by installation. One installation cannot read, cancel or execute another's records |
| Revocation | After uninstall, pending work refuses with `plugin_unauthorized` and the plugin says so rather than retrying |
| Secrets | No test fixture, log line, error body or screenshot contains a token, a launch code or an activation code |
| Writes for a person | A field write, draft, media upload or proposal names the delegation of the person it is for, pins the version or draft revision it read, carries an `Idempotency-Key`, and treats `version_conflict` and `draft_conflict` as a person's decision, not a retry |

The Scheduling plugin source (`plugins/scheduling` in the Dee Wan repository) has a suite that is a
worked example of every row, in `test/activation.test.ts`, `launch.test.ts`, `schedules.test.ts`,
`runner.test.ts`, `recovery.test.ts`, `time.test.ts`, `isolation.test.ts` and `flow.test.ts`. Its
`test/conformance.test.ts` runs the protocol cases of `@dee-wan/plugin-conformance` against it.

## Prove it against a fake core

Do not point your suite at a running Dee Wan. A fake core is deterministic, can inject failures a
real one will not produce on demand, and runs in milliseconds.

`@dee-wan/plugin-conformance` is the installable protocol v1 suite. Its source is
`packages/plugin-conformance` in the Dee Wan repository, where it is built and tested. It is NOT
published to the npm registry yet; publishing it needs authority. Until it is, a plugin in another
repository builds it from a Dee Wan checkout and installs the tarball:

```sh
cd packages/plugin-conformance     # in a Dee Wan checkout
npm install
npm pack                           # writes dee-wan-plugin-conformance-0.1.0.tgz
cd /path/to/your-plugin
npm install --save-dev /path/to/dee-wan-plugin-conformance-0.1.0.tgz
```

It carries the published schemas, so it reads nothing from a Dee Wan checkout at run time. It
exports:

| Export | What it is |
| --- | --- |
| `createFakeCore()` | A `fetch` implementation that plays Dee Wan core for one or more installations |
| `runConformance({ describe, it }, subject)` | Registers the protocol cases with vitest, `node:test` or jest |
| `conformanceCases(subject)` | The same cases as plain async functions |
| `validateManifest(value)`, `validateShape(name, value)` | Validation against the published manifest schema and the protocol `$defs` |
| `OUTCOMES`, `CAPABILITIES`, `TRANSITION_KINDS`, `PROTOCOL_VERSIONS`, `INBOUND_RETRY_STATUSES`, `SECRET_PATTERNS` | The published protocol data |

The fake core:

- authenticates a bearer token per installation, and answers `plugin_unauthorized` otherwise
- answers `/context`, `/content/:id` and `/launch/exchange` with protocol-shaped bodies, including
  the `workflow` block and the transitions the installation's capabilities and a delegation permit
- applies the installation's capability and model grant, and refuses a delegation that does not
  cover the item, the way core does
- refuses a command body that is not the published `transition_command` with `invalid_request`
- checks the pin and the workflow revision on a command, and answers `scheduled_target_stale` or
  `workflow_conflict` when they no longer hold, and `dependent_content` for an item marked with
  dependents
- keeps an idempotency record per key, so an exact replay answers `idempotent_replay` with the whole
  first result and a reused key with different input answers `idempotency_key_reused`
- reports `redirect` on every publish result, from the item's `redirect` field, and none on unpublish
- moves one language when a command names `locale` and the installation holds `workflow:locale`, and
  lists each language under `workflow.locales` for that installation
- consumes a launch code once and refuses it for another installation
- mints invocation envelopes with `createInvocation`, and consumes an invocation code once at
  `/invocations/exchange`, for the installation it was minted for, before it expires
- answers the write routes — `PUT /content/:id`, `PUT /drafts`, `POST /drafts/discard`, `GET /drafts`,
  `POST /media`, `POST` and `GET /content/:id/proposals`, `GET /proposals/:id` — with the published
  shapes, the capability, grant and delegation checks, version and draft-revision pins and
  per-key replay; field values replace the item's version, a draft belongs to the delegated person,
  and a proposal changes nothing
- pins a one-language publish to the group's current version and a one-language unpublish to that
  language's own live version, as core does
- injects failures on demand — a network error, a reply lost after the command was applied, any
  status, any `outcome.code`, a `Retry-After` header, or a deliberately malformed body
- records requests separately from applied effects, so recovery can resend the same key while the
  effect occurs at most once.

It does not answer the paginated `/content` list.

`runConformance` takes a subject: your manifest, your copy of the protocol data, your reply
classifier, and optional adapters for activation, launch exchange, delivery, operation invocation
(required when the manifest declares `operations`) and media source invocation (`mediaSource`,
required when it declares `media_sources`). A plugin that sends no commands, such as a media source,
leaves out the protocol copy and the classifier. Each adapter starts a
fresh instance of your plugin wired to a fake core. A minimal vitest file:

```ts
import { runConformance } from '@dee-wan/plugin-conformance';
import { describe, it } from 'vitest';
import { subject } from './conformance-subject';

runConformance({ describe, it }, subject);
```

The cases: your outcome table, retry statuses, capabilities, transition kinds, protocol version and
secret shapes equal the published ones; your manifest validates; every outcome code, wrong status,
wrong retry flag, malformed outcome and bare status classifies as the protocol says; activation
codes are single-use and rotation codes are bound to their installation; a launch code is exchanged
once; and through your own delivery path, a pinned command is sent once, a lost reply is resent
with the same key and body and applied once, every terminal outcome settles under its own name and
is never sent again, retryable outcomes retry, and a stale pin, a changed workflow, dependents, a
person who lost the permission and an uninstall each refuse. For each declared operation, the
plugin answers only after exchanging the code once, with a reply the published schema accepts and
only declared result components, and never answers `completed` for a refused code, a code minted
for another installation or an envelope with an unknown key. For each declared content-list column,
the exchange binds no delegation and the plugin answers one `cells` block for the rows it was asked
about only, each row once, each cell drawn as the declared `cell` kind (a `url` on a link and on no
other, a `tone` on a badge and on no other). For each declared media source, a
browse is answered only after the exchange, with every preview and download URL on the manifest's
origin and every delivery URL on a declared delivery origin; the declaration names its `modes` and
has `delivery_origins` exactly when it declares `reference`; its own `next_cursor` leads to a page that repeats no item; an item it listed is answered as
that item; and it never answers `completed` for a refused code or another installation's code. The
Scheduling plugin's `test/conformance.test.ts` is a complete subject;
`plugins/media-source-reference/test/conformance.test.ts` is one for a media source.

The fake core is not the real core, and it supports only a two-state draft/published workflow.
Assert on `outcome.code` and HTTP status, never on the human message — core's messages are for
people and are not stable.

The Scheduling plugin's `test/helpers/d1.ts` is a short `better-sqlite3` shim with D1's
`prepare`/`bind`/`first`/`all`/`run`/`batch` surface, so the plugin's real SQL — including its
compare-and-set claims and its partial unique index — runs in the suite. It applies every file in the
plugin's `migrations/`. Copy it and point it at your own migrations.

To run the reference plugin's suite:

```sh
cd plugins/scheduling
npm test          # vitest
npm run typecheck
```

Inside the Dee Wan repository its tools resolve from the repository root's install
(`node scripts/install-dependencies.mjs` at the root), and `@dee-wan/plugin-conformance` is linked
from `packages/plugin-conformance`: run `npm run build` there first.

## Validate against the published schemas

Two JSON Schema documents are generated from the definitions core validates with, and published
with each release:

- [`schemas/manifest-v1.schema.json`](/schemas/plugins/manifest-v1.schema.json) — validate your manifest in
  your own CI, before an administrator ever fetches it.
- [`schemas/protocol-v1.schema.json`](/schemas/plugins/protocol-v1.schema.json) — request and response
  shapes under `$defs`, plus the machine-readable `outcomes` table (HTTP status and retry flag per
  code), `capabilities`, `installation_states` and `limits`.

The `outcomes` table is the one worth wiring in: a plugin that keeps its own copy — the reference
plugin does, in `src/protocol.ts`, because it cannot import from core — should assert that its copy
equals the published one, so a status or retry flag that drifts fails your build rather than your
production runs. The protocol copy cases of `runConformance` do exactly that.

## A local two-service setup

Both services on one machine, with no Cloudflare account and no real credential. This is the one
local setup for plugin work. [Scheduling, end to end](/plugins/scheduling-end-to-end/)
starts from it.

You need the Node version pinned by `.nvmrc` in the Dee Wan repository, `openssl`, and these ports:
8787 (Dee Wan's admin Worker), 5173 (the admin UI) and 8788 (the plugin).

**Port 8788 is also the default of `npm run local:public`**, Dee Wan's public read Worker. If you
run that too, give one of them another port: `npm run local:public -- --port 8789`, or run the
plugin on another port and use that port everywhere `8788` appears below.

### Dee Wan

In `backend/.dev.vars` in the Dee Wan repository (create it if it does not exist), add the plugin's
origin:

```ini
PLUGIN_DEV_ORIGINS=http://localhost:8788
```

That is the only setting you add. The local admin Worker's configuration already sets
`ENVIRONMENT=development`, which is what lets `PLUGIN_DEV_ORIGINS` be read at all, and
`BACKEND_URL=http://localhost:8787`, which is what core sends to your plugin as `dee_wan_base_url`.
`PLUGIN_DEV_ORIGINS` is an exact-origin allowlist — no wildcard, no private-range shortcut — checked
against the manifest, base, activation and management URLs. Without the entry, installing from
`http://localhost:8788` is refused as `url_not_https`.

Then, from the repository root, each long-running command in its own terminal:

```sh
node scripts/install-dependencies.mjs
node scripts/install-dependencies.mjs frontend
npm run local:migrate
npm run local:api       # admin Worker on http://localhost:8787   (leave running)
npm run local:seed      # needs local:api running; prints the sign-in it creates
npm run local:admin     # admin UI on http://localhost:5173       (leave running)
```

### The plugin

For the reference plugin, from the repository root:

```sh
cd plugins/scheduling
cp wrangler.example.jsonc wrangler.jsonc
```

The placeholder `database_id` in the copied file is fine: `--local` never contacts Cloudflare, so
there is no `wrangler d1 create` step. Next to it, create `.dev.vars`:

```ini
ENVIRONMENT=development
PUBLIC_ORIGIN=http://localhost:8788
DEE_WAN_DEV_ORIGINS=http://localhost:8787
ADMIN_SECRET=local-admin-secret-0123456789
TOKEN_KEY=<the output of: openssl rand -base64 32>
```

- `.dev.vars` overrides the production values in `wrangler.jsonc` for `wrangler dev`.
- `DEE_WAN_DEV_ORIGINS` is the plugin's mirror image of `PLUGIN_DEV_ORIGINS`: the one non-HTTPS Dee
  Wan base URL it accepts, and only when `ENVIRONMENT=development`.
- `ADMIN_SECRET` is the operator bearer for the plugin's `/admin/*` routes, and must be at least 16
  characters.
- `TOKEN_KEY` is the base64 of 32 random bytes and encrypts stored installation tokens at rest. Lose
  it and every installation has to be rotated.

```sh
npx wrangler d1 migrations apply dee-wan-scheduling --local
npx wrangler dev --port 8788 --test-scheduled       # leave running
curl http://localhost:8788/dee-wan/manifest.json    # the manifest names http://localhost:8788
```

Mint a one-time activation code:

```sh
curl -X POST -H "Authorization: Bearer local-admin-secret-0123456789" \
  http://localhost:8788/admin/activation-codes
```

It answers `201` with `{ "code", "purpose", "installation_id", "expires_at" }`: `purpose` is
`activate`, `installation_id` is `null`, and `expires_at` is 15 minutes ahead, in milliseconds since
the epoch.

A plugin of your own needs the same three things: serve it on the origin you allowed, accept
`http://localhost:8787` as a base URL only in development, and have a way to mint an activation
code.

### Install

Sign in to the admin UI at `http://localhost:5173` with the account `local:seed` printed, then
**Settings → Plugins**: review `http://localhost:8788/dee-wan/manifest.json`, grant a capability set,
pick the models, and install with the code. Open a content item of a granted model and use the
action your manifest declared.

Do the installation through the UI rather than by hand: the administrative routes want a real
session, the site header and `site:plugins`, and the UI already has all three.

Two local gotchas:

- A `__Host-`/`Secure` session cookie needs HTTPS or `localhost` exactly — not `127.0.0.1`.
- A cron trigger does not fire in `wrangler dev` unless you ask it to. With `--test-scheduled`,
  `curl "http://localhost:8788/__scheduled?cron=*+*+*+*+*"` runs one tick.

## The automated cross-service run

The reference plugin and core run against each other, both live, in one command. With the Node
version `.nvmrc` pins, prepare a Dee Wan checkout, then run the plugin's script:

```sh
node scripts/install-dependencies.mjs
npm run build:packages
npm --workspace backend run prisma:generate
cd plugins/scheduling
npm run test:cross-service
```

The test lives in the plugin, at `test/cross-service/cross-service.test.mjs`. Outside the Dee Wan
repository, set `DEE_WAN_CORE_DIR` to the prepared Dee Wan checkout. It needs no Cloudflare
account, no credential and no network beyond `127.0.0.1`. It takes two to three minutes, because it
schedules for a real wall-clock minute and waits for it.

What it starts, each on a free port it picks, and stops again, with its temporary directory:

- Dee Wan's admin Worker under `wrangler dev`, on a fresh migrated local D1, with
  `PLUGIN_DEV_ORIGINS` naming the plugin.
- the Scheduling plugin under `wrangler dev --test-scheduled`, from a generated copy of
  `wrangler.example.jsonc`, on a fresh migrated local D1.
- an HTTP proxy in the test process. Core's `BACKEND_URL` names it, so every plugin call to core
  passes through it. It forwards requests and replies unchanged, apart from the `Host` header. It can
  drop a request before forwarding it, or drop the reply after core answered, and it records each
  transition command it saw. The proxy intercepts network traffic; every answer comes from core.

Everything goes through the real routes: the bootstrap claim and sign-in, the `/api/plugins` calls
Settings → Plugins makes, delegated launches, the plugin's own HTML forms, and `/__scheduled` ticks.
It checks:

| Case | What it asserts |
| --- | --- |
| Activation | Install through core activates the plugin. Reusing the activation code is refused `activation_refused` |
| Delegated launch | Each schedule is created through `POST /api/plugins/:id/launch`, the plugin's exchange and its form. The confirmation shows the local time, its zone and the UTC instant |
| Before due | A tick before the due minute sends nothing |
| Publish, reply lost | Core applies the publish, the proxy drops the reply, the plugin retries with the same key and byte-identical body, and core answers `idempotent_replay` with the same result data as the dropped reply, `redirect` included. One plugin workflow event, attributed to the installation and the delegating person |
| Publish, request lost | The proxy drops the first request unforwarded. The plugin retries and core answers `transition_applied` |
| Unpublish | The pinned published version is unpublished |
| `scheduled_target_stale` | The draft was edited after pinning |
| `workflow_conflict` | The item was published and unpublished by hand after pinning |
| `transition_unavailable` | The item was published by hand after a publish was pinned |
| `dependent_content` | A published item relates to the one being unpublished |
| Cancellation | Cancelled in the plugin UI. Core is never called |
| Isolation | One installation's session cannot read or cancel another installation's schedule |
| Revocation | Core uninstalls an installation with a pending schedule. The plugin settles it `plugin_unauthorized` |
| Settled stays settled | Every refused or cancelled case leaves core's state, revision and publication pointer unchanged, and a later tick sends nothing |

Dee Wan's CI does not run it. The plugin's own CI, `.github/workflows/ci.yml` in the plugin
directory, runs it against a Dee Wan checkout once the plugin is in its own repository. Until then,
run it by hand when a change touches either side of protocol v1.

### The browser run with the plugin live

`frontend/cypress/e2e/real-scheduling-releases.cy.ts` drives the plugin's release pages in a browser,
against the real admin Worker and the real plugin. The e2e runner (`frontend/scripts/run-e2e.mjs`)
starts the plugin for a run with `E2E_REAL_BACKEND=1` that can reach that spec: the whole suite, or a
`--spec` that matches it. `E2E_SCHEDULING_PLUGIN=1` forces it on and `0` forces it off.

```sh
E2E_REAL_BACKEND=1 npm --prefix frontend run test:e2e -- --spec cypress/e2e/real-scheduling-releases.cy.ts
```

What the runner does, so you do not repeat the setup above by hand:

- generates the plugin's `wrangler.jsonc` and `.dev.vars` into a temp directory it owns, from
  `wrangler.example.jsonc`, with `main` and `migrations_dir` made absolute and the vars set
  (`PUBLIC_ORIGIN`, `ENVIRONMENT=development`, `DEE_WAN_DEV_ORIGINS` = the run's admin Worker). Nothing is
  written under `plugins/scheduling/`. The directory goes when the run stops, and one
  left by a killed run (nobody listens on its owner socket any more,
  `/tmp/dwe2e-<suffix>.sock`, named after the directory) is removed when the next run starts
  the plugin;
- applies the plugin's migrations to a fresh local D1 in that directory, then serves it with
  `wrangler dev --test-scheduled`;
- starts the admin Worker with `PLUGIN_DEV_ORIGINS` naming the plugin;
- generates a per-run `ADMIN_SECRET` and `TOKEN_KEY`, and hands the spec the origin and the admin secret
  as `CYPRESS_E2E_PLUGIN_ORIGIN` and `CYPRESS_E2E_PLUGIN_ADMIN_SECRET`. The spec mints its activation code
  with that secret, installs through `POST /api/plugins`, and opens each plugin page from the code-bearing
  URL of `POST /api/plugins/:id/launch`, the call the Settings and entry buttons make.

The plugin port is `E2E_PLUGIN_PORT` (default 43190). It is refused up front if taken, like every other
port the run serves. The runner supervises the plugin: if it dies under a live browser run, the run stops
and names it.

## Failure fixtures

How to produce each failure on purpose. The fake-core column is what your test does. The local
Dee Wan column is how the same state arises against a real core, when you want to confirm it end to
end.

### Outcomes the protocol defines

Every plugin meets these, whatever it does. Each is a named `outcome.code` with a fixed HTTP status
and retry flag.

| Outcome | Against a fake core | Against a local Dee Wan |
| --- | --- | --- |
| `invalid_request` | Send an unknown body key, or omit `Idempotency-Key` | Same |
| `plugin_unauthorized` | Use an unknown token | Disable or uninstall the installation, then send a command |
| `capability_refused` | Remove the capability from the installation | Narrow the grant in Settings → Plugins |
| `requester_unauthorized` | Mark the delegation's person as no longer permitted | Remove the person's role, or deactivate them, after the delegation is made |
| `content_not_found` | Ask for an unknown instance | Use an id from another site, or remove the model from the grant |
| `scheduled_target_stale` | Change the content's `current_version_id` | Edit and save the draft after pinning it |
| `workflow_conflict` | Bump the content's `revision` | Publish and then unpublish the item by hand after pinning a publish |
| `dependent_content` | Answer `dependent_content` by injection | Relate another published item to it, then try to unpublish |
| `idempotency_key_reused` | Reuse a key with a different body | Same |
| `transition_unavailable` | Ask for a `to` the state does not offer | Publish by hand an item whose publish is pinned. Core checks the transition before the revision |
| `rate_limited` | Inject 429 with a `Retry-After`, in seconds and as an HTTP date | 120 requests in a minute for one installation |
| `temporary_failure` | Inject a structured 503 response, then let the retry through | Hard to force. Core also answers it while a publish's redirect outcome is not recorded yet; the retry with the same key answers the whole result. Trust the injected case |

### Failures without an outcome code

These have no `outcome.code`, so the protocol fixes only the rule — never treat one as success, and
never retry forever. How to record them is your plugin's decision. The last column is what the
reference plugin does.

| Failure | Against a fake core | Against a local Dee Wan | Reference plugin |
| --- | --- | --- | --- |
| bare transient HTTP | Inject 429, 500, 502, 503 and 504 without an outcome body | Hard to force. Trust the injected cases | Retries with bounded backoff or valid bounded `Retry-After` |
| transport failure | Inject a network error, and a timeout | Stop the Dee Wan Worker, then let the plugin send a command | Retries as `no_response`, with backoff, until its caps |
| untrusted response | Inject a 200 whose `outcome.code` is a 409 code, a non-JSON body, and a 3xx | Not producible. That is the point of injecting it | Refuses as `untrusted_response` |
| lease recovery | Leave a record `running` with an expired lease | Kill the plugin mid-command and let the next tick reclaim it | Resends with the same idempotency key, within the lateness cap |

Assert the terminal code and that no new request is sent after settlement. Separately prove recovery: a lost reply may produce repeated requests with the same key and byte-identical body, but only one applied effect. Race two workers and fence a stale owner before sending. Recorded commands alone do not prove at-most-once effects.

## Gaps, stated plainly

- **The contract package is not published.** `@dee-wan/plugin-conformance` is built and tested in
  the Dee Wan repository. Publishing it to npm needs authority. Until then a plugin in another
  repository installs a tarball made with `npm pack`.
- **The cross-service run covers the cases in its table and nothing else.** It does not drive
  `requester_unauthorized`, `capability_refused`, `rate_limited`, token rotation, `retry_exhausted`,
  a plugin crash mid-command, or a cron trigger that fires on its own. Those are covered on each side
  against a double, or by hand with the local setup above. Dee Wan's CI does not run it, and the
  plugin's own CI runs only once the plugin has its own repository.
- **Nothing here is deployed evidence.** Both services run under local `wrangler dev`.

<!-- dee-wan-docs page: /plugins/protocol-v1/ -->

# Protocol v1

Source: https://dee-wan-docs.pages.dev/plugins/protocol-v1/

Every route, header, body, outcome code and retry rule of the remote plugin protocol. A plugin is
a separately deployed service: it speaks HTTP to Dee Wan and runs no code inside it. See also
[Writing a plugin](/plugins/authoring/) for a first plugin end to end, [Plugin security](/plugins/security/)
for the trust boundary, and [Testing a plugin](/plugins/testing/) for how to test one.

Supported protocol versions: `1`. The version is
negotiated once, at install, and pinned on the installation. An upgrade that would change it is
refused (`protocol_changed`): moving an installation to v2 means uninstalling it and installing
the new release. A breaking change to a route, a meaning or an error code requires protocol v2.
Additive response fields are permitted only because clients are required to ignore response
keys they do not know. **Request shapes are closed** — an unknown key is refused, never ignored.

## Authentication

Every plugin route takes `Authorization: Bearer <token>`, where the token is `dwp_` followed
by 43 URL-safe characters of 256-bit randomness. Core stores only its SHA-256 hash and can never
show it again. The plugin receives it once, at activation.

The routes live under `/api/plugin/v1`. They need no `Origin` header and no cookie, because a
server sends neither. Core resolves the installation and the site BEFORE any request body is
read, in this order: refuse a caller-named site or database, resolve the token to one active
installation, spend the rate limit, resolve the site, route to the tenant database.

Consequences worth stating plainly:

- The site is derived from the token. A plugin cannot name one, and sending `X-Site-Id` at all is
  `invalid_request`.
- A user cookie is not plugin authentication, and a plugin token is not accepted on any
  administrative route.
- `pending`, `disabled` and `revoked` installations answer `plugin_unauthorized` before any
  tenant access happens. So does every installation on a site that is not active.

## Headers

| Header | Where | Meaning |
| --- | --- | --- |
| `Authorization: Bearer <token>` | every plugin request | This required header contains the installation token. |
| `Idempotency-Key` | transitions, writes, drafts, media and proposals; future-version preparation uses its installation/release/entry identity instead | This header is required. Use 1 to 128 characters in `\x21`–`\x7e` (printable ASCII, no space). Core keeps the idempotency record for 30 days. Do not use this header with `/launch/exchange`. |
| `Content-Type: application/json` | requests with a body | Requests with a body must use this format. |
| `X-Site-Id` | never | Core refuses this header. The site comes from the token. |
| `Retry-After` | on a retryable response | Core emits seconds on 429. Clients also accept HTTP dates on inbound retryable statuses. Honour it within attempt, age and wait caps. |
| `Referrer-Policy: no-referrer` | core’s launch response, and your management page | Core sets it only on its own launch response. The browser then opens your `management_url` with `dee_wan_launch` in the query. So your page must send `Referrer-Policy: no-referrer` itself and remove the code from the address bar. Exchange it server-side, then redirect to the same URL without `dee_wan_launch`. |

## Limits

| Limit | Value |
| --- | --- |
| Request body | 16384 bytes; over a limit is `limit_exceeded` |
| Field write or proposal body | 81920 bytes, 50 fields, 65536 bytes of values |
| Draft body | 1916384 bytes; a draft 1900000 bytes, 200 per person |
| Media body | 33619968 bytes; a file 33554432 bytes |
| Manifest body | 32768 bytes |
| Idempotency key | 128 characters |
| Content page | 50 items, default 20 |
| Delegation entries | 100 entry ids per read |
| Requests per installation | 120 per 60s window, keyed by installation |
| Launch code lifetime | 60s, single use, stored hashed |
| Token rotation overlap | at most 10 minutes, ended by the first request with the new token |
| Idempotency record | 30 days. Afterwards the same key is a new command |
| Delegation lifetime | no time limit. See Delegations |
| Invocation | 10s for the POST, the exchange and the answer together; the code expires with it |
| Invocation answer | 65536 bytes |
| Invocation input | 32768 bytes of operation values or policy facts |
| Operation replay | 24 hours for one `Idempotency-Key` of one caller |

## Capabilities

| Capability | What it permits |
| --- | --- |
| `content:read` | The content read routes, within the granted models. |
| `workflow:read` | The `workflow` block on a read: state, revision and the boundary transitions. Commands must pin `workflow.revision`, so a plugin that sends them needs this. |
| `workflow:publish` | A `kind: publish` command. |
| `workflow:unpublish` | A `kind: unpublish` command. |
| `workflow:locale` | A command that names one `locale` and moves that language alone, and the `workflow.locales` list on a read. Without it a command that names a locale is `capability_refused`; a command without `locale` always moves the whole translation group. |
| `workflow:release` | Prepare and read installation-bound future versions, or submit one bounded same-site final-state publish/unpublish command with one atomic tenant commit. |
| `content:write` | Saving value fields of an item as the delegating person, pinned to its current version. |
| `content:create` | Create entries as the delegating person, within reviewed model grants. |
| `content:delete` | Move entries to Trash as the delegating person, within reviewed model grants. |
| `draft:write` | Reading, writing and discarding the delegating person’s own working drafts. |
| `media:write` | Upload files within the person’s current media grants. |
| `media:read` | Read existing media metadata and bytes within the person’s current media grants. |
| `media:update` | Edit existing media metadata within the person’s current media grants. |
| `media:delete` | Delete eligible unused media with current media:delete permission and retained-reference checks. |
| `content:restore` | Restore a Trash item through the current actor’s delete and language grants. |
| `comments:read` | Read visitor comments with the current actor’s moderation authority and granted model visibility. |
| `comments:moderate` | Moderate visitor comments through the existing consent and state-conflict checks. |
| `redirects:read` | Read redirects with current site:settings permission. |
| `redirects:write` | Review and change redirects through the existing Site Chrome revision and pattern checks. |
| `mail:send` | Send administrator-approved templates to fixed addresses, the entry author or assigned reviewer, with current site:plugins permission and bounded declared substitutions. |
| `renderer:metadata` | Save declared per-language metadata contributions as a new draft version; core SEO and verification values win. |
| `content:propose` | Proposing value fields for an editor to review, and reading this installation’s proposals. |
| `media:source` | Answering the manifest’s `media_sources`: people browse them inside the media picker and copy a chosen file into the site’s own library, or, for a source that declares the `reference` mode, link it. It reads nothing from core. |

A grant is the intersection of these with a per-site list of content-model ids. An empty model
list means no content access — not every model. Capabilities outside the stored manifest request
cannot be granted, so a plugin update can never widen an existing grant.

## Installation states

`pending`, `active`, `disabled`, `revoked`. Only `active` may call the plugin API. `revoked` is terminal:
its token never becomes valid again, and uninstall revokes before anything else.

## Activation hand-off

On install (`kind: "activate"`) and on token rotation (`kind: "rotate"`) core POSTs
`$defs/activation_handoff` as JSON to the manifest’s `activation_url`. It carries the raw token
and the `activation_code` the administrator pasted into Dee Wan. The plugin mints that code, one
per install or rotation, and must check it. Core accepts only codes matching `^[A-Za-z0-9_-]{16,128}$`.
Any 2xx accepts the token. Any other status, a redirect, or no answer within 5s refuses it.

The token is not valid while core waits for that answer: the installation stays `pending` until
core receives your 2xx. A call to `/api/plugin/v1` made from inside the handler answers
`plugin_unauthorized`. Store the token, answer 2xx, then call `/context`. A rotation works the
same way: the new token is valid only after your 2xx.

## Delegations

A person opens the plugin from Dee Wan. The plugin exchanges the launch code at
`/launch/exchange` and receives a `delegation_id`. The exchange of an entry operation returns one
too, bound to that entry. Every command names one, and reads may name one. It says who asked. It
adds no capability beyond the installation grant.

- **No time limit.** A delegation does not expire with time, so a schedule can use it days or
  weeks later.
- **It stops working** when its person is deactivated or is no longer a member of the site
  (`requester_unauthorized`), and for good when the installation is uninstalled, which revokes its
  token (`plugin_unauthorized` on every request). While the installation is disabled or the site
  is inactive, every request answers `plugin_unauthorized` too.
- **Authority is re-read on every request.** A command is refused `requester_unauthorized` when
  the person may no longer take that transition. A read answers `transitions: []` instead.
- **Content-action delegations** (`instance_id` is set) speak only for the translation group of
  the item they were launched on: that item, its translations and the group primary. Any other
  item, or a launched item that no longer exists, is `requester_unauthorized`.
- **`manage` delegations** (`instance_id` is null) speak for items of the models in their
  `model_ids`: the granted models their person could read at launch, every entry or only their own.
- **Models are re-checked on every request.** An item whose model is not in `model_ids`, or that
  the person may no longer read, is `requester_unauthorized`. `/delegations/:delegationId` lists
  what a delegation reaches now.
- **Own entries are checked one by one.** Under `read:own` or `update:own` a model comes back
  `entries: "checked"`. `/delegations/:delegationId/entries` says which of the entries you hold the
  person may read now and what they may do there. Show nothing it leaves out.
- **A credential caps it.** A delegation a management credential opened carries only the
  installation capabilities that credential's scopes allow. A command outside them is
  `capability_refused`.
- **The model grant is re-checked on every request.** An item outside the current grant is
  `content_not_found`, whatever the delegation.
- `action` comes back exactly as launched. Core gives it no meaning beyond `manage`.

## Operations and policies

A manifest may declare `operations` (at most 8) and `policies` (at most 8). Core
runs them on the plugin. It renders every form and result with its own components; nothing a plugin sends
is markup or code.

- An **operation** has a closed `input` of at most 8 fields — `text` (with `max_length`), `number`
  (`min`, `max`, `integer`), `boolean`, `select` (closed `options`) — and a `result` list of CMS components:
  `text`, `rows` (key/value), `links` (https only) and `json` (offered as a download). `scope: "site"` runs
  from Settings → Plugins and needs `site:plugins`. `scope: "entry"` runs on one entry of a granted model
  the person reads; with `destructive: true` the person must also be able to update it and confirms first.
  `audience` is required. `interactive` operations are listed and run in the admin, the management API, the
  CLI and MCP. `automation` operations never appear there and those run routes refuse them; only a named
  core workflow (the content planner’s Scheduling handoff) invokes one, through the same transport, live
  authority, grants, idempotency and audit.
- A **policy** declares one `kind`: `save` (every content save, including one that changes only links,
  media or search settings), `restore` (an old version restored, or an entry leaving Trash), `delete` (an
  entry or a language moved to Trash, or deleted permanently), `publish`, `unpublish`, and `transition`
  (every workflow move, scheduled and plugin moves included). Its bound input is `$defs/policy_facts`: the
  kind, the model id and slug, the entry id (null for a new entry), the locale, `changed_fields`, `values`,
  and where they apply `links`, `media`, `seo`, `action` and `transition`. For `save` and `restore` they
  hold the candidate’s changed parts; for the other kinds the whole version in question. Links every
  language shares and media ride on the primary language only. No credential and no other content. It
  answers `$defs/policy_reply`: `allow`, `warning` with a message, `refuse` with a code and a message, or
  — for `save` and `restore` only — `transform` with replacement `values`, `links`, `media` or `seo`.
  `fields` name field keys.
- An operation may instead be a **content-list column** or a **list action**. A column is `scope: "page"` with
  `audience: "column"`, a `cell` kind (`text`, `badge` or `link`), `result: ["cells"]`, no `input` and not
  `destructive`. For one granted model it receives `$defs/column_request` — the model and at most 50 row ids the
  person may read, never values — and answers one `cells` block: at most one cell per named row, each
  `{ id, text, tone?, url? }` (`tone` for a badge, an https `url` for a link, text up to 80). It
  reads what it needs through its own grant. A column binds no delegation and is never listed or run as an
  ordinary operation. A list action is an interactive `entry` operation with `list_action: true`: Core runs it
  once for each of at most 25 rows a person selects, with that person’s live authority checked
  per row.
- `requires` lists installation capabilities from `requested_capabilities`. While the grant lacks one the
  item is unavailable. An accepted manifest update never widens a grant, so a new item that needs more is
  unavailable until an administrator grants it.

One invocation, in order:

1. Core records the invocation — installation, site, caller, declared id, optional model and entry, input
   digest, expiry — and the SHA-256 of a one-time `dwi_` code.
2. Core POSTs `$defs/invocation_envelope` to the declared `endpoint`: protocol version, installation id,
   invocation id, code, expiry. It carries no content and no credential. Redirects are refused.
3. The plugin sends the code to `POST /api/plugin/v1/invocations/exchange` with its bearer token and gets the
   bound input (`$defs/invocation_binding`). Core consumes the code once.
4. The plugin answers core’s POST with HTTP 200 and `$defs/operation_reply` or `$defs/policy_reply`.

Core accepts the answer only when this installation exchanged the invocation and still covers it: active,
the same accepted version and declaration, every required capability and the model still granted. Core
classifies everything else and stores digests, never the bodies, in the audit ledger:

| Failure | When |
| --- | --- |
| `plugin_timeout` | no complete answer within 10s |
| `plugin_unreachable` | no connection, a redirect, or a 5xx |
| `plugin_response_invalid` | any other status, not the reply schema, a result component not declared, too large, or answered without the exchange |
| `plugin_refused` | an operation answered `status: "refused"` with its own code and message |
| `plugin_unavailable` | the installation was disabled, revoked, narrowed or changed while the invocation ran |

Those are all of them: `plugin_timeout`, `plugin_unreachable`, `plugin_response_invalid`, `plugin_refused`, `plugin_unavailable`. Never answer before exchanging,
and never cache a binding: every invocation has its own code.

### How core uses a policy answer

- Core asks after its own checks (fields, rules, permissions, workflow, publication) and before it commits.
  A policy never replaces them, and it never moves a workflow.
- It asks the active installations whose grant holds the entry’s model and whose policy is available, all
  at once, at most 8 at a time. A save or a restore asks once per language whose values,
  links, media or search settings change; a publication, unpublication, deletion or move once per language
  it affects. A restore asks `save` and `restore` policies.
- `transform` replaces parts of the entry and language you were asked about, by field key, and nothing
  else: it names no entry, so it cannot reach another one. `values` and per-language `links` land in that
  language; links every language shares and `media` only from the primary language; `seo` replaces that
  language’s search settings (the editor’s shape, image as `{ media_id, alt }`). A list replaces the whole
  list. A restore takes `values` and `seo` only. Core then runs the whole write again with your parts in
  place, through every rule user input meets (field rules, rich text, relations, media, uniqueness,
  permissions). If core rejects any part, it refuses the write as `plugin_policy_transform_invalid` with the cause;
  two policies that change one part differently refuse it as `plugin_policy_transform_conflict`. Your
  policy is not asked again on that second pass. The result lists `outcome: "transformed"` with the
  fields you changed and your optional `message`, and the stored version records it in
  `meta.policy_transforms`. A transform that changes nothing is an allow. A `transform` to any other kind
  is an answer core does not accept.
- `refuse` always refuses the write. The editor names your plugin and policy and shows your message on
  the fields you name. `warning` lets the write through and shows the message. Nobody submits twice.
- A timeout, an outage or an answer core does not accept follows the mode an administrator chose for the
  policy in Settings → Plugins: `warn` (the default) lets the write through with a warning, `required`
  refuses it.
- `caller.via` is `person`, `management_credential`, `planner` when the content planner works for its plan
  owner, or `plugin` when another plugin’s delegated write is being checked. An import, a spreadsheet and a
  restore are asked as the person who runs them.
- The write is committed only if what you were shown is still current. A change in between is the
  ordinary version conflict, and your answer is not applied to other content.

## Pre-operation hooks

A manifest may declare `hooks`: at most one per kind, `upload_metadata` and `comment_moderation`. Each has an
`id`, a `label`, a same-origin HTTPS `endpoint`, and `requires` (capabilities listed in
`requested_capabilities`). A hook is **off** until an administrator turns it on for the installation in
Settings → Plugins. Core asks an enabled hook BEFORE the operation, not after: `upload_metadata` before a new
library file is stored, `comment_moderation` before a visitor comment is stored.

- A hook is called through the same invocation transport, with `kind: "hook"` in the binding, `caller: null`
  and no delegation. Core tells a hook what it is asked and never who asked: no person, email, credential,
  file bytes or other entry.
- `upload_metadata`: the bound input is `$defs/hook_upload_facts` (file name, MIME type, size, folder and alt
  texts; width and height are `null`, not measured yet). Answer `$defs/hook_upload_reply`: `accept`, optionally
  with `normalized` (a new `filename` that keeps the extension, and alt texts only in languages the upload
  already named), or `refuse` with a code and a message the uploader reads (422 `upload_hook_refused`).
- `comment_moderation`: the bound input is `$defs/hook_comment_facts` (the entry, the comment’s id, parent,
  author name, website and body; never the email). Answer `$defs/hook_comment_reply`: `approve`, `hold`
  (stays pending) or `reject` (stored as spam, or as refused with `as: "refused"`).
- **A hook that cannot answer never approves.** A timeout (5 seconds), an outage, a body that is not one of the
  closed replies, or an installation that was disabled or changed while it ran refuses the upload (503
  `upload_hook_unavailable`, nothing stored) or leaves the comment pending for moderation.
- The retry identity is a digest of the question: a retried upload or a re-sent comment replays the first
  ACCEPTED answer for 24 hours instead of asking again. A failed question is not replayed; the next identical
  one asks again.

## Media sources

A manifest may declare `media_sources` (at most 4) and request `media:source`. Each source is a library
people browse inside the media picker, next to the site’s own library, and through the management API. Each
source declares `modes`: `copy` (core copies the chosen file into the site, so published content never depends
on the source), `reference` (core keeps only the file’s delivery URL and identity and the source keeps the bytes),
or both. The person or the API caller names the mode on every add; core never infers it from a URL or a name.

- A source is called through the same invocation transport, with `kind: "media_source"` in the binding and
  no delegation. Its bound input is `$defs/media_source_request`: `browse` with `query` (empty for the first
  page), `cursor` (the previous `next_cursor`, or null) and `limit` (at most 24), or `item` with the
  `item_id` a person chose.
- Answer `browse` with `$defs/media_source_page_reply` and `item` with `$defs/media_source_item_reply`, or
  `status: "refused"` with a code and a message. Each item carries a title, a file name, its MIME type,
  optional size and dimensions, a `thumbnail_url`, a `download_url` (required for `copy`), a `delivery_url`
  (required for `reference`) and an `attribution`: `source_name`,
  `license`, and optional `author`, `author_url`, `license_url` and `source_url`. An image’s `description`
  (at most 125 characters) becomes its alt text in the site’s default language.
- `thumbnail_url` and `download_url` must be on the manifest’s one origin. A `delivery_url` must be on one of
  the source’s `delivery_origins` (at most 4 bare origins, required with `reference` and absent without it; the manifest origin
  may be one of them). An answer naming any other origin is `plugin_response_invalid`. The picker loads
  thumbnails straight from your origin with no referrer and no Dee Wan credential. Attribution links are
  shown, never fetched.
- When a person chooses an item, core asks `item` again, then GETs `download_url` with no credential and no
  redirect, within 20s and the media file limit. The bytes go through the same checks as an upload:
  the site’s kinds, formats and size limits, and its duplicate check. The new media keeps the attribution
  and the plugin, source and item ids. Sign `download_url` yourself if your files are not public.
- In `reference` mode core fetches nothing. The media row keeps your `delivery_url` as its address, your
  plugin, source and item ids as its identity and the metadata you declared; the same item added twice follows
  `on_duplicate`. Published pages, site copies and generated sites use the `delivery_url` as it is, so it must
  stay served for as long as sites use it. Core never proxies it, replaces its bytes, or calls you when the file is
  deleted from the library. A mode the source does not declare is refused with `media_source_mode_unsupported`.
- Browsing changes nothing, so it is not audited. The copy is an ordinary media upload by the person who chose it.
- The caller needs `media:upload`. A disabled installation, a narrowed grant without `media:source`, or a
  changed declaration makes the source unavailable at once.

## Plugin routes

### GET `/api/plugin/v1/context`

**What this installation is.** The installation id, the site it is bound to, the accepted protocol version and the grant. Read it at start-up to learn what this installation may ask for. It names no user, no token hash, no database and no infrastructure.

- Caller: the plugin, with its installation token
- Requires: none
- No query, no body.
- Answers: `{ "data": <context> }` — `$defs/context`.

Outcomes:

- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**What this installation may do**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": {
    "installation_id": "plg_0000000000000000000000000000d1ee",
    "site": {
      "id": "cdocssite00000000000000001",
      "name": "docs-site",
      "default_lang": "en"
    },
    "protocol_version": 1,
    "capabilities": [
      "content:read",
      "workflow:read",
      "workflow:publish",
      "workflow:unpublish"
    ],
    "model_ids": [
      "cdocsmodel0000000000000001"
    ]
  }
}
```


**An unknown, disabled or revoked token**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_UnknownTokenNotRealUnknownTokenNotRealUnkno"
```

```json
{
  "outcome": {
    "code": "plugin_unauthorized",
    "message": "The installation token is missing, unknown, disabled or revoked.",
    "retry": false
  }
}
```

One answer for all four. Nothing tells a caller which of them applies.


**A plugin cannot name a site**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "X-Site-Id: cotherdocsite00000000001"
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "A plugin request cannot name a site.",
    "retry": false
  }
}
```

The site comes from the token. Sending the header at all is refused, even with the right value.


**An unknown plugin route**

```sh
curl "https://cms.example/api/plugin/v1/schedules" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "content_not_found",
    "message": "No such plugin route.",
    "retry": false
  }
}
```

Protocol v1 exposes only the documented routes. A 404 here is not a temporary failure.

### GET `/api/plugin/v1/content`

**List content in one granted model.** One page of primary instances in one model. `model_id` is mandatory: there is no "all models" read. The filter set is closed — any other query parameter is `invalid_request` rather than ignored. The page is a narrow summary, not a content snapshot. Only translation-group primaries appear. The group is the unit a transition moves.

- Caller: the plugin, `content:read`
- Requires: `content:read`
- `model_id` (required) — a model id from the grant.
- `published` — `true` or `false`.
- `after` — the previous page’s last `instance_id`.
- `limit` — 1..50, default 20.
- Answers: `{ "data": [<summary>], "next": <instance_id|null> }` — `$defs/content_page`.

Outcomes:

- `capability_refused` — no `content:read`, or a model outside the grant
- `invalid_request` — missing `model_id`, an unknown filter, a `limit` out of range
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**One page of one model**

```sh
curl "https://cms.example/api/plugin/v1/content?model_id=cdocsmodel0000000000000001&published=false&limit=1" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": [
    {
      "instance_id": "cdocsinstance00000000000001",
      "primary_instance_id": "cdocsinstance00000000000001",
      "translation_group_id": "cdocsgroup0000000000000001",
      "model_id": "cdocsmodel0000000000000001",
      "model_slug": "article",
      "lang": "en",
      "label": "Hello",
      "slug": "hello",
      "current_version_id": "cdocsversion00000000000001",
      "published_version_id": null
    }
  ],
  "next": null
}
```

A filter outside `model_id`, `published`, `after`, `limit` is `invalid_request`, not ignored.


**The filter set is closed**

```sh
curl "https://cms.example/api/plugin/v1/content?model_id=cdocsmodel0000000000000001&sort=title" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "model_id is required; filters are model_id, published, after, limit.",
    "retry": false
  }
}
```

### GET `/api/plugin/v1/content/:instanceId`

**Read one item, and what it may do next.** Ids, label (the entry's title in its own language, else the current version's note), slug, and the current and published version ids. With `workflow:read`, the read adds the workflow state, its revision and the transitions that cross the publication boundary. Transitions are narrowed to the capabilities this installation holds. Pass `delegation_id` and they are narrowed again to what that person may do NOW, re-read on every request. If the person is deactivated or no longer a member of the site, the request returns `requester_unauthorized`. If the person is still a member but may no longer update this item, the request returns 200 with `transitions: []` (a command would still be refused `requester_unauthorized`). A content-action delegation is accepted only for items in the translation group it was launched on. A `manage` delegation is accepted for any item in the models it was launched with. Every delegation is also refused for an item whose model is not in its `model_ids`, or that its person may no longer read. Without `workflow:read` there is no `workflow` block. A valid delegation adds a projected `saved` snapshot. `workflow.revision` is what every command must pin, so a plugin that sends commands needs `workflow:read`. An item that has never moved through its workflow has revision `0`. An item outside the site or the model grant is `content_not_found`, which is also what a cross-site id answers.

- Caller: the plugin, `content:read`
- Requires: `content:read`, plus `workflow:read` for the `workflow` block
- `delegation_id` — a delegation from `/launch/exchange` or from an entry-operation binding. No other query parameter is accepted.
- Answers: `{ "data": <summary> }` — `$defs/content_summary`.

Outcomes:

- `capability_refused`
- `content_not_found`
- `requester_unauthorized` — the named delegation is unknown, belongs to another installation, is bound to another translation group or to an item that no longer exists. This also happens when its person is deactivated or no longer a member of the site, when the item’s model is not in the delegation’s `model_ids`, or when its person may no longer read the item
- `invalid_request`
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**One item, with the transitions the requester may take now**

```sh
curl "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001?delegation_id=pld_0000000000000000000000000000d1ee" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "translation_group_id": "cdocsgroup0000000000000001",
    "model_id": "cdocsmodel0000000000000001",
    "model_slug": "article",
    "lang": "en",
    "label": "Hello",
    "slug": "hello",
    "current_version_id": "cdocsversion00000000000001",
    "published_version_id": null,
    "workflow": {
      "state": "draft",
      "revision": 0,
      "transitions": [
        {
          "to": "published",
          "kind": "publish"
        }
      ]
    }
  }
}
```

Pin what this answers: `current_version_id` for a publish, `published_version_id` for an unpublish, and `workflow.revision` for both. A delegated read also returns `saved`; this example shows the summary keys.

### POST `/api/plugin/v1/content/:instanceId/transitions/:targetState`

**Publish or unpublish, conditionally.** This route only publishes or unpublishes content. It is conditional in four ways at once, all checked inside the same atomic lifecycle mutation. The pinned version must still be the one the transition would move. Ordinary publication pins the current ordinary draft. A future publication names both `future_draft_id` and `expected_future_revision`, pins that branch’s current saved version, and leaves the ordinary draft intact. Only a currently authorized future command may republish an already-published workflow stage. The workflow revision must still be the one the schedule was made against. `targetState` must be a transition available from the current state, and that transition’s publication meaning must match `kind`. The delegation must cover the item (see Delegations), and the delegating person’s authority is re-read before the write. A newer draft is never published silently. A changed workflow is never traversed silently. Publication applies to the whole translation group, which is why the result names the primary instance. With `workflow:locale`, a body that names `locale` moves that one language: `targetState` is checked against that language’s own state in `workflow.locales`, an unpublish pins that language’s own published version, and the result names the `locale` it moved. A transition that publishes also reports `redirect`: the automatic redirect the same lifecycle call made for a changed address, or why it made none. An exact replay answers the whole first result, `locale` and `redirect` included. Core writes the redirect after the transition commits. Until its outcome is recorded, the command and any replay of it answer `temporary_failure` with a message saying the transition was applied. Retry with the same key and body: the replay then answers the whole result.

- Caller: the plugin, `workflow:publish` or `workflow:unpublish`
- Requires: `workflow:publish` for `kind: publish`, `workflow:unpublish` for `kind: unpublish`
- `Idempotency-Key` (required) — 1 to 128 characters in `\x21`–`\x7e` (printable ASCII, no space). Derive it from the schedule, not from the clock: an exact replay returns the first result, and the same key with different input is `idempotency_key_reused`. Core keeps the record 30 days. After that the same key is treated as a new command.
- Body — `$defs/publish_command` or `$defs/unpublish_command`. The shape is CLOSED: an unknown key, or the other kind’s pin, is `invalid_request`.
- Answers: `{ "outcome": {...}, "data": <transition_result> }` — `$defs/transition_result`.

Outcomes:

- `transition_applied` / `idempotent_replay`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized` — the delegation is unknown, does not cover this item, or its person no longer holds the authority the transition needs
- `content_not_found`
- `scheduled_target_stale`
- `workflow_conflict`
- `dependent_content`
- `idempotency_key_reused`
- `transition_unavailable` / `transition_refused`
- `rate_limited`
- `temporary_failure`


**Publish the pinned draft**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0001:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000001",
  "expected_workflow_revision": 0,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "transition_applied",
    "message": "The transition was applied.",
    "retry": false
  },
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "from": "draft",
    "to": "published",
    "published": true,
    "published_changed": true,
    "published_version_id": "cdocsversion00000000000001",
    "revision": 1,
    "redirect": {
      "status": "none",
      "reason": "no_public_address"
    },
    "policy_results": []
  }
}
```


**The same command again**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0001:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000001",
  "expected_workflow_revision": 0,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "idempotent_replay",
    "message": "This command was already applied. The first result is returned.",
    "retry": false
  },
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "from": "draft",
    "to": "published",
    "published": true,
    "published_changed": true,
    "published_version_id": "cdocsversion00000000000001",
    "revision": 1,
    "redirect": {
      "status": "none",
      "reason": "no_public_address"
    },
    "policy_results": []
  }
}
```

A retry after a network failure is safe: the whole first result comes back, `redirect` included, and nothing runs twice.


**The same key, a different command**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0001:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000001",
  "expected_workflow_revision": 7,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "idempotency_key_reused",
    "message": "This idempotency key was already used for a different command.",
    "retry": false
  }
}
```

Derive the key from the schedule and its revision. Rescheduling is a new revision, so a new key.


**Unpublish the pinned live version**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/draft" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0002:r1" \
  --data '{
  "kind": "unpublish",
  "expected_published_version_id": "cdocsversion00000000000001",
  "expected_workflow_revision": 1,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "transition_applied",
    "message": "The transition was applied.",
    "retry": false
  },
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "from": "published",
    "to": "draft",
    "published": false,
    "published_changed": true,
    "published_version_id": null,
    "revision": 2,
    "policy_results": []
  }
}
```


**A newer draft is never published silently**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0003:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000001",
  "expected_workflow_revision": 2,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "scheduled_target_stale",
    "message": "The pinned version is no longer the one this transition would move.",
    "retry": false
  }
}
```

Somebody saved a newer draft after the schedule was made. Terminal: a person decides what to do.


**A changed workflow is never traversed silently**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0004:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000002",
  "expected_workflow_revision": 0,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "workflow_conflict",
    "message": "The content moved through its workflow after this was requested.",
    "retry": false
  }
}
```


**The request shape is closed**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0005:r1" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000002",
  "expected_workflow_revision": 2,
  "delegation_id": "pld_0000000000000000000000000000d1ee",
  "override_dependents": true
}'
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "The request is not valid for protocol v1.",
    "retry": false
  }
}
```

There is no override in protocol v1. An unknown key is refused rather than dropped.


**A mutation without an idempotency key**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  --data '{
  "kind": "publish",
  "expected_current_version_id": "cdocsversion00000000000002",
  "expected_workflow_revision": 2,
  "delegation_id": "pld_0000000000000000000000000000d1ee"
}'
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "Idempotency-Key is required.",
    "retry": false
  }
}
```

### PUT `/api/plugin/v1/content/:instanceId`

**Save field values, as the person.** An ordinary lifecycle save of named value fields of one item, made AS the delegating person: their model permission, ownership and current account are re-read, and the save is theirs in the content history. It is pinned: `expected_version_id` must still be the current version, or the answer is `version_conflict` and nothing is written. The same rules the editor applies decide the values — field types, uniqueness, hierarchy, the language, the version size. `fields` accepts values for up to 50 value fields, with at most 65536 bytes of values in total. Use the separate `relations`, `locale_relations` and `media` properties for typed reference writes; `fields` may be empty when one of those changes references. Without `locale` the values are for the addressed item’s own language. A translatable `slug` field renames that language’s address only; a shared one names the primary language’s. `slugs` in the answer lists every language’s address. The administrative history records the person, with this installation named in it.

- Caller: the plugin, `content:write`
- Requires: `content:write`
- `Idempotency-Key` (required) — as for transitions. A replay answers the first result.
- Body — `$defs/content_write_command`. Closed.
- Answers: `{ "outcome": {...}, "data": <save_result> }` — `$defs/content_save_result`.

Outcomes:

- `content_saved` / `idempotent_replay`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized` — the delegation does not cover this item, or its person may not update it now
- `content_not_found`
- `version_conflict`
- `validation_failed` — `data` names the rule’s `reason` and, when it has them, the `fields`
- `limit_exceeded`
- `idempotency_key_reused`
- `rate_limited`
- `temporary_failure`


**Save one field, pinned to the current version**

```sh
curl -X PUT "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: write:plg_0000000000000000000000000000d1ee:0001" \
  --data '{
  "delegation_id": "pld_0000000000000000000000000000d1ee",
  "expected_version_id": "cdocsversion00000000000002",
  "fields": {
    "title": "Hello from the plugin"
  }
}'
```

```json
{
  "outcome": {
    "code": "content_saved",
    "message": "The field values were saved as a new version.",
    "retry": false
  },
  "data": {
    "instance_id": "cdocsinstance00000000000001",
    "primary_instance_id": "cdocsinstance00000000000001",
    "translation_group_id": "cdocsgroup0000000000000001",
    "version": {
      "id": "cdocsversion00000000000003",
      "version_number": 3
    },
    "current_version_id": "cdocsversion00000000000003",
    "published_version_id": null,
    "slugs": {
      "en": "hello",
      "fr": "hello"
    },
    "locales": {
      "en": "cdocsinstance00000000000001",
      "fr": "cdocsinstancefr000000000001"
    },
    "warnings": [],
    "policy_results": []
  }
}
```

The new version is the delegating person’s. Pin `current_version_id` for the next write.


**A write pinned to an older version**

```sh
curl -X PUT "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: write:plg_0000000000000000000000000000d1ee:0002" \
  --data '{
  "delegation_id": "pld_0000000000000000000000000000d1ee",
  "expected_version_id": "cdocsversion00000000000001",
  "fields": {
    "title": "Lost update"
  }
}'
```

```json
{
  "outcome": {
    "code": "version_conflict",
    "message": "The entry changed after the pinned version. Read it again before writing.",
    "retry": false
  }
}
```

Nothing was written. Read the item again and decide with the person.

### GET `/api/plugin/v1/content/:instanceId/proposals`

**This installation’s proposals for one item.** The proposals this installation made for the item, newest first, at most 50, in every state: `open`, `applied` or `dismissed`. Another installation’s or a management credential’s proposals are not listed.

- Caller: the plugin, `content:propose`
- Requires: `content:propose`
- No query, no body.
- Answers: `{ "data": [<proposal>] }` — `$defs/proposal_list`.

Outcomes:

- `capability_refused`
- `content_not_found`
- `invalid_request`
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`

### POST `/api/plugin/v1/content/:instanceId/proposals`

**Propose field values for an editor to review.** Records proposed values of named value fields, pinned to `base_version_id`, for the item’s editor to review. THE CONTENT DOES NOT CHANGE until a person applies the proposal in Dee Wan: Apply is that person’s ordinary save, with their permissions, against the pinned version. The editor shows the plugin’s name and the person it acted for. The delegating person must still be able to read the item.

- Caller: the plugin, `content:propose`
- Requires: `content:propose`
- `Idempotency-Key` (required) — as for transitions.
- Body — `$defs/proposal_command`. Closed.
- Answers: `{ "outcome": {...}, "data": <proposal> }` — `$defs/proposal`.

Outcomes:

- `proposal_created` / `idempotent_replay`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized`
- `content_not_found`
- `version_conflict` — `base_version_id` is no longer the current version
- `validation_failed`
- `limit_exceeded`
- `idempotency_key_reused`
- `rate_limited`
- `temporary_failure`


**Propose a value for an editor to review**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/proposals" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: propose:plg_0000000000000000000000000000d1ee:0001" \
  --data '{
  "delegation_id": "pld_0000000000000000000000000000d1ee",
  "base_version_id": "cdocsversion00000000000003",
  "fields": {
    "title": "A better title"
  },
  "note": "Shorter and clearer."
}'
```

```json
{
  "outcome": {
    "code": "proposal_created",
    "message": "The proposal was created. Nothing changes until a person applies it.",
    "retry": false
  },
  "data": {
    "id": "prop_00000000000000000000000000000d1e",
    "revision": 0,
    "instance_id": "cdocsinstance00000000000001",
    "lang": "en",
    "base_version_id": "cdocsversion00000000000003",
    "fields": {
      "title": "A better title"
    },
    "note": "Shorter and clearer.",
    "source": {
      "kind": "plugin",
      "id": "plg_0000000000000000000000000000d1ee",
      "label": "My Plugin",
      "requested_by": "admin@example.com"
    },
    "state": "open",
    "applied_version_id": null,
    "created_at": "2026-01-01T00:00:00.000Z",
    "resolved_at": null
  }
}
```

Nothing changed. The entry editor shows it as from My Plugin, requested by the person.

### GET `/api/plugin/v1/proposals/:proposalId`

**One proposal this installation made.** Read one proposal to learn whether a person applied or dismissed it, and which version was created when it was applied. Another installation’s proposal, or one for an item outside the grant, is `content_not_found`.

- Caller: the plugin, `content:propose`
- Requires: `content:propose`
- No query, no body.
- Answers: `{ "data": <proposal> }` — `$defs/proposal`.

Outcomes:

- `capability_refused`
- `content_not_found`
- `invalid_request`
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`

### GET `/api/plugin/v1/drafts`

**Read the person’s working draft.** The delegating person’s own unsaved editor draft of one item and language — the work the entry editor restores. A draft is never a version or an audit record. It belongs to the person: a plugin reads only the draft of the person who launched it. `target` is an item id, or `new:<model id>` for an item not created yet, which needs a `manage` delegation. The person must still be able to change the item (or create one of that model). Drafts expire after 30 days.

- Caller: the plugin, `draft:write`
- Requires: `draft:write`
- `delegation_id`, `target`, `locale` — all required, nothing else. `$defs/draft_query`.
- Answers: `{ "data": <draft|null>, "expired": <boolean> }` — `$defs/draft_read`.

Outcomes:

- `capability_refused`
- `content_not_found`
- `requester_unauthorized`
- `invalid_request`
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`

### PUT `/api/plugin/v1/drafts`

**Write the person’s working draft.** Replaces that draft only when its revision matches `expected_revision` (`0` when there is none yet); another device or tab writing first is `draft_conflict`, with the current draft in `data.current`. A draft holds at most 1900000 bytes, and a person keeps at most 200 on a site; beyond either is `limit_exceeded`. `data` is the editor’s working state; Dee Wan validates it only when a person saves.

- Caller: the plugin, `draft:write`
- Requires: `draft:write`
- `Idempotency-Key` (required).
- Body — `$defs/draft_write_command`. Closed.
- Answers: `{ "outcome": {...}, "data": <draft> }` — `$defs/working_draft`.

Outcomes:

- `draft_saved` / `idempotent_replay`
- `draft_conflict`
- `limit_exceeded`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized`
- `content_not_found`
- `idempotency_key_reused`
- `rate_limited`
- `temporary_failure`

### POST `/api/plugin/v1/drafts/discard`

**Discard the person’s working draft.** Removes exactly `revision` of that draft. A newer revision is kept and answered `draft_conflict`. A draft that is already gone is `draft_discarded`.

- Caller: the plugin, `draft:write`
- Requires: `draft:write`
- `Idempotency-Key` (required).
- Body — `$defs/draft_discard_command`. Closed.
- Answers: `{ "outcome": {...} }`.

Outcomes:

- `draft_discarded` / `idempotent_replay`
- `draft_conflict`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized`
- `content_not_found`
- `idempotency_key_reused`
- `rate_limited`
- `temporary_failure`

### POST `/api/plugin/v1/media`

**Upload media, as the person.** The ordinary media upload, through the same verification and storage as the media library: the bytes must be one of `media_types` of a kind the site accepts (images and documents by default; audio and video when the site turns them on), of at most 33554432 bytes. The delegating person must hold `media:upload`. Any delegation of this installation may upload. Send `multipart/form-data` with exactly these parts: `file`, `delegation_id`, and optionally `alt_texts` (a JSON object of site language code to text), `width`, `height`, `on_duplicate`. Any other part is `invalid_request`. A refused file is `validation_failed` with the media rule’s `reason`. When the site already holds the same bytes, `on_duplicate` decides: `ask` (default) answers `media_duplicate` with the existing file and uploads nothing, `use_existing` answers `media_reused` with the existing file, `copy` uploads a separate copy.

- Caller: the plugin, `media:write`
- Requires: `media:write`
- `Idempotency-Key` (required).
- Body — multipart, `$defs/media_upload_form`.
- Answers: `{ "outcome": {...}, "data": <media> }` — `$defs/media`; `media_duplicate` carries `$defs/media_duplicate`.

Outcomes:

- `media_uploaded` / `media_reused` / `idempotent_replay`
- `media_duplicate` — the site already holds these bytes and `on_duplicate` is `ask`
- `invalid_request`
- `capability_refused`
- `requester_unauthorized`
- `validation_failed`
- `limit_exceeded`
- `idempotency_key_reused`
- `content_not_found` — a replay whose media was since deleted
- `rate_limited`
- `temporary_failure`

### POST `/api/plugin/v1/launch/exchange`

**Exchange a launch code for a delegation.** The browser arrives at `management_url` carrying `dee_wan_launch`. The plugin BACKEND sends that code here, with its own bearer token, within 60 seconds. The code is consumed once. What comes back is the binding — installation, site, action, optional content instance, and `model_ids`: the exact granted models the person could read at launch, every entry or only their own (for a content action, the item’s model) — and a display-safe identity for the plugin’s own session. Show and act only inside `model_ids`; `/delegations/:delegationId` says what still applies now. It grants no Dee Wan capability the installation token does not already have, and a code minted for another installation is refused. No `Idempotency-Key` is needed: the code itself is single use, so a retry after a lost response answers `invalid_request` and the person has to launch again.

- Caller: the plugin, with its installation token
- Requires: none
- Body — `$defs/launch_exchange_request`. No `Idempotency-Key`.
- Answers: `{ "data": <delegation> }` — `$defs/launch_delegation`.

Outcomes:

- `invalid_request` — unknown, already used, expired, or minted for another installation
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**Turn a launch code into a delegation**

```sh
curl -X POST "https://cms.example/api/plugin/v1/launch/exchange" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  --data '{
  "code": "dwl_ExampleLaunchCodeExampleLaunchCodeExampleLa"
}'
```

```json
{
  "data": {
    "delegation_id": "pld_0000000000000000000000000000d1ee",
    "installation_id": "plg_0000000000000000000000000000d1ee",
    "site_id": "cdocssite00000000000000001",
    "action": "schedule",
    "instance_id": "cdocsinstance00000000000001",
    "model_ids": [
      "cdocsmodel0000000000000001"
    ],
    "user": {
      "id": "cdocsuser00000000000000001",
      "email": "admin@example.com"
    }
  }
}
```

Keep `delegation_id`. Every later command carries it, and core re-reads that person’s authority.


**A launch code is single use**

```sh
curl -X POST "https://cms.example/api/plugin/v1/launch/exchange" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  --data '{
  "code": "dwl_ExampleLaunchCodeExampleLaunchCodeExampleLa"
}'
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "The launch code is unknown, used or expired.",
    "retry": false
  }
}
```

### POST `/api/plugin/v1/invocations/exchange`

**Exchange an invocation code for the bound input.** Core POSTs `$defs/invocation_envelope` to a declared operation or policy `endpoint`. Before answering that POST the plugin sends the envelope’s `code` here with its own bearer token. The code is consumed once. What comes back is the binding core recorded: the operation or policy id, the optional model and entry, a display identity of who asked, and the bound `input` — operation values, or for a policy `$defs/policy_facts`. An entry operation’s binding also carries `delegation_id`: a durable delegation bound to the caller, site, installation, model and entry. Keep it like a launch delegation for later reads and transition commands on that entry; core re-reads its person’s authority on every use. A site operation’s binding carries a delegation like a `manage` launch: no entry, and the granted models the caller reads. A policy carries `null`. Core accepts the answer to its POST only from the installation that exchanged this invocation, and only while that installation still covers it. Everything happens within 10 seconds.

- Caller: the plugin, with its installation token, while it answers an invocation
- Requires: none
- Body — `$defs/invocation_exchange_request`. No `Idempotency-Key`.
- Answers: `{ "data": <binding> }` — `$defs/invocation_binding`.

Outcomes:

- `invalid_request` — unknown, already used, expired, or minted for another installation
- `capability_refused` — the installation was narrowed, or its manifest changed, after core asked
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**An invocation code works once, for the installation it was minted for**

```sh
curl -X POST "https://cms.example/api/plugin/v1/invocations/exchange" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  --data '{
  "code": "dwi_ExampleInvocationCodeExampleInvocationCodeE"
}'
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "The invocation code is unknown, used or expired.",
    "retry": false
  }
}
```

### GET `/api/plugin/v1/delegations/:delegationId`

**Read what a delegation may reach now.** The delegation’s `model_ids`, narrowed to the live model grant and to what its person may do NOW, re-read on every request. A `manage` delegation lists each model its person still reads: every entry, or only their own under `read:own`. A content-action delegation lists its item’s model while its person may still read that item. `kinds` names the transition kinds the person may take on that model’s items: the installation holds `workflow:publish` / `workflow:unpublish`, the person may update the items, and the model’s workflow has an edge of that kind whose permission the person holds. `entries` says whether that holds for every item. `all`: the person reads every item of the model and `kinds` applies to each. `checked`: the person reads or updates only their own items there, so `kinds` is the most they may take on an item they may update; ask `/delegations/:delegationId/entries` which items to show and what each allows. Use it to show only what the person may see, and to offer moving or cancelling a planned transition only when its kind is listed. A delegation a management credential opened lists only kinds inside its capability ceiling. Commands are still checked on their own.

- Caller: the plugin, with its installation token
- Requires: none
- No query parameter and no body.
- Answers: `{ "data": { "delegation_id", "models": [{ "id", "slug", "kinds", "entries" }] } }` — `$defs/delegation_models`.

Outcomes:

- `requester_unauthorized` — the delegation is unknown, belongs to another installation, or its person is deactivated or no longer a member of the site
- `invalid_request`
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**What a delegation may reach now**

```sh
curl "https://cms.example/api/plugin/v1/delegations/pld_0000000000000000000000000000d1ee" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": {
    "delegation_id": "pld_0000000000000000000000000000d1ee",
    "models": [
      {
        "id": "cdocsmodel0000000000000001",
        "slug": "article",
        "kinds": [
          "publish",
          "unpublish"
        ],
        "entries": "all"
      }
    ]
  }
}
```

Ask again before each page and action. A person who lost a model or a permission loses it here too.

### GET `/api/plugin/v1/delegations/:delegationId/entries`

**Read which entries a delegation may reach now.** For models `/delegations/:delegationId` marks `entries: "checked"`. Name up to 100 entry ids; the answer lists only those the delegation’s person may read NOW, each with the transition kinds they may take on it: the model’s `kinds` when they may update that entry, otherwise none. An entry of another site, in the trash, of a model outside the delegation’s `model_ids` or the live grant, outside a content-action delegation’s translation group, or that the person may not read, is left out without a reason. Ownership and permissions are re-read on every request, so ask again before each page and action. Keep the answer private to that person: never show an entry it leaves out.

- Caller: the plugin, with its installation token
- Requires: none
- `instance_id` — 1 to 100 times, each an entry id. Repeats count once. No other query parameter and no body.
- Answers: `{ "data": { "delegation_id", "entries": [{ "instance_id", "model_id", "kinds" }] } }` — `$defs/delegation_entries`.

Outcomes:

- `invalid_request` — no `instance_id`, more than 100, a malformed one, or another parameter
- `requester_unauthorized` — the delegation is unknown, belongs to another installation, or its person is deactivated or no longer a member of the site
- `plugin_unauthorized`
- `rate_limited`
- `temporary_failure`


**Which of these entries a delegation may reach now**

```sh
curl "https://cms.example/api/plugin/v1/delegations/pld_0000000000000000000000000000d1ee/entries?instance_id=cdocsinstance00000000000001&instance_id=cotherinstance0000000000001" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "data": {
    "delegation_id": "pld_0000000000000000000000000000d1ee",
    "entries": [
      {
        "instance_id": "cdocsinstance00000000000001",
        "model_id": "cdocsmodel0000000000000001",
        "kinds": [
          "publish",
          "unpublish"
        ]
      }
    ]
  }
}
```

The other site’s entry is left out, with no reason given. Show only the entries listed.

### POST `/api/plugin/v1/content`

**Create a saved entry.** Create through ordinary lifecycle validation. A manage delegation must include the model.

- Caller: plugin for a delegated person
- Requires: `content:create` and current create authority
- `Idempotency-Key` required.
- Body: `$defs/content_create_command`.
- Answers: `content_saved` with `$defs/content_save_result`.

Outcomes:

- `content_saved` / `idempotent_replay`
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `validation_failed` / `idempotency_key_reused`

### DELETE `/api/plugin/v1/content/:instanceId`

**Move an entry to Trash.** Moves the whole entry to Trash through the ordinary lifecycle. Published entries must be unpublished first. The current version is guarded atomically.

- Caller: plugin for a delegated person
- Requires: `content:delete` and current delete authority
- `Idempotency-Key` required.
- Body: `$defs/content_delete_command`.
- Answers: `content_deleted` with the ordinary trash result.

Outcomes:

- `content_deleted` / `idempotent_replay`
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `version_conflict` / `validation_failed` / `idempotency_key_reused`

### GET `/api/plugin/v1/content/:instanceId/versions`

**List retained versions.** Lists retained version ids with bounded pagination. Primary-entry ownership is checked.

- Caller: plugin for a delegated person
- Requires: `content:read` and current history read authority
- Query: `delegation_id` required; `limit`, `cursor` optional.
- Answers: `$defs/content_versions`.

Outcomes:

- 200
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `invalid_request`

### GET `/api/plugin/v1/content/:instanceId/versions/:versionId`

**Read a retained version.** Read one retained canonical snapshot, projected to field/locale grants and ownership.

- Caller: plugin for a delegated person
- Requires: `content:read` and current history read authority
- Query: `delegation_id` required.
- Answers: `{data: <content_version>}`; `$defs/content_version`.

Outcomes:

- 200
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `invalid_request`

### GET `/api/plugin/v1/media/:mediaId`

**Read existing media metadata.** Read site-owned media through the shared media resource service.

- Caller: plugin for a delegated person
- Requires: `media:read` and current media-library read authority
- Query: `delegation_id` required.
- Answers: `{data: <media>}` with presentation metadata.

Outcomes:

- 200
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `invalid_request`

### GET `/api/plugin/v1/media/:mediaId/bytes`

**Read existing media bytes.** Uses the shared provider reader for site-owned public and private bytes. External references have no local bytes. The response is private and is not cached.

- Caller: plugin for a delegated person
- Requires: `media:read` and current media-library read authority
- Query: `delegation_id` required.
- Answers: Binary file with safe content type/disposition.

Outcomes:

- 200
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `limit_exceeded` / `temporary_failure`

### PUT `/api/plugin/v1/media/:mediaId`

**Edit media metadata.** Uses shared media-metadata validation and an atomic, idempotent write.

- Caller: plugin for a delegated person
- Requires: `media:update` and current `media:update` authority
- `Idempotency-Key` required.
- Body: `$defs/media_update_command`.
- Answers: `media_updated`, `{id}`.

Outcomes:

- `media_updated` / `idempotent_replay`
- `capability_refused` / `requester_unauthorized` / `content_not_found` / `validation_failed` / `idempotency_key_reused`

### POST `/api/plugin/v1/content/:instanceId/futures`

**Prepare an independent future version.** Creates an immutable saved branch from the entry’s current ordinary draft, bound to this installation and release. Repeating the same installation, release and primary entry returns its existing branch. The ordinary draft and EAV values do not change. The person must still be able to read and update the entry; optional locale checks that language. A new name is trimmed and limited to 120 characters. The branch is edited through editor_url in Dee Wan, with its own revision and version CAS. It can be frozen only by an authorized publication command.

- Caller: plugin for a delegated person
- Requires: `workflow:release` and current delegated editorial authority
- Body — `$defs/future_create_command`. Closed. Required: `delegation_id`, `release_id`, `name`; optional `locale`. No `Idempotency-Key`.
- Answers: 201 `{ "data": <future with editor_url> }` — `$defs/future_created`, including the existing branch on a repeat.

Outcomes:

- `invalid_request`
- `capability_refused` / `requester_unauthorized` / `content_not_found`
- `validation_failed` / `version_conflict` / `transition_refused` / `temporary_failure`

### GET `/api/plugin/v1/content/:instanceId/futures/:futureId`

**Read this installation’s future version.** Reads a branch only when its site, primary entry and installation match. The response includes its state, revision and current_version_id, plus a currently authorized content summary whose current_version_id names this branch. It does not return unprojected field values. The workflow summary reflects the current authority and future-publication transitions, including an authorized future-only republish. For publication, pair future_draft_id with expected_future_revision and pin expected_current_version_id to this branch’s saved version. Core rechecks required fields, review tasks, workflow, references and media before freezing and publishing; ordinary drafts remain unchanged. A retry after an uncertain result must keep the original command, version and key.

- Caller: plugin for a delegated person
- Requires: `workflow:release` and current delegated read authority
- Query: required `delegation_id` — `$defs/future_read_query`.
- Answers: 200 `{ "data": { "future": <future>, "summary": <content_summary> } }` — `$defs/future_read`.

Outcomes:

- `invalid_request`
- `capability_refused` / `requester_unauthorized` / `content_not_found`

### POST `/api/plugin/v1/releases/commit`

**Apply a coordinated release.** Plans the final state of up to 25 commands in one site. Permissions, model reach, workflow, version, locale and dependencies are checked. All publication data, workflow events and replay records commit in one guarded tenant batch, or none do. Distinct locales of a group are supported; overlapping coverage is refused. Delivery and automatic redirects follow the commit.

- Caller: plugin for a delegated person
- Requires: `workflow:release`
- `Idempotency-Key` required. Body: `$defs/release_command`.
- Answers: `release_applied` or `idempotent_replay`, with `$defs/release_result`.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### GET `/api/plugin/v1/comments`

**Read visitor comments.** Uses the existing moderation read and current model/entry visibility.

- Caller: plugin for a delegated person
- Requires: `comments:read`
- Query: `delegation_id`, plus existing management comment-list filters.
- Answers: A bounded comment list, without private email addresses.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/comments/moderate`

**Moderate visitor comments.** Uses the ordinary moderation service. Consent is not fabricated; stale states are refused per comment.

- Caller: plugin for a delegated person
- Requires: `comments:moderate`
- `Idempotency-Key` required. Body: `delegation_id`, `to`, `comments: [{id, expected}]`.
- Answers: The ordinary moderation result.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### GET `/api/plugin/v1/redirects`

**Read redirects.** Requires current site:settings authority.

- Caller: plugin for a delegated person
- Requires: `redirects:read`
- Query: `delegation_id`.
- Answers: Accepted `revision` and `redirects` only.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/redirects/review`

**Review pattern redirects.** Uses the same live-address pattern review as the admin.

- Caller: plugin for a delegated person
- Requires: `redirects:write`
- Body: `delegation_id`, `redirects`.
- Answers: The pattern review and digest needed by the save.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### PUT `/api/plugin/v1/redirects`

**Change redirects.** Only redirect changes are accepted. Existing revision, path conflict, loop and pattern-review checks apply.

- Caller: plugin for a delegated person
- Requires: `redirects:write`
- `Idempotency-Key` required. Body: `delegation_id`, `expected_revision`, `redirects`, optional `redirect_review_digest`.
- Answers: Accepted `revision` and `redirects` only.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/content/:instanceId/restore`

**Restore a Trash item.** Restores as a draft through the existing lifecycle, address, field/language and ownership checks.

- Caller: plugin for a delegated person
- Requires: `content:restore`
- `Idempotency-Key` required. Body: `delegation_id`.
- Answers: The ordinary Trash restore result.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/media/:mediaId/remove`

**Delete unused media.** Requires current media:delete authority. Current content, retained history and concurrent references keep media from being deleted. Storage cleanup is separate.

- Caller: plugin for a delegated person
- Requires: `media:delete`
- `Idempotency-Key` required. Body: `delegation_id`.
- Answers: The ordinary media deletion result and cleanup state.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/mail/send`

**Send an approved email template.** Requires current site:plugins authority and an administrator-approved template. Fixed recipients use a manage delegation. Contextual templates require `instance_id` inside the installation and delegation model/item grants and the actor’s current read access; a manage or matching content-action delegation may be used. The approved `recipient_source` chooses `entry_author` (the account that created the selected CMS entry, `content_instance.created_by_id`) or `entry_assignee` (its current workflow assignee, `content_workflow.assigned_to_id`). Entry author is not a public Blog author/profile relation or the last editor. The account must be active, have current site access and currently read the entry; an active superadministrator may qualify without an explicit site membership. No eligible account gives validation_failed. The plugin cannot supply an email address, user id, recipient policy, subject, message body or provider credential. Responses never expose the recipient address. The ordinary 16384-byte request-body limit applies, with at most 16 declared substitutions of 1000 characters each. Expanded subjects must fit 200 characters without line breaks and expanded text must fit 12000 characters; invalid expansion is refused before storing a replay record. Each accepted command snapshots its messages and recipient account. Same-key retries keep that snapshot even if the author, assignment or template changes; they recheck the actor’s current entry access and the saved recipient’s active account, site/entry access and unchanged email. A changed entry or substitutions with the same key is refused. Provider retries retain the same message identity; an unconfirmed provider result remains retryable.

- Caller: plugin for a delegated person
- Requires: `mail:send`
- `Idempotency-Key` required. Body: `$defs/mail_command`.
- Answers: `operation_applied` or `idempotent_replay`, `{sent:true}`. This confirms provider acceptance, not inbox arrival.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

### POST `/api/plugin/v1/content/:instanceId/renderer-metadata`

**Save renderer metadata.** Writes only this installation’s declared contributions for one locale as an ordinary new saved version. Publication is separate. Core canonical SEO, verification and language links take precedence; no script or runtime CMS call is introduced.

- Caller: plugin for a delegated person
- Requires: `renderer:metadata`
- `Idempotency-Key` required. Body: `$defs/renderer_metadata_command`.
- Answers: The ordinary `content_saved` result.

Outcomes:

- `operation_applied` or the documented save/release outcome
- `capability_refused`, `requester_unauthorized`, `validation_failed`, `version_conflict`, `limit_exceeded`, `temporary_failure`

## Outcomes

Commands and every refusal answer an outcome envelope — a machine code and a human message.
Successful reads, `/launch/exchange` and `/invocations/exchange` do not: they answer `{ "data": … }`
(and `"next"` on a list page) with no `outcome`. Three refusals carry `data` too: `validation_failed`
names the rule (`$defs/validation_detail`), `draft_conflict` carries the current draft as
`data.current`, and `media_duplicate` carries the existing file and its copy count (`$defs/media_duplicate`).

```json
{
  "outcome": {
    "code": "transition_applied",
    "message": "…",
    "retry": false
  },
  "data": {}
}
```

Branch on a validated `code`, HTTP status and `retry` tuple, not on the human message.
The message must be a string, but its text is not stable. A retry flag alone is not authority.

| HTTP | Code | Retry | Meaning |
| --- | --- | --- | --- |
| 200 | `release_applied` | no | The release was applied atomically. |
| 200 | `operation_applied` | no | The operation was applied. |
| 200 | `transition_applied` | no | The transition was applied. |
| 200 | `idempotent_replay` | no | This command was already applied. The first result is returned. |
| 200 | `content_deleted` | no | The entry was moved to Trash. |
| 200 | `media_updated` | no | The media metadata was updated. |
| 200 | `content_saved` | no | The field values were saved as a new version. |
| 200 | `draft_saved` | no | The working draft was saved. |
| 200 | `draft_discarded` | no | The working draft was discarded. |
| 200 | `media_uploaded` | no | The media was uploaded. |
| 200 | `media_reused` | no | The site already holds this file. The existing media is returned and nothing was uploaded. |
| 200 | `proposal_created` | no | The proposal was created. Nothing changes until a person applies it. |
| 400 | `invalid_request` | no | The request is not valid for protocol v1. |
| 401 | `plugin_unauthorized` | no | The installation token is missing, unknown, disabled or revoked. |
| 403 | `capability_refused` | no | This installation was not granted that capability or model. |
| 403 | `requester_unauthorized` | no | The person who requested this no longer holds the authority it needs. |
| 404 | `content_not_found` | no | No such content in this installation’s scope. |
| 409 | `scheduled_target_stale` | no | The pinned version is no longer the one this transition would move. |
| 409 | `workflow_conflict` | no | The content moved through its workflow after this was requested. |
| 409 | `dependent_content` | no | Other content depends on this item. A person must review the unpublish in Dee Wan. |
| 409 | `idempotency_key_reused` | no | This idempotency key was already used for a different command. |
| 409 | `version_conflict` | no | The entry changed after the pinned version. Read it again before writing. |
| 409 | `media_duplicate` | no | The site already holds this file. Nothing was uploaded. Send on_duplicate to reuse it or upload a copy. |
| 409 | `draft_conflict` | no | The working draft changed after the pinned revision. Read it again before writing. |
| 413 | `limit_exceeded` | no | The request exceeds a size or count limit. |
| 422 | `transition_unavailable` | no | That transition is not available from the content’s current state. |
| 422 | `transition_refused` | no | The lifecycle refused this transition. Nothing was changed. |
| 422 | `validation_failed` | no | The values were refused by the content rules. Nothing was changed. |
| 429 | `rate_limited` | yes | Too many requests for this installation. |
| 503 | `temporary_failure` | yes | Dee Wan could not complete the request. Nothing is known to have changed. |

## Retry rules

- Inspect a structured outcome before considering the HTTP fallback. Its known `code`, HTTP
  status and boolean `retry` must match the table, and `message` must be a string. Any mismatch
  or malformed `outcome` member is terminal `untrusted_response`, even on a retryable status.
- A valid `rate_limited` (429) or `temporary_failure` (503) is retryable. Core emits
  `temporary_failure` only with 503. It does not emit that code with 500, 502 or 504.
- A bare inbound 429/500/502/503/504 with no `outcome` member is retryable:
  this includes empty, non-JSON and intermediary error bodies. On every other status, a
  command body without a valid outcome is terminal `untrusted_response`. Redirects are not followed.
- Network errors, timeouts and response-read failures are retryable `no_response`. They never
  prove that the command had no effect. An unreadable stored token is terminal `token_unreadable`.
- Honour `Retry-After` on retryable replies: nonnegative integer seconds or a canonical HTTP date (IMF-fixdate).
  Past dates mean zero delay. Invalid values use bounded exponential backoff and jitter.
  A wait above the configured maximum, the attempt cap or the age cap ends as `retry_exhausted`.
- A valid success is a 200 code: `release_applied`, `operation_applied`, `transition_applied`, `idempotent_replay`, `content_deleted`, `media_updated`, `content_saved`, `draft_saved`, `draft_discarded`, `media_uploaded`, `media_reused`, `proposal_created`.
  Every other valid non-retryable outcome is a terminal refusal under its own code.
- Reuse the exact body and `Idempotency-Key` after a retry or recovered lease. Requests may
  repeat. Their effects must be at most once within the key retention. Only the current lease
  owner may start a command, with its request deadline before lease expiry. Do not deliberately
  execute one delivery concurrently. A timeout cannot prove the remote request stopped.
- Keep the age cap well under 30 days. After retention, core forgets the key.
  Exhaustion sends nothing further and leaves any unacknowledged effect unknown. Check the
  content before creating a replacement schedule with a new key.
- These are command retry rules. A successful read still needs its documented data shape.
  `/launch/exchange` consumes a single-use code and is not automatically replayable after a lost reply.

## Administrative routes

These browser-facing routes require a user session and the site header. Installation, grants,
token rotation, removal and mail-template configuration require `site:plugins`. Named views use
their declared current model and system permissions instead. A plugin token cannot call these
routes; they are documented so plugin authors understand the host interface.
Each one that mutates writes an audit entry, and refuses (503 `audit_unavailable`) rather than
mutating unaudited. A refusal answers `{ "error": <text>, "reason": <code> }`. Branch on
`reason`, not on `error`. `missing_permission` also names the permission in `required`.

### GET `/api/plugins/views`

**List available plugin workspaces.** Navigation, dashboard placements and direct routes use the same live permission check. Frames stay isolated from the admin origin.

- Caller: signed-in person
- Requires: current declared view capabilities and readable granted models
- Answers: Available named admin views and their reviewed frame declarations.

Outcomes:

- 200

### GET `/api/plugins/views/:installationId/:viewId`

**Open an available plugin workspace.** An unavailable, disabled, ungranted or unreadable view returns not_found.

- Caller: signed-in person
- Requires: same live view authority as the list
- Answers: One reviewed view.

Outcomes:

- 200
- 404

### PUT `/api/plugins/:id/mail-templates`

**Review email templates and recipients.** Only declared template ids and substitutions are accepted. The reviewed configuration is stored per installation and audited.

- Caller: site administrator
- Requires: site:plugins
- Map of declared template id to `{recipient_source?, recipients, subject, text}`: at most 8 templates. Omitted or `fixed` recipient_source requires 1–8 approved addresses. `entry_author` or `entry_assignee` requires no addresses (`recipients: []`). Subject is 1–200 characters without line breaks; text is 1–12000 characters.
- Answers: The approved template configuration.

Outcomes:

- 200
- 403
- 409
- 422

### GET `/api/plugins`

**List installations.** Every non-revoked installation on the site, redacted: no token, no hash.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": [<installation>] }` — `$defs/installation`.

Outcomes:

- 200
- 403 `missing_permission`

### GET `/api/plugins/models`

**Models that can be granted.** Id, name and slug of every content model on the site, for the grant screen. The GRANT stores ids, so a rename keeps it and a deleted model makes that part of it inert.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": [{ "id", "name", "slug" }] }`

Outcomes:

- 200
- 403 `missing_permission`

### GET `/api/plugins/catalogue`

**Read the plugin catalogues.** Fetches every catalogue URL the operator set in `PLUGIN_CATALOGUE_URLS`, under the same URL rules and redirect refusal as a manifest. Nothing is stored and nothing is trusted: an entry only supplies a manifest URL, and installing it is the ordinary Review and Install, which fetches and validates the manifest again. A catalogue page is `{ "catalogue_version": 1, "plugins": [<entry>], "next"?: "https://…" }`. An entry is `{ "id", "name", "manifest_url", "summary"?, "categories"?, "homepage"?, "icon"? }`, with no other key. `id` follows the manifest id rule. `name` is at most 64 characters, `summary` at most 280. `categories` holds at most 5 lower-case slugs. Every URL passes the plugin URL rules. `next` must stay on the first page’s origin. Limits per catalogue: 5 pages, 128 KiB per page, 100 entries per page and 200 in all. At most 4 catalogues are read. A catalogue that breaks a rule is omitted in its entirety and named in `catalogues`. An invalid entry is left out and named in `problems`. When two entries share an id, the first one wins: configured catalogue order, then page order, then entry order. A catalogue failure never changes installed plugins or direct installation.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": { "configured", "entries": [{ "id", "name", "summary", "categories", "manifest_url", "homepage", "icon", "catalogue" }], "catalogues": [{ "catalogue", "origin", "ok", "entries" | "reason" }], "problems": [{ "catalogue", "index", "plugin_id", "reason", "fields" }] } }`

Outcomes:

- 200 — also when no catalogue is configured (`configured: false`) and when every catalogue failed. A catalogue `reason` is `url_invalid`, `url_not_https`, `url_credentials`, `url_fragment`, `url_private_destination`, `remote_redirect_refused`, `remote_body_too_large`, `remote_unreachable`, `catalogue_unavailable`, `catalogue_invalid`, `catalogue_next_refused`, `catalogue_too_many_pages`, `catalogue_too_many_entries` or `too_many_catalogues`. A problem `reason` is `entry_invalid` or `entry_duplicate`
- 403 `missing_permission`

### GET `/api/plugins/actions`

**Content actions to render.** The bounded `{ id, label }` pairs active installations declare, so the content screen can render a core-owned button. No markup, no script, no CSS, no icon URL ever comes from a plugin. With `instance_id`, only installations whose model grant includes that item’s model are listed, and an unknown item lists none.

- Caller: any member of the site
- Requires: none beyond site access
- `instance_id` (optional query) — the item the buttons are for. No body.
- Answers: `{ "data": [{ "installation_id", "plugin_name", "actions": [{ "id", "label" }] }] }`

Outcomes:

- 200

### GET `/api/plugins/cards`

**Sidebar cards to render.** The `entry_sidebar` or `page_sidebar` cards that active installations declare in `ui_extensions`. Core draws ordinary cards itself; an explicitly declared frame may show an isolated embedded view. A card launches through the launch route below. A content-action card is listed only for an item whose model the grant includes. A manage-view card is listed for such an item, or for a user with `site:plugins`. An unknown item lists none.

- Caller: any member of the site
- Requires: none beyond site access
- `placement` (query) — `entry_sidebar` or `page_sidebar`. `instance_id` (optional query) — the item on screen. No body.
- Answers: `{ "data": [<plugin_card>] }` — `$defs/plugin_card`.

Outcomes:

- 200
- 400 `invalid_placement`

### GET `/api/plugins/operations`

**Operations this person may run.** The `operations` active installations declare that this person may run now. Without `instance_id`: site operations (they need `site:plugins`) and entry operations on models the person reads. With `instance_id`: that entry’s operations. An operation whose `requires` the grant lacks is not listed, and neither is an `automation` operation or a content-list column. The endpoint is never listed.

- Caller: any member of the site
- Requires: none beyond site access
- `instance_id` (optional query) — the entry on screen. No body.
- Answers: `{ "data": [{ installation_id, plugin_id, plugin_name, operation }] }`.

Outcomes:

- 200

### POST `/api/plugins/:id/operations/:operationId/run`

**Run an operation.** Core validates the values against the declared input, records an invocation, POSTs the envelope to the declared endpoint and waits for the exchange and the answer. A completed answer is validated against `$defs/operation_result` and the declared result components, and audited by digest. An exact retry with the same `Idempotency-Key` and body returns the first result with `replayed: true`.

- Caller: a person the operation is listed for
- Requires: the operation’s own rule: `site:plugins` for a site operation, read access to the entry for an entry one, update access for a destructive one
- Body — `{ "instance_id"?: string, "input"?: { … } }`. `instance_id` is required for an entry operation and refused for a site one.
- `Idempotency-Key` — required.
- Answers: `{ "data": { invocation_id, installation_id, plugin_id, plugin_name, operation, instance_id, outcome: "completed", result } }`.

Outcomes:

- 400 `idempotency_key_required`, `malformed_body`, `invalid_request`, `input_invalid` (with `issues`), `input_too_large`
- 404 `operation_unavailable` — unknown, an `automation` operation, a content-list column, or not offered to this person now
- 409 `idempotency_key_reused`, `invocation_in_progress`, `plugin_unavailable`
- 422 `plugin_refused` — the plugin’s own `refusal: { code, message }`
- 502 `plugin_unreachable`, `plugin_response_invalid`
- 503 `audit_unavailable`
- 504 `plugin_timeout`

### GET `/api/plugins/columns`

**Content-list columns to draw.** The `page` operations active installations declare for one model: `scope: "page"`, `audience: "column"` and a `cell` kind. Core adds a column headed by the operation’s label to that model’s content list. A column is listed only while the installation is active, the model is in its grant, its `requires` are granted and the person reads the model. A credential’s scopes and model list narrow it like any plugin surface.

- Caller: any member of the site who can read the model
- Requires: none beyond reading the model
- `model_id` (query) — required. No body.
- Answers: `{ "data": [{ installation_id, plugin_name, operation, header, cell }] }`. `cell` is `text`, `badge` or `link`.

Outcomes:

- 200
- 400 `model_id_required`

### POST `/api/plugins/:id/columns/:operationId/cells`

**Compute one column for a page of rows.** Core keeps the rows the person may read now (at most 50, in the named model, not in Trash), and runs the `page` operation through the one invocation transport with the input `$defs/column_request`: the model and those row ids, no values. The plugin answers one `cells` block with at most one cell for each row it was asked about. A cell for another row, a repeated row, a link without an https `url`, a `url` or `tone` on a kind that does not take one, or text over 80 characters makes the whole answer `plugin_response_invalid`. A column is a read: it binds no delegation, keeps no replayed answer and writes no audit row.

- Caller: a person who reads the model
- Requires: none beyond reading the model
- Body — `{ "model_id": string, "instance_ids": string[1..50] }`. Closed.
- Answers: `{ "data": { installation_id, plugin_name, operation, header, cell, cells: [{ id, text, tone?, url? }] } }`. `cells` is empty when the person reads none of the rows or the plugin has nothing to show.

Outcomes:

- 400 `malformed_body`, `invalid_request`
- 404 `operation_unavailable` — unknown, not a column, not offered to this person now
- 409 `plugin_unavailable`
- 422 `plugin_refused`
- 502 `plugin_unreachable`, `plugin_response_invalid`
- 504 `plugin_timeout`

### GET `/api/plugins/list-actions`

**Actions for selected rows.** The interactive `entry` operations with `list_action: true` that active installations declare for one model. Core offers them on the rows a person selects in the content list. A destructive one is listed only to a person who may update in the model. The endpoint is never listed.

- Caller: any member of the site who can read the model
- Requires: none beyond reading the model
- `model_id` (query) — required. No body.
- Answers: `{ "data": [{ installation_id, plugin_id, plugin_name, operation }] }`.

Outcomes:

- 200
- 400 `model_id_required`

### POST `/api/plugins/:id/list-actions/:operationId/run`

**Run an action on selected rows.** Core runs the operation once for each named row, through the same service as `Run an operation`, so every row is authorized against the person’s current access, validated against the declared input, audited and answered on its own. At most 25 distinct rows, run a few at a time. One row’s refusal never stops the others. Each row’s idempotency key derives from the request’s `Idempotency-Key` and the row id, so retrying the whole request replays the rows that already ran and runs the rest.

- Caller: a person the operation is listed for, row by row
- Requires: the operation’s own rule for each row: read access to the entry, update access for a destructive one
- Body — `{ "instance_ids": string[1..25], "input"?: { … } }`. Closed. The same `input` applies to every row.
- `Idempotency-Key` — required.
- Answers: `{ "data": { "results": [<item>], "summary": { completed, failed } } }`. An item is `{ instance_id, ok: true, run }` where `run` is the operation run of `Run an operation`, or `{ instance_id, ok: false, status, reason, error, refusal? }` with the reason that route would answer for that row.

Outcomes:

- 200 — whatever each row did
- 400 `idempotency_key_required`, `malformed_body`, `invalid_request`
- 404 `operation_unavailable` — unknown or not a list action

### GET `/api/plugins/field-editors`

**Field editors to render.** Every active or disabled installation, with the `field_editor` extensions its stored manifest declares. Core draws a plugin editor only for an active installation, and only when the field still fits it. Otherwise the field keeps its stored value and core draws its built-in editor, naming the plugin and why its editor is unavailable. A model field names an editor in `ui.pluginEditor` (`{ "plugin": "<plugin id>", "extension": "<extension id>" }`). A model save that adds or changes that reference is refused unless an active installation declares the editor and the field carries its stored type, rules and options (400 `plugin_editor_not_installed`, `plugin_editor_not_active`, `plugin_editor_not_found`, `plugin_editor_type_mismatch`, `plugin_editor_rules_mismatch`, `plugin_editor_options_mismatch` or `plugin_editor_invalid`). An unchanged reference is kept after its plugin is disabled or uninstalled.

- Caller: any member of the site
- Requires: none beyond site access
- No body.
- Answers: `{ "data": [<field_editor_source>] }` — `$defs/field_editor_source`.

Outcomes:

- 200

### GET `/api/plugins/rich-blocks`

**Rich blocks to offer.** Every active or disabled installation whose stored manifest declares `rich_blocks`, with each definition namespaced as `<plugin id>/<name>`. The rich text editor offers an active installation's blocks in its insert menu, draws their fields itself and previews them from the declared `render` tree. A stored block keeps its type, version and values when its plugin is disabled or removed; the editor shows it as kept but not registered, and renderers show nothing for it on a public page. A content save that adds or changes a plugin block is refused unless an active installation declares its type (422 `rich_block_unregistered`), knows its version (`rich_block_version_unknown`) and accepts its values after the declared migrations (`rich_block_values_invalid`). An unchanged block is kept whatever is registered.

- Caller: any member of the site
- Requires: none beyond site access
- No body.
- Answers: `{ "data": [<rich_block_source>] }` — `$defs/rich_block_source`.

Outcomes:

- 200

### GET `/api/plugins/calendars`

**Editorial views this person can open.** Each installation that is not uninstalled and whose stored manifest declares a manage view (`calendar`, `releases`), with the views it declares and its state for this person: `available` (active, and the person reads at least one granted model, own entries included), `no_readable_models` (the person reads no granted model at all), `disabled`, or `unavailable` (not yet active). An empty list means no such plugin is installed. Nothing about the grant beyond that is shown.

- Caller: any member of the site
- Requires: none beyond site access
- No query parameter and no body.
- Answers: `{ "data": [{ "installation_id", "plugin_name", "views", "state" }] }`

Outcomes:

- 200

### POST `/api/plugins/review`

**Fetch and validate a manifest.** Fetches the manifest URL, validates it and returns what it asks for. Nothing is stored and no installation exists afterwards. This is the review step that makes approval informed.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "manifest_url": "https://…" }`
- Answers: `{ "data": { "manifest": <manifest>, "protocol_version": 1 } }`

Outcomes:

- 200
- 400 `malformed_body` / a manifest reason — `manifest_invalid`, `protocol_unsupported`, `manifest_origin_mismatch`, `manifest_unavailable`, `url_invalid`, `url_not_https`, `url_credentials`, `url_fragment`, `url_private_destination`, `remote_redirect_refused`, `remote_body_too_large`, `remote_unreachable`
- 403 `missing_permission`

### POST `/api/plugins`

**Install.** Re-fetches and re-validates the manifest. Records a pending installation with the approved capabilities and model ids. Mints a token, and hands the raw token plus the one-time activation code to the manifest’s `activation_url`. The installation becomes `active` only after a 2xx from the plugin. Core keeps the hash and never the token. A failed activation leaves nothing behind. A second install of the same plugin on the same site is a conflict rather than a second installation.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "manifest_url", "activation_code", "capabilities": […], "model_ids": […] }`. The capabilities must be a subset of the manifest request. An empty `model_ids` means no content access, not every model.
- Answers: `{ "data": <installation> }`, 201.

Outcomes:

- 201
- 400 `malformed_body` / `invalid_activation_code` / `invalid_capabilities` / `invalid_model_ids` / a manifest reason
- 403 `missing_permission`
- 409 `installation_exists` / `backend_url_unset` / `activation_superseded`
- 502 with a `reason` — `activation_refused` (a non-2xx answer), `url_invalid`, `url_not_https`, `url_credentials`, `url_fragment`, `url_private_destination`, `remote_redirect_refused`, `remote_body_too_large`, `remote_unreachable` — the plugin refused or could not be reached. Nothing is installed
- 503 `audit_unavailable`

### PUT `/api/plugins/:id/grant`

**Change the grant.** Replaces capabilities and model ids. Capabilities and model ids must stay within what the stored manifest requested; a capability outside it is refused, so changing the served manifest alone cannot widen a grant. A reduction takes effect on the next plugin request.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "capabilities": […], "model_ids": […] }`
- Answers: `{ "data": <installation> }`

Outcomes:

- 200
- 400 `malformed_body` / `invalid_capabilities` / `invalid_model_ids`
- 403 `missing_permission`
- 404 `not_found`
- 409 `installation_state_changed`
- 503 `audit_unavailable`

### PUT `/api/plugins/:id/policies/:policyId`

**Choose what a content policy outage means.** Sets one declared policy to `warn` (the default: a timeout, an outage or a malformed answer lets the write through with a warning) or `required` (the same failures refuse the write). A real `refuse` always refuses. `expected_mode` is the mode the administrator saw; another change in between, or an accepted upgrade, is a conflict.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "mode": "required", "expected_mode": "warn" }`
- Answers: `{ "data": <installation> }`

Outcomes:

- 200
- 400 `malformed_body`
- 403 `missing_permission`
- 404 `not_found` / `policy_not_found`
- 409 `policy_mode_changed` with the current `mode`
- 503 `audit_unavailable`

### PUT `/api/plugins/:id/hooks/:hookId`

**Turn a pre-operation hook on or off.** Sets one declared hook to `on` or `off`. A declared hook is `off` until an administrator turns it on. While `on`, an `upload_metadata` hook is asked before a new library file is accepted and a `comment_moderation` hook before a visitor comment is stored; a hook that cannot answer refuses the upload or holds the comment, and never approves. `expected_mode` is the state the administrator saw; another change in between, or an accepted upgrade, is a conflict.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "mode": "on", "expected_mode": "off" }`
- Answers: `{ "data": <installation> }`

Outcomes:

- 200
- 400 `malformed_body`
- 403 `missing_permission`
- 404 `not_found` / `hook_not_found`
- 409 `hook_mode_changed` with the current `mode`
- 503 `audit_unavailable`

### POST `/api/plugins/:id/upgrade`

**Accept a new manifest version.** Re-fetches the stored manifest URL and accepts the release an administrator has just reviewed. `expected_version` must match what is served, or the review is stale. The plugin id, the origin and the accepted protocol version must not have moved. Capabilities are INTERSECTED with the new request. An upgrade never widens a grant. A release that changes the accepted protocol version cannot be accepted: uninstall and install it again. A policy the new release no longer declares loses its mode; a new policy starts as `warn`.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "expected_version": "0.2.0" }`
- Answers: `{ "data": <installation> }`

Outcomes:

- 200
- 400 `malformed_body` / a manifest reason
- 403 `missing_permission`
- 404 `not_found`
- 409 `manifest_identity_changed` / `protocol_changed` / `manifest_changed_since_review` / `installation_state_changed`
- 503 `audit_unavailable`

### POST `/api/plugins/:id/rotate`

**Rotate the token.** Needs a fresh one-time code from the plugin, because rotation is a hand-off and not a reset. Core mints a token, sends it to the pinned activation origin, and only then swaps the hash. If the plugin refuses, the old token keeps working. The previous hash stays valid for at most 10 minutes, and the first request carrying the NEW token ends that overlap immediately. From then on the old token answers 401 `plugin_unauthorized`. A plugin with several workers must switch them all together. Alternatively, a worker can re-read the stored token once when it gets 401 right after a rotation.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- Body — `{ "activation_code": "…" }`
- Answers: `{ "data": { "rotated": true } }`

Outcomes:

- 200
- 400 `invalid_activation_code` (also for a body that is not a JSON object)
- 403 `missing_permission`
- 404 `not_found`
- 409 `installation_not_active` / `backend_url_unset` / `installation_state_changed`
- 502 with a `reason` — `activation_refused` (a non-2xx answer), `url_invalid`, `url_not_https`, `url_credentials`, `url_fragment`, `url_private_destination`, `remote_redirect_refused`, `remote_body_too_large`, `remote_unreachable` — and the OLD token keeps working
- 503 `audit_unavailable`

### POST `/api/plugins/:id/disable`

**Disable.** Keeps the configuration and the audit trail and stops the plugin API dead: every request answers `plugin_unauthorized` before any tenant access. Its cards disappear, and fields that name its field editors keep their values and are drawn with the built-in editor.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": { "id", "state": "disabled" } }`

Outcomes:

- 200
- 403 `missing_permission`
- 404 `not_found`
- 409 `installation_state_changed`
- 503 `audit_unavailable`

### POST `/api/plugins/:id/enable`

**Enable.** Returns a disabled installation to `active`, with the same token and the same grant.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": { "id", "state": "active" } }`

Outcomes:

- 200
- 403 `missing_permission`
- 404 `not_found`
- 409 `installation_state_changed`
- 503 `audit_unavailable`

### DELETE `/api/plugins/:id`

**Uninstall.** Revokes first: the state becomes `revoked`, both hashes are dropped, and the token can never become valid again. Audit attribution survives, because the workflow event stored a snapshot of the installation rather than a foreign key. Dee Wan does NOT claim this deleted anything the plugin holds — remote deletion is the plugin’s own action. Uninstall is allowed while model fields name its field editors: those fields keep their values and rules and are drawn with the built-in editor.

- Caller: a user with `site:plugins`
- Requires: `site:plugins`
- No body.
- Answers: `{ "data": { "id", "state": "revoked" } }`

Outcomes:

- 200
- 403 `missing_permission`
- 404 `not_found`
- 409 `installation_state_changed`
- 503 `audit_unavailable`

### POST `/api/plugins/:id/launch`

**Open the plugin, delegated.** Mints a one-time code, valid for 60 seconds, stored hashed, bound to installation, site, user, action and optional instance. The result is the `management_url` with the code on it. The response carries `Referrer-Policy: no-referrer` and `Cache-Control: no-store`. `action` must be `manage` with no instance, or a `content_actions` id from the stored manifest with one. For a content action the item’s model must be in the installation’s grant. A `manage` launch may name a `view` from the stored manifest’s `manage_views`; the URL then also carries `dee_wan_view`, a landing hint that grants nothing. A view launch is editorial: it needs no `site:plugins`, only one granted model the person reads, every entry or only their own. A bare `manage` launch is plugin administration and needs `site:plugins`. The delegation records `model_ids`: the granted models the person reads (for a content action, the item’s model), narrowed to a management credential’s models when one acts. A launch a management credential makes also records a capability ceiling: the installation’s capabilities that the credential’s scopes allow. Every later command through that delegation is refused `capability_refused` outside it. Dee Wan session cookies never leave Dee Wan.

- Caller: a site member for a content action or a `manage` view, a user with `site:plugins` for a bare `manage`
- Requires: read access to the named item, for a content action; one readable granted model, for a view
- Body — `{ "action": "manage" }`, `{ "action": "manage", "view": "calendar" }` (or `"releases"`) or `{ "action": "<action id>", "instance_id": "…" }`
- Answers: `{ "data": { "url": "https://…?dee_wan_launch=…" } }` — `$defs/launch`.

Outcomes:

- 200
- 400 `malformed_body` / `invalid_launch_action`
- 403 `missing_permission` (for a bare `manage`) / `no_readable_models` (a view launch, and the person reads no granted model at all) / `model_denied` / `not_owner` (the person may not read the item) / `model_not_granted` (the item’s model is outside the grant)
- 404 `not_found` — no such installation, or no such item
- 409 `installation_not_active`

## Structured field editors

A `field_editor` extension with `control: "group"` draws one JSON object field as up to 8 labelled members:
`text` (`max_length` up to 500), `number` (`min`, `max`, `integer`), `boolean` and `select` (up to 12 options). Member keys are
unique. The stored value stays one JSON object of at most 8192 bytes. Choosing the editor in the model builder writes its
closed schema onto the field (`config.schema`, with `validationType: "object"`), and the ordinary save path
validates supplied members and structure: values outside bounds or choices, unknown member keys and non-object
values are refused. Draft mode may omit required members; strict saves and every publication require them. The schema stays on the field
when the plugin is disabled or uninstalled, so the stored values stay valid and the built-in JSON editor draws them.

## Editorial completion

Existing summary reads stay usable. Add `delegation_id` to `GET /content/:instanceId` to receive `saved: { id, version_number, data }`. `data` holds canonical snapshot values, relations and media. Saved data is projected according to the current actor’s model, field, locale and ownership rules. Without a delegation, only the summary is returned.

`GET /content/:instanceId/versions?delegation_id=…&limit=50&cursor=…` lists retained versions.
`GET /content/:instanceId/versions/:versionId?delegation_id=…` reads one projected snapshot.
History checks primary-entry ownership. Pruned versions return `content_not_found`.

`POST /content` creates an ordinary saved entry. It requires the `content:create` capability, a manage delegation and `Idempotency-Key`. The required body fields are `delegation_id`, `model_id` and `locales`; optional fields are `primary_lang`, `slugs`, `relations`, `locale_relations`, `media`, `seo` and `label`. These shapes match the management entry-create contract. The lifecycle checks create, model, field and locale grants, as well as every target. It returns `content_saved`.

`PUT /content/:instanceId` continues to accept the existing `fields`, `locale`, `expected_version_id` and `delegation_id` properties. Optional `relations`, `locale_relations` and `media` use the management write shapes. `fields` may be empty when a reference write is present. The same lifecycle validation, optimistic version pin and idempotency rules apply.

`DELETE /content/:instanceId` moves the whole entry to Trash. The body contains `delegation_id` and `expected_version_id`. It requires `content:delete`, the actor’s delete grant and `Idempotency-Key`. Live entries must be unpublished first. It returns `content_deleted`; a retry returns the first result. An atomic version guard prevents concurrent loss.

`GET /media/:mediaId?delegation_id=…` reads metadata. `/bytes` reads existing provider bytes. Both require `media:read` and the current actor’s media-library read access. Site isolation applies to public and private files. The byte response is private, is not cached and uses a safe disposition. External references have no local bytes. `PUT /media/:mediaId` accepts `{ delegation_id, metadata }` and `Idempotency-Key`. Metadata uses the management shape: `alt_texts`, `default_focal`, `loading`, `fetch_priority`. It requires the actor’s `media:update` grant. The shared media service validates framing. It returns `media_updated`, `{ id }`.

## Embedded extension frames

Existing cards and field editors may declare `frame: { url, origin, operations? }`. `origin` must exactly match the frame URL’s origin and the plugin origin. The origin is reviewed before installation is accepted. Operations must name this manifest’s declared operations. An upgrade adds no permission grants.

The host iframe is credentialless, uses `sandbox="allow-scripts"` and sends no referrer. It receives no admin cookies or plugin token. On load, the host sends `dee-wan:connect`, protocol `1`, the field value and disabled state, transferring one MessagePort. The child uses only the transferred port and sends `{type:"ready"}`. For a field change, it sends `{type:"change",value}`; the ordinary editor save validates the value. The host sends the current `{type:"value",value,disabled}` after updates. For a resize, the child sends `{type:"resize",height}`; the host bounds the height. For an operation, the child sends `{type:"operation",id,operation,input}`. The host checks that the action is declared and currently offered to the actor, then uses the existing operation endpoint. The host answers `{type:"result",id,result}`. A repeated id reuses the same result. No arbitrary fetch endpoint, installation token or launch code enters the frame.

## Rich controls and vendor snippets

Rich blocks add `relation` controls (`models`, optional `multiple`) and `group` controls (`fields`,
optional `repeatable`, `max_items`). Groups support up to three nested levels and fifty items per group.
They use normal typed field inputs and the relation picker. During lifecycle saves, relation values are checked against current site, model and actor read grants.
The render tree uses `{group,children}` or `{each,children}` to scope child bindings. Top-level and nested media controls retain ordinary media pins.

Paragraph and heading alignment uses `data-align` plus the canonical `text-align` style. The values are left, center, right and justify. The editor, saved rich HTML and supported renderers share this contract.

Vendor snippets store a typed `snippet` rich block with `html`, `css`, `javascript`, `title`.
Canonical HTML stores JSON in an inert figure. The admin preview and supported renderers use dedicated static frame endpoints and the same MessageChannel payload. The public parent bridge is hash-approved. The frame CSP enforces an opaque sandbox, and vendor code stays inside the frame. Both use the same document payload in credentialless frames with no same-origin permission; scripts, forms and popups run only inside the frame. The provider owns the submitted booking or form data. Never store provider credentials in snippet content.

## Resolved rich relation output

A declared relation keeps IDs in saved data. Public rich output replaces each readable target with
a bounded reader-only reference: `reference: true`, `instance_id`, current `title`, usable `url`,
and `properties` containing only projected scalar target fields named by render-node `property`.
`{ field: "target", property: "address" }` reads that target field; an ordinary `{ field: "target" }`
shows its title/name. Relation anchors use the shared live Page/Blog/managed-route address or a
projected public `url` field. Targets with no address stay text. Hidden targets and private fields
are omitted. Normal save still accepts IDs only; resolved labels and URLs cannot be submitted as authority.

## Machine-readable schemas

- [`schemas/manifest-v1.schema.json`](/schemas/plugins/manifest-v1.schema.json) — the manifest, generated
  from the object core validates every fetched manifest with.
- [`schemas/protocol-v1.schema.json`](/schemas/plugins/protocol-v1.schema.json) — requests, responses,
  the activation hand-off body, outcomes, limits and secret shapes, generated from the same
  definitions. Request shapes are closed. Response shapes allow additional properties, because
  clients must ignore response keys they do not know.

JSON Schema is not the entire semantic validator. Enable format validation: URL fields use
`uri`, while the management URL uses `uri-template`. Manifest, base, activation and substituted
management URLs must share one origin and pass the HTTPS/private-destination policy. Only exact
development origins are exempt. DNS resolution is not checked. Capabilities are unique. Content
action ids must also be unique. `ui_extensions` ids are unique, are not one of `reserved_ids`, and
a card launches only a `content_actions` id or a `manage_views` entry the same manifest declares.
At least one protocol version must be supported. Approved grants
must stay within the manifest request and this site’s models. Transition kind determines its
one required version pin. Status/code/retry agreement is checked after shape validation.

<!-- dee-wan-docs page: /plugins/security/ -->

# Plugin security

Source: https://dee-wan-docs.pages.dev/plugins/security/

What a Dee Wan installation token is, how it is stored and rotated, how a person's authority reaches
a plugin command, what a grant actually bounds, and what someone who takes over a plugin can and
cannot do with it.

Every example here is replayed against the real routes by Dee Wan's own test suite. The ids and
secrets are synthetic.

See also [Protocol v1](/plugins/protocol-v1/) for the route-by-route surface and
[Writing a plugin](/plugins/authoring/) for the installation flow.

## The boundary

```text
browser ── user session ──► Dee Wan admin Worker
                              │  control database: installations, token hashes, grants, launch codes
                              │  tenant database: content, versions, workflow, audit
                              │
                              │  HTTPS + installation bearer token
plugin service ◄──────────────┘
  │  its own database, its own clock, its own sessions
  └── HTTPS + installation bearer token ──► /api/plugin/v1 ──► the same lifecycle service a person uses
```

Three properties hold that boundary up:

1. **The plugin API is not the admin API.** It lives under `/api/plugin/v1`, has its own middleware,
   and shares only the lifecycle service — there is no second implementation of a transition that
   could drift from the one a person drives.
2. **Plugin UI runs inside its reviewed boundary.** Declarative cards use core controls. Optional
   frames use the reviewed plugin origin, an isolated sandbox and a bound MessageChannel. Frames
   receive neither admin sessions nor installation tokens. Field edits use ordinary Save; declared
   operations use live host authorization. Vendor HTML/CSS/JS runs inside a separate opaque frame
   in previews and supported site renderers, without access to the admin or site's parent document.
3. **No plugin database access.** A plugin gets no Prisma client, no D1 binding, no R2 credentials
   and no Cloudflare account access. Everything it can read or change goes through the routes
   under `/api/plugin/v1`, and through the answers core asks it for — an operation result, a policy
   decision or a media source listing — which core validates before it uses them.

## Tokens

| | |
| --- | --- |
| Shape | `dwp_` plus 43 URL-safe characters — 256 bits of randomness from `crypto.getRandomValues` |
| Given to the plugin | Once, in the activation hand-off, over HTTPS to the manifest's own origin |
| Stored by core | SHA-256 hash only. There is no code path that can print the token again |
| Sent by the plugin | `Authorization: Bearer <token>`, on every request |
| Never in | A URL, a query parameter, an error body, a log line, an audit entry or a fixture |
| Scope | One installation, which is one plugin on one site |

The prefix is there so a leaked string is recognisable as a Dee Wan plugin credential. The entropy
is what makes it a credential. A malformed bearer value is rejected before any database read, so these guessing attempts never trigger a database lookup.

### Rotation

Rotation is a hand-off, not a reset, and it needs a fresh one-time code from the plugin — otherwise
anybody who could reach the admin route could silently replace a credential.

1. The administrator gets a new activation code from the plugin.
2. Core mints a new token and sends it, with that code, to the **pinned** `activation_url` from the
   stored manifest. Core does not use a URL supplied at rotation time.
3. Only on a 2xx does core swap the hash. **If the plugin refuses or cannot be reached, the old
   token keeps working** — a failed rotation must never lock a working installation out.
4. The previous hash stays valid for at most 10 minutes, so a request already in flight is not
   killed mid-rotation.
5. The first request carrying the NEW token ends that overlap immediately. From that moment the old
   token answers `plugin_unauthorized`, which is terminal.

Step 5 matters if your plugin runs more than one worker. If one worker starts using the new token
while another still holds the old one in memory, the second worker's next request is refused with a
terminal `401 plugin_unauthorized`, and if it settles its work on that answer, the work is lost.
Either switch every worker to the new token together, or, on a `plugin_unauthorized`, re-read the
stored token once and retry with it only if it has changed since the request was sent.

Core never stores and never logs the activation code. The plugin that issued it needs only enough to
check it: the Scheduling plugin stores a SHA-256 hash of each code with its expiry, never the code
itself.

### Revocation

`disabled` and `revoked` both stop the plugin API at the door — before tenant access, before the
body is read. `revoked` is terminal: the hashes are dropped and that token can never be valid again.
Uninstall revokes first, and Dee Wan makes no claim about data it cannot see.

## Launch delegation and the `delegation_id`

A plugin's management UI is a separate page, and Dee Wan session cookies never leave Dee Wan. The
link between the two is a launch code:

- random, one-time, stored **hashed**, and valid for 60 seconds
- bound to installation, site, user, action and — for a content action — one content instance
- exchanged by the plugin's BACKEND, with its own bearer token, for a delegation record
- a code minted for one installation cannot be exchanged by another
- the launch response carries `Referrer-Policy: no-referrer`. The plugin's own management page
  must send the same header, load no third-party resource before the exchange, and redirect to a
  URL without `dee_wan_launch` once the exchange is done.

Core checks, before minting: the requester has a session and access to the site, a bare `manage`
requires `site:plugins`, a `manage` launch naming a declared view (the editorial calendar or releases) requires
one granted model the requester may read — every entry, or only their own — and a content action requires read access to that specific item and is refused
(`model_not_granted`) when the item's model is not in the installation's grant. The admin UI only
offers a plugin's content actions on items of granted models. The delegation records `model_ids`,
the exact granted models the requester may read, with `read` or `read:own` (for a content action, the item's model). Every
later read and command is refused for an item outside them, or one the person can no longer read.

**The delegation is not a credential.** It carries no capability. What it carries is identity — and
that is what makes the authority re-read possible:

> Every plugin command names a `delegation_id`, and core re-reads that person's CURRENT authority
> from the control database before it writes anything. Authority recorded when a schedule was
> created is never carried forward.

What a delegation reaches:

- A **content-action** delegation is bound to one instance, and acts only on items in that
  instance's translation group — the group moves together on publish, so that is the unit. Naming
  it for any other item is `requester_unauthorized`.
- A **manage** delegation has no instance. It reaches an item only when the item's model is still
  granted, is in the delegation's `model_ids`, and the person can read that item now. A person who
  reads only their own entries reaches only their own entries. Anything else is
  `requester_unauthorized` or `content_not_found`.
- Core does not check the delegation's `action` on a command. The action tells the plugin which
  screen to open. It is not a permission.

**A delegation does not expire by time.** That is deliberate: a schedule created today may run next
month, and it must still be able to name the person who asked. What bounds it instead:

- the person's CURRENT authority, re-read on every command — they must still be an active user,
  still have access to the site, and still hold the permission the transition needs
- the installation — a disabled installation, an uninstalled one, or a token that is no longer
  valid stops every request before any delegation is read
- the grant — the item's model must still be granted, and the capability must still be held.

Core refuses the command at execution in all of these cases, even if the delegation was valid when it was created: the
person lost their role on the site, their account was deactivated, their role no longer carries the
publish permission, the item is outside the delegation's translation group, or the delegation
belongs to another installation. A read with `delegation_id` checks the delegation the same way: an
unusable delegation is refused as `requester_unauthorized` rather than answered with a quietly
shorter list, and a usable one narrows the offered transitions to what the person may do now.


**The person who asked no longer holds the authority it needs**

```sh
curl -X POST "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001/transitions/published" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sched:plg_0000000000000000000000000000d1ee:sch_0009:r1" \
  --data '{"kind":"publish","expected_current_version_id":"cdocsversion00000000000001","expected_workflow_revision":0,"delegation_id":"pld_0000000000000000000000000000d1ee"}'
```

```json
{
  "outcome": {
    "code": "requester_unauthorized",
    "message": "The person who requested this no longer holds the authority it needs.",
    "retry": false
  }
}
```

Nothing was written. This is terminal: a plugin must not retry it, and must show its user that the
schedule needs a person with the right authority.

The one deliberate exception is a replay. An `Idempotency-Key` that was already applied returns the
first result even if the requester has since lost their authority — the work is already done, and
re-answering it is not a new grant of permission.

## Site and model scope

**The site comes from the token and from nothing a caller sends.** There is no `X-Site-Id` on a
plugin request, no site in a body, and no database name anywhere: both are refused outright rather
than ignored, so a bug in a plugin cannot become a cross-tenant read.


**Naming a database**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp" \
  -H "X-D1-Binding: SOME_OTHER_TENANT"
```

```json
{
  "outcome": {
    "code": "invalid_request",
    "message": "A plugin request cannot name a database.",
    "retry": false
  }
}
```

Model access is the intersection of a capability and a stored list of content-model ids. A request for out-of-scope content answers `content_not_found` — the same answer as "no such content", so a plugin cannot map the
shape of a site by probing.


**An id from another site**

```sh
curl "https://cms.example/api/plugin/v1/content/cotherinstance0000000000001" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "content_not_found",
    "message": "No such content in this installation’s scope.",
    "retry": false
  }
}
```

A narrowed grant applies to the very next request:


**After an administrator removes the model from the grant**

```sh
curl "https://cms.example/api/plugin/v1/content/cdocsinstance00000000000001" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "content_not_found",
    "message": "No such content in this installation’s scope.",
    "retry": false
  }
}
```

Grants store model **ids**, so renaming a model keeps the grant and deleting one makes that part of
it inert. The administrative UI shows the current slugs beside the ids.

## Authentication is one-way

A user cookie is not plugin authentication. Plugin routes read `Authorization` and nothing else, so
a stolen browser session cannot be replayed against the plugin API:


**A session cookie on a plugin route**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -b "__Secure-better-auth.session_token=$SESSION"
```

```json
{
  "outcome": {
    "code": "plugin_unauthorized",
    "message": "The installation token is missing, unknown, disabled or revoked.",
    "retry": false
  }
}
```

The reverse holds too: a plugin token presented to an administrative route is refused as
unauthenticated. Those routes want a user
session, the site header, and `site:plugins`. A plugin has none of the three.


**A disabled installation, before any tenant access**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "plugin_unauthorized",
    "message": "The installation token is missing, unknown, disabled or revoked.",
    "retry": false
  }
}
```

One answer covers missing, unknown, disabled and revoked. Nothing tells a caller which applies.

## Rate limits

Requests are limited per installation — 120 per 60-second window — using the same enforcement
primitive as the rest of the product, and answered as the protocol's own envelope with
`Retry-After`. These are abuse controls. Nothing here is measured, reported or retained as
telemetry.


**Over the limit**

```sh
curl "https://cms.example/api/plugin/v1/context" \
  -H "Authorization: Bearer dwp_ExampleTokenNotRealExampleTokenNotRealExamp"
```

```json
{
  "outcome": {
    "code": "rate_limited",
    "message": "Too many requests for this installation.",
    "retry": true
  }
}
```

Respect `Retry-After`, and refuse your own record rather than waiting if the delay exceeds a maximum
you chose in advance.

## Outbound calls core makes

Core calls a plugin for four things: the manifest fetch, the activation or rotation hand-off, an
invocation of a declared operation, policy or media source, and the download of a media source file
a person chose. All are bounded and pinned.

- HTTPS only. Credentials in the URL and fragments are refused.
- Destinations are judged from the host name in the URL:
  - An IPv4 literal is refused if it is private, loopback, link-local, shared (CGNAT), multicast,
    reserved, benchmarking, or one of the documentation ranges (`192.0.2.0/24`, `198.51.100.0/24`,
    `203.0.113.0/24`). A public IPv4 literal is accepted.
  - Decimal and hexadecimal spellings such as `https://2130706433/` or `https://0x7f000001/` are
    normalised to dotted form by the URL parser first, and then judged the same way.
  - Every IPv6 literal is refused.
  - A name with no dot is refused, and so are `localhost`, `localdomain`, `local`, `internal` and
    `home.arpa`, and any name ending in one of them (`printer.local`, `db.internal`).
- Redirects are refused, not followed. A 3xx is `remote_redirect_refused`.
- The response body is capped at 32 KB and the call at 5 seconds. An invocation is capped at 64 KB
  and 10 seconds for the request, the exchange and the answer together.
- Every URL — manifest, base, activation, management, operation and policy endpoints — must share one
  origin, so no call can be pointed somewhere the reviewed manifest did not name.
- An invocation sends no content and no credential: only the installation id, the invocation id, a
  one-time code and its expiry. The plugin exchanges the code with its own token. Core accepts the
  answer only from that installation, only after the exchange, and only while the installation is
  active and its grant still covers the operation or policy.
- An operation's exchange also returns a `delegation_id`. Core records it with the invocation,
  bound to the caller, site and installation, and to the model and entry of an entry operation. A
  site operation's delegation has no entry and reaches the granted models the caller reads, like a
  `manage` launch; site operations already need `site:plugins`. It is never a code and cannot be
  exchanged at `/launch/exchange`. Every use is checked exactly like a launch delegation.
- The remote response is parsed as untrusted input against the manifest schema. An unknown key is a
  refusal, not something to ignore.
- A media source answer is accepted only when every `thumbnail_url` and `download_url` is on the
  manifest's origin and a `delivery_url` is on one of the source's declared `delivery_origins`. Core
  GETs a chosen `download_url` with no credential, no cookie and no redirect, within 20 seconds and
  the media file limit, and then checks the bytes like any upload. The picker loads previews from the
  plugin with `referrerpolicy="no-referrer"`, so neither the admin address nor any Dee Wan credential
  reaches the plugin. A copy is the site's own file; nothing public loads from the plugin. A file added
  in `reference` mode is the one exception: core never fetches its `delivery_url`, but published pages,
  site copies and generated sites load it from the declared delivery origin, so that origin is part of
  what the site's visitors' browsers contact.
- Workers cannot resolve DNS before `fetch`, so this is what the URL itself names. A public name
  that resolves to a private address is outside what the check can see.
- Local HTTP is possible **only** when `ENVIRONMENT=development` and the exact origin is listed in
  `PLUGIN_DEV_ORIGINS`. No wildcard, no private-range shortcut, no production fallback.

### Plugin catalogues

An operator may list catalogue URLs in `PLUGIN_CATALOGUE_URLS`, comma-separated. **Settings →
Plugins → Discover** reads them. None is set by default, and Dee Wan has no built-in registry.

- A catalogue URL, every `next` page and every URL in an entry pass the same rules as a manifest
  URL. Redirects are refused. `next` must stay on the first page's origin.
- At most 4 catalogues, 5 pages each, 128 KiB per page, 100 entries per page and 200 per
  catalogue. A catalogue over a limit is left out whole, with its reason shown.
- An entry is `id`, `name` and `manifest_url`, plus optional `summary`, `categories`, `homepage`
  and `icon`. Unknown keys are refused. An invalid entry is left out and listed by position.
- Two entries with one id: the first wins, in configured order, then page order, then entry order.
- The icon is shown only as an image, with no referrer.
- A listing grants nothing. **Review** sends the entry's manifest URL to the ordinary review, and
  Install fetches and validates the manifest again. The page format is in
  [Protocol v1](/plugins/protocol-v1/), under `GET /api/plugins/catalogue`.
- A catalogue failure never touches installed plugins or install by manifest URL.

## Audit

A plugin is an actor, not a user. No fake user is created, and no installation id is written into a
user foreign key.

A plugin transition records the installation id, the accepted plugin id, name and version, the
protocol version, a digest of the idempotency key — never the key itself — the resulting state and
publication pointer, and the email of the person whose delegation authorised it. Installation
identity lives in the control database and workflow audit in the tenant database, with no
cross-database foreign key: the tenant event stores an immutable snapshot. That is also why
uninstall cannot erase attribution.

Administrative acts — install, grant change, manifest acceptance, rotation, disable, enable,
uninstall — are written to the admin audit ledger by the acting user, and refuse (503
`audit_unavailable`) rather than mutating unaudited.

A write a plugin makes for a person — a field save, a media upload, a proposal — runs as that person:
the version or media row is theirs, and the admin audit ledger records them as the actor with the
installation id and plugin id in the change (`plugin.content.save`, `plugin.media.upload`,
`plugin.proposal.create`). It refuses (`temporary_failure`) rather than writing unaudited. A proposal
also stores the plugin's name and the person's email, which the entry editor shows. Working drafts
are the person's own unsaved work: they are neither versions nor audit, and a plugin reads only the
drafts of the person whose delegation it names.

An operation run or a policy check is audited as `plugin.operation.run` or `plugin.policy.check`, with
the person who asked as the actor and the installation, the declared id, the classified outcome and
digests of the input and the answer in the change. The values and the answer themselves are not
stored there. An administrator's choice of what an unanswered policy means is audited as
`plugin.policy.mode`.

A policy sees the facts of one write — model, entry, language, changed field keys and their values —
and nothing else: no credential and no other content. It answers allow, warning or refuse. A `save` or
`restore` policy may instead answer `transform`: replacement values, links, media or SEO overrides for
the same entry and language it was asked about. Core validates a transformed candidate like the
person's own input and stores it as part of that person's write. No policy answer can reach another
entry or language, move a workflow, or replace Dee Wan's own checks, which run first. A write is
committed only while the version the policy was shown is still current; a change in between is the
ordinary conflict.

## Threat model

**If a plugin is fully compromised**, an attacker holds one installation token for one site. It can
use only the capabilities the administrator granted, only on the granted models, and every write
needs a `delegation_id` whose person still holds the authority for that write, within that
delegation's reach (one translation group for a content action; for `manage`, the granted models the
person can still read). Within those limits it can:

- with `content:read`: read summaries and, with a live delegation, saved values and retained
  revisions projected to the person's model, field, locale and ownership limits
- with `workflow:publish`, `workflow:unpublish` or `workflow:locale`: publish or unpublish content,
  pinning the exact version and matching the current workflow revision
- with `content:write`: save values, relations and media on existing entries; with `content:create`: create entries; with `content:delete`: move entries to Trash, under the person’s normal lifecycle checks
- with `draft:write`: read, write and discard the delegated person's own working drafts
- with `media:write`: upload files; with `media:read`: read existing files and metadata; with `media:update`: edit metadata, under the person’s corresponding current media authority
- with `content:propose`: create proposals a person reviews, and read its own proposals
- through a granted `save` or `restore` policy: replace values, links, media or SEO overrides in the
  write it was asked about; through any granted policy: see that write's facts, and warn or refuse it
- through a granted operation or media source: answer what core asked, which core validates
- open the exchange route with codes it already holds.

It cannot:

- reach another site, or another model, or another installation's delegations
- use a capability, operation or policy the grant does not hold
- write without a delegation, or beyond what the delegated person may do now
- read users, roles, sessions, settings, model definitions or audit, or list the whole media library
- read saved values or retained revisions outside the delegated person's readable projection
- use media reads or metadata edits without the installation capability and the person's media
  authority; protected bytes keep the same site and visibility checks
- execute code in the parent admin document, or reach the database, R2 or any Cloudflare credential
- publish a newer draft than the one pinned, traverse a changed workflow, override dependent
  content, or use any override route — there are none in protocol v1
- act for a person who has lost their authority, or forge one: `delegation_id` is a lookup, not an
  assertion
- replay a mutation into a second effect, or save a version, upload media or create a proposal
  without its audit record. Working drafts are not audited (see [Audit](#audit)).

**Delegations are long-lived by design.** A delegation obtained today can still be used months from
now, because scheduled work needs that. The window is bounded by people and grants, not by a clock:
it closes when the person loses the authority or the site access, when the grant loses the model or
the capability, or when the installation is disabled, uninstalled or its token revoked. An
administrator who wants every outstanding delegation of a plugin to stop at once uninstalls it.

**If a launch code leaks** — a referrer, a log, a shared URL — it is one-time, 60 seconds old at
most, stored hashed, and useless without the installation token that exchanges it.

**An agent can create a launch link.** A management credential or connected app with `plugins:use`
gets the same link through the management API or MCP, minted by the same code with the same checks,
as the credential's creator. The answer is only the link and its expiry, never a plugin result. The
delegation that follows is the creator's, limited to the credential's models and capped by its
scopes: it carries only the installation capabilities those scopes allow (`content:read` for
`content:read` and `workflow:read`; `lifecycle:publish` for `workflow:publish`, `workflow:unpublish`
and `workflow:locale`; `content:write` for `content:write`, `content:create` and `draft:write`; `content:trash` for `content:delete`;
`media:write` for `media:write`, `media:read`, `media:update` and `media:source`; `content:propose`).
A command outside that ceiling is `capability_refused`. A scope only takes away.

**An agent can run a declared operation.** With `plugins:use`, the management API and MCP also run
an `interactive` operation the manifest declares and return its result. That is the only plugin
result an agent gets. Core POSTs your endpoint a one-time code, never the management credential or
the caller's values; you exchange the code with your installation token for the bound input. Core
rechecks the plugin state, the grant and the caller's live permissions before each run and before it
replays a keyed result. The audit keeps digests of the values and the result, not the values. An
`automation` operation is never offered to an agent.

**If an administrator is compromised**, an attacker can install a plugin and grant it the permissions held by that account. This risk is why `site:plugins` is a separate permission and is never implied by publish permission. Of the roles a new site starts with, only `admin` holds it. It is also why every installation step is audited and every grant is chosen manually from an explicit manifest request.

**What Dee Wan cannot defend against** is the plugin's own operation: its uptime, its clock, its
retry policy, what it keeps in its database, and whether it deletes your data when you ask. The
plugin's own documentation has to answer those, and an administrator has to read it before granting
anything. See the [Scheduling plugin](/plugins/scheduling/) for what that
looks like.

Creation, deletion, existing-media reads and metadata edits each need their own reviewed capability. Existing `content:write` and `media:write` grants do not gain these powers. Changed relation targets, including links inside components, must fit both the installation’s model grant and the launch delegation’s model list. An unchanged opaque link can remain during another edit.

<!-- dee-wan-docs page: /plugins/scheduling/ -->

# Scheduling plugin

Source: https://dee-wan-docs.pages.dev/plugins/scheduling/

This is a remote service plugin. It schedules one pinned version to be published, or one pinned published version to be unpublished. It also runs named releases: groups of publish and unpublish items across models and languages, run together at a set time or now. It carries out each change through Dee Wan plugin protocol v1. It has its own Cloudflare Worker, its own D1 database, its own cron trigger, and its own management UI. None of its code runs inside Dee Wan.

The manifest `id` is `dev.dee-wan.scheduling`, set as `PLUGIN_ID` in `src/app.ts`. It never changes across releases: an installed plugin's `id` cannot change, and a release with a different `id` is refused as `manifest_identity_changed`. A fork that you deploy as a different plugin needs its own reverse-domain `id`.

This directory is prepared to become the root of its own repository, `https://github.com/dee-wan-cms/dee-wan-scheduling.git`. Until that move happens it lives in the Dee Wan repository at `plugins/scheduling`. The last section, Moving to its own repository, lists the steps.

Documentation: [Testing a plugin](/plugins/testing/#a-local-two-service-setup) sets up this plugin alongside a local Dee Wan instance. [Scheduling, end to end](/plugins/scheduling-end-to-end/) then walks through install, a scheduled publish, and each failure. On the core side, see [Writing a plugin](/plugins/authoring/), [Protocol v1](/plugins/protocol-v1/), [Plugin security](/plugins/security/), and [Testing a plugin](/plugins/testing/).

## Compatibility

| Plugin | Manifest | Dee Wan protocol |
| ------ | -------- | ---------------- |
| 0.1.0  | v1       | v1               |

## Routes

| Route | Who | What |
| ----- | --- | ---- |
| `GET /dee-wan/manifest.json` | Dee Wan admin | Manifest v1, with the origin taken from `PUBLIC_ORIGIN`. |
| `GET /assets/scheduling.css` | Browser | The management UI's stylesheet. |
| `POST /admin/activation-codes` | Operator, with `Bearer ADMIN_SECRET` | Issues a one-time code, valid for 15 minutes. Body `{}` issues an activation code. `{"installation_id":"..."}` issues a rotation code for that installation only. Answers 201 with `{"code", "purpose", "installation_id", "expires_at"}`: `purpose` is `activate` or `rotate`, `installation_id` is `null` for an activation code, and `expires_at` is in milliseconds since the epoch. |
| `POST /dee-wan/activate` | Dee Wan core | `activate` creates an installation and refuses an existing one. `rotate` replaces the token. Each code is consumed once. |
| `POST /dee-wan/operations/schedule-status` | Dee Wan core | The `schedule-status` operation. Takes the closed invocation envelope, exchanges its code with the installation's token, reads the bound entry and answers its pending, retrying and running schedules as rows. Read-only. An open envelope is 400 and an unknown installation 404; if core will not exchange the code, if the request names another operation, or if the entry cannot be read, the operation returns `status: "refused"`. |
| `POST /dee-wan/operations/schedule-column` | Dee Wan core | The `schedule-column` content-list column. Takes the closed invocation envelope, exchanges its code, and answers one `cells` block: a badge for each named entry that has a pending, retrying or running schedule (the soonest, as `Publish 2026-09-20 09:00`; tone `warning` once it is retrying or running). It reads only this installation's schedules and writes nothing. An entry with no live schedule gets no cell. A code core will not exchange, another operation, a bound entry or input that is not a list of entry ids answers `status: "refused"`. |
| `POST /dee-wan/operations/schedule-draft` | Dee Wan core | The `schedule-draft` operation. Exchanges the code, takes the closed input `{ locale, transition, due_at, timezone, version_id }` (`due_at` a whole UTC minute, `timezone` IANA, `version_id` the saved draft version to pin), reads the bound entry through the binding's `delegation_id` and creates the same pinned publish schedule as the form, pinned to exactly `version_id`, keeping that delegation and the caller's email. The same request again answers the schedule it made. Refusals answer `status: "refused"` by name: `invalid_input`, `invalid_instant`, `unknown_timezone`, `past_time`, `entry_unreadable`, `requester_unauthorized`, `locale_unavailable`, `transition_not_allowed`, `nothing_to_pin`, `version_moved`, `draft_changed` (the entry's current draft is not `version_id`), `already_scheduled`, `execution_in_progress`. It never supersedes another live schedule. |
| `POST /dee-wan/operations/releases` | Dee Wan core | The `releases` site operation. Exchanges the code and reads the reach of the binding's `delegation_id`. Empty `release_id`: every release as rows and `releases.json`. With `release_id`: that release's items the caller may read, with readiness or outcome, as rows and `release.json` (the receipt). Read-only. |
| `POST /dee-wan/operations/release-edit` | Dee Wan core | The `release-edit` site operation: `action` `create` (`name`), `rename` (`release_id`, `name`), `add` / `add_future` (`release_id`, `instance_id`, `kind`, optional `locale` and `transition`) or `remove` (`release_id`, `instance_id`, `kind`, `locale`). Answers the release as `releases` does. Refusals answer `status: "refused"` by name, as in Releases below. |
| `POST /dee-wan/operations/release-run` | Dee Wan core | The `release-run` site operation, destructive: `action` `schedule` (`release_id`, `due_at` a whole UTC minute, `timezone` IANA), `cancel`, `run_now` or `retry`. The caller's delegation becomes the one the release runs under. `run_now` and `retry` start the first items at once and answer the release. |
| `POST /dee-wan/operations/timeline-preview` | Dee Wan core automation | Read-only cumulative release timeline for `release_id`, under the current delegation. Requires a release time; refuses `release_time_required` or overlapping same-instant changes as `release_time_ambiguous`. Not directly available through management API, CLI or MCP. |
| `GET /installations/:id?dee_wan_launch=dwl_...` | Browser, from Dee Wan | Exchanges the code, sets a session, and redirects with 303 to the page without the code. A manage launch with `dee_wan_view=calendar` or `dee_wan_view=releases` redirects to that view instead. |
| `GET /installations/:id` | Session | A content launch shows the content, the schedule form and that content's schedules. A manage launch shows the agenda. |
| `GET /installations/:id?month=&zone=&model=&lang=&state=` | Manage session | The agenda: one month as a list, grouped by day. |
| `GET /installations/:id/calendar?month=&zone=&model=&lang=&state=` | Manage session | The calendar: one month as a grid, with a count per day. |
| `GET /installations/:id/calendar/:day?zone=&model=&lang=&state=` | Manage session | One day (`YYYY-MM-DD`): its schedules by due time, then id. |
| `GET /installations/:id/schedules/:scheduleId` | Session | One schedule, with a preview of its content read through the session's delegation. |
| `POST /installations/:id/schedules` | Session and CSRF token | Creates a schedule. |
| `POST /installations/:id/schedules/:scheduleId/reschedule` | Session and CSRF token | Moves a pending or retrying schedule to a new time. |
| `POST /installations/:id/schedules/:scheduleId/cancel` | Session and CSRF token | Cancels a pending or retrying schedule. |
| `GET /installations/:id/releases` | Manage session | Every release, newest first, and the form that creates one. |
| `POST /installations/:id/releases` | Manage session and CSRF token | Creates a release (`name`, 1 to 80 characters). |
| `GET /installations/:id/releases/:releaseId` | Manage session | One release: when it runs, progress, its items with readiness, or its receipt. |
| `POST /installations/:id/releases/:releaseId/rename` | Manage session and CSRF token | Renames the release. |
| `POST /installations/:id/releases/:releaseId/schedule` | Manage session and CSRF token | Sets or moves the time (`local`, `timezone`, `fold`) of a draft or scheduled release. |
| `POST /installations/:id/releases/:releaseId/run` | Manage session and CSRF token | Runs a draft or scheduled release now. |
| `POST /installations/:id/releases/:releaseId/cancel` | Manage session and CSRF token | Unschedules a scheduled release, or stops a running one. |
| `POST /installations/:id/releases/:releaseId/retry` | Manage session and CSRF token | Runs the failed and cancelled items of a finished release again. |
| `POST /installations/:id/releases/:releaseId/items/:itemId/remove` | Session and CSRF token | Removes an item while the release has not started. A content session removes only its own entry's items. |
| `POST /installations/:id/release-items` | Content session and CSRF token | Adds the session's entry to a release (`release`), or to a new one (`new_release`), with `transition` `kind:to`, optional `locale`, and `version_mode` `ordinary` (default) or `future` (publish only). |
| `POST /admin/installations/:id/delete-data` | Operator, with `Bearer ADMIN_SECRET` | Deletes all plugin data for the installation, releases included, and answers `{"deleted": true}`. 404 `not_found` if the plugin holds no such installation. 409 `execution_in_progress` while one of its schedules or release items is running. |

`scheduled()` runs one schedule runner tick, then one release tick.

## Develop

Node 24 and npm. From this directory:

```sh
npm install
npm run typecheck
npm test
npm run dev        # wrangler dev on port 8788, with --test-scheduled
```

`npm install` also installs `@dee-wan/plugin-conformance`, the protocol v1 suite the tests run. Inside the Dee Wan repository it is the local package `packages/plugin-conformance`, declared as `file:../../packages/plugin-conformance`. Build it first with `npm run build` in that directory. The other tools also resolve from the Dee Wan root install there. In this plugin's own repository the package is a semver range from the npm registry, once it is published.

## Install

1. Deploy the Worker (see below) and set `PUBLIC_ORIGIN`.
2. Mint an activation code:
   ```sh
   curl -X POST -H "Authorization: Bearer $ADMIN_SECRET" https://scheduling.example/admin/activation-codes
   ```
3. In Dee Wan, go to Settings → Plugins and install from `https://scheduling.example/dee-wan/manifest.json` with the code. Grant the capabilities and models. `workflow:locale` is needed only to schedule one language at a time. Without it, every schedule moves the whole translation group.
4. To rotate the token, mint a code with `{"installation_id":"<id>"}` and give it to the rotate action in Dee Wan.

## Cards in Dee Wan

The manifest declares four `ui_extensions`. They are data. Dee Wan draws each card itself and opens Scheduling through its normal delegated launch.

- `schedule-card` (`entry_sidebar`) and `page-schedule` (`page_sidebar`): a **Schedule** card beside an entry or a page whose model the grant includes. It launches the `schedule` content action.
- `calendar-row` (`settings_row`): a **Calendar** card on the Scheduling row in Settings → Plugins. It launches the `calendar` manage view, so it replaces the plain Calendar button there.
- `releases-row` (`settings_row`): a **Releases** card on the same row. It launches the `releases` manage view.

Scheduling declares no field editor.

Its operations cover schedule status, content-list badges, releases and core automation. It declares no policy.

- `schedule-column` (`scope: "page"`, `audience: "column"`, `cell: "badge"`, `requires: ["content:read"]`, result `cells`).
  Dee Wan adds a **Scheduled** column to the content list of every granted model. Core sends the ids of rows on the current page that the person may read, never their values; the operation returns a badge for each entry with a live schedule. It binds no delegation and is never listed as an ordinary operation.
- `schedule-status` (`audience: "interactive"`, `requires: ["content:read"]`, result `rows`, `list_action: true`). Dee Wan shows it beside an entry of
  a granted model; a person runs it there and sees the entry's pending schedules. In the content list it is
  also a **Plugin actions** entry for the rows a person selects, run once per row. An agent runs it
  through the management API or MCP.
- `schedule-draft` (`audience: "automation"`, `requires: ["content:read", "workflow:read", "workflow:publish",
  "workflow:locale"]`, result `rows` and `json`, destructive). Only Dee Wan's content planner runs it, as
  the plan owner, to schedule the exact draft version it saved (`version_id`); when the entry's current
  draft is another version the operation refuses with `draft_changed` and schedules nothing. It is never an editor, management API, CLI or MCP
  operation, and those invocation routes reject it. The result's `schedule.json` block is the reference Dee Wan keeps:
  `{ schedule_id, status, locale, transition, due_at, timezone, local_datetime, pinned_version_id }`.
  The schedule keeps the operation's `delegation_id`, so Dee Wan re-reads the owner's authority when
  it runs, exactly as for a schedule made in the form.
- `timeline-preview` (`scope: "site"`, `audience: "automation"`, `requires: ["content:read", "workflow:read", "workflow:release"]`, result `json`): core-only cumulative preview through `release_id`, under the current delegation. It writes nothing.
- `releases`, `release-edit` and `release-run` (`scope: "site"`, `audience: "interactive"`, result `rows` and
  `json`; `release-run` is destructive and also requires `workflow:publish` + `workflow:release`). They are the Releases page as
  operations, so the admin, the management API, the CLI and local and remote MCP run the same rules. Dee
  Wan offers site operations to people with `site:plugins` and binds the caller's manage delegation, on
  the granted models they read; Scheduling reads that delegation's reach on every call. One operation
  per kind of change, with an `action` input, keeps the manifest inside the operation cap.

## Wrangler

Copy `wrangler.example.jsonc` to `wrangler.jsonc`. For a deployment, replace the placeholder `database_id` with the id `wrangler d1 create` prints. Local development keeps the placeholder.

- Binding: `PLUGIN_DB` (D1).
- Cron: `* * * * *`.
- Variables: `PUBLIC_ORIGIN`, `ENVIRONMENT`, `DEE_WAN_DEV_ORIGINS`, `MAX_ATTEMPTS` (5), `MAX_LATENESS_MS` (900000), `LEASE_MS` (60000), `MAX_RETRY_AFTER_MS` (300000).
- Secrets: `ADMIN_SECRET` (at least 16 characters), `TOKEN_KEY` (base64 of 32 random bytes, `openssl rand -base64 32`).

```sh
npx wrangler d1 create dee-wan-scheduling
npx wrangler d1 migrations apply dee-wan-scheduling --remote   # --local for dev
npx wrangler secret put ADMIN_SECRET
npx wrangler secret put TOKEN_KEY
npm run deploy
```

Apply new files in `migrations/` with the same `migrations apply` command before you deploy a release that needs them.

Losing `TOKEN_KEY` makes the stored installation tokens unreadable. Schedules are then refused with `token_unreadable`, and each installation has to be rotated.

## Local development against a local Dee Wan

The setup — both services, their settings, and the commands — is in [Testing a plugin](/plugins/testing/#a-local-two-service-setup). It needs no Cloudflare account.

The management UI cookie uses the `__Host-` prefix and the `Secure` attribute, so the browser needs HTTPS or `localhost`. An HTTP Dee Wan base URL is accepted only when `ENVIRONMENT=development` and its exact origin is listed in `DEE_WAN_DEV_ORIGINS`. Otherwise the base URL must use HTTPS and must contain no credentials, no query, and no fragment.

## Schedule semantics

- A schedule can be created only from a content launch (the `Schedule` action). The plugin reads the content with the delegation, and the chosen `(kind, to)` must be in the delegated `workflow.transitions`.
- Language: when the installation holds `workflow:locale` and the content has more than one language, the form offers `All languages` or one language. Single-language content shows no choice. `All languages` moves the whole translation group. One language moves only that language: the chosen `(kind, to)` must be in that language's transitions under `workflow.locales`, and the command sends `locale`. A posted language that Dee Wan does not list is refused with `locale_unavailable`.
- Pins: a publish pins `current_version_id`, an unpublish pins `published_version_id`, and both also pin `workflow.revision`. A one-language unpublish pins that language's own `published_version_id`. A one-language publish pins the group's `current_version_id`, because one version holds every language. The revision is always the group's. The schedule is stored against the primary instance, with `locale` set for one language and empty for the whole group.
- There is at most one live (`pending|retrying|running`) schedule per installation, content item, kind, and language. A whole-group schedule and a one-language schedule of the same item and kind conflict too: the group includes that language. A new schedule supersedes every conflicting live pending or retrying schedule in one batch. So a whole-group schedule replaces the item's one-language schedules of that kind, and a one-language schedule replaces the whole-group schedule of that kind. One-language schedules for different languages wait side by side. If a conflicting schedule is running, creation fails with `execution_in_progress`.
- Rescheduling creates a new row with a new revision and a new idempotency key. Revisions count per installation, content item and kind, across languages.
- The idempotency key is `sched:<installation_id>:<schedule_id>:r<revision>`. It stays the same on every retry.
- Only pending or retrying schedules can be cancelled. Cancelling a running schedule returns `execution_in_progress`. A finished schedule cannot be cancelled. Cancelling never calls Dee Wan and never reverses a transition.
- At execution time, core re-checks the person's authority, the pins, and the revision.
- A manage launch opens the agenda, or the calendar when Dee Wan asked for it: the schedules of the models the delegation reaches. The person can preview them, and reschedule or cancel those they may change. They cannot create schedules.

Statuses: `pending`, `retrying`, `running`, `completed`, `refused`, `cancelled`, `superseded`.

## Releases

A release publishes or unpublishes up to 25 items in one CMS command. Items may span models and languages within one site. Each item names an entry, a language or the whole translation group, a kind (`publish` or `unpublish`) and a target state.

- Open the Releases card in Settings → Plugins, or **Releases** on the Dashboard. This is a manage launch with `view: releases`; it needs access to a granted model, not `site:plugins`. Site operations still require `site:plugins`. Add entries from **Add to release** on their Schedule cards.
- Each change must currently be offered to the person through their delegation. Different languages of one translation group are allowed. Duplicate language scopes, or a whole-group item overlapping a language item, are refused as `already_in_release`. The limit is 25 items (`release_full`).
- Items show their title, language, model, change and current readiness. Unreadable items are counted without exposing their titles or reasons. **Run now** and **Retry unfinished items** are disabled while an item is blocked. An unavailable readiness check is unknown, not blocked; nothing starts.
- States are `draft`, `scheduled`, `running`, `done`, `failed`, `unknown` and `cancelled`. `Failed` means the CMS refused the command and none of its publication changes committed. `Outcome unknown` means a response did not establish whether the command committed. Item receipts retain the reported result; the runner never guesses which items succeeded.
- Adding or removing items is allowed only in `draft` and `scheduled`. Scheduling uses the same date, time and timezone rules as a single schedule. The release runs as the person who schedules, starts or retries it. Core rechecks current grants immediately before commit.
- Ordinary items are not pinned when added. At execution, the runner records the latest saved ordinary draft for publication (`expected_current_version_id`), the live version for withdrawal (`expected_published_version_id`) and the workflow revision. An independent future item uses its own branch instead, as described below. The whole recorded set goes to `/releases/commit` with reviewed `workflow:release` and the required per-change capabilities.
- Core validates the complete final publication state, including dependencies between items in the release. List order does not determine whether a shared section and its page can publish together. Distinct locales of one translation group commit together. Permission, version, workflow, locale, dependency or statement-budget refusal changes nothing. Core never splits an oversized command into smaller commits.
- **Run now** checks the whole release and sends one command. A scheduled tick checks one due release before starting it. A blocked scheduled release stays `scheduled`, records `blocked_at` and a Blocked attempts receipt, and is not automatically started again. Fix or remove the blocking items and use **Run now**, or set a new time to clear the mark.
- If the item set changes during readiness checks, starting or retrying is refused as `release_changed`; nothing is sent. The scheduled tick checks the new set on a later tick.
- Unscheduling returns a scheduled release to `draft`. Stopping prevents work that has not been sent. It cannot reverse an in-flight atomic command; the recorded result must still be recovered.
- Idempotency uses `rel:<release_id>:a<attempt>` for the complete command. A missing, transient or untrusted response retains every recorded pin and repeats the same command under the same key. After automatic retry limits, the release shows `Outcome unknown` when commit status remains unknown. Retry recovers that command before starting new work. A definite refusal permits a new attempt with fresh versions after readiness checks. Completed publication is never repeated as a new command.
- Receipts keep the release outcome, per-item published versions, last code and completion time. The `releases` operation downloads them as `release.json`. Delivery of notifications and automatic redirect completion happen after the tenant commit and cannot roll it back.

## Independent future versions

In **Add to release**, **Version → Latest ordinary draft** keeps the ordinary behavior. For publication, choose **Version → Independent future version** to create a separate version for this release. Future versions cannot be used for unpublish (`future_requires_publish`). The `release-edit` operation offers the same choice through `action: add_future` with `kind: publish`; `action: add` keeps the ordinary draft.

In Dee Wan, open **Future versions** on the entry and select the release's version. Edit its fields, or the sections and facts of a composed page, then **Save**. **Future history** lists that branch's immutable saved versions. Other releases can hold their own branches for the same entry. Editing or publishing one leaves the ordinary draft intact. When execution starts, core freezes the selected branch revision and version; it cannot be edited after freezing. Retries recover that exact recorded command and version rather than substituting a newer ordinary draft.

Set the release's date, time and timezone before **Preview through this release**; otherwise preview refuses with `release_time_required`. The preview starts from published content, applies earlier releases' publish and unpublish items, then the selected release. It respects current read permissions and does not change publication or public caches. Releases at the same instant are ordered by stable release id, but overlapping changes to the same entry and language at that instant refuse with `release_time_ambiguous`: choose different times. For composed pages, use the preview inside the future page editor.

Core obtains this timeline through the read-only `timeline-preview` automation operation with `release_id`. It is not a management API, CLI or MCP operation. Publication still rechecks current delegated authority, required fields and tasks, workflow, references and pinned media for the selected future snapshot. Editing a frozen branch or previewing an unavailable target is refused; the ordinary draft is never substituted.

## Calendar and agenda

The site-wide publishing calendar. It reads only the schedules this plugin stores. Dee Wan keeps no copy of them and runs no scheduler.

- Who: anyone who reads at least one model granted to Scheduling, own entries included. **Calendar** on the Dashboard or the Content list, or on the Scheduling row in Settings → Plugins, is a manage launch with `view: calendar`; it needs no `site:plugins`. **Manage** in Settings → Plugins is a bare manage launch and still needs `site:plugins`; it lands on the agenda. The manifest declares `manage_views: ["calendar", "releases"]`, and Dee Wan adds `dee_wan_view=calendar` to the launch URL. The hint grants nothing; the plugin reads it only after a successful exchange of a manage code. A content launch has no calendar or agenda and answers 403 there.
- Reach: before every page and every change the plugin asks Dee Wan `GET /api/plugin/v1/delegations/<id>`. Each view, count, filter, notice and schedule page shows only schedules of the models listed there. Any other schedule answers `not_found`. A person with access to no model sees `No content you can see is scheduled here.` Scheduling keeps the schedules; Dee Wan keeps no copy.
- Own entries: a model listed `entries: "checked"` is one where the person reads or updates only their own entries (`read:own`, `update:own`). For it the plugin asks Dee Wan `GET /api/plugin/v1/delegations/<id>/entries`, up to 100 entry ids a call, on every page and change. It shows, counts and offers filters only for the entries Dee Wan lists, and offers Reschedule or Cancel only for the kinds listed on that entry. Any other schedule answers `not_found`. A person with no own schedules sees an empty calendar. Scheduling stores no owner. A view pages through every entry of such models in its range and asks once per entry, however many schedules it has; counts, lists and filters come from that one checked set. A range with more than 4,000 such entries, past what one Workers Free request may ask, is refused whole: `This range is too large to check with Dee Wan at once. Nothing is shown. Open a single day.` The model and language filters of such models come from the checked entries of the view's range.
- Removed: when Dee Wan answers that read with 401 `plugin_unauthorized` (the installation was uninstalled, turned off, or its token revoked), every page answers 200 and says `This installation was removed from Dee Wan or turned off there. Its schedules no longer run.` It shows no schedule, no count and no action. Without the delegation’s current model list the plugin cannot tell which models the person may see, so it shows none. A Cancel or Reschedule sent anyway changes nothing.
- Dee Wan unavailable: no answer, a 5xx, or 429 `rate_limited` answers 403 with `Dee Wan is not available right now. Nothing changed. Try again in a minute.` and shows no schedules.
- Who may change what: Reschedule and Cancel appear only when the schedule's kind (`publish` or `unpublish`) is listed for its model. Dee Wan lists a kind when the installation holds `workflow:publish` or `workflow:unpublish`, the person may update the item (any item of the model, or under `update:own` their own), and the model's workflow has an edge of that kind whose permission the person holds. A person who does not meet these conditions browses read only and the page says so. A Reschedule or Cancel sent anyway answers `not_permitted` and changes nothing. A reschedule then still re-reads the content, as below.
- Views: **Calendar** is a month grid, Monday first, with a count per day. A day with schedules links to that day. **Agenda** is the same month as a list, grouped by day. **Day** lists one day's schedules by due time, then id.
- Address: the month and every filter live in the query, so each view is a plain GET link and the filter form works without JavaScript. Previous and next month keep the filters. So do the links between Calendar and Agenda, and the day links.
- `month`: `YYYY-MM`. Default: the current month in the chosen timezone. An unusable value falls back to the default.
- `zone`: the IANA timezone the days are interpreted in. Default `UTC`. Each row lands on the local day of its due time in that zone; month and day bounds are that zone's local midnights, also across clock changes and where midnight itself is skipped. An unknown zone is refused by name with 400 and a link to the same view in `UTC`.
- `model`: a model id. The list holds only models this installation has schedules for and the delegation reaches, by the slug recorded when the schedule was created.
- `lang`: a language. The list holds only languages this installation has one-language schedules for, on models the delegation reaches. A whole-group schedule moves every language, so it matches any language filter.
- `state`: `current` (the default: pending, retrying, running, completed, refused), `live` (pending, retrying, running), `all`, or one status. Completed and refused schedules show their result code and message.
- Bounds: each view reads one month, or one day, with a range on `due_at` served by the `schedule_agenda (installation_id, due_at, id)` index. The calendar counts per day in that one query. The agenda and the day show at most 200 rows, then a note to narrow the filters. Views write nothing.
- Names: each schedule shows the item's title recorded when it was created, or its slug when the item has no title. A one-language schedule shows the language name, in the UI language. When the viewing zone differs from the schedule's own zone, the time also shows in the viewing zone.
- Preview: `Open` on a schedule reads its content from Dee Wan with the session's delegation. It shows the title, model, language and current state, and whether the pinned version and workflow revision still match the current values. For a one-language schedule the language, state and pin are that language's own. If Dee Wan no longer lists that language, the preview says `locale_unavailable`. If Dee Wan refuses the read, the page says why. `Back` returns to the view it was opened from.
- Reschedule: a new local time and timezone for a pending or retrying schedule. The pins, the kind, the target and the language stay as they were. The plugin first re-reads the content through the session's delegation: the person must still be offered that transition, for that language when the schedule has one, and the pinned version and revision must still be current. Otherwise it refuses with `locale_unavailable`, `transition_not_allowed`, `scheduled_target_stale` or `workflow_conflict` and changes nothing. A reschedule inserts a new row with the next revision and marks the old one `superseded`, so it gets a new idempotency key. The new row carries the rescheduling person's delegation. A running schedule answers `execution_in_progress`, and a finished one cannot be moved.
- Cancel: pending or retrying schedules only, as in Schedule semantics. It never calls Dee Wan. From a view it returns to that view with the notice. A `return` address is accepted only for this installation's views, and its query is re-read, not echoed.

Dee Wan's Workflow panel links here. When the last workflow move of an item was made by this plugin, the panel offers `View schedule`, which opens this plugin's page for that item through the `Schedule` content action.

## Time

Each schedule stores the UTC `due_at`, the IANA timezone, the local wall time, and the fold. A timezone rule change never rewrites `due_at`. Resolution uses only `Intl.DateTimeFormat`.

| Input | Result |
| ----- | ------ |
| `2026-07-01T09:00` `America/New_York` | `2026-07-01 13:00 UTC` |
| `2026-03-29T02:30` `Europe/Berlin` | refused `nonexistent_local_time` (clocks jump 02:00→03:00) |
| `2026-10-25T02:30` `Europe/Berlin`, no fold | refused `ambiguous_local_time` |
| same, fold `earlier` | `2026-10-25 00:30 UTC` (CEST) |
| same, fold `later` | `2026-10-25 01:30 UTC` (CET) |
| `2026-07-01T09:00` `Mars/Base` | refused `unknown_timezone` |
| `2025-12-31T23:59` `UTC`, already past | refused `past_time` |

The confirmation and the list show the local time with its zone, and the UTC time. When the zone is `UTC`, the time shows once.

## Runner

Each cron tick takes up to 20 due rows, round-robin across installations. A compare-and-set claim changes the observed status and lease token, increments `attempt_count`, and assigns a fresh token with `lease_until = now + LEASE_MS`. After token decryption, the sender rechecks ownership and attempt/age limits, and checks that enough lease time remains for the complete request timeout. A runner that no longer owns the lease sends nothing and cannot settle another owner’s row. Recovery may resend the identical key and body. A timeout does not prove that remote execution stopped. Core idempotency is the effect boundary, not a promise of one HTTP request.

| Dee Wan answer | Plugin result |
| -------------- | ------------- |
| 200 `transition_applied` / `idempotent_replay` | `completed` |
| 400 `invalid_request` | `refused`, no retry |
| 401 `plugin_unauthorized` | `refused`, no retry |
| 403 `capability_refused` / `requester_unauthorized` | `refused`, no retry |
| 404 `content_not_found` | `refused`, no retry |
| 409 `scheduled_target_stale` / `workflow_conflict` / `dependent_content` / `idempotency_key_reused` | `refused`, no retry |
| 422 `transition_unavailable` / `transition_refused` | `refused`, no retry |
| Present outcome with a status/code/retry mismatch or malformed fields. Body without an outcome on other statuses. Redirects | `refused`, `untrusted_response` |
| 429 `rate_limited` | `retrying`. Uses a valid bounded `Retry-After`. Otherwise, uses exponential backoff with jitter. |
| 503 `temporary_failure` | `retrying`. Uses a valid bounded `Retry-After`. Otherwise, uses exponential backoff with jitter. |
| Bare 429/500/502/503/504 without an outcome. Network failure or timeout (10 s) | `retrying`. Uses bounded `Retry-After` when supplied. Otherwise, uses exponential backoff with jitter. |
| past `MAX_ATTEMPTS`, past `due_at + MAX_LATENESS_MS`, or `Retry-After` > `MAX_RETRY_AFTER_MS` | `refused` `retry_exhausted`, nothing more sent |

A structured outcome is checked before the bare-status fallback. Retry-After accepts nonnegative integer seconds or a canonical HTTP date (IMF-fixdate). A past date means zero and malformed values use backoff. A Retry-After value above `MAX_RETRY_AFTER_MS`, an exceeded attempt cap or an exceeded age cap yields `retry_exhausted`. `LEASE_MS` has a minimum of 11 seconds, longer than the 10-second request timeout. A claim with insufficient lease time sends nothing. A valid success is only `transition_applied` or `idempotent_replay`.

`retry_exhausted` after a network failure means the outcome is unknown, so check the content in Dee Wan. A schedule is never sent later than the lateness cap, including when a lease left by a crashed runner is reclaimed.

Attempts are recorded in `schedule_attempt` (attempt, start, finish, code, HTTP status). This is an operational record for the user, not telemetry.
## Data, retention, uninstall

- Stored data includes the installation id, site id, Dee Wan base URL and AES-GCM-encrypted token. It also includes hashed activation codes, hashed sessions (30 minutes) with their CSRF tokens, schedules and attempts, and releases with their items and receipts. No content snapshots and no Dee Wan user sessions are stored.
- Launch codes and raw tokens are never logged or stored raw.
- Uninstalling the plugin in Dee Wan revokes the token. The plugin data stays. Remaining schedules are refused with `plugin_unauthorized` when they come due. The plugin pages then say the installation was removed and show no schedules.
- To delete plugin data, the operator calls `POST /admin/installations/:id/delete-data` with `Bearer ADMIN_SECRET`. The call is refused with 409 `execution_in_progress` while a schedule is running. No automatic retention purge is built.

## Tests

```sh
npm test                     # vitest, from this directory
npm run typecheck
npm run test:cross-service   # this plugin and a live Dee Wan, both under wrangler dev; two to three minutes
```

`npm test` includes `test/conformance.test.ts`, which runs the `@dee-wan/plugin-conformance` protocol v1 cases against this plugin: the outcome table, statuses, retry flags, capabilities and secret shapes against the published schemas, the manifest against the published manifest schema, reply classification, activation, launch exchange, and delivery through the real runner against the package's fake core. `test/helpers/d1.ts` is a better-sqlite3 D1 shim that applies every file in `migrations/`.

`test/docs.test.ts` runs the Runner and Time tables above through `classify` and `resolveLocalTime`, so a row that nobody updated fails.

`test:cross-service` runs `test/cross-service/cross-service.test.mjs`. It starts Dee Wan's admin Worker and this plugin under local `wrangler dev`, installs the plugin through Dee Wan, and runs scheduled publishes, unpublishes and refusals through protocol v1. Dee Wan is an external checkout: set `DEE_WAN_CORE_DIR` to a Dee Wan repository with its dependencies installed (`node scripts/install-dependencies.mjs`), its packages built (`npm run build:packages`) and its Prisma client generated (`npm --workspace backend run prisma:generate`). Inside the Dee Wan repository the variable may be left unset. [The automated cross-service run](/plugins/testing/#the-automated-cross-service-run) lists what it asserts.

`.github/workflows/ci.yml` is this plugin's own CI, for its own repository: install, typecheck, `npm test`, then the cross-service run against a Dee Wan checkout at `vars.DEE_WAN_CORE_REF` (default `main`). GitHub does not run it while this directory is inside the Dee Wan repository, and Dee Wan's CI does not run this plugin.

## Moving to its own repository

The move needs explicit authority: creating `dee-wan-cms/dee-wan-scheduling`, pushing to it and publishing `@dee-wan/plugin-conformance` are external actions. With that authority, from the Dee Wan repository root:

```sh
# 1. Publish the conformance package (needs npm publish rights for the @dee-wan scope).
cd packages/plugin-conformance
npm install
npm test
npm publish --access public
cd ../..

# 2. Split this directory with its history into a branch.
git subtree split --prefix=plugins/scheduling -b scheduling-split

# 3. Create the empty repository dee-wan-cms/dee-wan-scheduling on GitHub, then push the branch as main.
git push https://github.com/dee-wan-cms/dee-wan-scheduling.git scheduling-split:main

# 4. In a clone of the new repository: depend on the published package and commit a lockfile.
git clone https://github.com/dee-wan-cms/dee-wan-scheduling.git
cd dee-wan-scheduling
npm pkg set devDependencies.@dee-wan/plugin-conformance=^0.1.0
npm install
npm run typecheck
npm test
git add package.json package-lock.json
git commit -m "Depend on the published @dee-wan/plugin-conformance"
git push
```

Then, in that repository: if `dee-wan-cms/dee-wan` is private, add a read-only `DEE_WAN_CORE_TOKEN` secret, and optionally set the `DEE_WAN_CORE_REF` variable to the Dee Wan ref to test against. The links in this README and in `docs/end-to-end.md` that point into `../../docs/plugins/` must become links to the published Dee Wan documentation.

Removing `plugins/scheduling` from the Dee Wan repository is a separate change there. It also drops this README and `docs/end-to-end.md` from the Dee Wan documentation site (`docs-site/allowlist.mjs` and their `ru` and `th` translations) and points `docs/plugins/*.md` at the new repository.

<!-- dee-wan-docs page: /plugins/scheduling-end-to-end/ -->

# Scheduling, end to end

Source: https://dee-wan-docs.pages.dev/plugins/scheduling-end-to-end/

Both services on one machine, no Cloudflare account, no production credentials: install the plugin into a
local Dee Wan, schedule a real publish, make the runner execute it, and then make it fail in each of
the ways it is supposed to fail.

[The plugin README](/plugins/scheduling/) is the reference for routes, configuration, schedule semantics and the retry table.
This guide gives the sequence. Core-side documentation lives in
[`docs/plugins/`](/plugins/authoring/) of the Dee Wan repository —
[protocol v1](/plugins/protocol-v1/), [security](/plugins/security/),
[testing](/plugins/testing/).

Nothing below needs a real domain, a real token or a deployed Worker. Do not point any of it at a
production site.

## 1. Set up both services

Follow [A local two-service setup](/plugins/testing/#a-local-two-service-setup) in
Testing a plugin, using this plugin. When you are done:

- Dee Wan's admin Worker runs on `http://localhost:8787` and its admin UI on `http://localhost:5173`,
  with `PLUGIN_DEV_ORIGINS=http://localhost:8788` in `backend/.dev.vars`, and `local:seed` has
  printed a sign-in.
- this plugin runs under `npx wrangler dev --port 8788 --test-scheduled` from `plugins/scheduling`,
  with its local D1 migrated and `ADMIN_SECRET=local-admin-secret-0123456789` in `.dev.vars`.
- you hold a fresh activation code from `POST /admin/activation-codes`. It is one-time and expires
  after 15 minutes, so mint another if it has lapsed.

The commands below run from `plugins/scheduling`.

## 2. Install, in the admin UI

Sign in at `http://localhost:5173` with the account `local:seed` printed, then
**Settings → Plugins → Install**:

- manifest URL `http://localhost:8788/dee-wan/manifest.json`.
- the activation code from step 1.
- capabilities: tick all five for this walkthrough. Every box starts unticked.
- models: tick `Article` (or whatever the seeded site has).

Use the UI rather than curl: the administrative routes require a real session, the site header and the
`site:plugins` permission, and the UI has all three.

![Settings → Plugins after Review: the manifest's requested capabilities and the site's models, each a checkbox, above an empty activation code](/assets/screenshots/plugins-review.webp)

![Settings → Plugins after Install: Scheduling 0.1.0 is Active with its grant and models](/assets/screenshots/plugins-installed.webp)

What happens, in order: Dee Wan fetches and validates the manifest, records a pending installation,
mints a token, `POST`s it with your code to `http://localhost:8788/dee-wan/activate`, and marks the
installation active only after this plugin answers 2xx. Check the plugin's side:

```sh
npx wrangler d1 execute dee-wan-scheduling --local \
  --command "SELECT id, site_id, dee_wan_base_url FROM installation"
```

The `token_ciphertext` column is what a stored token looks like. There is no column, log line or
route on either side that will show you the raw token.

## 3. Schedule a publish

In Dee Wan: open a draft item in that model, and use the **Schedule** action the manifest declared.
That is a delegated launch: Dee Wan mints a one-time code, your browser lands on
`http://localhost:8788/installations/<id>?dee_wan_launch=…`, this plugin's backend exchanges it for a
delegation, sets its own session cookie, and redirects to the same page without the code in the URL.

The form reads the item through the delegation, so the transitions it offers are the ones **you**
may take right now. Pick a local time a minute or two ahead and a timezone. The confirmation shows
both the local time with its zone and the resolved UTC instant; both values matter and both are stored. With the zone `UTC` the two are the same, so it shows one.

```sh
npx wrangler d1 execute dee-wan-scheduling --local \
  --command "SELECT id, kind, target_state, pinned_version_id, expected_workflow_revision, local_datetime, timezone, due_at, status FROM schedule"
```

`pinned_version_id` is the exact version this will publish — not "whatever is current when it runs".

## 4. Make it run

A cron trigger does not fire in `wrangler dev` on its own. With `--test-scheduled`:

```sh
curl "http://localhost:8788/__scheduled?cron=*+*+*+*+*"
```

One tick claims up to 20 due rows with a lease, sends one command per schedule, and records each outcome. Then:

```sh
npx wrangler d1 execute dee-wan-scheduling --local \
  --command "SELECT id, status, attempt_count, last_code, last_message FROM schedule"
npx wrangler d1 execute dee-wan-scheduling --local \
  --command "SELECT schedule_id, attempt, code, http_status FROM schedule_attempt ORDER BY attempt"
```

A completed schedule reads `status = completed`, `last_code = transition_applied`. In Dee Wan the
item is now published, its whole translation group moved together, and the content history shows
**Scheduling plugin** as the actor, rather than your user account; no fabricated user account is created.

A tick before the due time claims nothing. After the due time, the first tick completes the
schedule, and a second tick finds nothing to do, because only due `pending` or `retrying` rows (and
`running` rows whose lease has expired) are claimed, and this one is now `completed`. If the same
command were ever sent twice — a crashed worker whose lease is reclaimed, say — the idempotency key
makes Dee Wan answer `idempotent_replay` instead of publishing again.

To see it on the calendar: **Calendar** on the Dashboard or the Content list, or **Settings →
Plugins**, then **Open** on the Calendar card of the Scheduling row. That is a `manage` launch with
`"view": "calendar"`. It needs no `site:plugins`, only one model granted to Scheduling that you read,
all entries or only your own. A person who reads but may not publish sees the same calendar with no
Reschedule or Cancel. A person who reads only their own entries sees only the schedules of those.
The launch URL carries
`dee_wan_view=calendar` next to the code, and after the exchange the plugin redirects to
`/installations/<id>/calendar`. The day of the schedule shows a count; the day link lists the
schedule as `Completed` with `transition_applied`. Pick another timezone in the filter to see the
same row on that zone's local day.

## 4a. Run a release

Open **Settings → Plugins**, then **Open** on the Releases card of Scheduling (a manage launch with `view: releases`). The Dashboard also offers **Releases**. Create `Launch` and add two entries from different models through **Add to release** on their Schedule cards. Select the publish action and the language or whole translation group. A release holds at most 25 items.

For an ordinary item, keep **Version → Latest ordinary draft**. Save a new draft of one entry, then reload the release. It remains ready to send the latest saved ordinary draft: adding an ordinary item does not pin its version. If any item is blocked, **Run now** is disabled with its reason. Unreadable items count as blocking without exposing their names. Fix or remove the blocking item. A scheduled release blocked at its time stays scheduled, records Blocked attempts and waits for a person to run it or change its time.

For a second release, choose **Version → Independent future version** when adding a publish item. In Dee Wan, open **Future versions**, select that release, change its title or page sections and **Save**. Check **Future history** and confirm the ordinary draft still has its original content. Set a release time, then use **Preview through this release** (the page editor has its own preview for composed pages). Preview includes published content and earlier release changes; without a time it refuses `release_time_required`. Give an overlapping change to the same entry and language a different time to avoid `release_time_ambiguous`.

Start the future release and confirm its branch is frozen. Publication must use that exact branch version, retain its media pins and pass current authority, required fields and review tasks. After a lost reply, retry the recorded command rather than selecting a new draft. The ordinary draft remains unchanged. Automation uses `timeline-preview`; `release-edit` uses `add_future` for this version mode and refuses an unpublish request with `future_requires_publish`.

Press **Run now**. The runner records every version and workflow revision, then sends one atomic `/releases/commit` command. All publication changes commit together or none do. Inspect the receipt and local rows:

```sh
curl "http://localhost:8788/__scheduled?cron=*+*+*+*+*"
npx wrangler d1 execute dee-wan-scheduling --local \
  --command "SELECT instance_id, status, attempt, published_version_id, last_code FROM content_release_item"
```

The release reads `Done`; the receipt contains `release_applied` and the committed version for each published item.

To exercise refusal, include an unpublish item that still has a published dependent outside the release. Core returns `dependent_content`, the release reads `Failed`, and neither that withdrawal nor the other publication applies. Resolve the dependency and use **Retry unfinished items**. A definite refusal starts a new attempt with fresh versions under `rel:<release>:a2`.

Also publish a shared section and a page that uses it in one release, in either item order. Check two different locales of the same translation group together. Duplicate language scopes and whole-group/locale overlap must be refused.

A lost response must not be treated as failure or partial success. The runner retries the complete recorded command under the same key. If retry limits leave its result unknown, it shows `Outcome unknown`; retry recovers that command rather than guessing which items committed.

To schedule, choose a date, time and timezone and press **Schedule**. A tick before that time changes nothing; a due tick checks the release and sends one command. **Unschedule** returns it to draft. **Stop remaining items** cancels unsent work. Completed changes remain; a command already sent cannot be undone.

The same actions are available through the `releases`, `release-edit` and `release-run` plugin operations in the management API, CLI and MCP. Those operations require `site:plugins`.

## 5. Make it fail, on purpose

Each of these is a real state a user will hit. Do them in a scratch site.

| To see | Do this | Expect |
| --- | --- | --- |
| `scheduled_target_stale` | Schedule a publish, then edit and save the draft, then tick | `refused`, no retry, and the item stays unpublished |
| `workflow_conflict` | Schedule a publish, then publish and unpublish the item by hand, then tick | `refused`, no retry |
| `transition_unavailable` | Schedule a publish, then publish the item by hand, then tick | `refused`. Dee Wan checks the move before the revision, and a published item offers no publish |
| `dependent_content` | Publish A, relate published B to it, schedule an unpublish of A, tick | `refused`, and Dee Wan names the dependency |
| `requester_unauthorized` | Schedule as a user, remove that user's role in Dee Wan, tick | `refused`. Authority is re-read at execution, never carried forward |
| `plugin_unauthorized` | Schedule, then disable or uninstall in Settings → Plugins, tick | `refused`, stored with `last_code = plugin_unauthorized`. The plugin pages say the installation was removed or turned off, and show no schedules |
| a transport failure | Stop Dee Wan's admin Worker (`local:api`), tick | `retrying` with `last_code = no_response` and a `next_attempt_at`. Restart it and tick after that time to complete |
| `retry_exhausted` | Stop Dee Wan and tick past `MAX_ATTEMPTS`, or past `due_at + MAX_LATENESS_MS` | `refused` `retry_exhausted`, and nothing more is ever sent |
| cancellation | Cancel a pending schedule in the plugin UI | `cancelled`. Dee Wan is never called and nothing is reversed |
| a running schedule | Cancel while a tick is in flight | `execution_in_progress`, and the UI reloads the final state |

Set `MAX_ATTEMPTS=2` and `MAX_LATENESS_MS=60000` in `.dev.vars`, and restart `wrangler dev`, to reach
the caps in a minute rather than a quarter of an hour.

A stopped Worker is a transport failure, not `temporary_failure`: there is no answer at all, so
there is no outcome code. `temporary_failure` is an answer: Dee Wan sends it as a structured
outcome only with 503, and the plugin also records a bare 500, 502, 503 or 504 with no outcome under
that code. A local Dee Wan does not produce either on demand. The plugin's own suite covers it with an injected
reply.

After a `retry_exhausted` that followed a transport failure, the outcome is genuinely **unknown** —
the command may have been applied by a Dee Wan that could not answer. Check the item in Dee Wan.
That is why the schedule says so rather than claiming a failure.

## 6. Rotate, and uninstall

Rotation, which an operator should practise before they need it:

```sh
curl -X POST -H "Authorization: Bearer local-admin-secret-0123456789" \
  -H 'content-type: application/json' \
  --data '{"installation_id":"<installation id>"}' \
  http://localhost:8788/admin/activation-codes
```

Then Settings → Plugins → Rotate with that code. Dee Wan mints a new token, hands it here, and only
then swaps its stored hash. The old token stays valid for a bounded overlap, and the first request
carrying the new one ends the overlap. If this plugin refuses, the old token keeps working — check
that too, by rotating with a code you have already used.

Uninstall in Dee Wan revokes the token immediately and permanently. This plugin's data stays: any
remaining schedule is refused with `plugin_unauthorized` when it comes due. The plugin pages stop
showing schedules and say instead that the installation was removed from Dee Wan and its schedules
no longer run: without Dee Wan's answer the plugin cannot tell which models the person may see.
Audit attribution in Dee Wan also stays, because the workflow event stored a snapshot of the
installation.

To remove this plugin's data for an installation, an operator asks for it:

```sh
curl -X POST -H "Authorization: Bearer local-admin-secret-0123456789" \
  http://localhost:8788/admin/installations/<installation id>/delete-data
```

It answers `{"deleted": true}`, 404 `not_found` if the plugin holds no such installation, and 409
`execution_in_progress` while a schedule or release item of that installation is running. There is no automatic
retention purge. Deletion must be requested explicitly.

## 7. Reset

```sh
rm -rf .wrangler/state            # in plugins/scheduling: the local plugin D1
npx wrangler d1 migrations apply dee-wan-scheduling --local
```

The Dee Wan side resets with its own local database. Re-run `npm run local:migrate`, and
`npm run local:seed` with `local:api` running.

## What this proves, and what it does not

It proves the two services agree: manifest, activation, launch delegation, a pinned conditional
transition, the named refusals, retries, revocation and deletion.

It does not prove anything about a deployment — real DNS, real D1 latency, a real cron schedule, or
two Workers under load. Nor is it a substitute for the plugin's own suite (`npm test` in
`plugins/scheduling`), which uses a fake core deliberately, so that a failure names one service
rather than two.

`npm run test:cross-service` in `plugins/scheduling` runs most of this walkthrough unattended: both Workers running locally, installation, delegated launches, a scheduled publish and unpublish, a lost request and a
lost reply, `scheduled_target_stale`, `workflow_conflict`, `transition_unavailable`,
`dependent_content`, cancellation, isolation and uninstall.
[The automated cross-service run](/plugins/testing/#the-automated-cross-service-run)
lists what it asserts and what it leaves to this walkthrough.

<!-- dee-wan-docs page: /reference/vocabulary/ -->

# One word per thing

Source: https://dee-wan-docs.pages.dev/reference/vocabulary/

The words Dee Wan uses in its screens and documentation, and what each one means. Where a word
could mean two things, the entry says which one we mean and what we call the other.

## Installation and sites

### Installation

One deployment of Dee Wan: an admin Worker, the admin UI, a control database, and the accounts
behind them. The command-line installer (`npm run setup`) creates it. The
[web installer preview](/guides/web-installer-preview/) drives the same installer but is not a supported
install path.

- One installation serves many **sites**.
- It has one control database and one set of superadmins.
- Not "an install of a site". A site is created inside an installation, not installed.

### Site

One tenant inside an installation: a name, a slug, a hostname, and its own content, languages,
roles and grants.

- Created in the admin UI, never by the installer.
- A site's **hostname** (its domain) is where its public read API serves requests. The `Host` header of a
  public request must equal it.
- Depending on the installation's topology, a site has its own content database or shares one.

### Cloudflare zone

The Cloudflare object that holds a domain's DNS and edge settings. Cache purge credentials and
rate limiting are configured per Cloudflare zone. Always written "Cloudflare zone" in these
documents, so it is not confused with an **ownership zone**.

## Content

### Model

The definition of one kind of content: its fields, and whether it is public or private. A model's
slug is the path segment in `/v1/<model>`.

### Field

A model property with a name and data type: text, rich text, number, boolean, select, date, media, JSON,
relation or component. A **relation** field links an item to items of another model.

### Content item

One entry of a model, for example one article. It has an id, a slug, and content in one or more
languages. In API responses, `instance_id` means a content item's id.

### Translation group

The language versions of one content item, kept together. Each language has its own workflow
stage and its own published version. A group action moves every language at once; a language
action moves one. (Older text may say "locale group". It means the same thing.)

### Locale policy

A per-site setting for what the public API does when an item has no content in the requested
language:

- **strict**: nothing is served for that language. Fallback languages are ignored.
- **fallback**: the requested language, then that language's own fallback languages in the order
  the site lists them (each expanded through its own fallbacks), then the site's default language,
  then the item's own primary language. Only a published language is served. The response's
  `locale` says which language was served.

### Publishing

Making a content item's current version the one the public read API serves. Publishing acts on
one language, or on every language of the translation group at once. Unpublishing one language
withdraws only that language; the others stay live.

- Changes what `/v1/…` answers on the site's public hostname. It changes no code and deploys
  nothing.
- Not "publishing the site". A site is not published. Its content is.

### Snapshot

The immutable copy of an item's content written when it is published. The public read API serves
snapshots. Each has a version number. A snapshot is never edited: restoring an older version
creates a new version.

### Page

A content item whose model has a `slides` field holding a page document. See the
[page-document contract](/reference/page-contract/).

## Public reading

### Public read API

The read-only HTTP API on a site's hostname, under `/v1/`. See the
[public read API reference](/reference/public-api/).

### Public model, private model

A **public** model is readable by anyone. A **private** model is readable only with a site API
token that names it. A request for a private model without a valid token gets the same 404 as a
model that does not exist.

### Site API token

A bearer token, created under Settings → API, that reads the private models it names. It starts
with `dw_site_` (or `dw_site2_` after a signing-key rotation), is shown once, may expire, and can be
revoked.

### Preview token

A short-lived token (`dw_prev_…`) the CMS creates when an editor opens a preview. It grants access to one item's draft
for 30 minutes. It is not a site API token.

### Cursor

The opaque `page.next_cursor` value used to fetch the next page of a list. Send it back unchanged.

## Standalone backend

### Standalone backend

A typed backend project generated from a site's models and published content: a Prisma schema,
migrations, a Worker and typed routes, written into a repository you own.
Settings → Source & delivery provides delivery and deployment controls; source generation runs locally.

- Its API makes no calls to Dee Wan at runtime.
- Generating it deploys nothing.
- It is generated on your machine (`npm run backend:generate` or `npm run backend:deliver`). The CMS has no hosted
  source compiler.
- It is a release of schema and content, not a live feed: later publishes reach it only when it is
  regenerated and redeployed.

**Graduation** is the internal name for this. You will see it in file names, such as
`graduation.manifest.json`. It means the same thing as generating a
standalone backend.

### Ownership zone

Which files in a standalone backend belong to whom: **generated** (rewritten on every
regeneration), **owned** (`src/owned/`, never overwritten) or **shared** (written once, then
yours). See [Extending your backend](/guides/extending-your-backend/). An ownership zone is not a **Cloudflare zone**.

### Detachment

Stopping regeneration from Dee Wan and keeping the standalone backend as an ordinary repository.
See the [detachment contract](/detachment-contract/).

## Deployment and provisioning

### Deployment

Getting a specific revision running on Cloudflare. The term refers to two different operations:

| Term | Acts on | How |
| --- | --- | --- |
| **installation deployment** | the admin Worker and admin UI | `npm run deploy` |
| **site deployment** | one standalone backend's Worker and database | the Deploy button, which calls the build webhook to the repository's CI |

Generating a standalone backend produces the code. A site deployment runs it.

### Provisioning

Creating the Cloudflare resources something needs (databases, storage, DNS) and recording that they
exist. Provisioning makes the resource. Deployment puts code on it.

## Words we avoid

| Avoid | Because | Say |
| --- | --- | --- |
| "tenant" in the UI | it is an implementation word | site |
| "instance" for an installation | it also means a content item | installation |
| "migrate" for importing content | migration means a schema change | import |
| "export" or "graduate" for the standalone backend | export is content leaving. Graduate names a mechanism | generate standalone backend |
| "locale group" | two names for one thing | translation group |
| "zone" on its own | it has two meanings | Cloudflare zone, or ownership zone |
| "sync" | it has meant several things | name the direction |
| "workflow" for a site with review off | the site has no review stage enabled | publish / unpublish |

<!-- dee-wan-docs page: /reference/page-contract/ -->

# Page-document contract

Source: https://dee-wan-docs.pages.dev/reference/page-contract/

A composed page in Dee Wan is an ordinary content item whose model has a `json` field named `slides`
and a `text` field named `title`. The `slides` field holds a **page document**: structured data that
lists the page's sections in order. It carries text, links and media references. It never carries
HTML, CSS or scripts. Your renderer and your theme decide how each section looks.

This page describes the document a renderer receives from the [public read API](/reference/public-api/), and
how to parse it.

## Where the document comes from

Read the page item from `GET /v1/<model>/<slug>?locale=<locale>`. The document is in
`data.fields.slides`, and the page title is in `data.fields.title`. Each locale has its own document,
so read the locale you are rendering.

```js
const res = await fetch("https://example.com/v1/page/about?locale=en");
if (!res.ok) throw new Error(`${res.status}`);
const { data } = await res.json();
const parsed = parsePublicRenderablePage(data.fields.slides);
```

The item also carries `data.page_contract.required`, the lowest contract version that can read this page. See [Compatibility](#compatibility).

## Where the parser lives

The contract is a small TypeScript module with no dependencies. It imports nothing outside its own
directory, so it runs in Cloudflare Workers, in browsers and in Node.

- A **generated site** already contains it, copied unchanged, at `src/lib/page-contract/`.
- Otherwise it lives in the Dee Wan repository at `backend/src/lib/page-contract/`. There is no
  published npm package. Copy the whole directory from the Dee Wan version you run, and replace it
  when you upgrade. Do not retype the types by hand.

## Which parser to use

| Function                         | Returns             |
| -------------------------------- | ------------------- |
| `parsePublicRenderablePage(raw)` | `{ sections }`      |
| `parsePublicPageDocument(raw)`   | the parsed document |

**Use `parsePublicRenderablePage`.** It turns a stored page into one ordered list of sections.

Each parser takes one argument, the raw value of `fields.slides` (an object, or a JSON string). It
needs no database and makes no network call.

Every parser returns a value and never throws:

```ts
type Parsed<T> =
  | { ok: true; value: T }
  | {
      ok: false;
      error: { code: string; message: string; detail: Record<string, unknown> };
    };
```

When a page is refused, do not render part of it. Treat it as an error for that URL.

## Supported formats

`PAGE_FORMATS` is `[2, 3]`. A document states `format: 2`, or `format: 3` when at least one of its
sections pins a reusable component (see [Reusable components](#reusable-components-format-3)). A
missing format, or any other value, is refused with `unreadable_page`. An empty or missing document
is refused with `unreadable_page` too, so an item with no page content never renders as a blank page.

Format 2 is unchanged: its `component` value must be `null`. A format-3 document that pins no
component is refused with `noncanonical_default`, so each page has exactly one canonical representation.

The format says how a page is stored. It is not the contract version, which says which vocabulary
reads it (see [Compatibility](#compatibility)).

### The stored page

Each locale stores its own document. The structure (which sections, in which order, with which
variant and layout) belongs to this locale, and two locales of one page may differ in every part of
it. The content for this locale is in `props`, keyed by section id.

```json
{
  "format": 2,
  "sections": [
    {
      "id": "intro",
      "type": "hero",
      "variant": "split",
      "layout": "default",
      "component": null
    },
    {
      "id": "story",
      "type": "text_media",
      "variant": "balanced",
      "layout": "media_side=start",
      "component": null
    }
  ],
  "props": {
    "intro": {
      "heading": "Fresh cakes daily",
      "subheading": null,
      "media": null,
      "link": { "label": "See the menu", "href": "/menu" }
    },
    "story": {
      "heading": "Our story",
      "paragraphs": ["We started in 2019."],
      "media": null
    }
  }
}
```

Rules:

- Every section must have props, and every props entry must belong to a section.
- `component` must be present. In a format-2 page it is `null`. In a format-3 page it is `null`, or on
  a `custom` section a component pin.
- Props must not repeat `id`, `type` or a layout key such as `media_side`. Those belong to the
  structure.
- A section may carry `appearance` in the structure. It is optional, and belongs to this locale
  like `variant`. See [Section appearance](#section-appearance).

### What the parser gives you

The parser gives one shape:

```ts
type SectionType =
  | "hero"
  | "rich_text"
  | "text_media"
  | "feature_grid"
  | "cta"
  | "cards"
  | "stats"
  | "faq"
  | "testimonials"
  | "media"
  | "logos"
  | "steps"
  | "pricing"
  | "menu"
  | "contact"
  | "latest_entries"
  | "form"
  | "custom"
  | "search";

type RenderablePage = {
  sections: Array<{
    id: string;
    type: SectionType;
    variant: string;
    layout: string;
    component: {
      component_id: string;
      version_id: string;
      artifact_digest: string;
    } | null;
    appearance?: {
      background?: "muted" | "inverse" | "accent";
      spacing?: "compact" | "roomy";
      motion?: "reveal" | "parallax";
    };
    /** `custom` sections only: the registered section version this section pins. */
    definition?: { key: string; version: number; digest: string };
    props: SectionPropsMap[SectionType];
  }>;
};
```

The real type is a union keyed on `type`, so switching on `section.type` narrows `props`.
`SectionPropsMap` names the props of each type.

## Section types

Optional values come back as `null` when absent. The fields listed under Later fields are the exception: they are left
out. Text is trimmed, except the text of a formatting run. Every item in a
list is a closed object. An unknown key is refused.

| Type             | Props                                                                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hero`           | `heading` (required), `subheading`, `media`, `link`. Later: `eyebrow`, `secondary_link`                                                                                           |
| `rich_text`      | `heading`, `paragraphs` (required, 1–12)                                                                                                                                          |
| `text_media`     | `heading`, `paragraphs` (required, 1–12), `media`                                                                                                                                 |
| `feature_grid`   | `heading`, `features` (required, 1–12 items of `{ title, body }`)                                                                                                                 |
| `cta`            | `heading` (required), `body`, `link` (required). Later: `secondary_link`                                                                                                          |
| `cards`          | `heading`, `items` (required, 1–12 items of `{ title, body, media, link }`, where each item requires `title`)                                                                     |
| `stats`          | `heading`, `items` (required, 1–8 items of `{ value, label, note }`, where each item requires `value` and `label`)                                                                |
| `faq`            | `heading`, `items` (required, 1–20 items of `{ question, answer }`, both required)                                                                                                |
| `testimonials`   | `heading`, `items` (required, 1–12 items of `{ quote, name, role, media }`, where each item requires `quote` and `name`)                                                          |
| `media`          | `heading`, `items` (required, 1–24 image or video items)                                                                                                                          |
| `logos`          | `heading`, `items` (required, 1–24 items of `{ media, name, link }`, where each item requires `media` and `name`)                                                                 |
| `steps`          | `heading`, `items` (required, 1–12 items of `{ title, body }`, where each item requires `title`)                                                                                  |
| `pricing`        | `heading`, `plans` (required, 1–4 items of `{ name, price, period, description, features, link, highlighted }`, where each plan requires `name` and `price`)                      |
| `menu`           | `heading`, `groups` (required, 1–8 items of `{ title, items }`, where `items` holds 1–30 entries of `{ name, description, price }` and each entry requires `name`)                |
| `contact`        | `heading`, `body`, `address`, `hours` (0–14 items of `{ label, value }`), `phone`, `email`, `map_link`, `link`                                                                    |
| `latest_entries` | `heading`, `model` (required), `title_field` (required), `cover_field`, `summary_field`, `date_field`, `limit` (required, whole number 1–12), `empty_text` (up to 200 characters) |
| `form`           | `heading`, `body`, `fields` (required, 1–12 items of `{ name, kind, label, required, help, options }`), `consent`, `submit_label` (required), `success_text` (required)           |
| `custom`         | `heading`, `fields` (the values of the registered section the structure pins)                                                                                                     |
| `search`         | `heading`, `placeholder` (up to 80 characters)                                                                                                                                    |
| `shared`         | none. The structure names the shared section (`shared.entry`). A renderer never receives one.                                                                                     |

A link is `{ label, href }`. A media reference is `{ media_id, url, alt }`, where `alt` may be
`null`. List items hold media too: `media` in `cards`, `testimonials` and `logos` items, and
`media` or `poster` in `media` items.

A media reference may also carry its framing:

- `crop`: `{ x, y, width, height }`, fractions of the stored image from 0 to 1. Width and height are
  above 0, and the rectangle stays inside the image.
- `focal`: `{ x, y }`, fractions from 0 to 1. The point to keep in view when a box cuts the image.

Each key is present only when set; it is never `null`. Any other structure is refused. Framing belongs to
this one use of the image, so the same image can be framed differently in two sections. A list
answer's cover (`EntryMedia`) carries the entry's framing the same way.

### Later fields

| Field                 | Meaning                                         |
| --------------------- | ----------------------------------------------- |
| `hero.eyebrow`        | A short line above the heading.                 |
| `hero.secondary_link` | A second link. Allowed only when `link` is set. |
| `cta.secondary_link`  | A second link.                                  |

These fields are left out when unused, never `null` or empty. After parsing, an unused one is
absent (`undefined`). A public read refuses an explicit `null` or `""` with `noncanonical_default`.

### Items of the list types

- **`media`**: each item is `{ kind: "image", media, caption }` or
  `{ kind: "video", provider, video_id, title, poster, caption }`. An image item needs `media`. A
  video item needs `provider`, `video_id` and `title`. See [Video](#video).
- **`pricing`**: `features` is a list of text, 0–12 entries. Absent reads as `[]`. `highlighted` is
  `true` or absent, and at most one plan in a section is highlighted. `false` is refused with
  `noncanonical_default`.
- **`contact`**: needs at least one of `address`, `phone`, `email`, `map_link` or one `hours` entry.
  `hours` absent reads as `[]`. `phone` holds digits, spaces, `(`, `)`, `.` and `-`, with an optional
  leading `+`, at least 3 characters. `email` is one address, not a `mailto:` link. `map_link.href`
  must start with `https://`.
- **`logos`**: every item needs an image.

### `latest_entries`

The section stores a query mapping, never entries or a cursor. `model` and every `*_field` are slugs
(`^[a-z][a-z0-9_-]{0,63}$`). A renderer resolves it at request time through the site's public list
API, `GET /v1/<model>`, selecting only the mapped fields: newest first by `date_field` when set (entries
without it last), otherwise newest published first, at most `limit` entries. A missing model or field,
a refused query or an unreadable answer is a render error for that section, never an empty list. Only
a valid answer with no entries shows `empty_text` or neutral copy. A summary from a rich-text field is
rendered by `renderRichDocument` (`rich-document.ts`) before it is inserted. Pass the site's allowed
embed origins (`GET /v1/_embeds`) as `embedProviders`; without them an embed from a configured
origin draws as a plain link.

`collection.ts` holds the shared query contract every Dee Wan renderer uses: `entriesQuery`,
`readEntriesPage`, `resolveLatestEntries`, `walkToPage` and the refusal codes in
`COLLECTION_REFUSALS`. See [Blog sites](/guides/blog/#latest-posts) for the editor.

### `form`

A form names fields. It never names an endpoint, a recipient or a secret: where a submission goes is
the site's own setting (Settings → Integrations), and a visitor cannot choose it.

- Each field is `{ name, kind, label, required, help, options }`. Every key must be present.
- `name` is 1–32 lowercase letters, digits or `_`, starting with a letter. Names are unique in a form.
- `kind` is `text`, `email`, `phone`, `textarea`, `select`, `checkbox` or `file`.
- `options` lists 2–20 choices for `select`, and is `[]` for every other kind.
- A `file` field may also set `accept` (up to 10 exact supported MIME types or extensions),
  `max_files` (1–5, default 1) and `max_bytes` (1–5242880, default 5242880). Other kinds refuse these
  keys. Empty `accept` allows the image/document catalog in `FORM_FILE_TYPES`; wildcards are refused.
  All files together are limited to 5 files and 10485760 bytes. File bytes must match a supported format.
- `consent` is the statement a visitor must accept, or `null` for no consent box.

`forms.ts` is the interaction registry and the submission contract, shared by every renderer and the
intake:

| Export                                                           | What it is                                                                                                                                                                                                                            |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INTERACTIONS`, `FORM_SUBMIT_PATH`                               | The registered actions (registry version 3): `form.submit`, posted to `/v1/interactions/form.submit`; `comment.submit`, posted to `/v1/interactions/comment.submit`; and `comment.react`, posted to `/v1/interactions/comment.react`. |
| `readSubmission(raw)`                                            | The closed submission envelope: `{ action, page, locale, section, key, values, consent, website }`. Anything else is `null`.                                                                                                          |
| `checkSubmission(form, values, consent, files?)`                 | The values against the published form, with a `FieldError` per problem.                                                                                                                                                               |
| `FORM_STATES`, `FORM_STATE_COPY`, `FIELD_PROBLEM_COPY`           | Every state a form can display, and its text.                                                                                                                                                                                         |
| `readSubmissionAnswer(raw)`, `stateOfAnswer(answer)`             | The intake's JSON answer, and the state it leads to.                                                                                                                                                                                  |
| `formViews(sections, context)`, `readFormResult(query, section)` | What a renderer hands its form component, including the outcome read back from the page address.                                                                                                                                      |

Forms with file fields send `multipart/form-data`: scalar inputs use `values.<name>`, checkboxes
use `checks.<name>` with `true` when checked, and file parts repeat `files.<name>`. The ordinary
`action`, `page`, `locale`, `section`, `key`, `consent` and `website` controls remain scalar parts.
The JSON envelope stays unchanged for forms without files. Files are not JSON scalar values.
The multipart body is bounded to 10 MiB of files plus 64 KiB overhead, with at most 16 KiB of scalar
parts. An identical retry includes the same file names, types, sizes and bytes and returns the first
receipt; changing a file with the same key is refused.

Retained detail adds optional `attachments: Record<fieldName, Array<{ id, name, type, size }>>`.
`GET /api/forms/submissions/:id/attachments/:attachmentId` returns private attachment bytes with
site-scoped `site:infra` authorization. Expired, erased, missing and wrong-site attachments cannot
be downloaded. No storage keys or public URLs are exposed. See [File attachments](/guides/website-forms/#file-attachments).

`website` is a honeypot: a person never sees it, and a submission with a value in it receives an accepted response but is never stored. `key` (16–64 letters, digits, `_` or `-`) makes a retry the same submission: the same key
with the same values replays the first receipt, and with different values is refused.

The page never carries markup for a form. A renderer draws it with a platform component: in the
managed renderer `src/runtime/Form.astro`, in an exported site `src/components/FormRuntime.astro`.
A template may place that component; it may never write `<form>` or `<script>` itself.

`comments.ts` is the comment contract for every model that takes comments: `readCommentSubmission`
and `checkComment` for a comment, `readReactionSubmission` and `readReactionAnswer` for a Helpful
reaction, `readCommentsPage` and `walkComments` for the approved comments `GET /v1/_comments` serves
in one of `COMMENT_ORDERS` (`oldest`, `newest`, `best`), and `commentsView` for what an entry page
draws: threads with reaction counts, order links, pages, the form, and the outcome read back from the
address. Both renderers draw it with a platform component, `src/runtime/Comments.astro` in the
managed renderer (Blog posts and routed entry pages) and `src/components/Comments.astro` in an
exported site (Blog posts and entry pages of models that take comments). It carries no email, moderation state or reaction actor. See
[Visitor comments](/reference/models-and-fields/#visitor-comments).

### Registered sections (`custom`)

A developer can register a typed section through a managed template. Its definition and its Astro
component are built in the pinned offline sandbox, and accepting the template under `site:deploy`
promotes them to an immutable version. A page pins that exact version in its section structure:

```json
{
  "id": "sl_team",
  "type": "custom",
  "variant": "grid",
  "layout": "default",
  "component": null,
  "definition": {
    "key": "team-grid",
    "version": 2,
    "digest": "<64 hex characters>"
  }
}
```

- `definition` is required on a `custom` section and refused on every other type. In a format-2
  page `component` stays `null`: that format never reinterprets it.
- `digest` is SHA-256 over the canonical JSON of `{ definition, source }`: the definition the developer
  declared and the exact component bytes. A renderer never resolves a key to "latest".
- The locale props are `{ heading, fields }`. `fields` holds the definition's values: text, a flag,
  a link, a media reference, `null`, or a list of items holding those.
- Without the definition, a parser checks `fields` against that bounded grammar only: markup, unsafe
  links and malformed media are refused all the same. With it (`ParseContext.definitions`), every
  value is checked against the pinned definition, and an unknown pin is `unknown_section_definition`.
- `sections.ts` reads a definition (`parseSectionDefinitionSource`, `parseSectionDefinition`),
  classifies a change between two versions (`definitionChange`: unchanged, compatible or breaking,
  with reasons) and moves content onto a newer version (`migrateCustomFields`), keeping only values the
  new version still accepts.

A renderer that has no component for the pinned identifier refuses the page. An exported site carries
every pinned version's component under `src/registered/<digest>/`, and a build whose pages pin a
version it cannot carry is refused.

### Reusable components (format 3)

A reusable component is a registered section that was made from a section on a page: generated,
built in the pinned offline sandbox, reviewed and promoted under `site:deploy` (see
[Build and edit pages](/guides/page-builder/#reusable-components)). A page that uses one is stored in
format 3, and the `custom` section pins the exact version beside its definition:

```json
{
  "id": "sl_team",
  "type": "custom",
  "variant": "grid",
  "layout": "default",
  "component": {
    "component_id": "rcp_…",
    "version_id": "rcv_…",
    "artifact_digest": "<64 hex characters>"
  },
  "definition": {
    "key": "team-grid",
    "version": 2,
    "digest": "<64 hex characters>"
  }
}
```

- `component` is accepted only in a format-3 page and only on a `custom` section that also holds its
  `definition`. A bare name or slug is refused (`invalid_slide`): a name does not say which code was
  meant.
- `component_id` names the site's component, `version_id` the immutable version, and
  `artifact_digest` is the SHA-256 of the compiled build that version was promoted with. The `definition` identifier is the one that version resolves to, so a renderer draws by `digest` exactly as
  for any registered section.
- A reader with access to the site's components (`ParseContext.components`) checks that the version is
  promoted and that the pin and the definition belong together; otherwise it refuses with
  `unknown_component_version`. A request-side parser without that access refuses every pin, so a pin is never created from input the site cannot check.
- Nothing resolves a pin to a newer version, when rendering, saving or restoring. A newer version is
  an explicit change of the pin.
- A page without any pin stays in format 2, and `storedPage` writes the format its content needs.

### `search`

The site's own search box. The page holds words only: `heading` and `placeholder`, both optional. It
names no index, endpoint or query. Results come from the site's search, in the page's language.

- The editor offers it only while site search is on (`GET /api/pages/renderer-capability` →
  `site_search.active`), under every renderer.
- A managed release draws it with the platform's own search component, whatever the template
  (`PLATFORM_DRAWN_TYPES`). The form sends `q` to the same page, which reads `GET /v1/_search` and
  draws the results in place. A template maps no component for it.
- An exported site draws it with its `SiteSearch` component. A page that holds one renders on each
  request and reads `GET /v1/_search` on the site's own host. A site built with search off refuses to
  build a page that holds one.
- Both renderers add suggestions while the visitor types: the form reads its site's own
  `/search?suggest=` and still works as a plain GET form without JavaScript.
- While search is off, the editor's quality list blocks Save on a page that holds one.

### Shared sections (`shared`)

Contract version 5. A shared section is content the site keeps once and shows on many pages: an
announcement, a promotion, footer content, a call to action. It is an ordinary item of the reserved
`shared_section` model (a `title` and `slides`, like a page), edited, versioned and published like a
page.

A page stores a reference, never a copy:

```json
{
  "id": "notice",
  "type": "shared",
  "variant": "default",
  "layout": "default",
  "component": null,
  "shared": { "entry": "ci_…" }
}
```

Its props are `{}`. `shared.entry` is the shared section's owning item id. Each locale holds its own
references. `variant` and `layout` are `default`. It takes no `appearance`.

- **Delivery expands it.** Every public read (`/v1/:model`, `/v1/:model/:slug`, a preview), a managed
  working render, a template preview and an exported site replace the reference with the shared
  section's published sections in the page's language (the site's locale fallback chain applies).
  Section ids become `<reference id>.<n>`. A draft never shows anywhere. A shared section with nothing
  published in that language shows nothing. A renderer therefore never receives `type: "shared"`:
  `parsePublicRenderablePage` refuses one with `shared_section_unexpanded`.
- **Cache.** A response that embeds a shared section carries `instance:<shared section id>`, the tag
  its publication purges.
- **What a shared section holds.** Up to `SHARED_SECTION_MAX` (6) sections. No other shared section
  (`shared_section_nested`), and no `form`, `search` or `custom` section
  (`shared_section_type_unsupported`). Exceeding this limit returns `shared_section_too_many`. Saving rejects each of these cases.
- **Publishing a page** refuses `shared_section_not_live` while a shared section it uses is not
  published, and `shared_section_page_limit` when its expanded sections exceed `LIMITS.slides`.
  Publishing a shared section refuses `shared_section_page_limit` when a live page using it would exceed the limit. An import replays a site where both were live, so it skips the first check.
- **Withdrawing one.** Unpublishing a shared section lists every page using it in the dependent
  acknowledgement (`field_keys: ["slides"]`). Deleting needs it unpublished first. After that, each
  page shows nothing in its place.
- **Not a page.** It has no address, no route (`shared_section_not_routable` in a route map), no
  sitemap entry and no search entry.
- **Saved patterns** stay copies: a pattern refuses a shared section (`pattern_shared_section`).
- Every version records the shared sections it uses in `meta.shared_sections`, readable by SQL even
  when the snapshot is compressed.

### Variants and layouts

| Type             | Variants                                       | Default variant | Layouts                              |
| ---------------- | ---------------------------------------------- | --------------- | ------------------------------------ |
| `hero`           | `centred`, `split`, `full_bleed`               | `centred`       | `default`                            |
| `rich_text`      | `single_column`, `wide`, `narrow`, `statement` | `single_column` | `default`                            |
| `text_media`     | `balanced`, `media_dominant`, `text_dominant`  | `balanced`      | `media_side=start`, `media_side=end` |
| `feature_grid`   | `two_column`, `three_column`, `list`           | `three_column`  | `default`                            |
| `cta`            | `banner`, `card`, `inline`                     | `banner`        | `default`                            |
| `cards`          | `grid`, `bento`, `scroller`                    | `grid`          | `default`                            |
| `stats`          | `row`, `grid`, `spotlight`                     | `row`           | `default`                            |
| `faq`            | `accordion`, `list`, `split`                   | `accordion`     | `default`                            |
| `testimonials`   | `spotlight`, `grid`, `scroller`                | `spotlight`     | `default`                            |
| `media`          | `full_width`, `grid`, `masonry`, `scroller`    | `full_width`    | `default`                            |
| `logos`          | `grid`, `row`, `marquee`                       | `grid`          | `default`                            |
| `steps`          | `numbered`, `timeline`, `columns`              | `numbered`      | `default`                            |
| `pricing`        | `cards`, `compact`, `stacked`                  | `cards`         | `default`                            |
| `menu`           | `list`, `two_column`, `cards`                  | `list`          | `default`                            |
| `contact`        | `split`, `card`, `compact`                     | `split`         | `default`                            |
| `latest_entries` | `grid`, `list`                                 | `grid`          | `default`                            |
| `form`           | `stacked`, `split`, `card`                     | `stacked`       | `default`                            |
| `custom`         | the pinned definition's own                    | its first       | `default`                            |
| `search`         | `default`                                      | `default`       | `default`                            |

The constants are `SECTION_VISUAL_VARIANTS`, `DEFAULT_VISUAL_VARIANT` and `SECTION_LAYOUTS`.

### Section appearance

A section may carry `appearance` beside its variant:

```json
{
  "id": "story",
  "type": "rich_text",
  "variant": "wide",
  "layout": "default",
  "component": null,
  "appearance": { "background": "muted", "motion": "reveal" }
}
```

| Key          | Values                       | When the key is absent |
| ------------ | ---------------------------- | ---------------------- |
| `background` | `muted`, `inverse`, `accent` | the default background |
| `spacing`    | `compact`, `roomy`           | normal spacing         |
| `motion`     | `reveal`, `parallax`         | no motion              |

- Each value is a name. Your theme decides what it looks like.
- A key at its default is left out. A section with no key set has no `appearance` at all. An empty
  object is refused with `noncanonical_default`.
- Any other key or value is refused with `unknown_section_appearance`.
- Turn off all motion when the visitor asks for reduced motion
  (`prefers-reduced-motion: reduce`).

The constant is `SECTION_APPEARANCE`.

## Limits

| What                                       | Maximum         |
| ------------------------------------------ | --------------- |
| Slides or sections per page                | 24              |
| Paragraphs per section                     | 12              |
| Formatting runs per paragraph              | 32              |
| Features per grid                          | 12              |
| Cards, testimonials or steps per section   | 12              |
| Stats per section                          | 8               |
| FAQ items per section                      | 20              |
| Media items or logos per section           | 24              |
| Pricing plans per section                  | 4               |
| Features per pricing plan                  | 12              |
| Menu groups per section                    | 8               |
| Items per menu group                       | 30              |
| Opening-hours entries                      | 14              |
| Heading                                    | 200 characters  |
| Paragraph, subheading, CTA or contact body | 2000 characters |
| Eyebrow                                    | 80 characters   |
| Link label                                 | 80 characters   |
| Link or media URL                          | 2000 characters |
| Feature title                              | 120 characters  |
| Feature body                               | 600 characters  |
| Card or step title, menu group title       | 120 characters  |
| Card or step body                          | 600 characters  |
| Stat value                                 | 24 characters   |
| Stat label                                 | 80 characters   |
| Stat note                                  | 200 characters  |
| FAQ question                               | 200 characters  |
| FAQ answer                                 | 2000 characters |
| Testimonial quote                          | 600 characters  |
| Person name                                | 80 characters   |
| Person role                                | 120 characters  |
| Caption or video title                     | 200 characters  |
| Logo name                                  | 80 characters   |
| Plan name                                  | 80 characters   |
| Price or period                            | 24 characters   |
| Plan description                           | 300 characters  |
| Plan feature                               | 120 characters  |
| Menu item name                             | 120 characters  |
| Menu item description                      | 300 characters  |
| Address                                    | 500 characters  |
| Opening-hours label or value               | 80 characters   |
| Phone                                      | 40 characters   |
| Email                                      | 254 characters  |
| Slide or section id                        | 64 characters   |
| Media id                                   | 64 characters   |
| Media alt text                             | 1000 characters |
| Variant or layout name                     | 64 characters   |
| Form fields                                | 12              |
| Form field label                           | 80 characters   |
| Form field help                            | 200 characters  |
| Choices in a form field                    | 20              |
| Form choice                                | 80 characters   |
| Consent statement                          | 300 characters  |
| Form button text                           | 40 characters   |
| Message after sending                      | 300 characters  |
| Values in a registered section             | 24              |
| Items in a registered list                 | 24              |
| Registered text value                      | 2000 characters |
| Search box placeholder                     | 80 characters   |

The constants are `LIMITS` and `SECTION_LIMITS`.

## Content rules

**Text is plain text.** Headings, paragraphs, labels, item text and formatting runs may not contain
`<`, `>`, `&lt;`, `&gt;`, numeric entities, `javascript:` or `data:text/html`. Render them as text
and let your templating escape them as usual.

**Links** (`link.href`, and `href` in a formatting run) must be one of:

- a path on the same site, starting with exactly one `/`.
- an `https://` URL with a named host (containing a dot).
- a plain `mailto:` address with no query.

**Media URLs** are checked with a real URL parser:

| URL                                                          | Result                          |
| ------------------------------------------------------------ | ------------------------------- |
| `https://cdn.example.com/a.jpg` (query and fragment allowed) | accepted                        |
| `/local-media/abc` (exactly one leading slash)               | accepted                        |
| `http://localhost…`, `http://127.0.0.1…`, `http://[::1]…`    | accepted, for local development |
| `http://` on any other host                                  | refused                         |
| `https://` with no host                                      | refused                         |
| `https://user:pass@host/a.jpg`                               | refused                         |
| `//evil.example/a.jpg`                                       | refused                         |
| any backslash or whitespace                                  | refused                         |
| `javascript:`, `data:` or any other scheme                   | refused                         |

Media alt text is length-checked but not checked for markup. Put it in an escaped attribute.

### Inline formatting

In `rich_text` and `text_media`, an entry of `paragraphs` is a string or a formatted paragraph:

```ts
type RichParagraph = {
  inline: Array<{ text: string; bold?: true; italic?: true; href?: string }>;
  list?: "bullet" | "number";
};
```

Each meaning has one spelling:

- Use the object only when it carries bold, italic, a link or a list. A plain paragraph stays a
  string. An object with no formatting is refused with `noncanonical_default`.
- `bold` and `italic` are `true` or absent. `false` is refused with `noncanonical_default`.
- Two neighbouring runs with the same marks and link are one run. Writing them as separate runs is refused
  with `noncanonical_default`.
- `inline` holds 1–32 runs. Run text is not trimmed, so the spaces between runs survive. A run
  cannot be empty, and the paragraph cannot be only spaces.
- Consecutive entries with the same `list` form one list.

`paragraphBlocks(paragraphs)` turns a paragraph list into blocks to draw: `{ kind: 'paragraph', runs }`
or `{ kind: 'list', ordered, items }`. A plain string becomes one run with no marks. Escape
`run.text`. Never build raw HTML from it. `paragraphText(paragraph)` returns the words of one
paragraph without formatting.

### Video

A video item names a provider and a video id. It never carries embed code or a player URL.

| `provider` | `video_id`                             |
| ---------- | -------------------------------------- |
| `youtube`  | exactly 11 letters, digits, `_` or `-` |
| `vimeo`    | 6 to 12 digits                         |

Any other provider, or an id in the wrong form, is refused with `unsafe_link`. These are the
built-in rules of the embed registry (`embed.ts`), the same ones a rich-text embed uses, and the
section editor reads a pasted watch, share, Shorts or player link with the same parser.

By default, draw the poster (or a neutral frame) and a link to the provider's page.
`videoPageHref(item)` returns that link. Make no third-party request before the visitor clicks, and
load no client script. A theme that plays video in the page creates the player frame only after the
click, from `youtube-nocookie.com` or `player.vimeo.com`, with `dnt=1`.

## Refusal codes

`DOCUMENT_REFUSALS` lists every code a parser can return for a page document:

| Code                         | Meaning                                                                                                                                                                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unreadable_page`            | Not a page document, empty, or a slide without a usable id.                                                                                                                                                                                        |
| `unknown_slide_type`         | A section type outside the list above.                                                                                                                                                                                                             |
| `invalid_slide`              | Wrong shape, a missing required value, an unsupported property, or an invalid phone number or email address.                                                                                                                                       |
| `markup_not_allowed`         | Text that contains markup.                                                                                                                                                                                                                         |
| `unsafe_link`                | A link that breaks the link rules, or a video provider or id that is not allowed.                                                                                                                                                                  |
| `unknown_media`              | Media not in the site's library. The public parsers never return it.                                                                                                                                                                               |
| `duplicate_slide_target`     | Two slides or sections share an id.                                                                                                                                                                                                                |
| `unknown_section_variant`    | A variant the type does not offer.                                                                                                                                                                                                                 |
| `unknown_section_layout`     | A layout the type does not support.                                                                                                                                                                                                                |
| `missing_section_props`      | A section with no props for this locale.                                                                                                                                                                                                           |
| `orphan_section_props`       | Props for a section that does not exist.                                                                                                                                                                                                           |
| `too_many`                   | A limit was exceeded. `detail.max` names it.                                                                                                                                                                                                       |
| `noncanonical_default`       | A value in a spelling the contract does not use. This includes an empty later field, `false` for a mark or for `highlighted`, or a formatted paragraph with no formatting. It also includes two runs that should be one, or an empty `appearance`. |
| `unknown_section_appearance` | An appearance key or value the contract does not offer.                                                                                                                                                                                            |
| `unknown_section_definition` | A registered section pins a version this reader does not hold.                                                                                                                                                                                     |
| `unknown_component_version`  | A format-3 section pins a reusable component version this reader does not hold, or one that does not match its definition.                                                                                                                         |
| `shared_section_unexpanded`  | A renderer was handed a shared section. Only `parsePublicRenderablePage` returns it.                                                                                                                                                               |

## Helpers

The contract also exports:

| Function or constant                                  | Returns                                                                                                                                    |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `paragraphBlocks(paragraphs)`                         | Paragraphs as blocks to draw. See [Inline formatting](#inline-formatting).                                                                 |
| `paragraphText(paragraph)`                            | The words of one paragraph, without formatting.                                                                                            |
| `videoPageHref(item)`                                 | The provider page of a video item.                                                                                                         |
| `slideStrings(slide)`                                 | Every authored string a slide shows, in reading order. For a section, pass `slideFromSection(section)`.                                    |
| `pageMediaReferences(document)`                       | Every media reference in a document, list items included.                                                                                  |
| `mapPageMedia(document, visit)`                       | The same document with each media reference passed through `visit`. It never moves a section or changes its variant, layout or appearance. |
| `slideMediaPaths(type)`                               | Where a type may hold media, as key paths with `*` for a list index.                                                                       |
| `SLIDE_ITEM_MEDIA_KEYS`                               | The media keys inside list items, per type.                                                                                                |
| `currentPageContractVersion()`                        | The contract version this copy reads (`PAGE_CONTRACT_VERSION`).                                                                            |
| `isPageContractVersion(value)`                        | Whether a value is that version. There is one version; any other value is `false`.                                                         |
| `pageContractCapabilities(version)`                   | One entry of `PAGE_CONTRACT_VERSIONS`.                                                                                                     |
| `PAGE_CONTRACT_VERSIONS`                              | The current contract version and what it reads.                                                                                            |
| `sectionTypeName(type)`                               | The type's name as the admin shows it, such as `Text with image`.                                                                          |
| `componentSectionTypes(version)`                      | The types a template draws with its own per-type components: every type but `custom` and `PLATFORM_DRAWN_TYPES`.                           |
| `PLATFORM_DRAWN_TYPES`                                | The types a managed release draws with platform components: `search`.                                                                      |
| `DRAWN_SLIDE_TYPES`, `DrawnSlideType`                 | Every type a renderer may receive: all but `shared`.                                                                                       |
| `expandSharedSections(document, lookup)`              | The document with each shared section replaced by `lookup(entry)`'s sections. Always parses.                                               |
| `sharedEntries(document)`, `storedSharedEntries(raw)` | The shared sections a parsed or stored document uses.                                                                                      |
| `isMediaValue(value)`                                 | Whether one registered-section value is a media reference.                                                                                 |

The functions that take a `document` take a parsed one. `parsePublicPageDocument(raw)` returns it
without a database.

## Testing your renderer

`fixtures.ts`, in the same directory, holds the documents Dee Wan tests its own parser with:
`ACCEPTED_PAGES`, `REFUSED_PAGES`, `STORED_ACCEPTED_PAGES` and `STORED_REFUSED_PAGES`. They cover every
built-in section type, every later field, formatted paragraphs, every appearance value, and values
exactly at each limit.
`V4_REFUSED_FORMS` holds refused forms. `V4_CUSTOM_PAGES`, `V4_CUSTOM_REFUSED` and
`V4_CUSTOM_REFUSED_WITH_DEFINITION` cover registered sections against `SECTION_DEFINITION_FIXTURE`.
`V5_SHARED_PAGE` and `V5_SHARED_REFUSED` cover shared sections; `V5_RENDERER_REFUSED` is what a
renderer must refuse. Run your renderer over the accepted sets to
check that it handles every section type. They are not exported from `index.ts`, so they stay out of
your production bundle. Import `./fixtures` in tests only.

## Compatibility

### Formats and contract versions

There are two numbers.

- The **format** (`format` in the document, `2` or `3`) says how a page is stored. Format `3` carries
  reusable-component pins. Your copy of the contract refuses formats outside `PAGE_FORMATS` rather
  than guessing.
- The **contract version** (`PAGE_CONTRACT_VERSION`, now `5`) names the vocabulary: section types,
  variants, layouts, fields, structure keys and limits. An additive change (a new type, optional
  field, variant, layout value or structure key) raises it. Stored pages keep their format and stay
  valid byte for byte.

`PAGE_CONTRACT_VERSIONS` holds only the current version and its exact set. It reads that set, never
more. Dee Wan computes the version's digest from its own contract sources. A later version will be a
superset of this one.

### What the public API tells you

Every `/v1` response carries `contracts.page.served`, the contract version that produced it. Every
page item carries `page_contract.required`, the contract version that reads its page. The stored
document does not change: `fields.slides.format` is still the storage format.

```json
{
  "contracts": { "page": { "served": 5 } },
  "data": {
    "id": "ci_…",
    "slug": "about",
    "model": "page",
    "locale": "en",
    "version": 4,
    "published_at": "2026-09-01T08:00:00.000Z",
    "fields": {
      "title": "About",
      "slides": {
        "format": 2,
        "sections": [
          {
            "id": "intro",
            "type": "hero",
            "variant": "centred",
            "layout": "default",
            "component": null
          }
        ],
        "props": {
          "intro": {
            "heading": "About us",
            "subheading": null,
            "media": null,
            "link": null
          }
        }
      }
    },
    "relations": {},
    "media": {},
    "page_contract": { "required": 5 }
  }
}
```

- Items of models without a `slides` field never carry `page_contract`.
- With `fields=`, `page_contract` is kept only when `slides` is selected.
- An item whose page cannot be read carries no `page_contract`. The parser refuses that page anyway.

A renderer built for version N renders a page only when `required` is N or lower. Otherwise it treats
the whole page as an error for that URL and shows its generic error page. It never renders part of
the page.

### Declaring your renderer's version

Dee Wan verifies a preview renderer through `/.well-known/dee-wan-renderer.json`.

- `version` is `2`. Any other protocol is refused (`preview_contract_incompatible`).
- `page_contract_version` is the contract version the renderer was built for.
- `renderer_contract_digest` must equal that version's digest, or Dee Wan refuses the renderer with
  `renderer_contract_unknown`.
- `page_formats` must equal `PAGE_FORMATS`.

```json
{
  "version": 2,
  "site_id": "site_…",
  "routes": { "page": "/preview/page/{slug}" },
  "token_param": "preview",
  "page_contract_version": 5,
  "renderer_contract_digest": "<64 hex characters>",
  "page_formats": [2, 3]
}
```

A generated site serves this file from `src/lib/renderer-contract.ts`. A stored verification without
`page_contract_version` is not sufficient: verify the renderer again.

Dee Wan refuses to publish a page the active renderer cannot draw (`renderer_capability_exceeded`):
a registered section the active managed template does not include. A site with no verified renderer
can still publish.

### Editor bridge and field links

`editor_bridge` in the renderer contract is optional. Dee Wan reads `{ "version": 1 }` or
`{ "version": 3 }` and drops any other value. Version 1 selects sections. Version 3 also links each
rendered value to the field that holds it. A generated site declares version 3. Older generated sites
keep version 1, and their preview works as before; the editor says field links are not available.

A field-link path names one value of one entry (`field-links.ts`). Segments are joined by `/`. Each
segment is a field key, a list index, or `~` plus a percent-encoded instance id: a page section, a
component instance (`variant_id`) or a mixed block (`_id`).

| Path                                               | Value                               |
| -------------------------------------------------- | ----------------------------------- |
| `slides/~hero-1/heading`                           | heading of section `hero-1`         |
| `slides/~hero-1/features/2/title`                  | third feature title of that section |
| `slides/~hero-1/link/label`, `slides/~hero-1/link` | button text, button link            |
| `slides/~hero-1/media`                             | section image                       |
| `faqs/~v1/question`                                | question of component instance `v1` |
| `body/3`                                           | block 3 of a rich field             |
| `seo/image`                                        | the SEO image, where it is drawn    |

`readFieldLinkPath` refuses every other spelling. `pageFieldLinks(sections)` lists, per section, the
text, link and media values a page may draw. Alternative text, provider names and ids are not listed.
`entryFieldLinks(id, values, rich)` lists an entry page, such as a Blog post: plain values by field
key, and each stored rich value block by block (`body/3`), with a block's words and library media.

A generated site finds a section by its `data-dw-section` wrapper. The managed renderer finds it by
its positional section marker comment, so the list's `id` is that marker's id. An entry page marks
its whole article with `data-dw-section`, and selecting a point outside all listed values identifies no field.
Both built-in renderers route the `post` model in their renderer contract on a Blog site.

Only a preview render carries field links. The generated preview route writes the list as JSON
(`fieldLinksJson`, safe inside a `<script>` element) and runs the bridge. The bridge finds the
elements that show each value and marks them with `data-dw-field` (the path) and
`data-dw-occurrence` (0 for the first element showing that value). It makes them focusable. If two fields contain the same text, they map to its elements in order, and only when the counts agree. Published
pages never carry the list, the marks or the bridge.

For version 3 messages, the frame posts only to the exact editor origin from `editor_origin`. It carries
the `editor_nonce` from its address. Both sides check the window, the origin, the nonce and the exact
keys, and ignore any other message.

| From   | Message                 | Keys besides `type`, `version: 3`, `nonce`                |
| ------ | ----------------------- | --------------------------------------------------------- |
| frame  | `dee-wan:preview:ready` | `current_version_id`, `locale`, `model`, `entry`, `links` |
| frame  | `dee-wan:preview:pick`  | `path`, `occurrence`                                      |
| frame  | `dee-wan:preview:edit`  | `path`, `occurrence`, `anchor`                            |
| frame  | `dee-wan:preview:close` | none                                                      |
| editor | `dee-wan:preview:show`  | `path`                                                    |
| editor | `dee-wan:preview:focus` | `path`                                                    |
| editor | `dee-wan:preview:clear` | none                                                      |

A custom renderer may speak version 3 with its own markup: it marks the elements itself and sends
the same messages. To use `FIELD_LINK_BRIDGE`, provide the identity marker below, the field-link
JSON and the section roots described above. Replace the example values with the rendered entry's
actual identity. `data-dw-editor-version` is its current saved version id, not bridge version `3`.
`data-dw-editor-model` is the model slug, `data-dw-editor-entry` is the entry id, and
`data-dw-editor-locale` is the rendered locale. The host matches readiness against the version and locale.

```html
<div
  data-dw-editor-version="cver_example"
  data-dw-editor-locale="en"
  data-dw-editor-model="post"
  data-dw-editor-entry="instance_example"
  data-dw-editor-inplace
  hidden
></div>
```

The presence of `data-dw-editor-inplace` opts into inline editing; remove the attribute to opt out
(setting it to `"false"` still opts in). Without it, the runtime sends `pick`, which opens the normal
field controls. Without the identity marker, the runtime does not start; the normal editor remains
available.

An opted-in selection sends `edit` instead of `pick`. A custom bridge can send it directly:
`target` is the selected rendered element, `editorNonce` comes from `editor_nonce`, and `editorOrigin`
is the exact `editor_origin` from the frame's address.

```js
const box = target.getBoundingClientRect();
window.parent.postMessage(
  {
    type: "dee-wan:preview:edit",
    version: 3,
    nonce: editorNonce,
    path: "body/3",
    occurrence: 0,
    anchor: { x: box.x, y: box.y, width: box.width, height: box.height },
  },
  editorOrigin,
);
```

`anchor` is the selected element's rectangle in the iframe viewport's CSS pixels at selection time.
Use `getBoundingClientRect()` directly: do not add page scroll offsets or the iframe's position in
the parent page. The object has exactly `x`, `y`, `width`, `height`; every value is finite with
absolute value at most `100000`, and width and height are nonnegative. Negative x/y are allowed.
`occurrence` is an integer from `0` to `9999`. Adding `anchor` to `pick` is invalid: send `edit`.

`path` must pass `readFieldLinkPath`: at most 512 characters and 12 segments, beginning with a
field key. Keys match `[A-Za-z][A-Za-z0-9_]{0,63}`; indices are `0`–`9999` without leading zeroes.
An instance segment is `~` plus the canonical `encodeURIComponent` spelling of a nonempty id of
at most 128 decoded UTF-16 code units. Messages and anchors must be plain objects with the exact keys
listed; unknown keys or invalid bounds are ignored. The ready message's `links` is an integer
from `0` to `999999`.

The host supports ordinary entries' top-level text/rich fields and a single rich block index such
as `body/3`. Nested component paths and composed pages use normal field selection. It opens its
existing controls only for a visible field the person may edit. An unsupported inline path falls
back to normal field selection; a path absent
from the form is reported rather than edited. The frame never mutates CMS data. Edits update the
host's unsaved form under its normal permissions and validation. **Done** closes inline editing
and returns focus through `dee-wan:preview:focus`; it does not save. **Save** persists the entry.
The runtime handles `focus` by revealing and focusing the first rendered element for `path`.

<!-- dee-wan-docs page: /reference/capability-matrix/ -->

# Capability matrix

Source: https://dee-wan-docs.pages.dev/reference/capability-matrix/

Source contract for the unreleased integration candidate, reviewed on 2026-10-18. Each row names the implementation and related tests; listing a test is not a claim that final release acceptance has passed. The current integration additions and remaining acceptance gates are listed below.

Terms:

- **CMS** — the admin API and the public read API (`/v1`).
- **Generated** — a standalone backend produced by `npm run backend:generate` or `npm run backend:deliver`.
- **Presentation only** — the admin screen applies it. No server enforces it.

## Model shapes

| Capability                                  | CMS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Generated                                                                                                                                                                                                                                                                                                                                                                 | Where a problem is caught                                                                                                  | Evidence                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single-entry model (one record only)        | A model is a `collection` or a `single` (`content_model.kind`). A single model holds at most one logical entry, counting Trash. A second create is refused (409 `single_entry_exists`) and names the entry that exists; of two concurrent creates exactly one wins. Adding a language adds to the same entry. The entry keeps its place while in Trash and frees it only on a permanent delete. A collection turns single only while it holds at most one entry, counting Trash (`single_entry_conflict`); the change moves the model contract, so a create planned against the old kind aborts. A site copy carries the kind; its dry run is blocked when the destination already holds the entry, in Trash too (`single_entry_taken`), or when the copy carries more than one entry for it. A Strapi single type imports as a single model.                                                                                                                                                                                                                                         | The model is marked in the schema, a second create is refused by name, and the database holds the table to one row, from the first migration and when the kind changes.                                                                                                                                                                                                   | Every create, import and kind change.                                                                                      | `backend/src/lib/lifecycle/single-entry.ts`. `backend/test/single-entry-model.test.ts`. `backend/test/single-entry-import.test.ts`. `backend/test/graduate-private-and-single.test.ts`. `backend/test/import-strapi-components.test.ts`                                                                                                                                          |
| Content folders (admin navigation grouping) | A model has an optional folder label, `content_model.nav_folder`: 1 to 40 characters after trimming, grouped without regard to case, flat, and implicit while a model uses it. It is set by its own write, `PUT /api/models/:id/folder`, under `model:apply`, not by Apply, so it never changes the model revision or blocks a save. The Content list shows unfoldered models first, then folders by name; each folder is a button with `aria-expanded`, the browser remembers which folders are collapsed, and a folder holding the open model opens. Not part of generation input, generated backends or public reads. A site copy carries it onto models it creates. The management API sets it with `setModelFolder` and lists it as `folder`.                                                                                                                                                                                                                                                                                                                                    | Not part of generated backends.                                                                                                                                                                                                                                                                                                                                           | Model folder updates and site copy.                                                                                        | `backend/src/lib/model-folder.ts`. `backend/src/api/model-folder.ts`. `backend/test/model-folder-route.test.ts`. `backend/test/model-folder-site-copy.test.ts`. `backend/test/management-models.test.ts`. `frontend/src/lib/content/model-folders.ts`. `frontend/src/routes/content/components/ModelFolderGroups.svelte`. `frontend/cypress/e2e/journey-model-nav-folders.cy.ts` |
| Unique field declared by an author          | Individual text/number uniqueness and up to eight named combinations of two to four text/number fields. Combination members use the same shared/translated storage; scope is the model or each language. Empty members do not claim a combination. Save, import, restore, publication and definition changes use atomic guards. See [Unique combinations](/reference/models-and-fields/#unique-combinations).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Single and compound unique indexes; locale-scoped indexes include `lang`.                                                                                                                                                                                                                                                                                                 | Generation readiness and the build refuse published duplicates and shared one-to-one targets before anything is generated. | `backend/src/lib/lifecycle/unique-values.ts`. `backend/src/lib/graduate/unique-values.ts`. `backend/test/field-uniqueness.test.ts`. `backend/test/graduate-uniqueness.test.ts`                                                                                                                                                                                                   |
| Private field (hidden from public reads)    | Per field (`custom_field.private`) and per field inside a component. A private field is never served by a public list or item, nor its relations or media, the feed, site search or the generated public client. A public filter, sort, selection or expansion naming one is refused exactly as an unknown field. Cache keys carry the set of private fields, so a field turned private is never served from an older cached response. Turning a field private re-indexes the model's search rows. A component field whose library cannot be read is removed whole. A saved query on a public route may not name a private column, also through a component column that holds one (422 `private_field_on_public_route` when binding or editing, `saved_query_private_field` at generation). Per-model `private` visibility still needs an in-scope read token.                                                                                                                                                                                                                        | Private columns are left out of every reader and write answer and kept for editors. A private list relation's join table is served to editors only. A generated site shows no private value, relation or media, and removes a component's private fields from inside its values. Per-model, per-operation access policy (`anonymous`, `session`, `service`) is unchanged. | Public read and generation.                                                                                                | `backend/src/lib/private-fields.ts`. `backend/test/private-fields.test.ts`. `backend/test/public-feed.test.ts`. `backend/test/graduate-private-and-single.test.ts`. `backend/test/saved-query-graduation.test.ts`. `backend/test/public-private-routes.test.ts`. `backend/test/backend-policy.test.ts`                                                                           |
| Conditional field visibility                | Typed Boolean, select, text, number and date conditions; AND/OR groups with at most four terms and three levels. The native editor, save and model validation share the same rules. Hidden values stay stored; visibility never grants or removes access. See [Show only when](/reference/models-and-fields/#show-only-when).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | The same conditions gate required-field validation.                                                                                                                                                                                                                                                                                                                       | Model save.                                                                                                                | `frontend/src/lib/eav/field-condition.ts`. `backend/test/field-conditions.test.ts`. `backend/test/mixed-components-site-copy.test.ts`                                                                                                                                                                                                                                            |
| Mixed component field                       | Ordinary and mixed components support retirement and retained definition versions. Existing instances stay editable under their pinned definition; retired types cannot be added or duplicated. Upgrade is explicit. Mixed fields keep stable instance ids, enabled state and their allowed component list. See [Component definition versions](/reference/models-and-fields/#component-definition-versions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Backend generation reads each block by its own component and declares media paths per component. A block of a component the field does not allow, a key its component does not declare, and a lone block where a list is expected are refused. Hidden blocks stay in the rows and are dropped from every reader answer and from a generated site.                         | Save, model save and generation.                                                                                           | `backend/src/lib/component-contract.ts`. `backend/src/lib/hidden-blocks.ts`. `backend/test/mixed-components.test.ts`. `backend/test/mixed-components-site-copy.test.ts`. `backend/test/hidden-blocks.test.ts`                                                                                                                                                                    |
| Field-level authorization                   | A role's `limits` name, per model or for every model (`*`), the fields it may read and write; a role without field limits can access every field. Unreadable fields are left out of instance reads, value lists and their totals, searches, version payloads, page reads and the page library, and a preview uses its creator's read scope. A save keeps every stored value the role could not see. A restore that would rewrite a field it may not write is refused (`field_denied`). A whole-site export is refused to a role that narrows reading (`export_limited_role`). A person holding several roles gets the union per operation. A role manager may grant only permissions they hold, and a management credential keeps its person's limits. Renaming a field key rewrites every role's field lists for the model.                                                                                                                                                                                                                                                          | Unsupported. You can implement it only through your own hooks in `src/owned/backend.ts`.                                                                                                                                                                                                                                                                                  | Save, restore, read and role save.                                                                                         | `backend/src/lib/permission-limits.ts`. `backend/test/permission-limits.test.ts`. `backend/test/permission-limits-routes.test.ts`. `backend/test/permission-limits-lifecycle.test.ts`. `backend/test/permission-limits-pages.test.ts`. `backend/test/management-roles.test.ts`                                                                                                   |
| Locale-level authorization                  | `limits` also name languages per action: read, create, update, delete, restore, review, publish and unpublish. A save, bulk batch, workflow move, publish or unpublish that touches a language outside the role is refused in its entirety (`locale_denied`) and writes nothing. A publish override, single or bulk, counts only the languages whose live version it would change, and its refusal names them. Restoring an old version of one language needs `restore` for that language only and changes that language's fields, own relation lists and address, never shared values or other languages; restoring the whole entry needs every language. A changed shared field needs update on the primary language; an unchanged one does not. When a role lacks delete permission for another language of the entry, it can move an allowed language to Trash on its own, but cannot move the whole entry. A preview never falls back through a language the maker may not read. An `:own` key widens a language only for the person's own rows. A superadmin is never narrowed. | Unsupported.                                                                                                                                                                                                                                                                                                                                                              | Save, workflow, Trash, read and preview.                                                                                   | `backend/src/lib/permission-limits.ts`. `backend/test/permission-limits-lifecycle.test.ts`. `backend/test/permission-limits-routes.test.ts`. `backend/test/permission-limits-preview.test.ts`. `backend/test/permission-limits.test.ts`                                                                                                                                          |

## Relations

| Surface                        | One-to-one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Many-to-one                         | One-to-many                                                                                                                                                                         | Many-to-many                                     |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Model editor                   | Offered, described as "Each linked item belongs to only one `<owner>`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Offered                             | Offered, described as "Each linked item belongs to only one `<owner>`". Component fields do not offer it (`relation_type_not_authorable`).                                          | Offered                                          |
| Related from (target editor)   | The target lists the entries whose field points at it, by source model and field, with "Live only", "Draft only" and "View only" marks. An editor who may read the target and update the source adds or removes the link; the change is a new draft version of the source, saved under the source's own permissions, version check, field rules, cardinality, one-owner rule and hierarchy rule, and never published. Replacing a source's other target needs a confirmation that names both (409 `related_from_replace_unconfirmed`). Nothing is stored on the target side. | Same                                | Same, without the replacement step                                                                                                                                                  | Same, without the replacement step               |
| CMS write                      | One target                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | One target                          | Many targets                                                                                                                                                                        | Many targets                                     |
| CMS write forms                | A plain list or `{ set }` replaces the field's ordered list. `{ connect, disconnect, move }` removes, then connects in the given order (a plain id goes to the end, `{ id, position }` places it), then moves related items; positions are `before`, `after`, `start`, `end`. On a to-one field a position or `move` is refused (`relation_position_not_ordered`)                                                                                                                                                                                                            | Same                                | Same                                                                                                                                                                                | Same                                             |
| CMS write checks               | On a changed list: the target exists in the site, is of the declared target model (one of the accepted models, when the field accepts several), is readable by the writer (`:own` read included). It appears once, and a to-one field holds one. A list equal to the stored one is not revalidated. Restore performs the same checks. A target another item points at in this field, live or draft, is refused (409 `relation_target_taken`)                                                                                                                                 | Same, without the one-owner refusal | Same as one-to-one                                                                                                                                                                  | Same, without the one-owner refusal              |
| CMS public read                | `{ instance_id, model, slug, display }` list in the snapshot. A target of a translated model is served with the address and label of the item's served language, then the fallback chain; under a strict policy a target with no such language is left out. The `tag` filter matches that same address                                                                                                                                                                                                                                                                       | Same                                | Same                                                                                                                                                                                | Same                                             |
| Generated schema               | `<key>_id` column, `@unique`, foreign key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `<key>_id` column, foreign key      | Junction table owned by the declaring model, unique target column, foreign keys                                                                                                     | Junction table, foreign keys                     |
| Generated read                 | The id column                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | The id column                       | Read-only junction route                                                                                                                                                            | Read-only junction route                         |
| Generated write                | Sets the id column after checking that the target row exists. Otherwise, it returns 422 `relation_target_missing` and writes nothing. Single-model output has no target table and refuses every non-null id.                                                                                                                                                                                                                                                                                                                                                                 | Same                                | `PUT /api/<owner>/relations/<field>` with `set`, `connect`, `disconnect`, validated against the CMS rules in one batch. A target another owner holds is 409 `relation_target_taken` | `PUT /api/<owner>/relations/<field>`, same rules |
| Generated delete of the target | An optional column becomes null. A required one refuses the delete (409 `relation_target_referenced`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Same                                | The link is removed                                                                                                                                                                 | The link is removed                              |

- A missing target, a target of another model and a target the writer may not read are refused the same way (422 `relation_target_not_found`). The refusal names the refused ids, so the answer does not reveal which ids exist.
- Rows written before these checks stay readable. The next save that changes that field must satisfy them.
- Translatable fields are written through the generated translation routes. A locale row names its row and a language the site's content was generated with, once (`unknown_locale`, `translation_row_missing`, `locale_exists`); an update changes only translated values.
- Deletion: relation rows are removed when either entry is deleted for good. Moving an entry to Trash keeps them, and restore brings them back. A link to an entry in Trash cannot be newly chosen. The other entry stays. There is no per-field setting. In the whole-site generated backend every relation id is a foreign key with the behaviour above. A relation id inside a component JSON value is not a key.
- Different links in each language (`localizedMembership`, translated models only, not inside components): each language keeps its own ordered list in rows, versions and the editor, and every relation rule (to-one, one owner, hierarchy, item limits) is checked per language. A public read serves each language its own list; a fallback language serves its own list, never another language's. Restore brings back each language list, also from a version written before the option changed. Turning the option on copies the shared list to every language; turning it off keeps the primary language list and is blocked when two items would then share a one-owner target or the primary-language parents would loop. Deleting a language for good deletes its list. A site copy carries each language list. A generated backend stores such a field, to-one included, as junction rows carrying the locale, and its relation route reads and writes one language list at a time. Evidence: `backend/src/lib/lifecycle/relation-sets.ts`. `backend/test/relation-localized-membership.test.ts`. `backend/test/relation-localized-membership-site-copy.test.ts`. `backend/test/graduate-localized-membership.test.ts`.

Evidence: `backend/src/lib/lifecycle/service.ts` (`planRelations`, `checkRelationLists`, `resolveRelationWrites`). `backend/src/api/models.ts`. `backend/src/lib/relation-type.ts`. `backend/src/lib/graduate/templates.ts` (`relationTargetsExist`). `backend/test/relation-writes.test.ts`. `backend/test/lifecycle-atomicity.test.ts`. `backend/test/models-apply.test.ts`. `backend/test/graduate-relation-writes-worker.test.ts`. `backend/test/graduate-relation-load.test.ts`. `backend/test/graduate-relation-schema.test.ts`. `backend/test/relation-cardinality.test.ts`. `backend/test/graduate-junction-http.test.ts`. `frontend/src/routes/model-builder/[id]/tabs/config-types/RelationConfig.svelte.test.ts`.

## Presentation only versus enforced

| Control                                                                                                                                                             | Enforced by the server?                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Field "hidden" in the editor                                                                                                                                        | No. The value is still stored and served.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Show condition (`ui.showWhen`)                                                                                                                                      | Partly. A hidden value is still stored and served. The server requires a field only while its condition shows it and refuses a condition it cannot honour.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Field "read-only"                                                                                                                                                   | Removed from the model editor. Stored values of the old setting are ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Field validation: required, length, pattern, number range and step, item counts, dates, select options, on model fields and on every field inside a component value | Supplied values are checked on Save by the editor's own rule module. Default draft mode defers missing/empty required values; optional strict mode requires them on Save. Publication checks the exact snapshot with full required-value validation (422 `field_validation_failed`, naming each field by full path: `seo.meta_title`, `faqs[2].question`). A component value is validated against the definition its field names. A list where one instance is expected is refused. An instance that is not an object is refused. A key the definition does not declare (beside `variant_id`, `enabled`, `id`, `_id`) is refused. Media inside a component is taken in every shape the generated standalone backend reads. The shapes are an id, `{ media_id, url }`, a list of either, and a one-item list on a single field. It is stored as an id, or a list of ids. An optional single component holding only empty values counts as left out. Hidden fields, derived fields nobody may edit and a page's composer-owned fields are skipped, as in the editor. A version restore is validated against the current model and refused with the same 422, writing nothing. Import validation checks the values that each phase writes. Where the job plans relation and media links, counts are checked from the planned links. The dry run reports each problem as a blocking row per path and language before anything is written. A spreadsheet check validates each edited row the same way before the first save. |
| Relation deletion behavior                                                                                                                                          | Removed from the model editor. Deletion is fixed (see Relations).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Media crop rules on a field (`aspectRatio`, `minWidth`, `minHeight`)                                                                                                | Yes, for a crop an editor sends. A rule changed later does not block an unrelated save. An import is not revalidated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Model `settings.permissions`, drafts, versioning, default sort                                                                                                      | Legacy settings removed. `settings.validation_mode` is supported: `draft` by default, or `strict` for complete fields on Save.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Role grants per model, `:own` ownership, workflow transition permissions, publish and unpublish permissions                                                         | Yes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Model visibility (`public` / `private`) on the CMS public API                                                                                                       | Yes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Rich-text size (256 KiB)                                                                                                                                            | Yes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

Evidence: `backend/src/lib/lifecycle/field-rules.ts`. `frontend/src/lib/eav/content-validator.ts`. `backend/src/lib/import/rule-findings.ts`. `backend/test/field-rules.test.ts`. `backend/test/field-rules-save.test.ts`. `backend/test/component-rules-route.test.ts`. `backend/test/import-field-rules.test.ts`. `backend/test/import-strapi-field-rules.test.ts`. `backend/test/spreadsheet-import.test.ts`. `frontend/src/routes/content/[id]/component-rules.svelte.test.ts`. `backend/test/media-framing.test.ts`. `backend/test/transition-requires-write.test.ts`. `backend/test/ownership-enforcement.test.ts`. `backend/test/rich-field-contract.test.ts`.

## Editorial operations

| Capability                               | CMS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Locale publication                       | Each language has its own workflow stage and live version. Publish, unpublish or review one language from the Workflow panel. A group action that publishes or unpublishes moves every language; a group move between two unpublished stages (such as **Approve · All languages** or **Send back · All languages**) leaves a language that is already published live, in the Published state, and **Unpublish {language}** takes it off. Public reads, previews, addresses, redirects and generated sites follow each language's own published version; a generated site emits each language from its own version and address. When the primary language is not live, generation emits the item from its live languages under the same id, taking shared values from the live version of the first live language in site order (default first). A site copy carries each language's pointer and the import, its receipts and undo restore it. Scheduling one language needs the plugin capability `workflow:locale`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `backend/test/locale-publication.test.ts`, `backend/test/locale-publication-route.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Search, sharing, redirects and sitemap   | Per-language search and sharing overrides live in each version, with a page type for structured data. Site Chrome holds the defaults, who runs the site, search-engine verification codes, the sitemap and robots policy, and up to 256 address and 32 pattern redirects answering 301, 302, 307, 308, 410 or 451. One redirect service refuses loops through any mix of rules, ambiguous patterns, reserved and live addresses; a changed pattern needs a review of the live pages it covers; publishing at an address a redirect holds is refused by name. Both renderers run one matcher, one sitemap writer (an index of 5,000-address chunks with images) and one JSON-LD serializer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `backend/test/redirect-service.test.ts`, `backend/test/redirect-runtime-parity.test.ts`, `backend/test/redirect-lifecycle.test.ts`, `backend/test/sitemap-runtime-parity.test.ts`, `backend/test/sitemap-public-route.test.ts`, `backend/test/structured-data.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Live site search                         | Off until turned on in Settings → Source & delivery → Site search (`site:infra`). `GET /v1/_search` answers published pages, posts on a Blog site and up to 16 chosen public models, in the requested language under the site's fallback chain. Drafts, private models, entries in Trash and languages set to hide from search engines never appear. Every word must match by the type's matching: whole words (default), English word forms (Porter2 stemming of stored text and query alike, on every site; decided per result by the language it is served in: `en`, `en-*` and `en_*` match word forms, any other language whole words, in one query) or parts of words; title matches come first, then the newest. Every form is stored with each version, so a matching change rebuilds nothing, and cursors and cache keys carry it and the language fallback chain. Under Matching and ranking a type can instead search up to 16 chosen fields, each weighted 1–10 (title 10, others 1 to start); a result ranks by the highest weight among its chosen fields that hold every word, then the newest. Weights are read at search time, so nothing is rebuilt. Each version's words are stored in the batch that saves it; whether a row is live and its address are decided when searching, so publishing, unpublishing, Trash and address moves take effect at once. Search turned off answers 404 `search_off`. Managed and generated sites draw `/search`, `/<language>/search` and the Site search section from it at request time; nothing is rebuilt to update search. `GET /v1/_search/suggest` answers up to 10 title-first matches from the same rows, matching, cache tags and purge, the last word matching the start of a word; every search box lists them while the visitor types (keyboard and screen-reader combobox, plain GET form without JavaScript) and records nothing about the query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `backend/src/lib/search/public-search.ts`. `backend/src/lib/search/projection.ts`. `backend/src/lib/search/suggest-script.ts`. `backend/src/lib/search/english-stem.ts`. `backend/test/public-search.test.ts`. `backend/test/search-projection.test.ts`. `backend/test/english-stem.test.ts`. `frontend/src/lib/sites/search-suggest-script.test.ts`                                                                                                                                                                                                                                                                                                                                                                                          |
| Trash                                    | Delete moves the whole entry, every language, to Trash. Live content is refused until it is unpublished. Trash entries leave ordinary lists, search, relation pickers, dashboards, exports and previews. Each content and page list has a Trash beside it, limited to models the person can read. Restore needs delete on the model, returns the entry as a draft with versions, translations, links and media, and first lists addresses now taken and links that no longer work. Delete permanently is a separate confirmed action. Entries are deleted for good 30 days after they were trashed. One language that does not own the entry’s history can go to Trash alone ("Move this language to Trash"): it leaves the current version, the language switcher and public reads, the rest stays editable and publishable, adding that language again is refused (`language_in_trash`), and restore puts it back as a draft. Posts have their own Trash beside the list. Content in Trash that links to an item does not block unpublishing that item; it is listed as In Trash. Import refuses an entry whose address belongs to an entry in Trash, a re-import into an entry now in Trash, and a link to one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `backend/src/lib/lifecycle/trash.ts`. `backend/src/api/content_lifecycle.ts`. `backend/test/content-trash.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Bulk actions                             | Move to a workflow stage, publish or unpublish by override, or move explicit ids to Trash, restore them or delete them for good. A request accepts at most 25 ids. Each entry runs its single route's checks, including its own revision and reviewed dependents. Results are in input order. A retry with the same key replays committed entries instead of re-running them, even after a request stopped part-way. Keys are bound to the person. Generic `/many` and `/bulk` routes answer 410. `relate` adds or removes up to 10 linked entries in one many-to-many field of each entry (Posts → Categories and tags), as that entry's own save with its version check; it never publishes, an entry that already has the change is `unchanged`, and a one-to-many field is refused (`batch_relation_exclusive`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `backend/src/api/content_lifecycle.ts` (`/batch`). `backend/test/content-batch.test.ts`. `backend/test/content-batch-relate.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Editing ownership                        | The first editor of an entry and language holds its editing lease. Others who open it see who holds it, read along in a read-only form that follows the holder's shared draft, and can **Take over** in one action. The lease moves at once: the previous holder is told who took over, their next save or move is refused `423 lock_lost`, and their unsaved typing is kept as their own recovery draft, offered back when they hold the lease again. Joining or taking over the lease of a language needs the person's change grant in that language (create, when it has no row yet; otherwise `locale_denied`), and an own-only role must own that language's row (`not_owner`). Saves, adding a language, workflow moves, assignment, version restore, the publish override, Trash and permanent deletion of that entry and language from any other session are refused `423 locked`; a list batch refuses only the held entry. The same person's content list and management credentials are not blocked by their own open editor; another person's are. Plugins, imports, scheduled publication and spreadsheet apply are never blocked; the version check still protects the editor. The lease is checked when a write is planned and again inside the write's own batch, so a takeover concurrent with a save causes that save to be refused. A lease lasts two minutes after its last renewal, stops renewing in a hidden tab, ends on tab close, and an expired lease never blocks. While following someone else's lease the editor asks every 10 seconds (never from a hidden tab) and shows their newer shared draft. People on other languages of the same entry are named on one line. Nothing is logged, counted or kept in history. At most 20 open editors per person and site. A shared-draft write or discard that loses the lease before it commits is refused `423 lock_lost` and changes nothing; a refused autosave is kept as the person's own recovery draft, and a refused discard says **Not discarded — taken over. Your work is kept.** and keeps the on-screen work as the recovery draft. The page composer works the same way: read-only while someone else holds the page and language, one Take over, and its change-set kept as the person's own draft when the lease is lost.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `backend/src/lib/presence.ts`. `backend/src/lib/lifecycle/editing-lease.ts`. `backend/src/api/presence.ts`. `backend/test/editing-ownership.test.ts`. `backend/test/editor-presence.test.ts`. `frontend/src/lib/presence/presence.svelte.test.ts`. `frontend/src/lib/drafts/draft-discard-refused.svelte.test.ts`. `frontend/cypress/e2e/journey-editor-presence.cy.ts`                                                                                                                                                                                                                                                                                                                                                                       |
| Shared draft                             | Unsaved work on an entry autosaves, after a short pause, as one shared draft per entry and language: written by the lease holder, read by everyone who may read the entry and, for an own-only role, owns that language's row (`not_owner` otherwise). Every draft answer, conflicts included, is projected to the fields and languages the person may read; read access is decided on the read grants alone, apart from the write grants, so a person who may write a draft but not read that row or language is never shown the draft (`current: null` on a conflict, `draft: null` from a management take over); a holder who cannot read every field writes only the ones they can, and the others are kept. A page draft has an empty title for a role that cannot read the title and is refused (`field_denied`) to a role that cannot read the sections. The draft shows on any device after a reload. Each write names the revision it replaces; a stale one requires the person to choose how to proceed. The editor says **Saving draft…**, **Draft saved**, **Offline — kept here** (kept on this device and sent on reconnection or Retry), **Changed on another device** or **Draft not saved**. A draft is never a version. Save promotes it: the version is written and the draft cleared in one batch. A workflow move or an override publish saves unsaved work first; an override unpublish does not. A shared draft is kept 30 days after its last change. The page composer keeps its change-set as the page's shared draft the same way. A new item keeps the person's own draft.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `backend/src/lib/working-drafts.ts`. `backend/src/api/presence.ts`. `backend/test/editing-ownership.test.ts`. `frontend/src/lib/drafts/draft-sync.svelte.test.ts`. `frontend/src/lib/drafts/DraftStatus.svelte.test.ts`. `frontend/cypress/e2e/journey-cross-device-drafts.cy.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Reviewer assignment                      | One workflow assignee and optional due date per whole item, checked against who can act from the current stage. Independent locale owners and multi-person editorial tasks have their own assignment, state and revision; they do not replace the workflow assignee. A stale revision returns 409. The same write records an assignment event. A move clears it unless it names the next assignee. The UI identifies inactive assignees and assignees without access. Use `assigned=me` on the review queue. An assignment notifies the new assignee. Required tasks must be completed for the affected snapshot before publication. Unrelated-language edits preserve locale approval; changed shared/reviewed values need review again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `backend/src/lib/lifecycle/assignment.ts`. `backend/test/workflow-assignment.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Review notifications                     | Field discussions retain version, language and canonical field path, with replies, user/team mentions and thread-wide resolve/reopen. Current field, language and recipient access are rechecked. In-admin notices for assignment, review requests and returns for changes, written in the same batch as the workflow move; the unique key (kind, entry, language, workflow revision, recipient) means a retried or racing move writes one notice per recipient, and a refused move writes none. Editor, management API and plugin moves use one notice path (`reviewNoticesFor`). Every recipient, an explicit assignee included, must be an active member who may read the model (own-row scope counted against every affected row) and the affected languages; update or review authority alone is not enough. A single-language move notifies only people who may also review every moved language; a returned author or an assignee needs read access to one of them. Reads recheck entry and language access, link to that language's entry and show its current stage. Imports are quiet by default; an import job stores `review_notify` (`quiet` or `notify`, changed with `data:import` until the job ends), and a notifying import writes in-admin notices only. Carried history never notifies. At most 50 recipients per notice; mail is optional.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `backend/src/lib/review/context.ts`. `backend/src/lib/review/notifications.ts`. `backend/src/lib/review/notification-read.ts`. `backend/test/review-feedback-notifications.test.ts`. `backend/test/review-locale-notifications.test.ts`. `backend/test/import-notify-policy.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Content-list field filters and sorting   | One model, latest saved values including drafts: `field_filters` supports up to four conditions in AND/OR groups, three levels deep. Scalar comparisons, relation membership/empty checks and configured same-site relation display fields use current target access. `field_sort` accepts one scalar field or the display field of a single-valued, single-target relation; missing/unreadable values sort last with stable ID ties. Points support exact radius, bounding-box and nearest queries. Rich text, media, component and JSON fields remain unsupported. Rows, counts, matching IDs, saved views and bulk freezing share the same SQL plan without a capped candidate scan. Cursors bind the full query; oversized parameters are refused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `backend/src/lib/content-fields/`. `backend/src/lib/scoped-crud.ts`. `backend/test/content-field-query.test.ts`. `backend/test/content-views.test.ts`. `backend/test/content-bulk.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Crop and focal point                     | Per media reference, fractions of the stored image, on top-level media fields. Framing is per occurrence: each occurrence keeps its own framing when the same image appears twice in one field. Bytes never change. Kept by unrelated saves, captured in versions, carried by restore and bundle moves, kept on file replacement (with a shape warning). Served by the CMS public API and carried into generation input. A default focal point per image starts new uses only, and a site copy carries it. Component media is framed per use inside its value (`{ media_id, crop?, focal? }`, the bare id when unframed); site copy and standalone backend delivery keep it. A generated site delivers resized, cropped copies through Cloudflare Image Transformations on hosts its owner declares, and falls back to the original URL with CSS framing elsewhere. A page section's image is framed per slot (page contract version 4). The managed renderer draws images through the same rule from built-in template version 4, with transform hosts set at installation (`MANAGED_IMAGE_TRANSFORM_ORIGINS`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `backend/src/lib/lifecycle/media-framing.ts`. `backend/src/lib/graduate/site-media-presentation.ts`. `backend/test/media-framing.test.ts`. `backend/test/media-default-focal.test.ts`. `backend/test/component-media-framing.test.ts`. `backend/test/media-default-focal-bundle.test.ts`. `backend/test/image-delivery.test.ts`. `backend/test/media-mime.test.ts`. `backend/test/import-bundle-spine.test.ts`                                                                                                                                                                                                                                                                                                                                |
| Media tags                               | Flat, site-owned tags for the media library. Tags are independent of folders. A name is unique in its site regardless of letter case, up to 64 characters. The shared media dialog filters by every chosen tag, or by Untagged, together with the search. It tags the selected images, renames tags and deletes them. Deleting a tag never deletes an image. A tag in use is deleted only after a confirmation that names how many images carry it. Reading requires media read permission. Changes need `media:update`. A site copy carries each image's tag names. A tag on no image is not carried. Strapi import creates no tags. No public API serves tags.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `backend/src/api/media-tags.ts`. `backend/src/lib/media/tags.ts`. `backend/test/media-tags-route.test.ts`. `backend/test/media-tags-bundle.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Media folders                            | Logical, site-owned folders for the media library. A folder never moves or renames a stored file or its address. Each file is in one folder or in **Unfiled**. Folders nest at most 5 levels, a site holds at most 500, and a name is 1–80 characters, unique under its parent whatever its case. The shared media dialog, in the library and in every picker, shows **All media**, **Unfiled** and the folder tree with counts. A folder view shows that folder's own files, not its subfolders'. New uploads and saved generated images go into the folder shown. Selected files (at most 200) move together. Rename and move send the revision read; a stale one is refused with `media_folder_changed`. A move into the folder itself or below it is refused (`media_folder_cycle`), and so is a move beyond 5 levels (`media_folder_too_deep`). Deleting a folder deletes its subtree after one confirmation that names its folder and file counts; no file is deleted, each becomes Unfiled. The delete is refused if either count changed. Reading requires media read permission. Changes need `media:update`; the management API uses the same service under `media:write`. A site copy and a history transfer carry the whole tree, empty folders included, in `media-folders.json` (bundle 1.10), and each file names its folder. Import rebuilds the tree with new ids, parents first, one receipted item per folder, reusing a folder already at the same path whatever its case. Undo removes a folder the import made only while it is unchanged and holds no file or folder; otherwise it is kept, as tags are. A Strapi 4 or 5 import recreates the folder tree from the archive's folder entities and their explicit parent and file-to-folder links, only for folders the selected files sit in, and never from file paths; a folder that cannot be created under these limits blocks the dry run and is never renamed (see Strapi media folders). No public API, generated site or generated standalone backend carries folders.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `backend/src/lib/media/folders.ts`. `backend/src/api/media-folders.ts`. `backend/test/media-folders.test.ts`. `backend/test/media-folders-transfer.test.ts`. `backend/src/lib/import/media-folder-apply.ts`. `backend/src/lib/import/undo-media-folder.ts`. `backend/test/management-media-folders.test.ts`. `frontend/src/lib/components/custom-ui/image-select/MediaFolders.svelte.test.ts`                                                                                                                                                                                                                                                                                                                                                 |
| Media files                              | Site-configured image, document, audio, video and download formats. SVG is an image after its supported static structure is validated; scripts, external resources and unsupported markup are refused. Raster images and whole-file operations keep their documented bounds. Large accepted files travel through chunked native transfers. See [Media](/guides/media/#file-kinds-and-formats) and [size limits](/guides/media/#size-limits).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `backend/src/lib/page-contract/media-kinds.ts`. `backend/src/lib/media/media-type.ts`. `backend/src/lib/media/duplicate.ts`. `backend/src/lib/media/media-settings.ts`. `backend/test/media-type.test.ts`. `backend/test/media-files.test.ts`. `backend/test/media-asset-renderers.test.ts`. `backend/test/management-api.test.ts`. `backend/test/plugin-operations.test.ts`. `backend/test/media-formats.test.ts`. `backend/test/media-stream-upload.test.ts`                                                                                                                                                                                                                                                                                |
| Image editing                            | Media center → Edit → **Crop and rotate**: quarter turns and a free crop, by pointer (44px corner handles), touch or keyboard (arrows move, Alt+arrows resize, R rotates, Enter saves). **Save as copy** uploads the edited bytes through the ordinary upload as a new file with its own digest, size, dimensions and uses; it records `edited_from`, takes the original's tags, alt text and folder, and is selected at once. The original is kept. **Replace original** (behind ⋯) first lists where the image is used, then replaces it through the existing replacement after one confirmation; a stored format conversion is a replacement too and shows the same review. The management API and a streamed upload take `edited_from`; export, import and site copy carry it, relinked to the copied original or dropped when the original is not in the bundle.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `frontend/src/lib/components/custom-ui/image-select/ImageEditor.svelte`. `frontend/src/lib/components/custom-ui/image-select/image-edit.ts`. `backend/src/lib/media/upload.ts`. `frontend/src/lib/components/custom-ui/image-select/ImageEditor.svelte.test.ts`. `backend/test/media-files.test.ts`. `backend/test/management-media.test.ts`. `frontend/cypress/e2e/journey-media-edit.cy.ts`                                                                                                                                                                                                                                                                                                                                                 |
| Private media and media permissions      | Private files remain in private storage. Protected rich text can contain private images and attachments; delivery checks current reader access. Named protected image variants use the same authorization. Public contexts refuse private assets. Native transfers carry private bytes and variants privately. See [Private files](/guides/media/#private-files).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `backend/src/lib/media/private-storage.ts`. `backend/src/lib/media/visibility.ts`. `backend/src/lib/media/capability.ts`. `backend/src/lib/media/delivery.ts`. `backend/src/api/private-media.ts`. `backend/test/media-private.test.ts`. `backend/test/media-private-content.test.ts`. `backend/test/media-private-stream.test.ts`. `backend/test/media-private-transfer.test.ts`. `backend/test/media-private-protected.test.ts`. `backend/test/graduate-media-private.test.ts`. `backend/test/graduate-private-files-worker.test.ts`. `backend/test/graduate-private-files-node.test.ts`. `backend/test/media-private-placement-race.test.ts`. `backend/test/media-permissions.test.ts`. `frontend/cypress/e2e/journey-media-private.cy.ts` |
| External media sources                   | A remote plugin granted `media:source` declares up to four `media_sources`. The shared media dialog then shows **Sources** beside the library (arrow keys switch, 44px controls on phones): pick a source, search, page with **Show more**, and **Add** a file. Previews load from the plugin's origin with no referrer. Each source declares `modes` (`copy`, `reference` or both) and the add request names one, never inferred (`media_source_mode_unsupported`, 422, for a mode the source does not declare). A source with both shows **Add** and **Link without copying**; a single-mode source shows one action. Adding a copy copies the file into the site: core reads the item again through the invocation exchange, fetches it from the plugin's one origin with no credential and no redirect, and runs the ordinary upload rules (the site's kinds, formats, size limits and duplicate check). The new file keeps the source's credit and origin (`media.attribution`: source name, author, license, links, plugin, source and item ids), shown in its details; published content never loads from the plugin for a copy. Linking (`reference`) fetches nothing: the row has storage provider `external`, its address is the item's `delivery_url` on one of the source's declared `delivery_origins`, its object ledger entry has no checksum, and the same plugin, source and item follows `on_duplicate`. A linked file's metadata, tags, folder and framing edit like any file; its bytes cannot be replaced or edited (`media_external_bytes_unavailable`); deleting it removes only the library row and the in-use rule still holds. Published pages, the public read, the managed renderer and the preview frame (whose image policy lists the delivery origin) use the delivery URL; a generated standalone backend and generated sites do not copy it, the media manifest records it as `external` with the URL as it was; site copy and history carry the identity, URL and metadata without bytes and import recreates the link. Existing content keeps rendering the stored URL when the plugin is uninstalled or disabled; the details say the source is not available and new links from it are refused. Loading, empty, offline, refused, unavailable and permission states are shown in the dialog. Browsing needs `media:upload` and is not audited. The management API, CLI and MCP offer `listMediaSources`, `browseMediaSource` and `importMediaSourceItem` (`media:write`). Export, import and site copy carry `attribution` on each media line. A save records the file's read-only `credit` (`{ author, source, license, url }`, never the plugin, source or item ids) in the version; the public read (response schema r8) and generated sites serve it, and the built-in managed and generated renderers show a small credit line under the image. | `backend/src/lib/plugins/media-sources.ts`. `backend/src/lib/media/sources.ts`. `backend/src/lib/media/external.ts`. `backend/src/api/media-sources.ts`. `frontend/src/lib/components/custom-ui/image-select/MediaSources.svelte`. `plugins/media-source-reference`. `backend/test/media-sources.test.ts`. `backend/test/media-sources-reference.test.ts`. `backend/test/media-sources-reference-roundtrip.test.ts`. `backend/test/media-sources-bundle.test.ts`. `backend/test/media-credit.test.ts`. `frontend/src/lib/components/custom-ui/image-select/MediaSources.svelte.test.ts`. `frontend/cypress/e2e/journey-media-sources.cy.ts`                                                                                                   |
| Comments                                 | Any public model can take comments (`content_model.settings.comments`); Blog posts are one such model. A thread belongs to one language of an entry and keeps one reply level. Visitor comments arrive through the intake Worker as JSON or a plain form post, keyed, consent required, email optional and kept privately; they wait for moderation. While a model takes no comments, its entry pages show a closed form, nothing is taken, existing comments are hidden from public reads and still listed for moderation. Moderation (`/api/comments`) lists, approves, refuses, marks spam and deletes, needs the publishing permission (delete on the comment's model to delete), reports a comment another moderator moved as a conflict and never reaches another site. Reactions: one kind, `helpful`, one per actor and comment, only on an approved comment; a visitor is identified by a keyed digest that no other comment shares, a signed-in person by account and needs read on the model. Public order is oldest (default), newest or best (helpful reactions, then age, then id), each paged with its own cursor. The management API, CLI and MCP list, read, moderate, publish imported comments, delete and change which models take comments. A site copy carries comments with their state and email and imports a published comment as pending; undo removes them. The managed renderer and a generated site draw the comments component on every entry page of a model that takes comments, read at request time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `backend/src/lib/comments/service.ts`. `backend/src/lib/comments/reactions.ts`. `backend/src/api/comments.ts`. `backend/test/comments-models.test.ts`. `backend/test/comments-route.test.ts`. `backend/test/comments-contract.test.ts`. `backend/test/comments-site-copy.test.ts`. `backend/test/blog-comments.test.ts`. `backend/test/graduate-site-comments.test.ts`                                                                                                                                                                                                                                                                                                                                                                        |
| Coordinated releases (Scheduling plugin) | Up to 25 non-overlapping entry/language commands in one same-site CMS batch, within the existing atomic statement budget. Validation uses the intended final publication state. A refused or rolled-back batch changes no publication pointer. Different languages of one entry may share a release. Scheduling sends one command with stable pinned versions, workflow revisions and retry identity; an uncertain answer is retried unchanged. Webhook delivery, cache purges and automatic redirects remain separate outcomes. Deployment and final acceptance are pending.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `backend/src/lib/lifecycle/service.ts`; `backend/test/coordinated-release-events.test.ts`; `plugins/scheduling/src/release-runner.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Plugin policies that change content      | A save or restore policy may answer `transform`, naming fields only. The transformed candidate passes the same validation as an editor's save (field rules, canonical rich text, links, media, search settings) and is stored with a record of which policy changed what; an answer equal to the candidate is a plain allow. Two policies changing one field differently are refused (`plugin_policy_transform_conflict`); a field the model lacks, a link or media part on the wrong field, another entry, or a transform answered to a kind that writes no candidate is invalid (`plugin_policy_transform_invalid`). A refusal from another policy still blocks the write. A repeated key replays the stored transformed result without asking again. A restore transform may change values and search settings only. Delete policies are asked before Trash and permanent deletion, restore policies when leaving Trash, transition policies on every move, a plugin's publish command and an import that publishes, unpublish policies when content goes offline. The management API save answers with the transformation and lists the new policy kinds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `backend/test/plugin-policy-transforms.test.ts`. `backend/test/plugin-policy-fixture.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Field-linked preview                     | The editor opens the site render beside its fields. Current managed and maintained generated Blog renderers open the normal text or rich-text control over a rendered value; changes stay in the draft until Save. Other fields and older renderers focus the matching form field. The bridge checks origin, source, nonce, binding and write access; published pages carry no editor bridge. See [Edit from the preview](/guides/preview-and-client/#edit-from-the-preview).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `backend/src/lib/page-contract/field-links.ts`. `backend/src/lib/field-link-runtime.ts`. `backend/test/preview-field-links.test.ts`. `frontend/src/routes/content/[id]/EntryPreviewPane.svelte.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Management API integrity                 | Keyed commands claim their key first: a duplicate request sent while the first runs is answered 409 `idempotency_in_progress` with `Retry-After`, then replays the exact first answer (a media metadata edit included); another body under the same key is a reused key; a refused command releases its key; a claim whose request stopped is never taken over because time has passed: each command settles it by its own proof (one batch with its answer, its own record, or the job's recorded position), and otherwise it stays pending. Settings changes and proposals are written and audited once for duplicate requests. An import part is bound to the SHA-256 of its first bytes before any is stored; other bytes for that part are refused (`import_part_conflict`). A content export is kept as immutable pages, finished into one file with its digest and size, and only then are the pages removed; two racing advances never lose or double a page. Reads are byte-ranged and bounded, and a stored file that is not the recorded one is refused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `backend/src/lib/management/keyed.ts`. `backend/src/lib/management/idempotency.ts`. `backend/test/management-integrity.test.ts`. `backend/test/management-idempotency.test.ts`. `backend/test/management-data-transfer-export.test.ts`. `backend/test/management-data-transfer.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| WordPress import                         | WordPress pages retain headings, code, tables and longer structured bodies. Source-provided custom metadata and supported SEO fields use explicit mappings; omitted or unsupported source data is reported. WXR and connected acquisition use the same reviewed import and receipts. See [WordPress import](/guides/import-migration/#import-from-wordpress).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `backend/src/lib/import/wordpress-models.ts`. `backend/src/lib/import/wordpress-acf.ts`. `backend/src/lib/import/wordpress-seo.ts`. `backend/test/import-wordpress-fidelity.test.ts`. `backend/test/import-wordpress-real-plugins.test.ts`. `backend/test/import-wordpress.test.ts`. `backend/test/import-wordpress-source.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                           |
| Strapi components and single types       | A Strapi component becomes a site-owned component definition (slug `category-name`); an identical site-owned definition is reused and a different definition already using that slug is refused by name. A dynamic zone becomes a mixed component list in source order, with Strapi row ids dropped and media and relations inside remapped. A single type becomes a single-entry model, each language its own localized component. Definitions are planned and checked before any is written. A re-import is create-or-skip. A site copy carries the definitions, remaps relations inside them and refuses one naming an entry it does not carry. Undo removes definitions only once nothing uses them. Proven on the recorded Strapi 4.25.9 and 5.51.1 archives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `backend/src/lib/import/strapi-components.ts`. `backend/test/import-strapi-components.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Strapi media folders                     | A Strapi 4 or 5 archive's `plugin::upload.folder` entities, their `parent` links and each file's `folder` link are the only authority. Inspection lists the tree with depth and file counts. A file whose `folderPath` names a folder but carries no link imports Unfiled and is reported (`media_folder_link_missing`); a link to a folder the archive lacks blocks the dry run (`media_folder_missing`). The dry run blocks a folder with an unusable name (`media_folder_name_invalid`, 1–80 characters), a missing parent (`media_folder_parent_missing`), a cycle (`media_folder_cycle`), more than 5 levels (`media_folder_too_deep`), a sibling that differs only by case (`media_folder_name_collision`) or the 500-folder limit (`media_folders_limit`), and the children of a blocked folder (`media_folder_ancestor_blocked`). Nothing is renamed or re-parented. Only folders that selected files need, with their ancestors, are created, through the library's folder service with one receipt each; a folder already at the same path is reused and not receipted, and a rerun creates none. Each new file is filed in its folder when it is created. Undo follows the site-copy rules above. Roles and permissions are unchanged. Proven on the recorded Strapi 4.25.9 and 5.51.1 folder archives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `backend/src/lib/import/strapi-folders.ts`. `backend/test/import-strapi-media-folders.test.ts`. `backend/test/fixtures/strapi/v5-folders`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Site history transfer                    | Chunked `.deewan` native transfer (`dee-wan-transfer`, version 1) carries content and optionally retained history, workflow events, Trash, assignments, actor labels, folders and referenced media. Export passes process at most 100 records, preparation passes at most 80 records, and sealing passes at most 32 MiB; media chunks are 5 MiB, records at most 8 MiB, and the archive ceiling is 50,000 MiB (52,428,800,000 bytes). Checksums, source mapping, private storage and receipts remain enforced. The old 64 MiB/20,000-row cap applies to legacy buffered formats, not this transfer. See [Import and migration](/guides/import-migration/).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `backend/src/lib/export/site-history.ts`. `backend/src/lib/import/bundle-history-handlers.ts`. `backend/src/lib/lifecycle/imported-history.ts`. `backend/test/site-history-transfer.test.ts`. `backend/test/principal-mapping.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Public field filters                     | Supports equality on text, select, boolean, number and date fields. Supports `gt` and `lt` (exclusive) and `gte` and `lte` (inclusive) on number and date fields. Accepts one `sort` and sparse `fields`. Accepts at most 4 filtered fields with values up to 255 characters. Repeating `filter[field]=` gives up to 10 alternatives for one field: OR within a field, AND across fields. `expand=` names up to 3 relation fields, one level deep: each item carries up to 25 published, readable targets per field, and `GET /v1/_related/:model` pages the rest with a cursor bound to the source, field, language and token. The API refuses excess input and never narrows it. Cursors carry their query and are refused under any other query. No row-count ceiling is claimed or measured on D1. Point fields support exact Haversine radius/nearest queries and inclusive bounding boxes, including antimeridian crossing, with the same access, count and cursor rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `backend/src/public/index.ts`. `backend/src/lib/public-read/relation-expansion.ts`. `backend/test/public-field-filters.test.ts`. `backend/test/public-filter-alternatives.test.ts`. `backend/test/public-relation-expand.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Shapes accepted before generation refuses them

Generation reads every model and refuses these by name. **Settings → Source & delivery → Advanced — build webhook and deployment → Standalone backend** now lists them before a build (`GET /api/sites/:siteId/generation-readiness`). Content-level refusals surface before a build too: `GET /api/sites/:siteId/generation-readiness/content` walks published content in bounded pages and names what a build would refuse. The build itself stays the authority on site-wide conflicts.

| Refusal                                                                                  | Why the CMS accepted it                                                                                          |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `relation_type_unsupported`                                                              | A relation kind outside the four. Reachable through the API or an import.                                        |
| `relation_bounds_unsatisfiable`                                                          | Selection limits no list can meet, such as at least 3 and at most 1.                                             |
| `relation_required_cycle`                                                                | Required to-one fields that lead back to their own model. The first item could never be created.                 |
| `ambiguous_relation`, `ambiguous_component`                                              | A relation or component with no target can be saved.                                                             |
| `unsupported_field_type`                                                                 | Save accepts any type name. Reachable through the API or an import.                                              |
| `invalid_field_config`, `empty_model`                                                    | Save does not check field config JSON or require a field.                                                        |
| `column_name_collision`, `model_name_collision`                                          | The editor reserves only `id`, `created_at` and `updated_at`. Slugs such as `blog-post` and `blog_post` collide. |
| `relation_target_absent`                                                                 | A relation target can name a model outside the site.                                                             |
| `relation_arity_unsupported`, `relation_target_model_mismatch`, `duplicate_row_identity` | Content-level: rows written before the CMS relation checks, or by an import.                                     |
| `required_value_missing`, `unsupported_value_type`, `unpublished_reference`              | Content-level: imports and content saved before field rules were enforced on the server.                         |

Evidence: `backend/src/lib/graduate/preflight.ts`. `backend/test/graduate-preflight.test.ts`. `backend/test/generation-readiness-route.test.ts`. `backend/test/graduate-plan.test.ts`.

## Rich text

A rich-text field stores one rich document as canonical HTML, up to 256 KiB: paragraphs, headings, lists, quotes, code blocks, rules, bold, italic, underline, strike, inline code, sub- and superscript, links, images, tables (up to 12 columns and 200 rows, with an optional header row, row headers and caption), image galleries (2–24 library images), audio, video and file blocks naming library media, and embeds stored as provider id, canonical https address and title: YouTube and Vimeo built in, plus up to 20 exact https origins an administrator allows under Settings → Integrations ([embed origins](/guides/blog/#embed-origins)). Every write (editor save, restore, management API, plugins, spreadsheet import, site copy) reads the value strictly and refuses anything else by name — field, language, element or attribute — and never echoes the content. A gallery, audio, video or file block must name a media item of this site of that kind. A Strapi import converts Markdown (GFM tables included) to the same HTML, keeps raw HTML only as far as the document holds it, and reports what it left out as a `rich_markup_dropped` finding.

An active plugin may declare `rich_blocks`: a closed set of controls (text, textarea, rich, number, boolean, select, url, media, relation and repeatable groups; groups nest up to 3 levels and hold at most 50 items) with rules, a declarative render tree and migration steps; no HTML, CSS or script. A block is stored as `<figure data-block="plugin" data-type data-version data-values>`. A save refuses an added block no active plugin declares (`rich_block_unregistered`), a newer version (`rich_block_version_unknown`) and values its declaration refuses (`rich_block_values_invalid`); an older version is accepted when its migrated values pass, and an unchanged block is kept after its plugin is removed. Its media references count toward version pins, and its words reach search. `GET /v1/_rich-blocks` serves the active definitions, and stops when the plugin is disabled. The host render adapter escapes every bound value, refuses unsafe addresses, migrates older blocks, draws nothing public for a block no adapter draws and a named placeholder in preview. A site copy keeps stored block versions and remaps media and relation IDs through the counted, checksummed `rich-relations.json` inventory. Copy and history transfer require the matching source declaration; `export_rich_relation_schema_unavailable` means restore it and export again. The destination does not receive plugin installations or grants. A declaration with `inline: true` instead stores a structured inline element as `<span data-block="plugin">` inside a paragraph; it uses the same declared fields, version, reference handling and renderer rules.

| Where rich text is shown                                                | What protects it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The admin rich-text editor                                              | The editor emits the canonical document. It authors paragraphs, headings 1–6, bold, italic, underline, strike, inline code, sub- and superscript, code blocks, quotes, lists, rules, line breaks, links, inline images, tables (up to 12 columns and 200 body rows, header row, row headers, caption), galleries of 2–24 library images, file, audio and video blocks from the media library, and embeds from a pasted YouTube, Vimeo or allowed https link, shown as a placeholder whose Preview opens a new tab. It keeps left, center, right and justified paragraph/heading alignment as canonical data. Vendor snippets have their own isolated frame; arbitrary parent-document frames, styles and classes are refused. Any editor content the document format cannot represent is dropped before saving, and the server refuses anything else.                             |
| The generated Astro website and the managed renderer                    | Page sections hold no markup: the page contract refuses it. A paragraph may carry structured bold, italic, link and list runs ([inline formatting](/reference/page-contract/#inline-formatting)), and Astro escapes their text. Blog post bodies and Latest entries summaries are rendered by the page contract's `renderRichDocument` (`backend/src/lib/page-contract/rich-document.ts`), the same function in both renderers. Tables scroll inside their own box, galleries are a grid, audio and video play with a download link, and an embed is one CMS-owned frame (sandbox, `allow` list, referrer policy, lazy loading, 16:9) from `youtube-nocookie.com`, `player.vimeo.com` or an origin the site allows today (`GET /v1/_embeds`); an embed whose origin is not allowed draws as a plain link. A managed page's `frame-src` names the two players and the allowed origins only. |
| The page editor's Structure preview                                     | Latest entries summaries are shown as text derived from the same document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| The CMS public API, the generated backend API and the TypeScript client | The checked canonical HTML. Media and embed blocks are data (`<figure data-block=…>`), not players: render the value with `renderRichDocument`, or your own renderer of the same document. Pass the origins from `GET /v1/_embeds` to frame a configured embed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

Evidence: `backend/test/rich-document-contract.test.ts`. `backend/test/rich-plugin-blocks.test.ts`. `backend/test/rich-plugin-blocks-bundle.test.ts`. `backend/test/rich-document-render.test.ts`. `backend/test/rich-renderer-parity.test.ts`. `backend/test/rich-field-contract.test.ts`. `backend/test/rich-blocks-bundle.test.ts`. `backend/test/version-media-pins.test.ts`. `backend/test/rich-text-boundaries.test.ts`. `backend/test/import-strapi-markdown.test.ts`. `frontend/src/lib/components/custom-ui/rich-editor/rich-editor-adversarial.svelte.test.ts`. `backend/test/graduate-site-build.test.ts` (escaping page).

## Not in 1.0

Public filters across arbitrary linked fields, public `$or` and text-search filters, and multiple workflow assignees for one whole item are not available. Native lists can filter the configured scalar display field of ordinary same-site relations; see the delivery additions below. The [1.0 product boundary](/boundary/) is the authority.

## October 2026 source additions

These changes exist in the current source and have focused local checks. Final browser integration and live visual review are pending; this is not production acceptance. Entry-folder source is now present with focused service/transfer checks; final integration acceptance remains pending. Model navigation folders above are a separate feature.

| Capability                                   | Current source behavior                                                                                                                                                                                                                                                                                                                                                                                                                       | Evidence                                                                                                                                                 |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plugin content and media operations          | Delegated detail/version reads, normal create/update/Trash, typed relations and media metadata/bytes reuse lifecycle services and live actor grants.                                                                                                                                                                                                                                                                                          | `backend/test/plugin-operations.test.ts`; `backend/test/management-plugin-operations.test.ts`                                                            |
| Grouped field filters and contextual choices | Four leaf conditions, AND/OR, three group levels; shared list/count/view/bulk semantics. Relation choices and select options can depend on sibling fields, current user and entry context; changed dependencies are rechecked on save.                                                                                                                                                                                                        | `backend/src/lib/content-fields/contract.ts`; `backend/test/content-field-query.test.ts`; `backend/test/contextual-choices.test.ts`                      |
| Editorial rich text                          | Paragraph/heading alignment; plugin relation controls and repeatable groups; typed vendor HTML/CSS/JavaScript snippets run in isolated frames in admin and both site renderers.                                                                                                                                                                                                                                                               | `backend/test/rich-editorial-completion.test.ts`; `backend/test/rich-plugin-blocks.test.ts`; `backend/test/rich-snippets-route.test.ts`                  |
| Account maintenance                          | Verify a new mailbox before changing the existing account's email; preserve its identity, memberships, credentials and history, and end sessions. Self-service reset requests use existing short-lived single-use mail claims and equal known/unknown-address responses.                                                                                                                                                                      | `backend/test/account-maintenance.test.ts`                                                                                                               |
| Plugin updates and custom UI                 | Compare manifest/version/permissions before confirming upgrade; new permissions remain ungranted. Reviewed credentialless plugin-origin frames use declared operations and a bound channel without admin credentials.                                                                                                                                                                                                                         | `backend/test/plugin-schema.test.ts`; `backend/test/plugin-ui-extensions.test.ts`                                                                        |
| Document scopes                              | Bounded per-model role rules for read/create/update/delete, including current user context. Lists, counts, related reads, revisions, exports, matching bulk selections and atomic writes apply current rules alongside model, ownership, field and locale grants.                                                                                                                                                                             | `backend/src/lib/document-rules.ts`; `backend/test/document-scopes.test.ts`                                                                              |
| Structured spreadsheet editing               | CSV/XLSX offer Create, Update and Upsert through the reviewed Collection JSON core. Update is the default; match by stable entry ID or an eligible unique field. Review additions, changes and refused rows before Apply. Structured relation/media references and nested components use normal permissions, validation, definition checks and version conflicts. Blank structured cells preserve values; JSON null clears an optional field. | `backend/test/spreadsheet-scope.test.ts`; `backend/test/spreadsheet-collection.test.ts`; `backend/test/spreadsheet-xlsx-import.test.ts`                  |
| Connected WordPress and configuration        | Bounded same-origin HTTPS REST acquisition produces ordinary WXR for the existing review/import path. Explicit reviewed replacement covers title, tagline, logo, icon, SEO description and supplied indexability, with destination revision, import receipt and undo ownership.                                                                                                                                                               | `backend/test/wordpress-connect.test.ts`; `backend/src/lib/import/wordpress-site-configuration.ts`; `backend/src/lib/import/site-configuration-carry.ts` |
| AI authoring assistance                      | Vision models receive authorized image bytes; authors review/edit alt and caption before saving. After source save, opt-in updates target only selected translations with explicit replacement consent, including manually written values.                                                                                                                                                                                                    | `backend/test/ai-media-descriptions.test.ts`; `frontend/src/lib/ai/translate-saved.test.ts`                                                              |
| Entry folders                                | Nested site folders, one placement per translation group, scoped list/counts and separate move history. Placement changes do not create content versions. Copy/history transfer remaps placements with receipts and undo.                                                                                                                                                                                                                     | `backend/src/lib/entry-folders.ts`; `backend/src/lib/entry-folder-transfer.ts`; `backend/test/entry-folders.test.ts`                                     |

## 17 October integration and editorial additions

The following paths are present in source. Their integration checks have not yet been completed on this candidate; test files are coverage references, not a claim that this candidate passed.

| Capability                        | Scope                                                                                                                                                                                   | Source                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Outbound lifecycle events         | Successful content, workflow, release, media and model mutations enqueue notifications through the existing delivery pump. Refusals and idempotent replays create no new event.         | `backend/src/lib/outbound-events.ts`; `backend/src/lib/lifecycle/events.ts`           |
| Component links to several models | Nested, repeated and mixed components keep each selected model and entry identity through save, restore, transfer and rendering.                                                        | `backend/src/lib/component-relations.ts`                                              |
| Plugin workspaces                 | Declared routes, navigation and dashboard placements host the existing isolated plugin frame and authorized operations.                                                                 | `backend/src/lib/plugins/ui-surfaces.ts`                                              |
| Form handling                     | Authorized retained-value review, per-form destination overrides, text templates and consent-based acknowledgements use the existing retention, erase and retry paths.                  | `backend/src/api/forms.ts`; `backend/src/lib/forms/delivery.ts`                       |
| Media workspace and asset fields  | Direct library access; typed private-by-default asset fields, separate revision history and explicit public projection.                                                                 | `backend/src/lib/media/asset-metadata.ts`                                             |
| Collection order                  | Optional order shared by every language; visible anchors preserve hidden entries' relative order. Public clients explicitly request `order=manual`.                                     | `backend/src/lib/manual-order.ts`                                                     |
| Plugin CMS services               | Existing comments/moderation, redirects, Trash restore, eligible media deletion and admin-approved mail templates retain ordinary service checks.                                       | `backend/src/api/plugin-v1-services.ts`; `backend/src/api/plugin-v1-mail.ts`          |
| Renderer contributions            | Declared metadata, links and JSON-LD are stored with content versions. Core SEO takes precedence; renderers make no live call to a plugin.                                              | `backend/src/lib/plugins/renderer-metadata.ts`; `backend/src/lib/seo/head-runtime.ts` |
| Structured inline content         | A plugin declaration can opt into inline elements. Structured values remain inside paragraphs and follow normal version, reference and renderer handling.                               | `backend/src/lib/page-contract/rich-document.ts`                                      |
| Published hierarchy               | Ancestors and breadcrumbs use published labels and accepted routes, with the site's locale policy. Draft changes do not replace live labels.                                            | `backend/src/lib/public-read/published-list.ts`                                       |
| Maintained Astro starter          | The starter command emits ownable source connected to the live public API, with the current page and renderer contracts.                                                                | `backend/src/lib/managed-renderer/reference-starter.ts`                               |
| Supported release                 | A tagged release, scheduler deployment and real Cloudflare publication, preview, media, mail and recovery evidence are still required. Local source changes do not satisfy these gates. | [Product boundary](/boundary/)                                           |

Native form file fields and contextual plugin mail recipients extend these source additions. Form files stay in private storage and follow submission retention, authorized download and erasure. An approved mail template can select the entry author or assigned reviewer from an authorized entry. Runtime and provider acceptance remain pending.

## Current integration additions

These source features are part of the unreleased integration candidate. The final browser gate, live mobile/desktop review and external-provider acceptance remain separate requirements.

1. Chunked native site/history transfers carry accepted large media with checksums and continuation.
2. WordPress page conversion preserves headings, code, tables, longer bodies and explicitly mapped source metadata.
3. Protected rich text supports private images, attachments and authorized image variants.
4. Native-script addresses retain Unicode letters, numbers and combining marks and can be generated from titles.
5. Named compound uniqueness joins two to four scalar fields under atomic write guards.
6. Blog metadata can resolve live contributor, category and tag information; snapshot behavior remains an explicit option.
7. Ordinary and mixed components can be retired, retain older definitions and upgrade instances deliberately.
8. Plugin rich-text blocks can contain bounded host rich-text child fields.
9. Native relationship columns show scoped labels, counts and related values.
10. Typed visibility conditions combine up to four terms in AND/OR groups, at most three levels deep.
11. Optional translated fields can borrow absent values from published fallback languages; deliberate empty values stay empty. See [Field fallback](/guides/languages/#field-fallback).
12. Validated static SVG works through the image workflow.
13. Generated applications support up to 32 named application roles with model-operation grants, a non-admin signup default and existing admin/user roles.
14. DeepInfra remains the default inference provider; a deployment can select an OpenAI-compatible endpoint and explicit text, vision and image model lists.
15. [Related draft previews](/guides/preview-and-client/#preview-unsaved-changes) resolve authorized saved related drafts; ordinary public reads still require publication.
16. [Content search](/guides/content-editing/#find-and-open-an-item) covers saved rich-text bodies, including drafts, with matching fields and short excerpts inside the reader’s access scope.
17. [Live API browser origins](/reference/public-api/#browser-origins) configure CORS, preflight and permitted public-read headers per site.
18. [Management media replacement](/reference/management-api/) keeps the media ID and references while replacing bytes through the existing replacement service.
19. [Generated account administration](/reference/standalone-backend-api/#application-account-administration) creates named-role accounts and deletes unlinked accounts, with session revocation and last-administrator protection.
20. [Rendered entry editing](/guides/preview-and-client/#edit-from-the-preview) opens text and rich-text controls over supported renders; older renderers keep field-focus fallback.
21. [WordPress imports](/guides/import-migration/#import-from-wordpress) retain reviewed ACF groups/repeaters as editable JSON and explicitly keep future publication schedules or draft intent.
22. [Selected-content refresh](/guides/import-migration/#refresh-selected-content) reviews additions, updates and deletions in populated models, preserves excluded data and old media pins, and refuses conflicting edits. Resume and cancel remain available; replacement has no automatic Undo.

## Delivery additions

| Capability                      | Source contract                                                                                                                                                                                                         |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Native relation display queries | Configured scalar display field; current saved values, target ACL, shared list/count/view/bulk SQL. Cross-site display queries return `field_shared_display_unsupported`; membership and empty checks remain available. |
| Localized originals             | One asset ID, per-language current files, locale fallback and immutable retained pins. Native and management operations; export/import retain languages.                                                                |
| Explicit shared references      | Source-owned published public projection, current grant revision and per-delivery custody checks across dedicated databases. Revoke or unpublish resolves to null.                                                      |
| Point queries                   | Strict latitude/longitude; exact Haversine radius/nearest SQL, inclusive antimeridian boxes and bound cursors.                                                                                                          |
| Incremental sync                | Published authorized entries and public media; bounded snapshot, ordered replay/tombstones, signed scope-bound checkpoint and explicit reset.                                                                           |

`backend/test/delivery-query.test.ts`; `delivery-originals.test.ts`; `delivery-shared-content.test.ts`; `delivery-sync.test.ts`; `delivery-sync-triggers.test.ts`.

<!-- dee-wan-docs page: /reference/strapi-comparison/ -->

# Dee Wan and Strapi

Source: https://dee-wan-docs.pages.dev/reference/strapi-comparison/

A factual comparison for teams moving from Strapi. Dee Wan's column describes what the code does today,
as listed in the [capability matrix](/reference/capability-matrix/) and the [1.0 product boundary](/boundary/).
Strapi's column quotes the Strapi 5 documentation at docs.strapi.io, read on 2026-09-23. It was not
tested against a running Strapi. Where the documentation is silent, the cell says so.

Dee Wan imports from Strapi v4 and v5 (see [Import and migration](/guides/import-migration/)). It is not a
Strapi replacement feature for feature, and the rows below include what Dee Wan does not do.

## Content model

| Topic                           | Dee Wan                                                                                                                                                                                                                                                                                                                                                                        | Strapi 5 (documentation)                                                                                              |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Single types                    | A model can be a single-entry model: one entry with its languages, counting Trash. A Strapi single type imports as one.                                                                                                                                                                                                                                                        | "Single types: content-types that can only manage one entry." (Content-type Builder)                                  |
| Components and dynamic zones    | Site-owned components, nested up to 3 levels. A component field holds one component or a list; a field allowing several components is an ordered block list. Strapi components import as components of the site (`shared.seo` becomes `shared-seo`), dynamic zones as block lists.                                                                                             | Components, repeatable components and dynamic zones. (Content-type Builder)                                           |
| Relation kinds                  | One-to-one, many-to-one, one-to-many and many-to-many. In one-to-one each target is linked from at most one item. In one-to-many each linked item belongs to one owner; standalone generation emits it as an owned list with a unique target. Component fields do not offer one-to-many.                                                                                       | One way, one-to-one, one-to-many, many-to-one, many-to-many, many way. (Content-type Builder)                         |
| Relation writes                 | Replace the ordered list, or `connect` / `disconnect` single items. Each changed list is checked for target model, site, visibility to the writer, duplicates and to-one cardinality. `connect` items may carry a position (`before` or `after` an id, or `start` or `end`), and a `move` list repositions items already related. Applied in order: disconnect, connect, move. | `connect`, `disconnect`, `set`, with positional `before`, `after`, `start`, `end` on `connect`. (REST API: relations) |
| Field validation                | Editor and server share type, structure, bounds, uniqueness and reference checks. Drafts may omit required values by default; optional strict mode requires completeness on Save. Publication checks the exact snapshot, including required values. Private fields stay out of public reads.                                                                                   | Required, unique, private, minimum and maximum length, regular expression. (Content-type Builder)                     |
| Deletion behaviour of relations | Fixed: relation rows go when either entry is deleted for good. Trash keeps them. The other entry stays. No per-field setting.                                                                                                                                                                                                                                                  | Not described on the pages read.                                                                                      |

## Editorial work

| Topic                                | Dee Wan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Strapi 5 (documentation)                                                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Review workflow                      | Optional review mode, named model workflows, approval stages and transition permissions. Version- and language-bound field threads support replies, user/team mentions and resolve/reopen.                                                                                                                                                                                                                                                                                                                                               | Review Workflows: "This feature is available with an Enterprise plan."                                                                            |
| Assignment                           | Whole-entry assignment plus independent locale owners and due dates. Required editorial tasks must be completed against the affected version before publication; unrelated-language changes preserve locale approval. In-admin notifications cover assignments and review; email is optional. Imports stay quiet unless notifications are selected. See [feedback and notifications](/guides/content-editing/#feedback-and-notifications).                                                                                                     | "Entries of a review workflow content type can be assigned to any admin user in Strapi for review." Notifications are not mentioned. (Enterprise) |
| Bulk actions                         | Explicit-row actions handle up to 25 items. Select all matching handles up to 5,000 across pages, with exclusions, in steps of at most 25. Move, publish/unpublish by override, Trash and scalar-field editing; restore/delete in Trash use explicit rows. Access and revisions are rechecked per item; progress resumes and retries preserve completed effects. See [change many items](/guides/content-editing/#change-many-items-at-once).                                                                                                  | The list view has an "Enable bulk actions" setting for multiple selection. The page read does not list the actions. (Content Manager)             |
| Content-list filters and saved views | One model, latest saved values including drafts: up to four conditions in AND/OR groups, three levels deep, and one sort. Native relations support filters on their configured scalar display field and sorting for single-valued, single-target relations; target access is checked. Point fields support radius, bounding-box and nearest queries. Saved views and all-matching selections use the same conditions. No arbitrary related-field queries. See [filter and sort by fields](/guides/content-editing/#filter-and-sort-by-fields). | Not compared: not on the pages read.                                                                                                              |
| Versions                             | Immutable published snapshots, version history and restore. Restore can cover one language only.                                                                                                                                                                                                                                                                                                                                                                                                                                         | Not compared: not on the pages read.                                                                                                              |

## Media

| Topic                | Dee Wan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Strapi 5 (documentation)                                                                                                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Crop and focal point | Per reference, as fractions of the image, stored beside the reference. The stored image is never changed or copied. A published version keeps its framing. A page section's image is framed per slot. The public API returns the framing. A generated site and the managed renderer serve resized, cropped copies (`srcset`) through Cloudflare Image Transformations on media hosts the owner declares, and the original with CSS framing elsewhere. Your own renderer applies the framing itself. | Cropping edits the asset: "Click **Apply** to crop the original asset. The asset keeps its ID, so content already using it is updated", or "**Save as copy**". The focal point "is stored on the asset and returned by the API as a `focalPoint` value". (Media Library) |
| Private files        | Optional per file, in separate private storage, opened by members through five-minute links. Usable only in fields of private models; public reads carry no private bytes or address. Site copy and history transfer carry them privately. A generated application serves them only to callers its own sessions and row access allow. See [private files](/guides/media/#private-files).                                                                                                                  | Not compared: not on the pages read.                                                                                                                                                                                                                                     |

## Reading content

| Topic              | Dee Wan                                                                                                                                                                                                                                                                                                                                                   | Strapi 5 (documentation)                                                                                                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filters            | Equality on text, select, boolean, number and date fields. Inclusive ranges on number and date. Relation and tag filters. Up to 10 alternatives per field, ORed; different fields ANDed. At most 4 filtered fields. `expand` returns up to 3 relation fields one level deep. No general `$or`, no text search, no filter through a relation's own fields. | `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$contains`, `$startsWith`, `$endsWith`, `$in`, `$notIn`, `$and`, `$or`, `$not`, and deep filtering on relations' fields. (REST API: filters) |
| Sort and fields    | One sort field, sparse top-level `fields`.                                                                                                                                                                                                                                                                                                                | Sort and field selection are supported. (REST API)                                                                                                                                        |
| Pagination         | Cursor bound to its query.                                                                                                                                                                                                                                                                                                                                | Not compared.                                                                                                                                                                             |
| Standalone backend | A generated backend you own (Prisma schema, migrations, routes, published content) whose API does not call Dee Wan at runtime (some website routes do; see the [detachment contract](/detachment-contract/#what-still-depends-on-dee-wan)). Scoped read tokens for it are issued from the CMS by model.                                                  | No equivalent on the pages read.                                                                                                                                                          |

## What this page does not claim

- Performance, hosting cost or scale on either side.
- Strapi behaviour beyond the quoted documentation, or plugins from the Strapi marketplace.
- Anything about Strapi versions other than 5.

## Further Dee Wan source capabilities

The October source adds the capabilities below. These rows make no claim about Strapi: those topics were not compared in the documentation review above. Final browser integration and live visual review of the new Dee Wan paths remain pending.

| Topic                          | Dee Wan                                                                                                                                                                                                                                                             | Strapi 5 (documentation) |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| Contextual choices and scopes  | Relation/select choices can depend on sibling fields, user and entry context. Role document rules scope core reads and atomic writes; related API/export audit is pending.                                                                                          | Not compared.            |
| Structured spreadsheet updates | CSV/XLSX offer Create, Update and Upsert through the reviewed Collection JSON core. Update is the default; match by stable entry ID or an eligible unique field. Structured relations, media and nested components use normal scope, validation and version checks. | Not compared.            |
| Plugin extensibility           | Delegated CRUD, retained versions and media operations; upgrade comparison; isolated custom plugin frames; relation/repeatable rich blocks and isolated vendor snippets.                                                                                            | Not compared.            |
| Account and AI assistance      | Verified email changes preserve the account; self-service mail reset requests; reviewed image descriptions and opt-in source-save translation replacement.                                                                                                          | Not compared.            |
| Connected migration            | Bounded WordPress REST acquisition feeds existing WXR review/import. Explicit site identity/SEO replacement uses reviewed destination revision, receipts and undo.                                                                                                  | Not compared.            |

Current authoring also includes localized model, field/group, help and option labels without changing stored keys; reviewed model promotion between sites binds both definition revisions. Zoned datetimes retain a UTC instant and IANA zone, refuse nonexistent times and require an offset choice for ambiguous times. Batch AI produces editable retained proposals without saving content; cancellation keeps completed proposals. Independent future drafts retain their own snapshots and media pins without changing the ordinary draft; release start freezes the selected branch, and cumulative previews use the scheduled future state.

<!-- dee-wan-docs page: /guides/local-development/ -->

# Local development and repository guide

Source: https://dee-wan-docs.pages.dev/guides/local-development/

![Dee Wan CMS — the Dee Wan letter mark set in a Thai-ornament banner](/assets/readme-header.png)

**Dee Wan CMS** (ดีหวาน 🇹🇭) is a multi-tenant, multilingual headless CMS that runs entirely on
Cloudflare: a Hono Worker over D1 for the API, and a SvelteKit admin on Pages.

It is a CMS first: model content, author it, publish it, manage it. What separates it from other
headless CMSs is what it can hand you at the end — **standalone backend generation** turns a site into
a repository you own, with a normalized Prisma schema, reviewable append-only migrations, generated
routes with familiar Prisma query semantics, its own database, deployment and credentials, and no
runtime dependency on Dee Wan. Your own code survives regeneration, and detaching from Dee Wan
entirely is a supported outcome.

There are two ways to serve published content. The **CMS public API** updates the moment content is published. The **standalone backend** is an
independent release of the schema and content: later CMS changes reach it only through an explicit
regeneration and deployment.

> **Pre-release:** Dee Wan 1.0 is not a released product yet. Acceptance against real Cloudflare,
> final browser checks and migration of real sites are still open. See the
> [1.0 product boundary](/boundary/) for what is and is not covered.

Start here:

- [Try it locally](#try-it-locally-with-no-cloudflare-account) — no Cloudflare account needed.
- [Installing Dee Wan](/guides/installation/) — the full guide for your own Cloudflare account.
- [Public read API](/reference/public-api/) — how a website reads published content.
- [Standalone backend: Overview](/guides/standalone-backend/) — what a generated backend is and how to generate it.
- [Extending your backend](/guides/extending-your-backend/) — working in a generated standalone
  backend.
- [Database migrations](/guides/database-migrations/) — changing and applying the schema.

## What it does

- **Model builder** — define content models and fields (text, rich text, number, boolean, select,
  date, media, JSON, relation, component) in the UI. Models are stored as data, so adding a "Recipe"
  type takes no code and no migration. A change is diffed before it is applied, and edits that would
  invalidate existing content are flagged first.
- **Multi-site** — one installation serves many sites. Every admin request names its site, and the
  data layer adds the site to every query. The API refuses to guess a site rather than risk reading
  another site's data.
- **Multilingual** — configure languages in the UI. Content is stored per language.
- **Versioning and publishing** — content revisions with publish and unpublish. Editorial review is
  an optional per-site mode, **off by default**: a new site publishes straight from draft, and no
  review controls appear until someone turns review on in **Settings → Workflow**.
- **AI assistance** — generate and translate copy, and generate images, through the Worker. The
  provider key never reaches the browser.
- **Media** — upload to R2 or Cloudflare Images, with automatic WebP/AVIF conversion.
- **Sign-in** — the installation's own accounts and sessions. A single-use claim link creates the
  first administrator with password, magic link, Google or GitHub. Password, magic-link, Google and
  GitHub sign-in never create accounts. Cloudflare Access is optional, off by default. Where a site
  administrator adds an Access rule, a matching verified Access identity gets an account and that
  site's role when it signs in.
- **Remote plugins** — a plugin is a separately deployed service. Its code does not run in the
  Dee Wan backend or the admin page's main document; optional plugin interfaces run in isolated
  frames. Plugins receive no direct database access. A versioned HTTP protocol lets them work with
  content, media and workflow within both the per-site grant chosen in **Settings → Plugins** and
  the current user's delegated permissions. Scheduled publishing is the Scheduling plugin
  (`plugins/scheduling/`), not a core feature. Plugin developers:
  [writing a plugin](/plugins/authoring/) · [protocol v1](/plugins/protocol-v1/) ·
  [security](/plugins/security/) · [testing](/plugins/testing/) ·
  [manifest schema](/schemas/plugins/manifest-v1.schema.json) ·
  [protocol schema](/schemas/plugins/protocol-v1.schema.json).

### Roles

Each person gets a role per site. The built-in roles:

| Role | Can do |
| --- | --- |
| `admin` | Everything on the site: content, publishing, models, settings, people, roles, plugins, import and export. |
| `editor` | Create, edit, publish, unpublish and approve any content. Can export. Cannot change models or settings. |
| `author` | Create content and read all of it, but **edit only content they created**. Cannot publish, unpublish, approve or restore. |
| `viewer` | Read only. |

How the author rule works:

- The account that created an item owns it. An item with no recorded creator cannot be edited
  by an author.
- Translations of one item form a group with one primary item, and every save also writes the
  primary. So an author can edit a translation only if they created both that translation and the
  group's primary item.
- Every action an author is allowed on an item — editing, and workflow steps such as sending it for
  review — is refused with `not_owner` on someone else's item, and the editor hides controls the
  author cannot use.

A superadmin is not limited by any of this.

## Architecture

| Piece | Stack |
| --- | --- |
| Admin UI | SvelteKit (single-page app), shadcn-svelte, TipTap — on Cloudflare Pages |
| Admin API | Hono on a Cloudflare Worker |
| Public read API | A second Worker, reading published content only |
| Database | D1, through Prisma (`@prisma/adapter-d1`) |
| Media | R2 or Cloudflare Images |
| Auth | Better Auth sessions. Cloudflare Access is optional. |
| Inference | DeepInfra |

The repository is an npm workspace. Most shared libraries in `packages/` are **git submodules**, so
clone with `--recurse-submodules`. `page-contract` and `plugin-conformance` live in this repository.

```
backend/     Admin and public Workers: API, auth, site-scoped data access, AI proxy, Prisma schema
frontend/    SvelteKit admin UI
packages/    submodules: schema-parser, prisma-guard, prisma-rbac, prisma-generator-express, eav-to-prisma,
             cache, prisma-query-builder-ui. In this repository: page-contract, plugin-conformance
plugins/     remote plugins built against protocol v1 (Scheduling)
scripts/     install, deploy, migrate, health, teardown
```

## Try it locally, with no Cloudflare account

This runs the whole product against a local D1 file on your machine: no account, no API token, no
DNS. You need Node and npm as listed under [Prerequisites](#prerequisites).

```bash
git clone --recurse-submodules https://github.com/dee-wan-cms/dee-wan.git
cd dee-wan
node scripts/install-dependencies.mjs            # root and backend dependencies
node scripts/install-dependencies.mjs frontend   # admin UI dependencies
npm run local:migrate    # apply the schema to the local database
npm run local:api        # admin Worker on http://localhost:8787   (leave running)
npm run local:seed       # sample sites and content (in a second terminal)
npm run local:admin      # admin UI on http://localhost:5173       (leave running)
```

`local:seed` prints the sign-in it created: `admin@localhost.test`, password
`local-dev-password-1234`. Running it again reports what already exists instead of making copies.

It seeds two things, which are also separate commands:

| Command | What it makes |
| --- | --- |
| `npm run local:seed:fixture` | The **Local Dev Site**: the first admin, an `Article` model, three drafts and one demo page. |
| `npm run local:seed:corpus` | Two realistic fictional sites — **Meridian Review**, a magazine with an eighteen-month back catalogue, and **Fern & Ash**, a small studio site. They use the blog fixture definitions and contain about fifty items in published, draft, in-review, approved and scheduled states. They include relations, images with alt text, and German translations. Needs the fixture's admin first. |

Corpus dates are anchored to when the corpus was first created, so reruns do not move existing
content. Images come from `backend/scripts/fixtures/media/` when that directory has any. Otherwise
the corpus generates simple placeholder images.

Then, in the admin UI, open **Content**, edit one of the seeded articles, and publish it.

![The admin dashboard on the seeded local site: content totals, what is live, and recent changes](/assets/screenshots/dashboard.webp)

![Content: the three seeded Article drafts in a list, with stage and delivery filters](/assets/screenshots/content-list.webp)

![A seeded article open in the content editor, with the Publishing panel beside it](/assets/screenshots/content-editor.webp)

To read what you published the way a website would:

```bash
npm run local:public     # public read Worker on http://127.0.0.1:8788 (leave running)
curl -H "Host: localhost" http://127.0.0.1:8788/v1/article
```

The public Worker finds the site from the `Host` header and nothing else, so a request without it
answers 404 — the same rule a deployment runs under.

From here, **Settings → Data transfer** imports and exports content. The dashboard's **Standalone
backend delivery** link opens **Settings → Source & delivery** to connect a repository and manage
deployment. Project generation is separate; deployment needs a Cloudflare account.

This rig uses `backend/wrangler.dev.jsonc`, which is tracked, holds no credential or account id, and
never touches Cloudflare.

## Install on Cloudflare

The full guide, including unattended installs, upgrading and teardown, is
[Installing Dee Wan](/guides/installation/). The short version follows.

### Prerequisites

- A Cloudflare account with Workers, D1, Pages, and R2 **or** Cloudflare Images.
- Node 22 (≥22.14) or 24 (≥24.10). The repository's `.nvmrc` pins 24.18.1, so `nvm use` picks it.
- npm exactly as `package.json#packageManager` declares (11.16.0), which is the npm that the
  `.nvmrc` Node ships. Always install with `node scripts/install-dependencies.mjs`,
  never a bare `npm install` or `npm ci`: it refuses any other npm, installs the locked tree with
  install scripts off, checks every dependency script against `package.json#allowScripts`, and only
  then rebuilds the approved ones.
- Optionally, a DeepInfra API key for the AI features.

Cloudflare Access (Zero Trust) is **not** required. Setup asks whether to enable it. The default is
no, and sign-in then works through the installation's own sessions.

### Quickstart

```bash
git clone --recurse-submodules https://github.com/dee-wan-cms/dee-wan.git
cd dee-wan
node scripts/install-dependencies.mjs
node scripts/install-dependencies.mjs frontend

npm run setup     # provisions everything, builds and deploys the admin UI and both Workers
npm run health    # checks the deployment answers
```

`setup` creates the D1 database and media storage, applies the schema, builds and deploys the admin
UI, the admin Worker and the public read Worker, stores their secrets, and offers DNS and optional
Access. At the end it prints a **claim link**: open it and choose any configured password, magic-link,
Google or GitHub method to create the superadmin. Every method must prove the exact normalized
`BOOTSTRAP_ADMIN_EMAIL`.
The link is single-use and expires in 15 minutes. If you miss it, run `npm run setup` again — an
unused expired link counts as unfinished, so the run mints a new one while nobody has claimed the
installation.

Later code or configuration changes are shipped with `npm run deploy` (see [Deploy](#deploy)).

A fresh clone needs no manual build step: `packages/*/dist` and the Prisma client are build output,
and `setup`, `deploy` and `migrate:d1` build them when they are missing. `npm run doctor` is a
read-only check. On a fresh clone it reports those outputs as missing, so run it after `setup` or
after `npm run build:packages && npm run prisma:generate`.

### Serving published content (the public read Worker)

Published content is served by a separate public read Worker, configured by
`backend/wrangler.public.jsonc`.

**`npm run setup` writes that file for you**, once the account, the zone and the database id are
settled, and never overwrites an existing one. If one of those cannot be worked out, setup says so by
name rather than guessing. That is the case where you prepare it by hand:

```bash
cp backend/wrangler.public.example.jsonc backend/wrangler.public.jsonc
# edit backend/wrangler.public.jsonc — account id, D1 id, route
npm run deploy
```

`deploy` refuses to run when that file is absent, because an installation with no public Worker
cannot serve published content. An installation that only wants the admin says so with
`npm run deploy -- --admin-only`, which is then reported as admin-only rather than complete.

A non-default admin config (`--config`) needs its public config named too, for example
`npm run deploy -- --config wrangler.v3.jsonc --public-config wrangler.v3.public.jsonc`. Both are
read and their `account_id` values compared before anything is deployed.

**The public cache is off until you turn it on.** A default installation sets
`PUBLIC_CACHE_MAX_AGE=0`, and the public Worker answers `Cache-Control: no-store`, so every publish,
update, unpublish or delete is visible on the next read. To cache, the admin Worker must be able to
purge on publish, which needs `CF_PURGE_ZONE_ID` and a `CF_PURGE_API_TOKEN` with `Zone → Cache
Purge` (see [Secrets](#secrets)). Raising `PUBLIC_CACHE_MAX_AGE` also exposes you to the zone's
**Browser Cache TTL**, which rewrites browser caching whenever the origin asks for less, and a purge
can never clear a browser. Set Browser Cache TTL to *Respect Existing Headers* before relying on the
cache.

### Credentials

`setup` needs a Cloudflare API token. It **prompts for one** if none is set, and prints the exact
permission list with a reason for each. [Installing Dee Wan](/guides/installation/#credentials)
marks which permissions depend on your choices, such as your own domain or Access. `npm run doctor` prints the same list.

```bash
export CLOUDFLARE_API_TOKEN=…    # optional — skips the prompt
export CLOUDFLARE_ACCOUNT_ID=…   # optional — skips the account picker
```

`setup` itself needs no other environment variable. Application secrets are set with
`wrangler secret put` (below), never in a file. Optional variables used by other commands:

| Variable | Used by |
| --- | --- |
| `DEEWAN_RESOURCE_PREFIX` | `setup` — namespaces every resource name. See [shared account](#running-the-installer-against-a-shared-account). |
| `DEEWAN_YES=1` or `CI=true` | `setup`, `install:cms` — never prompt. Take defaults or fail. |
| `D1_PLAN` (`free` or `paid`) | Unattended installs — answers the D1 plan question. |
| `DEEWAN_CF_OAUTH_CLIENT_ID`, `DEEWAN_CF_OAUTH_REDIRECT` | `install:web` — Cloudflare sign-in. Without a client id the web installer cannot connect to Cloudflare. |
| `DEEWAN_INSTALL_PORT` | `install:web`, `install:web:dry-run` — port on `127.0.0.1`. |
| `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET` | `health` — a Cloudflare Access service token, to check the Access perimeter when Access is on. |
| `DEE_WAN_ADMIN_COOKIE` | `provision:site`, `acceptance` — an admin session cookie for the checks that need one. |
| `DEEWAN_GITHUB_CLIENT_ID` | `wire:github`, `backend:deliver` — the GitHub OAuth client used for device sign-in. |
| `VERIFY_ADMIN_URL`, `VERIFY_PUBLIC_URL`, `VERIFY_EMAIL`, `VERIFY_PASSWORD` | `verify` (the password is read only from the environment). |
| `DEEWAN_ACCEPTANCE_ADMIN_EMAIL`, `DEEWAN_ACCEPTANCE_SITE_ID`, `DEEWAN_PUBLIC_HOST`, `DEEWAN_PUBLIC_STRANGER_HOST` | `acceptance`. |
| `DEEWAN_SMOKE_PAGES`, `DEEWAN_SMOKE_HOST` | The [deployment smoke test](#deployment-smoke-test). |
| `PUBLIC_BACKEND_URL` | `local:admin` — the admin API the local UI talks to (default `http://localhost:8787`). |

### Secrets

Secrets are never stored in `wrangler.jsonc` or in the database. Set them from the `backend/`
directory:

```bash
npx wrangler secret put DEEPINFRA_API_KEY   # AI text and image generation
```

Plain settings (not secrets) go under `vars` in `backend/wrangler.jsonc` and take effect on the next
`npm run deploy`. Everything below is optional. A feature whose settings are missing is off.

| Name | Kind | What it turns on |
| --- | --- | --- |
| `DEEPINFRA_API_KEY` | secret | Default DeepInfra connection for chat, images and structured generation. |
| `AI_RATE_LIMIT_PER_HOUR` | var | AI calls allowed per site per hour. Default 250. |
| `CF_IMAGES_API_TOKEN` | secret | Uploads when `STORAGE_PROVIDER` is `cf-images`. |
| `R2_PUBLIC_DOMAIN` | var | The public address R2 media is served from. `setup` writes it. R2 media needs it. |
| `CF_PURGE_ZONE_ID` | var | Edge cache purge on publish, with `CF_PURGE_API_TOKEN`. This applies only if you raise `PUBLIC_CACHE_MAX_AGE`. |
| `CF_PURGE_API_TOKEN` | secret | A token with `Zone → Cache Purge` for that zone. |
| `RESEND_API_KEY` | secret | Magic-link sign-in, invitation email and invitation codes, and email delivery of administrator-minted password links through Resend. Needs `MAIL_FROM`. Without both, magic link is unavailable, and invitation and password links are shown to the administrator to pass on. |
| `MAIL_FROM` | var | The From address, e.g. `Dee Wan <cms@example.com>`. Must be a verified sender at Resend, or at your own mail transport. |
| `MAIL_TRANSPORT_URL` | var | An `https://` address of your own mail service. When set, it replaces Resend for every message. Needs `MAIL_TRANSPORT_TOKEN` and `MAIL_FROM`; without both, mail reports not configured and links are shown to pass on. An address that is not public https is refused. See [Mail transport](/guides/people-and-access/#mail-transport). |
| `MAIL_TRANSPORT_TOKEN` | secret | The bearer token Dee Wan sends to `MAIL_TRANSPORT_URL`. |
| `AUTH_INITIAL_METHODS` | var | Comma-separated methods offered before the first administrator exists: `password`, `magic_link`, `google`, `github`. Defaults to `password`. Missing required bindings still make a method unavailable. |
| `GOOGLE_CLIENT_ID` | var | Google OAuth client for CMS sign-in. Callback: `BACKEND_URL/api/auth/callback/google`. |
| `GOOGLE_CLIENT_SECRET` | secret | Secret for the Google OAuth sign-in client. |
| `GITHUB_CLIENT_ID` | var | GitHub OAuth app client for CMS sign-in. Callback: `BACKEND_URL/api/auth/callback/github`. Separate from source delivery and CLI device flow. |
| `GITHUB_CLIENT_SECRET` | secret | Secret for the GitHub OAuth sign-in app. |
| `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_CLIENT_ID` | var | A GitHub App for **Settings → Source & delivery** (connecting a repository and managing deployment). Without all five `GITHUB_APP_*` values, that screen reports `github_app_not_configured`. |
| `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_PRIVATE_KEY` | secret | The rest of that GitHub App. |
| `PLUGIN_CATALOGUE_URLS` | var | **Settings → Plugins → Discover**. Comma-separated `https://` plugin catalogue URLs, at most 4 read. None by default. A listing grants nothing: installing still reviews and validates the manifest. See `docs/plugins/security.md`. |
| `OPERATOR_SENTRY_DSN` | secret | Sends cleaned error reports to **your own** Sentry project. |
| `DEEWAN_ERROR_REPORTING` | var | `off` stops reports to Dee Wan's Sentry project. |
| `TEMPLATE_ARTIFACTS` | binding | Site templates: a private R2 bucket, bound under `r2_buckets`, that holds each template candidate's source, compiled output and gate report. Accepting a template needs only this. See `docs/MANAGED-TEMPLATES.md`. |
| `TEMPLATE_BUILD_SERVICE_URL` | var | Uploading a site template, and generating one with `DEEPINFRA_API_KEY`. The origin of a host running `npm run template-build-service`: a bare `https://` origin, or `http://` on `localhost`, `127.0.0.1` or `[::1]`. Also needs `TEMPLATE_BUILD_SERVICE_KEY`, `TEMPLATE_SANDBOX_IMAGE` and `TEMPLATE_ARTIFACTS`. |
| `TEMPLATE_BUILD_SERVICE_KEY` | secret | Signs every build request. The build host holds the same value. A key shorter than 32 characters counts as unset. |
| `TEMPLATE_PREVIEW_SERVICE_URL` | var | Previewing a site template candidate. The origin of the preview host, with the same rules. One host may serve both. Also needs `TEMPLATE_PREVIEW_SERVICE_KEY`, `TEMPLATE_SANDBOX_IMAGE` and `TEMPLATE_ARTIFACTS`. |
| `TEMPLATE_PREVIEW_SERVICE_KEY` | secret | Signs every preview request. The preview host holds the same value. A key shorter than 32 characters counts as unset. |
| `TEMPLATE_SANDBOX_IMAGE` | var | The container image the build and preview hosts run generated code in, pinned by digest (`<repository>@sha256:<64 hex>`). A tag counts as unset. Upload, generation and preview need it. |
| `MANAGED_RENDER_HMAC_KEY` | secret | Signs the page editor's exact site-design render. A key shorter than 32 characters counts as unset. That render also needs an active managed renderer release; without one the site sees the Structure preview. Preparing, activating and rolling back a release need it too: the admin sends the deployment service only each site's key derived from it. Never give this value to a site renderer or the deployment service. |
| `MANAGED_RENDER_DEPLOY_SERVICE_URL` | var | Preparing, activating and rolling back a managed renderer release. The origin of a host running `npm run managed-deploy-service`: a bare `https://` origin, or `http://` on `localhost`, `127.0.0.1` or `[::1]`. Also needs `MANAGED_RENDER_DEPLOY_SERVICE_KEY`, `MANAGED_RENDER_INSTALLATION_ID`, `MANAGED_RENDER_HMAC_KEY`, `TEMPLATE_ARTIFACTS` and an active site binding for the site. |
| `MANAGED_RENDER_DEPLOY_SERVICE_KEY` | secret | Signs every deployment request and checks every receipt. The deployment host holds the same value. At least 32 characters. |
| `MANAGED_RENDER_INSTALLATION_ID` | var | Stable, non-secret id of this installation: lower-case letters, digits and hyphens, 3 to 63 characters. Each site's renderer Worker name is derived from it and the site id. Never change it after a first release. |

Generating, uploading, previewing or accepting a site template without its settings answers
`503 template_operation_unavailable` with the operation and the names of what is missing, never a
value. The build and preview settings deploy nothing, and accepting a template changes nothing that
is live. Releases are delivered by the separate deployment service, which holds the Cloudflare API
token; the admin Worker never does. Without the delivery settings, Settings lists what is missing.
See `docs/MANAGED-TEMPLATES.md`.

The admin API talks to AI providers only through `/api/ai/*` on the Worker, which holds the key and
enforces the hourly quota.

**Error reports.** Unhandled errors can be reported with the error type, a cleaned message, stack
frames and the route — never content, form values, emails or credentials. With
`OPERATOR_SENTRY_DSN` set, they go to your Sentry project. This build contains no Dee Wan Sentry
address, so nothing is sent to Dee Wan unless `DEEWAN_SENTRY_DSN` is set. **Installation → Error
reports** (superadmins only) then shows "No Dee Wan destination in this build. Nothing is
sent." The switch on that screen and `DEEWAN_ERROR_REPORTING=off` only affect reports to Dee Wan,
not to your own DSN. Secrets belong to one Worker: set `DEEWAN_SENTRY_DSN` or `OPERATOR_SENTRY_DSN`
on the public read Worker too (`npx wrangler secret put <NAME> --config wrangler.public.jsonc`) for
its errors to be reported.

### Deploy

```bash
npm run deploy   # admin UI (Pages), admin Worker, and the public read Worker
npm run health   # post-deploy checks; with Access on, also checks the perimeter
```

`deploy` builds the admin UI with `PUBLIC_BACKEND_URL` set, in the build's environment, to the
`FRONTEND_URL` from `backend/wrangler.jsonc`. It needs no `frontend/.env`. It refuses to ship the
admin Worker while the database has pending migrations, or when it cannot tell — apply them with
`npm run migrate:d1` first, or pass `--skip-migration-check` when you know the new code does not
need them.

Upgrading to a newer release (pull, reinstall, migrate, deploy) is described step by step in
[Installing Dee Wan](/guides/installation/#upgrading).

### Migrations

A fresh install needs none of this — `setup` applies the schema. Afterwards:

| Command | Applies to |
| --- | --- |
| `npm run migrate:d1` | The deployed control database. |
| `npm run tenant:upgrade` | Per-site databases created by `provision:site`. |
| `npm run local:migrate` | The local rig's database (`backend/wrangler.dev.jsonc`). Works on any clone. |
| `npm run migrate:d1:local` | The local mirror of an installed configuration. Reads `backend/wrangler.jsonc`, so it fails on a clone that was never installed. |

Migrations are Prisma migrations under `backend/prisma/migrations/`, mirrored into
`backend/migrations-wrangler/` for D1 by `npm run migrate:sync` (`npm run migrate:check` verifies
the mirror). `schema.prisma` is assembled from fragment files. Edit the fragments. Applying never
writes a migration. Authoring one is a separate, explicit step. See
[Database migrations](/guides/database-migrations/) for the full workflow.

## Inference provider

DeepInfra remains the default. To use another OpenAI-compatible provider, set these deployment
variables and store its key with `wrangler secret put AI_API_KEY` from `backend/`:

| Variable | Value |
| --- | --- |
| `AI_PROVIDER` | `openai-compatible` |
| `AI_BASE_URL` | Provider API base, such as `https://inference.example/v1`; no credentials, query or fragment |
| `AI_TEXT_MODEL` | Default chat model, also used by translation and structured generation |
| `AI_VISION_MODEL` | Optional model accepting image input for media descriptions |
| `AI_IMAGE_MODEL` | Optional image-generation model; without it image generation is unavailable |
| `AI_TEXT_MODELS`, `AI_VISION_MODELS`, `AI_IMAGE_MODELS` | Optional comma-separated additional model IDs for each picker; at most 100 per capability, including its default |

The compatible-provider picker uses this reviewed configuration instead of inferring model
capabilities from arbitrary provider listings. Prices are unknown and are not invented. Use exact
IDs your provider serves. Compatible image generation requests inline `b64_json`; providers that
only return hosted image URLs are not supported by this connection. HTTPS is required except on
localhost during local development. No client request can change the provider endpoint or key.

Settings → Generation chooses among the configured models. Provider keys remain Worker secrets;
they never enter site settings, browser requests or generated output. The existing per-site quota,
review-before-apply flow and error handling apply to both connections. Switching providers does not
rewrite saved model choices: update those choices to IDs served by the new connection.

## Bringing content in, and taking it out

Both are in the admin under **Settings → Data transfer** — no terminal, no JSON editing.

- **In**: a Strapi export archive (`.tar` / `.tar.gz`, tested with Strapi 4.25.9 and 5.51.1), or a
  **Dee Wan site copy** (`.json`) exported from another installation. The wizard inspects the
  archive, shows what it found, maps types and languages, checks the plan, then runs it. Nothing is
  overwritten: an import creates content or skips it, and the whole job can be undone.
- **Out**: **Download site copy** writes one file with the site's models, fields, languages,
  workflows, settings, current content, the published version wherever it differs, and the exact
  bytes of every image. If any image cannot be read exactly from R2 or Cloudflare Images, the
  download is refused by name instead of writing a partial copy.
- **Spreadsheets** update rows that already exist, starting from the content list of one model.

![Import wizard, Source: Strapi export file, Dee Wan site copy, and the two disabled sources](/assets/screenshots/import-source.webp)

![Import wizard, Review: counts found in the archive and one row per source type it will create](/assets/screenshots/import-review.webp)

![Import wizard, Check: the verdict "Can import" above the list of findings](/assets/screenshots/import-check.webp)

![Import wizard, Run: Start importing, Pause and Cancel, before the run starts](/assets/screenshots/import-run.webp)

![Import wizard, Done: imported, skipped, failed and not-run counts per source type](/assets/screenshots/import-done.webp)

Archive import needs a private `IMPORT_BUCKET`. `npm run setup` offers to create it, and
`npm run doctor` reports whether it is enabled. Everything else works without it. Import is
implemented but not yet complete for 1.0. See the [1.0 product boundary](/boundary/).

## Signing in, and getting back in

Public registration is closed; accounts are created through authorized provisioning. With mail
configured, existing users can request a password-reset link from the sign-in screen. Passwords
are set by their owner through a single-use link, never chosen by whoever sent it.

Every link below is **single-use, expires in 15 minutes, and is shown exactly once**. Only its hash
is stored, so nothing can print it again. Minting another invalidates the first. Passwords must be
at least 12 characters.

### Claiming a new installation

The installer prints a claim link at the end of a fresh install. Open it and choose any configured
password, magic-link, Google or GitHub method. Every method must prove the exact normalized address
from `BOOTSTRAP_ADMIN_EMAIL`. The claim page cannot replace it. After signing in, the owner can change the account email
through Account security by verifying the new address.

If the link expires unused, run the installer again (`npm run setup`, or
`npm run install:cms -- resume`). It mints a new one as long as nobody has claimed the installation.
For an unclaimed installation, replace a lost or expired link explicitly:

```bash
npm run claim:link -- --remote --bootstrap --email owner@example.com
```

Without `--bootstrap`, `npm run claim:link` gives an existing sole active superadmin account back to
its owner and refuses when there is none. See
[Create and replace the first administrator](/guides/first-administrator/).

### Someone forgot their password

A superadmin generates a link from the **People** list. With mail configured (`RESEND_API_KEY` and
`MAIL_FROM`) it is also emailed. Either way it is shown once to the superadmin to deliver however
they like.

### The last superadmin is locked out

This is the one case nobody else can fix, so it needs deployment credentials:

```bash
npm run claim:link -- --remote --email locked-out@example.com
```

It refuses unless that address is the **only** active superadmin. If there are two, the other one
should mint a link from the People list instead.

### Your own account

Every signed-in user can open **Account security** from the identity menu to change the admin
language, unlink their own Google or GitHub connection and manage their passkeys. See
[Account security](/guides/first-administrator/#account-security).

## Development

```bash
cd backend  && npm test              # backend unit tests (Vitest, local SQLite)
cd frontend && npm test -- --run     # admin UI unit tests (Vitest, single run)
cd frontend && npm run check         # admin UI type check
npm run lint                         # lint the backend and scripts
npm run typecheck:scripts            # type check scripts/
npm run submodules:check             # fail if a submodule pin or worktree has drifted
```

To run the local admin Worker from an installed `backend/wrangler.jsonc` instead of the tracked dev
config, use `npm run dev:install --workspace backend`.

### Commands

Installing and operating:

| Command | What it does |
| --- | --- |
| `npm run doctor` | Read-only preflight: names what is missing and how to fix it. |
| `npm run plan` | Read-only: every install step and its state, from files on disk. `-- --json` for machines. |
| `npm run setup` | Interactive install: provisions, applies the schema, builds and deploys everything, prints a claim link. |
| `npm run install:cms -- <verb>` | The installer by verb: `plan`, `apply`, `resume`, `doctor`, `verify`, `teardown`, `manifest`. |
| `npm run install:web` | The web installer on `127.0.0.1`. Not a supported install path: it needs your own Cloudflare OAuth application (`DEEWAN_CF_OAUTH_CLIENT_ID`). See [Web installer preview](/guides/web-installer-preview/). |
| `npm run install:web:dry-run` | The web installer with every external effect faked, for review. Changes no external resources. |
| `npm run deploy` | Builds and deploys the admin UI and both Workers. `--config`, `--public-config`, `--admin-only`, `--skip-migration-check`. |
| `npm run health` | Post-deploy checks against the deployed addresses. |
| `npm run probe` | Anonymous, read-only reachability check. |
| `npm run verify -- --read-only --public <url>` | Post-deploy check that writes nothing. `--model <slug>` reads one model. |
| `npm run verify -- --admin <url> --public <url> --email <addr> --disposable` | Full check on a **disposable** deployment: creates a site, a model and content. Needs `VERIFY_PASSWORD`. |
| `npm run migrate:d1` | Applies pending migrations to the deployed control database. |
| `npm run migrate:d1:local` | The same, to the local mirror of an installed configuration. |
| `npm run provision:site -- --site <id>` | Gives one site its own D1 database and redeploys both Workers. `--plan` to preview, `--repair` to re-check. Billable. |
| `npm run tenant:upgrade` | Applies pending per-site schema changes to every active per-site database. `--plan`, `--site <id>`. |
| `npm run claim:link` | Mints a single-use password link for the sole active superadmin. Add `--bootstrap` to replace the first-admin claim on an unclaimed installation. |
| `npm run revoke:sessions` | Break-glass: signs everybody out. |
| `npm run teardown` | Deletes what setup recorded as created by an installation, default `backend/wrangler.jsonc` and its public and intake configs. Dry run unless `--apply`. Keeps adopted, changed and unreadable resources. See [Starting over or tearing down](/guides/installation/#starting-over-or-tearing-down). |
| `npm run backend:generate -- --site <id> --source <cms.sqlite> --dest <dir> --db <scratch.sqlite>` | Generates a standalone backend locally from a SQLite copy of the CMS database. Deploys nothing. A site with an active managed renderer release also needs `--template-artifacts <dir>`, a local copy of that release's template artifacts; it is exported to `managed-renderer/`. |
| `npm run backend:generate:all` | The same for every site. Deploys nothing. It cannot pass `--template-artifacts`, so a site with an active managed renderer release refuses there. Run `npm run backend:generate` for that site alone, with `--template-artifacts <dir>`. |
| `npm run template-build-service` | Runs the managed-template build and preview service on a build host. Every build and preview runs in a fresh container of the digest-pinned sandbox image. It refuses to start unless it has a build or preview key of at least 32 characters, a `TEMPLATE_SERVICE_AUDIENCE` origin and a valid value for every `TEMPLATE_SANDBOX_*` setting, and it refuses to run as root. It serves plain HTTP on `TEMPLATE_SERVICE_HOST:TEMPLATE_SERVICE_PORT` (default `127.0.0.1:8790`) and runs one operation at a time. The admin calls only `https://` origins (or `http://` on loopback), so a remote host needs TLS in front of it. Holds no deployment credential. Deploys nothing. See `docs/MANAGED-TEMPLATES.md`. |
| `npm run template-sandbox:context -- --out <dir> --node-image <node@sha256:…>` | Writes the build context of the template sandbox image. `--out` must be a new or empty directory, and `--node-image` must name its image by digest. It reads the npm, Wrangler, playwright-core and axe-core versions from this checkout, so install dependencies first. Builds, pulls and pushes nothing. |
| `npm run managed-deploy-service` | Runs the managed renderer deployment service on a trusted host. It holds the Cloudflare API token that uploads, deploys and routes each site's renderer Worker; the admin Worker never holds one. It also reads each renderer's identity for the admin to check. It refuses to start when a required setting is missing or invalid. See `docs/MANAGED-TEMPLATES.md`. |
| `npm run wire:github -- --repo <owner/name>` | Pushes a generated project to GitHub and seals the secrets its build workflow reads. |
| `npm run backend:deliver -- --site <id> --repo <owner/name> --source <cms.db> --dest <dir> --db <target.db>` | Hands a site over as your own repository and deploys it there. `--media` also moves published media into your R2. Accepts `--template-artifacts <dir>` like `backend:generate`. It does not deploy the managed renderer. |
| `curl -H "X-Site-Id: <id>" -b "<session>" <admin>/api/models/public-client.ts` | Downloads a typed, dependency-free TypeScript client for a site's public read API. |

Local rig:

| Command | What it does |
| --- | --- |
| `npm run local:migrate` | Applies the schema to the local database. No credential. |
| `npm run local:api` | Admin Worker on `http://localhost:8787`. |
| `npm run local:public` | Public read Worker on `http://127.0.0.1:8788`. |
| `npm run local:seed` | Fixture site plus the realistic corpus. Idempotent. |
| `npm run local:seed:fixture` | The fixture site only. |
| `npm run local:seed:corpus` | The corpus only. |
| `npm run local:admin` | Admin UI on `http://localhost:5173` against the local Worker. |

Contributors:

| Command | What it does |
| --- | --- |
| `npm run test:boot` | Starts both Workers under the pinned runtime and fails if either refuses to boot. |
| `npm run test:e2e` | Browser end-to-end suite (Cypress) against a dev server it starts. `E2E_REAL_BACKEND=1` adds real Workers. The full-screen editor spec then also gets the emitted Astro renderer on `E2E_EDITOR_PORT` (default 43189). Its first build needs the npm registry. The Scheduling release spec also gets the Scheduling plugin on `E2E_PLUGIN_PORT` (default 43190). |
| `npm run migrate:sync` | Regenerates `backend/migrations-wrangler/` from the Prisma migrations. |
| `npm run migrate:check` | Fails if that mirror is out of date. |
| `npm run prisma:generate` | Rebuilds `schema.prisma` from its fragments and regenerates the Prisma client. |
| `npm run prisma:drift` | Fails if `schema.prisma` no longer describes what the migrations build. |
| `npm run tenant:schema` | Regenerates the schema new per-site databases start from. |
| `npm run tenant:schema:check` | Fails if that schema is out of date. |
| `npm run docs:api` | Regenerates `docs/PUBLIC-API.md`. |
| `npm run docs:plugins` | Regenerates the plugin protocol document and JSON Schemas. |
| `npm run contract:embed` | Regenerates the embedded page contract after editing `backend/src/lib/page-contract/`. |
| `npm run submodules:sync` | Initialises or updates the `packages/` submodules. |
| `npm run submodules:check` | Fails when a submodule pin or worktree has drifted. |
| `npm run lint` | Lints the backend and scripts. |
| `npm run typecheck:scripts` | Type checks `scripts/`. |
| `npm run test:scripts-offline` | Runs the offline checks of the emitted deployment and auth code under Node's type stripping. |
| `npm run guard-editor:check` | Type checks the guard editor package and its contract with the CMS. |
| `npm run guard-editor:test` | Runs the guard editor package's tests and its contract check. |
| `npm run test:guard-editor-contract` | Builds the guard editor core and runs only its contract check. CI runs this. |
| `npm run acceptance -- plan` | Prints the release acceptance journey. Runs nothing. |
| `npm run acceptance -- run --account <id> --confirm-disposable` | Runs that journey against a **disposable** Cloudflare account and records a ledger. Creates billable resources and leaves them. |
| `npm run acceptance -- report --account <id>` | Prints that ledger. |
| `npm run public:query-probe -- --confirm-disposable …` | Exercises public API filters against a **disposable** deployment, then restores what it changed. Never point it at production. |

## Contributing

Pull requests are welcome. Two conventions:

- `packages/` are submodules — commit and push there first, then bump the pointer.
- Site-scoped routes must go through the site-scoped data layer, which adds the site to every query.
  Bypassing it is how one site's data leaks into another's.

## Running the installer against a shared account

The default resource names (`dee-wan-cms-backend`, `dee-wan-cms-db` and so on) are fixed, so two
installations in one Cloudflare account collide by name.

Set `DEEWAN_RESOURCE_PREFIX` to namespace everything a run provisions:

```bash
DEEWAN_RESOURCE_PREFIX=test-a1b2 npm run setup      # creates test-a1b2-dee-wan-cms-db, …
```

The prefix must contain only lowercase letters, digits and dashes and be at most 24 characters long. Teardown does not
decide by name: it deletes only what the install record says this installation created. See
[Starting over or tearing down](/guides/installation/#starting-over-or-tearing-down).

**Set it for a fresh install, not an existing one.** Wrangler finds the D1 database by the name in
`backend/wrangler.jsonc`, so the prefix works only once `setup` has written the prefixed names into
that file. Turning it on against an install whose config holds unprefixed names makes every command
fail with `Couldn't find a D1 DB with the name or binding '<prefix>-…'`. To move an existing
install under a prefix, re-run `setup`.

## Deployment smoke test

A short check against a live deployment, for after every deploy:

```bash
DEEWAN_SMOKE_PAGES=https://admin.example.com \
DEEWAN_SMOKE_HOST=https://cms.example.com \
npm run smoke --workspace=dee-wan-cms-backend
```

Replace both addresses with your own admin UI and admin API origins. It needs no session and checks
two things:

- the admin UI serves the app for **deep links**, not just `/` — a broken `_routes.json` breaks
  those first, and nobody notices while navigating from the home page.
- with Access on, `/api/*` on the public hostname is **behind Access**. With Access off (the
  default) the API is protected by sign-in instead, and this check does not apply.

With no addresses supplied it skips rather than fails.

## License

MIT. Copyright (c) 2026. The complete text is in [`LICENSE`](/license/).

Built in Thailand 🇹🇭 for the global edge

<!-- dee-wan-docs page: /reference/release-notes/ -->

# Release notes

Source: https://dee-wan-docs.pages.dev/reference/release-notes/

Changes that affect operators and site developers, newest first.

## How changes are recorded

- Dee Wan has not had a release yet. Everything below is under **Unreleased**. A released version
  gets its own heading with its version and date.
- Any change that removes or changes behaviour someone outside this repository could rely on gets
  an entry here, even if we believe nobody relies on it.
- The public read API is versioned in its path (`/v1/`). Within `v1`, documented paths, parameters,
  status codes and response keys keep their meaning. See
  [What is stable](/reference/public-api/#what-is-stable-and-what-is-not). A breaking change to it ships under
  a new path version.
- Page documents carry a `format` number. A change in how existing documents are read gets a new
  format number. See the [page-document contract](/reference/page-contract/#compatibility).

---

## Unreleased

### Added: coordinated authoring and consumer delivery

Draft saves now defer empty required fields by default; publication still requires complete values. Choose strict **Draft validation** on a model to require complete saves. CSV/XLSX imports add Create and Upsert beside Update. Project labels can follow the admin language without changing stored keys or option values.

Editorial work gains locale owners, required review tasks, field threads with replies and mentions, retained batch AI proposals, and separately editable future versions tied to releases. Native lists can filter and sort by related display values. Model promotion reviews selected definition changes between sites.

Media gains language-specific originals with retained version pins. Sites can explicitly grant other sites access to published shared content. Point fields support spatial queries; zoned datetimes retain their IANA timezone. Consumers can resume incremental reads through `GET /v1/_sync`, including deletion records and explicit checkpoint resets. See [content editing](/guides/content-editing/), [models and fields](/reference/models-and-fields/), [media](/guides/media/), [sites](/guides/sites/) and [public API](/reference/public-api/).

Management API additions use minor contract `1.12.0`. Schema changes remain in the initial migration before the first release. Final integrated acceptance and the paused external-provider work remain release requirements.

### Added: integration and editorial completion

The source adds lifecycle, workflow, release, media and model webhook events; one atomic same-site publication command; multi-model links inside components; plugin workspaces and dashboard placements; retained form-submission details and per-form notifications; a direct Media workspace with custom asset fields; and collection-wide manual ordering.

Plugins can use the existing moderation, redirect, Trash, eligible media-deletion and approved-template mail services. Versioned renderer metadata, structured inline elements and published hierarchy breadcrumbs share the existing content and rendering paths. `npm run reference:starter -- --out <directory> --config <file>` emits the maintained live-API Astro starter.

These changes are unreleased. Focused verification, the complete browser gate, live mobile/desktop review and real-provider release acceptance remain pending. The new schema belongs to the initial migration; no incremental migration is provided before the first release.

Native forms also gain private file attachments with field-level type, count and size limits, retained-submission downloads and erasure cleanup. Approved plugin email templates can resolve the recipient from an authorized entry’s author or assigned reviewer. Both additions reuse the existing services and remain pending final acceptance.

### Added: October account, editorial, plugin and migration source changes

Current source supports AND/OR groups in content-list filters and contextual choices for relation and select fields. Reviewed CSV/XLSX updates can change existing entries using JSON cells for relations, media and components. Core role rules restrict access by entry. Rich text supports alignment, relation controls, repeatable plugin groups and isolated HTML/CSS/JavaScript vendor snippets. Plugins support delegated CRUD, version and media operations, reviewed upgrades and isolated custom UI.

Account security verifies a new mailbox before changing the same account's email, keeps memberships, credentials and history, and ends sessions. Sign-in offers self-service password reset when mail is configured, with the same response for known and unknown addresses. AI suggestions for alt text and captions require review. To update translations when saving the source, users must select the target languages and explicitly consent to replacing their text. Connected WordPress REST acquisition produces ordinary WXR and supports explicit, revision-bound replacement of title, tagline, logo, icon, SEO description and supplied indexability through import receipts and undo.

Native site bundles now use format 1.16 and history files 3.1, including entry-folder trees and placements; history also carries placement events. Current readers require these formats and `entry-folders.json`; export older files again from a matching source.

Focused local checks exist. Final browser integration and live visual review are pending, entry-folder source still awaits final integration acceptance, and no deployment or real-provider acceptance is claimed. See the [capability matrix](/reference/capability-matrix/).

### Changed: site search finds linked items by their published names only

Site search and suggestions find an item by the names of the items it links to only while those
items are published, public and not in Trash, under their published names. A name saved from a
draft is never searched or shown, and a result's summary holds no linked names. See
[Linked items](/guides/search/#linked-items).

### Changed: each spreadsheet sheet carries its own address

The `slug` column on each sheet of an exported workbook is now that language's own address. Before,
every sheet carried the primary language's address, so an untouched workbook of an item with
different addresses per language was blocked with `spreadsheet_slug_mismatch`. Export such
workbooks again. The check also blocks a change in a language the role may read but not change
(`locale_denied`) and values typed into a language the item has no translation in
(`spreadsheet_locale_missing`). See [Spreadsheet round trip](/guides/content-editing/#spreadsheet-round-trip).

### Changed: site administrators can reactivate a site

`GET /api/sites` also lists an inactive site to a person whose role there holds `site:settings`, and
the admin offers them **Reactivate**. Before, only a superadmin saw an inactive site. Editors,
viewers and people without a grant still do not see it, and content work on an inactive site stays
refused. See [Reactivate a site](/guides/sites/#reactivate-a-site).

### Changed: a field key that kept versions still hold cannot be reused

A model or component save that gives a key a new field while kept versions still hold a value under
it is refused: `409 model_change_blocked` with a `retained_key_reuse` change, or
`409 retained_key_reuse` for a component. Choose another key. A component created or forked under a
slug the site already reads is judged the same way, against the definition the slug read before.
Confirming the override does not lift the refusal. On a per-site deployment a shared component
change that would read stored values another way, or add a field while content uses the component,
is refused with `409 split_topology_reinterpretation_unsupported`. Carried history and a language
put back from Trash wait for a component change that holds their content type, like a save. An
import refuses an entry or carried version whose value sits under a key a field took after the
import's check (`409 import_definition_changed`); give that field another key, then continue. A
site copy or history file is also judged against the source's own definitions: a value under a key
the source did not define, which a field here would read, blocks the check (`unmapped_source_key`),
whether that field was here before the check or came after it. Give that field another key, then
choose **Check again**. A value the source keeps private is refused where this site's field is
public (`source_private_value`); make that field private. A value under a key the destination will
not have is refused at the check (`unsupported_source_key`) instead of failing the run with
`unknown_fields`. See [Private fields](/reference/models-and-fields/#private-fields).

### Changed: shared-draft answers follow read access

Read access to a shared draft is decided apart from write access. A person who may change an item
but not read that row or language gets no draft back: `current: null` on `409 draft_conflict`, and
`draft: null` from a management take over. A discard refused after a take over says
**Not discarded — taken over. Your work is kept.** See [Shared draft](/guides/content-editing/#shared-draft).

### Changed: access sign-in rules check the role ceiling at commit

Saving a Cloudflare Access sign-in rule saves nothing when the mapped role or the saver's own access
changed during the save. The answer is `403 escalation_refused` or `403 missing_permission` when the
rule is now out of reach, otherwise `409 access_authority_changed`. See
[Sign in through Cloudflare Access](/guides/people-and-access/#sign-in-through-cloudflare-access).

### Changed: mail sends give up after 10 seconds

Every mail the CMS sends, form deliveries included, gives up after 10 seconds without an answer and
counts as failed. Each form delivery is claimed just before its own send. See
[Email delivery](/guides/website-forms/#email-delivery).

### Changed: deleting a model needs `model:delete`

`DELETE /api/models/:id` needs the `model:delete` permission instead of `model:apply`. A role that
holds only `model:apply` can no longer delete a model. Refusals, cleanup, audit and site isolation
are unchanged.

### Changed: a page needs an address before it is published

Publishing a page-model item without an address answers **409** `page_address_required` and
publishes nothing. Publishing claims the address in the same write, so an address another item
holds answers `slug_reserved` and nothing is published. `POST /api/pages/:id/address` sets or
changes a page's address in a new draft version. The live page keeps its address until that version
is published, and the publication adds a redirect from the old address. See
[Build and edit pages](/guides/page-builder/#page-address).

### Changed: a repeated save key replays only for the same person

A content save that repeats an idempotency key is replayed only to the person who made it. Another
person's matching key and body answers **409** `idempotency_key_reused` and writes nothing.

### Removed: the Blog System preset

The model builder no longer offers the Blog System preset. A Blog is a site purpose with its own
starter. See [Blog sites](/guides/blog/).

### Moved: the Error reports switch

The switch for reports to Dee Wan is now under **Installation** → **Error reports**. It was under
**Settings** → **Integrations**.

### 2026-09-19 — documentation and delivery contract update

This entry describes source changes, not a released version or an accepted Cloudflare deployment. The documentation banner identifies the exact source revision and build date. Its upgrade target is that revision only for a clean checkout. A modified checkout is not a reproducible upgrade target.

**Operator action:** use the [GitHub workflow matrix](/guides/github-authentication/) before changing credentials. Verify `ACCESS_CONFIG` and complete the [detachment runbook](/guides/detachment/) before removing CMS dependencies. Replace upsert-only external search with the [complete-generation contract](/guides/search/).

**Plugin action:** reject out-of-range limits and duplicate capabilities. Validate URL formats and semantic origin/grant constraints. Align command retries with [Protocol v1](/plugins/protocol-v1/): structured mismatches are terminal, bare transient statuses can retry, and recovered requests reuse their key. Install both root and frontend dependencies for local integration.

**Documentation:** task-based navigation adds first publication, fields, accounts, migration, backups, webhooks, preview/client and detachment guidance in English, Russian and Thai. Builds require current translation hashes, locale-correct screenshot references and source provenance. Translated pages omit admin screenshots where the admin UI has no real locale support. Genuine localized installer captures remain published.

**Authentication source change:** a fresh installation can create its first superadmin with password, magic link, Google or GitHub. Every method proves the one normalized `BOOTSTRAP_ADMIN_EMAIL`. Ordinary sign-in remains closed to account creation. Provider callbacks cannot rewrite canonical account email; the verified owner flow described above now permits an explicit change, same-email verified providers link to one account, a replacement superadmin is promoted with guards on its Settings → People row, and the old one is deactivated on the Installation page under Superadmins. These are source changes, not evidence of a released or deployed build.

### Removed: permission templates

`GET`, `POST`, `PATCH` and `DELETE` on `/api/permission_template` and
`/api/permission_template/:id` now return **404** for every caller. No permission brings the route
back.

The `permission_template` table is gone from the initial database schema. It stored per-model
permission templates that nothing read: access comes from a site's roles. Express
permissions as roles instead, under **Settings → Roles**.

Because Dee Wan has not been released, no deployed database holds this table. A local database
created from an earlier development schema still has it. Recreate that database from the current
schema.

### Removed: legacy media MIME repair

The `doctor` and `setup` check that counted media rows without a MIME type, and the repair scripts
behind it, are removed. Every write path records a verified MIME type, and no earlier version wrote
rows without one.

### Changed: `npm run doctor` checks the `DB` binding

`npm run doctor` reports a missing or blank `DB` D1 binding in its own row, `D1 binding (DB)`.

<!-- dee-wan-docs page: /boundary/ -->

# 1.0 product boundary

Source: https://dee-wan-docs.pages.dev/boundary/

Status: **Pre-release. Dee Wan has not been released.** Last updated: 2026-10-17.

This page lists what Dee Wan does today and how far each part has been proven. The established "1.0 contract" has local automated coverage. The October source additions below have focused checks; final browser integration and visual acceptance remain pending. No complete
acceptance run on a real Cloudflare account exists yet.

Dee Wan is a headless CMS for defining and operating structured content. It can also generate a
standalone backend that you own: a normalized Prisma schema, reviewable migrations, generated routes
with familiar Prisma model and query semantics, and the published content, in a repository, database
and runtime of your own. The generated backend reads normal tables and does not depend on Dee Wan at
runtime.

Cloudflare is the current platform. Strapi archives, WordPress exports and bounded connected WordPress REST acquisition are the import sources.
Import helps you move in and out. It is not the point of the product.

Each capability is in exactly one list: 1.0 contract, supervised pilot, or later/unavailable.
"Unavailable" is not a promise to build it.

## 1.0 contract: built and verified locally

### Content operations

- Content models and fields defined in the UI: text, rich text, number, boolean, select, date,
  media, JSON, relation, component and point.
- Breaking-change checks before a model change is applied.
- Multilingual content with configurable languages and a strict or fallback locale policy.
- Immutable published snapshots, version history, restore, publish and unpublish. Restore can cover one language: only that language's translatable values, its own relation lists, its draft address and its SEO overrides change; shared fields, shared relations and media stay. It needs `restore` for that language.
- Direct publishing, or an approval workflow.
- **Optional review mode**, off by default, set per site under Settings → Workflow.
  - It cannot be turned off while content is waiting for review. The refusal names the items.
  - With review on, the dashboard is the review queue: what is waiting, what you may do next, what
    a row you cannot move is waiting on, and what was sent back.
  - With review off, the dashboard shows recent changes.
  - Switching it does not rewrite any workflow definition, so a customised workflow comes back
    unchanged.
- **Editing ownership and unsaved-work recovery** for ordinary content editing and the page
  composer.
  - One editor at a time holds an entry and language. Others read along and can take over in one
    action; the previous holder's saves are refused from then on and their unsaved typing is kept as
    their own recovery draft.
  - An existing entry's unsaved edit autosaves as one shared draft per entry and language, with
    the server version it started from. Reloading, or opening it on another device or as another
    person who may read it, shows it. One made on an older version is compared before it is restored,
    so it never overwrites someone else's save.
  - A new item's unsaved edit is kept as that person's own draft and offered back.
  - It survives a crashed tab, a reload, a discarded tab and a closed browser. A leave warning
    covers deliberate navigation.
  - The browser keeps a copy until the server has it, so an offline or failed write loses nothing.
  - When another device replaced the draft, the editor asks which one to keep.
  - A draft is kept for 30 days after its last change.
  - The page composer shares its change-set the same way, per page and language. An unapplied AI
    proposal stays the person's own.
- **Components**, owned by a site or shared.
  - A site can own components. A shared library is readable by every site and editable only by a
    superadmin. Two sites may each own a component with the same slug.
  - A site can fork a shared component. The fork overrides the shared one for the whole site: every
    field that names that slug uses the fork from then on. The UI states how many references move
    before you confirm.
  - Creating a site component with a shared component's slug is refused until you confirm the
    override. Confirming does not let it expose a key whose retained values belonged to a private field in the shared
    component (`retained_key_reuse`).
  - Field-list edits automatically retain the previous definition. Existing pins keep their values until an explicit **Update component**. Retired types cannot be added or duplicated; existing instances stay editable.
  - On a deployment with separate site databases, shared field-list and retirement changes are refused (`split_topology_migration_unsupported`). Name-only edits remain available. Fork for the site before changing fields. See [private fields](/reference/models-and-fields/#private-fields).
  - A component's slug cannot change after creation, because fields and other components refer to
    it by slug. Its name can change.
  - Fork warnings and the delete guard count references from model fields and from other
    components.
  - Strapi components and dynamic zones import as components the site owns. See
    [import and migration](/guides/import-migration/#strapi-components-dynamic-zones-and-single-types).
- **Single-entry models**, for one-of-a-kind content such as a home page or site settings. A second
  entry is refused (`single_entry_exists`) on every path that creates one; an entry in Trash still
  holds the place. A Strapi single type imports as one. See
  [single-entry models](/reference/models-and-fields/#single-entry-models).
- Per-site roles and permissions.
- **Saved content-list views**: personal and shared views, configurable columns and their order,
  personal and site defaults. Views preserve stage, delivery and saved-text search filters, field
  conditions and one sort. See [saved views](/guides/content-editing/#saved-views).
- **Field filters and sorting on the content list**: up to four conditions in AND/OR groups, three levels deep, for one model. Scalar fields, relation membership/empty checks and configured same-site relation display fields use current saved values, including drafts. Sort by one scalar field or the display field of a single-valued, single-target relation. Point fields support radius, bounding-box and nearest queries. Counts, pages, views and all-matching selections share the same access checks and SQL plan. Rich text, media, component and JSON fields cannot be filtered or sorted. See [filter and sort by fields](/guides/content-editing/#filter-and-sort-by-fields).
- **Bulk actions on the content list**: move to a workflow stage, publish or unpublish by override,
  and move to Trash. Explicit-row actions handle up to 25 items; select all matching handles up to
  5,000 items across pages, with exclusions, in steps of at most 25. Scalar field editing is available
  for matching selections of one model. In Trash: restore, or delete for good on explicit rows.
  - Every item is checked on its own: role grants, `:own` ownership, workflow permission, its
    workflow revision when one is sent, and its own reviewed dependents when it goes offline. One
    refusal does not stop the rest. Results come back in the order sent.
  - A retry with the same key never applies an item twice, even after a request that stopped
    part-way. A key is bound to the person who used it.
  - Filter-wide selection is fixed when the operation starts. Current access and revisions are checked
    again for each item. Results distinguish changed, unchanged, refused and conflicting items. See
    [change many items](/guides/content-editing/#change-many-items-at-once).
- **Reviewer assignment**: a whole-entry assignee, independent locale owners and due dates. Editorial tasks have their own owner, optional language, due date and revision. Required tasks block affected publication until completed against the reviewed version; unrelated-language edits preserve locale approval. The review queue can show your workflow assignments. No automatic reminders.
- **Review feedback and notifications**: version- and language-bound field threads, replies, user/team mentions and resolve/reopen. Current field, language and recipient access are checked. In-admin notices cover assignments, review requests and returns for changes; mail is optional. Editor, management API and plugin commands share these paths. Imports are quiet unless notifications are selected; carried history never notifies. Models can use named workflows with the site workflow as fallback. See [feedback and notifications](/guides/content-editing/#feedback-and-notifications).
- **Crop and focal point per media reference**, stored as fractions of the image. The stored bytes
  never change.
  - Each use has its own framing: the same image twice in one field, each component value and
    each page-section slot.
  - A published version keeps its framing. Replacing the file keeps the framing and warns when the
    new image has a different shape. A default focal point applies to new uses only.
  - The public API and generation carry the framing. Generated sites and the managed renderer serve
    resized, cropped copies through Cloudflare Image Transformations on hosts the owner declares,
    and the original image with CSS framing elsewhere.
- **Relation writes** replace a field's ordered list, or `connect` and `disconnect` single items.
  A `connect` item may carry a position (`before` or `after` an id, or `start` or `end`), and a `move`
  list repositions items already related. They apply in order: disconnect, connect, move.
  Each written list is checked: the target exists in the site, is of the field's target model, is
  readable by the writer (`:own` included), appears once, and a to-one field holds one target. A
  missing target and an unreadable one are refused the same way.
- Field validation checks supplied types, structure, bounds, uniqueness and references on Save. By default, drafts may omit required values; optional strict mode also requires completeness on Save. Publication validates the exact snapshot, including required values.
- Page composition into a framework-neutral structured document (see the
  [page-document contract](/reference/page-contract/)). Page revisions use normal versioning, publishing and
  rollback. The admin does not serve your public website: the generated website, the managed
  template or your own front end draws its pages.
- **Search and sharing, sitemap and redirects.** See
  [Search and sharing](/guides/page-builder/#search-and-sharing) and [Redirects](/guides/page-builder/#redirects).
  - Each language of an entry or page can set a search title, a description, a social image, a
    canonical address, "hide from search engines" and a page type. They are saved in the version and
    served from the published version only. Nothing is filled in from the page's text or images.
  - Site Chrome holds the defaults, who runs the site, search-engine verification codes, the sitemap
    and robots policy, and redirects: up to 256 exact addresses and 32 patterns, answering 301, 302,
    307, 308, 410 or 451.
  - One redirect service refuses loops, ambiguous patterns, and reserved or live addresses. A changed
    pattern needs a review of the live pages it covers.
  - A publication that moves a live address adds and accepts a permanent redirect from the old one.
    When no redirect can be made, the publication still succeeds and the editor says why. Publishing
    at an address a redirect holds is refused by name.
  - The public API serves each item's `seo`, the accepted redirects (`GET /v1/_redirects`) and the
    sitemap data (`GET /v1/_sitemap`). The generated website writes the head tags, structured data,
    `hreflang` alternates, `/sitemap.xml` (an index of 5,000-address chunks with images) and
    `/robots.txt`. Its redirects and page sitemap chunks are fixed when it is generated; a Blog's
    post chunks are read live. Your own front end reads the same data and draws it itself.

### Standalone backend

- The admin API endpoint `GET /api/models/public-client.ts` generates a dependency-free TypeScript
  client for one site: exact model fields, the locale union, query types, the response envelope and
  one method per model. The file records the schema identity it was generated from. The
  `dee-wan-client.mjs` command from Settings → API refreshes it with a site API token and, before a
  deploy, exits non-zero on a breaking schema change. It is a script you commit, not a runtime
  dependency.
- Generating a standalone backend produces a typed backend you own and a snapshot of the content
  published at that moment. Its API does not call Dee Wan at runtime; Blog, search, Latest entries,
  comments and forms on its website still do (see the
  [detachment contract](/detachment-contract/#what-still-depends-on-dee-wan)). Its API accepts
  `API_BEARER_TOKEN`, `ACCESS_CONFIG` read tokens and optional standalone sessions.
- Regeneration managed from the CMS pulls model definitions and reports the result back to Dee
  Wan. Building and running the backend are separate from that reporting.
- Read tokens for a generated backend, issued from the CMS per model (never `*`), shown once and
  delivered as digests on the next regeneration and deploy. Revoking takes effect only after that
  regeneration and deploy. Relation writes in a generated backend check that a to-one target
  exists.

- **A generation-readiness scan.** Settings → Source & delivery lists model-level refusals
  before a build, and can also walk the published content and list what a build would refuse,
  one bounded page at a time. The build itself stays the authority on site-wide conflicts.

### Sites, accounts and access

- Many sites in one installation, each request scoped to one site. A caller cannot choose another
  site's data or database.
- Sites sharing one database are isolated from each other in code.
- Database-backed sessions, a one-time claim link for the first administrator, password ownership,
  recovery, session revocation, lockout and request limits.
- An optional Cloudflare Access perimeter, off by default.
- Existing accounts can be granted access to individual sites. Invitations are a supervised pilot,
  below.

### Public read API

- A separate public Worker serves each site's published content on the site's own hostname. The
  site is chosen by the `Host` header, never by a site id the caller sends. See the
  [public read API reference](/reference/public-api/).
- Published snapshot reads, strict or fallback locale policy, cursor pagination, and relation
  filters.
- Typed field filters: equality on text, select, boolean, number and date fields, exclusive and
  inclusive ranges on number and date fields, one sort field, and sparse `fields`. At most 4 filtered fields; repeating `filter[field]` gives up
  to 10 alternatives (OR within a field, AND across fields). `expand` returns up to 3 relation fields
  one level deep, 25 published targets each, with a cursor route for the rest. Requests
  that exceed a limit are refused rather than narrowed. A cursor only continues the exact query it came from. No
  measured row-count ceiling exists yet.
- Public models need no token. Private models need a site API token and are never stored in a
  shared cache.
- Edge caching is off by default. When an operator turns it on (`PUBLIC_CACHE_MAX_AGE`) and
  configures purge credentials (`CF_PURGE_ZONE_ID`, `CF_PURGE_API_TOKEN`), publishing purges the
  affected responses by cache tag.
- The public Worker never writes to the database. This is a code rule. D1 has no read-only binding
  setting.

### Media and AI

- Media stored in R2 or Cloudflare Images, with WebP and AVIF conversion.
- Text generation, translation and image generation through the server-side inference connection. Provider
  keys never reach the browser.
- A per-site hourly quota. DeepInfra is the default; an optional deployment-owned OpenAI-compatible connection selects text, vision and image models. See [Inference provider](/guides/local-development/#inference-provider).
- **Duplicate files in one site's library.** An upload whose exact bytes the site already holds
  stores nothing and offers **Use existing** or **Upload a separate copy**. The same choice applies
  in the media dialog, to a saved AI image, in the management API (`on_duplicate`) and for plugins.
  Another site's files are never matched. Only identical bytes match, so a resized or re-encoded
  copy is not found. Files already in the library are not scanned. Import and site copy keep one
  file per source asset and do not match duplicates.
- **Private files.** Public media is the default. A private file's bytes live in a separate
  private bucket and open only through a five-minute download link issued to site members.
  - A private file can be placed in a media field or protected rich text of a private model, including rich child fields in plugin blocks. Public models, snippets, site settings, social images and page sections refuse it by name. A private model cannot
    be made public while an entry uses a private file.
  - Public reads never carry private bytes or a usable address: an anonymous read of a private model
    answers 404, and a site-token read returns the file's details with an empty address.
  - A site copy and a transfer with history carry private files with their bytes, checksum and
    visibility, and the destination stores them privately. Building or downloading such a file needs
    permission to export and read access to the whole media library, checked again on every download.
    CSV, collection JSON and XLSX exports never depend on private files. A destination without private
    storage is refused by name
    before anything is written. No storage credential or bucket name travels.
  - A generated application serves a private file at `GET /api/<model>/files/<field>/<id>` only to a
    caller who may read that row under the application's own sessions and access rules; CMS library
    access grants nothing there. The application stores private bytes in its own private bucket
    (`PRIVATE_FILES`). The Node `serve` runtime serves them the same way from an adopter-owned directory named by
    `PRIVATE_FILES_DIRECTORY`, and answers 503 `private_files_unavailable` only while none is configured.
  - Making a private model public and saving a private file into it are checked inside their own
    writes, so a concurrent save, import or restore cannot leave a public model holding a private file.
    See [private files](/guides/media/#private-files).

### Import and export

- A portable Dee Wan site bundle, and CSV and XLSX content transfer.
- Strapi v4 and v5 import: archive inspection, explicit mapping, dry run, resume, repeatable reruns,
  receipts, problem rows, manifests and guarded undo.
- WordPress import from a Tools → Export file (format 1.2, UTF-8, at most 8 MiB): posts, pages,
  categories, tags, authors, comments, menus, custom post types and taxonomies, reviewed custom
  fields and Yoast SEO values, with up to 5,000 media files copied from public https hosts. Items
  that were not published come in as drafts; comments come in held for moderation. Undo removes
  what the import created. See [import from WordPress](/guides/import-migration/#import-from-wordpress).
- When it is unclear which source records belong together, the dry run stops. The importer never
  guesses from names, slugs or URLs.
- Imports of real production archives, Worker limits on a deployment, and cutover and rollback have
  not been proven yet.

### Operations

- Command-line install planning, apply and resume, diagnostics (`npm run doctor`), verification,
  an install manifest, and a dry-run teardown.
- A local browser installer, for a developer who already has Node, a checkout and a terminal.
- Deployment history, with rollback refused after a destructive migration.
- Outbound webhooks: configuration, signed delivery history, secret rotation and manual replay.
- **Automatic retry for outbound webhooks.**
  - A delivery that failed for a potentially temporary reason (no answer, `408`, `429` or any `5xx`)
    is retried on an exponential, jittered schedule, up to five attempts, honouring `Retry-After`.
  - A non-transient refusal from the subscriber is not retried.
  - Every attempt carries the same event id, so your consumer can recognise a duplicate.
  - A retry sends the exact recorded body, signed with the subscriber's current secret.
  - Retries waiting to be sent do not count against the delivery-history limit.
  - Delivery is bounded best-effort: at most five attempts, a notification can arrive more than once,
    and receipt is not guaranteed. Verified locally only.
- **Error reports.**
  - Unhandled errors from the admin Worker, the public Worker and the admin UI can be sent to a
    Sentry-compatible project.
  - Nothing is sent by default. This version has no built-in Dee Wan project address, so reports go
    to Dee Wan only if the deployment sets `DEEWAN_SENTRY_DSN`, and to your own project only if you
    set `OPERATOR_SENTRY_DSN`.
  - A report carries the error type, a scrubbed message, stack frames (function, file name, line),
    the route pattern, the release and the environment. Content, form values, email addresses,
    URLs, query strings and credentials are removed first.
  - A superadmin can switch reports to Dee Wan off for the whole installation at Installation →
    Error reports. The Worker variable `DEEWAN_ERROR_REPORTING=off` does the same. Neither switch
    affects `OPERATOR_SENTRY_DSN`.

  ![Installation: the Error reports switch](/assets/screenshots/settings-error-reports.webp)

- **Rich text is one checked rich document, and your renderer draws it.**
  - It is stored as canonical HTML, at most 256 KiB of UTF-8: text blocks, tables, image galleries,
    audio, video and file blocks, and embeds of YouTube, Vimeo or an https origin the site allows
    under Settings → Integrations.
  - Every write reads it strictly and stores the canonical spelling. Markup outside the document is
    refused with a 400 that names the field, language and element or attribute, never the content.
  - Its generated type is `Html`, not a "safe HTML" type: media and embed blocks are data, not
    players. Render it with the page contract's `renderRichDocument`, or your own renderer of the
    same document.
  - Dee Wan's own renderers (Blog post pages and Latest entries) draw it with `renderRichDocument`.
- **One place for delivery**, under Settings → Source & delivery.
  - The live CMS read API and the standalone backend are presented as two different contracts, with
    the differences in routes, authentication, response envelope, deployment, rollback and CMS
    dependency stated before you switch.
  - The status shows never generated, current, drifted, building, build or deployment failure, and
    detached. The revision list refuses rollbacks that are not safe. Verified locally only.
- **Generator version and drift.** A generated backend is identified by the generator version plus a
  fingerprint of the site's model contract, never a timestamp. A site rebuilt by a newer generator
  shows as drifted rather than current. Every deployment records its generator version: the build
  workflow stops with `generator_version_missing` when the artifact names none, and a build report
  without one is refused (`build_report_incomplete`). Nothing regenerates or deploys on its own. Regeneration of an artifact made by an older generator
  is refused until you generate the standalone backend again; there is no compatibility layer.
- **An administrative audit log**, at Settings → History, behind its own `audit:read` permission.
  - It records who changed a model, a component, a role, a grant, a site token, settings,
    infrastructure or the hostname, and who deployed or rolled back.
  - Each action writes its intent before it runs and its result after. If the intent cannot be
    written, the action does not run. If the result cannot be written, the outcome shows as unknown
    rather than as success.
  - It is append-only: nothing can edit it.
  - It filters by operation, outcome, actor, target type, target id and a from/to range, and downloads
    as CSV (`format=csv`) from the same `GET /api/sites/:siteId/audit` route under `audit:read`. CSV
    cells are formula-escaped. Results are paged with a cursor; there are no counts.

## Supervised pilot: built locally, not yet proven on real infrastructure

- **A separate content database per site.** One control database plus one content database per
  site. Routing, provisioning, migrations across sites, backup and restore, and teardown are
  verified locally. Capacity, backup and restore, and isolation between several sites have not been
  proven on a real Cloudflare account.
- **Deploying a standalone backend from the CMS.** The claim, the build token, the generated
  repository workflow, migrations, reporting back and rollback are verified locally. No complete run
  through GitHub Actions to Cloudflare has been recorded.
- **The complete installer path.** The admin Worker and UI follow the normal setup path. `setup`
  also writes `backend/wrangler.public.jsonc` once the account, the Cloudflare zone and the database
  are known. It never overwrites an existing file. When it cannot derive a value, it refuses and
  names the value instead of guessing. Copying the example by hand is only the fallback for that
  refusal. Without the file, `deploy` refuses rather than skipping. An installation that deliberately serves no public content
  says so with `--admin-only`, and the run is reported as admin-only rather than complete. What is
  missing is a recorded run on a real account.
- **Preview on your own front end.** The admin stores an HTTPS front-end address and a route template
  per model, and Preview opens the draft on your front end. The Preview panel, under Settings →
  Source & delivery → Advanced — custom renderer, reads and writes that configuration, explains what
  Preview does before it is set up, and names each refusal. Until a front end is configured and
  verified, Preview opens the public API's JSON response.
  - **Unsaved preview** on a verified renderer that declares it (the managed Blog renderer for posts,
    and generated or owned renderers through the published verification key): text, components,
    relationships, the images you picked and the language's address, from one signed draft that
    expires after 60 seconds. Files are looked up by id on the server with your current permissions.
    Nothing is saved, reserved or redirected, and public reads do not change. Other renderers and
    models show the saved version with the reason. See
    [preview unsaved changes](/guides/preview-and-client/#preview-unsaved-changes).
- **Remote plugins, protocol v1 (Dee Wan side).** Install from an HTTPS manifest with reviewed capability and model grants. Delegated operations recheck the actor's live grants: entry detail, retained versions, create, typed updates, Trash, media reads/metadata, publish and unpublish use existing lifecycle services. Settings compares a fetched manifest with the installed version before upgrade; newly requested permissions stay ungranted. Host-drawn controls remain available. A manifest can also declare a reviewed frame on its exact plugin origin with declared operations: the credentialless sandbox and bound message channel carry no admin cookie or token, field edits use normal saves, and actions use authorized operations. Disabling or removing the plugin returns fields to their built-in editor. An operator-configured catalogue (`PLUGIN_CATALOGUE_URLS`) supports discovery. Editors open Scheduling for readable models without `site:plugins`; management API, CLI and MCP list views/actions and mint one-time launch links. Verified locally; Scheduling deployment remains pending.
- **Backup and restore.** Verified against local SQLite, not against real D1.
- **Invitations**, at Settings → People. An administrator invites an address to one role on one
  site. The invited person types that address on the invitation page. With mail configured they also
  enter a code sent to that address. Without mail the administrator passes the link on, and the new
  account is recorded as unverified. An existing account gets the role and keeps its password. Links
  work once, expire after 7 days, and can be resent or cancelled. Verified locally with a stubbed
  mail provider. No delivery through a real Resend account has been recorded.
- **Passkeys**, off until a superadmin switches them on. Sign-in asks for no address. Each person
  adds, renames and removes their own passkeys under Account security; the last way to sign in
  cannot be removed. Verified locally with a software authenticator. No sign-in with a real device
  (Touch ID, Windows Hello, a phone) has been recorded.
- **Migrating live sites from Strapi.** The import path exists. No end-to-end migration of real
  sites, with cutover and rollback, has been completed.

## Later / unavailable: not built, or disabled

- Production acceptance of the maintained Astro reference starter. The source-emission command exists; the complete browser gate and real-provider acceptance remain open.
- A sitemap and robots preview in the admin.
- Managed renderer delivery, a post-1.0 track. Prepare, activate, roll back and Check deployment
  run through a separate deployment service that holds the Cloudflare token. This code has not
  been verified and has never run against a real Cloudflare account, so it is not part of the 1.0
  contract. Without the deployment service settings these actions stay unavailable. Accepting a
  site template changes nothing that is live.
- An installer that needs no terminal, and a registered Cloudflare OAuth application.
- A preconfigured shared GitHub App service. The admin Source & delivery workflow supports an operator-configured GitHub App. The CLI uses device flow. See the [authentication matrix](/guides/github-authentication/).
- Arbitrary related-field filters and field filters across several models at once. Configured same-site relation display queries are supported.
- Finding similar images that are not byte-identical. Exact duplicates, media search and alt-text
  filtering are built.
- Automatic review reminders and multiple workflow assignees for one whole item. Independent locale owners, editorial tasks and field discussions are built.
- Webhook queueing beyond the retry above, and any guarantee that a subscriber receives a notification.
- Continuous synchronisation from the CMS into a standalone backend's database.
- Sections a page's editor cannot remove or turn into a separate copy. Shared sections, which show
  one published set of sections on many pages and change only where they are edited, are built (see
  [page builder](/guides/page-builder/)).
- Splitting one model across several databases.
- Enterprise SSO and MFA.
- Scheduled publish and unpublish in the core product. Scheduling is the separate Scheduling plugin,
  which is not deployed. Coordinated content releases are built in that plugin, not in the core product.

## Two ways to read your content

1. **The CMS public read API is live.** A publish reaches it immediately. If edge caching is on and
   purge credentials are set, the publish also purges the affected cached responses.
2. **A standalone backend is a release.** It contains what was published when it was generated.
   Later publishes reach it only when you regenerate and redeploy it. It is not a live feed.

## October source additions and remaining acceptance

The current source adds the following to the established contract. Focused tests cover these paths; final browser integration, live review at mobile and desktop sizes, and provider acceptance are still required.

- Content-list AND/OR groups, contextual relation choices and conditional select options share bounded rules and recheck dependencies on save.
- Plugin entry/version/create/update/Trash and media operations use the existing lifecycle and delegated actor's current grants. Upgrades show version, permissions and origin changes before confirmation; new permissions need an explicit grant. Reviewed plugin-origin frames support custom UI without admin credentials.
- Rich text keeps paragraph/heading alignment, relation controls and nested repeatable plugin groups. Vendor snippets carry typed HTML/CSS/JavaScript and execute inside an isolated frame in the admin and both site renderers.
- Account security verifies the new mailbox before changing the same account's email and ending its sessions. Memberships, credentials and history stay attached. Sign-in offers mail-based self-service password reset when configured; unknown and known addresses receive the same response. Existing no-mail recovery remains available.
- Role document rules scope core reads and atomic create/update/delete using current user context and old/proposed values. Existing model, own-row, field and locale limits remain ceilings. The related API/export audit is pending.
- CSV/XLSX offer Create, Update and Upsert through the reviewed Collection JSON core, with structured relations, media, nested components and normal scope/version checks. Update is the default; match by stable entry ID or an eligible unique field.
- Connected WordPress acquisition uses the existing WXR review/import/receipt/undo path. Explicit configuration replacement covers title, tagline, logo, icon, SEO description and supplied indexability; it requires `site:settings` and the reviewed destination revision. Unsupported or REST-hidden source data stays visible as omissions.
- AI image alt/caption suggestions use authorized bytes and require author review before replacement. Translation updates run only after source save, for selected languages, with explicit consent to replace existing manual translations.

Entry-folder source adds nested trees, one placement per translation group, scoped counts/list filters and a separate placement history. Moving an entry does not create or publish a content version. Native copy carries the tree and placement; history transfer also carries placement history, with import receipts and undo. Final integration acceptance remains pending. Existing model navigation folders are separate. A production reference renderer/starter, Scheduling deployment, and real Cloudflare publication, preview, media, mail and recovery acceptance remain delivery gates. Source changes alone do not satisfy them.

A maintained live-API Astro starter is now present in source; see [First site](/guides/first-site/). Production starter acceptance, Scheduling deployment, and real Cloudflare publication, preview, media, mail and recovery evidence remain release gates. No tagged supported release is claimed.

The unreleased integration candidate also adds private file attachments to native website forms and approved plugin mail addressed to an entry’s author or assigned reviewer. These extend the existing intake and mail services. Their final integration checks remain open; no supported release or real-provider acceptance is claimed.

## Current integration additions

These source features are part of the unreleased integration candidate. The final browser gate, live mobile/desktop review and external-provider acceptance remain separate requirements.

1. Chunked native site/history transfers carry accepted large media with checksums and continuation.
2. WordPress page conversion preserves headings, code, tables, longer bodies and explicitly mapped source metadata.
3. Protected rich text supports private images, attachments and authorized image variants.
4. Native-script addresses retain Unicode letters, numbers and combining marks and can be generated from titles.
5. Named compound uniqueness joins two to four scalar fields under atomic write guards.
6. Blog metadata can resolve live contributor, category and tag information; snapshot behavior remains an explicit option.
7. Ordinary and mixed components can be retired, retain older definitions and upgrade instances deliberately.
8. Plugin rich-text blocks can contain bounded host rich-text child fields.
9. Native relationship columns show scoped labels, counts and related values.
10. Typed visibility conditions combine up to four terms in AND/OR groups, at most three levels deep.
11. Optional translated fields can borrow absent values from published fallback languages; deliberate empty values stay empty. See [Field fallback](/guides/languages/#field-fallback).
12. Validated static SVG works through the image workflow.
13. Generated applications support up to 32 named application roles with model-operation grants, a non-admin signup default and existing admin/user roles.
14. DeepInfra remains the default inference provider; a deployment can select an OpenAI-compatible endpoint and explicit text, vision and image model lists.
15. [Related draft previews](/guides/preview-and-client/#preview-unsaved-changes) resolve authorized saved related drafts; ordinary public reads still require publication.
16. [Content search](/guides/content-editing/#find-and-open-an-item) covers saved rich-text bodies, including drafts, with matching fields and short excerpts inside the reader’s access scope.
17. [Live API browser origins](/reference/public-api/#browser-origins) configure CORS, preflight and permitted public-read headers per site.
18. [Management media replacement](/reference/management-api/) keeps the media ID and references while replacing bytes through the existing replacement service.
19. [Generated account administration](/reference/standalone-backend-api/#application-account-administration) creates named-role accounts and deletes unlinked accounts, with session revocation and last-administrator protection.
20. [Rendered entry editing](/guides/preview-and-client/#edit-from-the-preview) opens text and rich-text controls over supported renders; older renderers keep field-focus fallback.
21. [WordPress imports](/guides/import-migration/#import-from-wordpress) retain reviewed ACF groups/repeaters as editable JSON and explicitly keep future publication schedules or draft intent.
22. [Selected-content refresh](/guides/import-migration/#refresh-selected-content) reviews additions, updates and deletions in populated models, preserves excluded data and old media pins, and refuses conflicting edits. Resume and cancel remain available; replacement has no automatic Undo.

Current authoring also includes localized model, field/group, help and option labels without changing stored keys; reviewed model promotion between sites binds both definition revisions. Zoned datetimes retain a UTC instant and IANA zone, refuse nonexistent times and require an offset choice for ambiguous times. Batch AI produces editable retained proposals without saving content; cancellation keeps completed proposals. Independent future drafts retain their own snapshots and media pins without changing the ordinary draft; release start freezes the selected branch, and cumulative previews use the scheduled future state.

<!-- dee-wan-docs page: /detachment-contract/ -->

# Detachment contract

Source: https://dee-wan-docs.pages.dev/detachment-contract/

A standalone backend is a repository Dee Wan generates from a site's models and published content.
This page says what you can rely on once you have one, and what happens if you stop using Dee Wan.

Status: every line below is covered by automated tests on a development machine. None has yet been
proven on a real Cloudflare deployment, and no performance figures exist.

For the ordered operator procedure, credential split and acceptance commands, use the [detachment runbook](/guides/detachment/). It combines `verify:deployment` and `verify:media` without treating a local check as real-cloud acceptance.

## What you get

| Guarantee | What it means for you |
| --- | --- |
| You own the repository | The project is written into the directory and GitHub repository you name. |
| You own the database | The D1 database is created in your Cloudflare account. Generation writes only to that database. |
| You own the deployment and its credentials | The project has its own Wrangler configuration and deployment script. Its API accepts the writer bearer `API_BEARER_TOKEN`, the read tokens listed in `ACCESS_CONFIG` and, when standalone authentication is on, sessions from its own Better Auth. |
| Real tables | Each content model becomes a table with typed columns, with indexes for sort fields, publication state and relations. |
| Reviewable, append-only migrations | A schema change adds a new migration after the ones already applied. An applied migration is never rewritten. |
| Familiar routes | Routes are generated with `prisma-generator-express` and follow Prisma model and query semantics. |
| The API does not call Dee Wan | The API Worker reads only its own D1 database. It never calls Dee Wan and does not depend on its accounts, uptime or infrastructure. Some website routes do call Dee Wan: see [What still depends on Dee Wan](#what-still-depends-on-dee-wan). |
| Your code survives regeneration | Files under `src/owned/` are written once and never touched again. |
| Your data survives regeneration | Rows you write into your own tables are kept across a schema change. |
| You can leave | `deploy-from-repository.yml` deploys a commit without Dee Wan. Regenerating needs a `definitions.json` you kept. See [Stopping](#stopping). |

Files in a standalone backend fall into three **ownership zones**: `generated` (rewritten on every
regeneration), `owned` (`src/owned/`, never overwritten) and `shared` (written once, then yours).
The full rule is in [Extending your backend](/guides/extending-your-backend/).

## What still depends on Dee Wan

The API and the website are different surfaces. Statically built pages come from the committed
`pages.json` and need nothing from Dee Wan. These website routes reach Dee Wan on every request:

| Route or feature | What it reads or sends | Answered by |
| --- | --- | --- |
| Blog routes and the Blog RSS feed | Published posts from `/v1` on the site's own host | Dee Wan public Worker |
| Blog chunks of the sitemap | `/v1/_sitemap` | Dee Wan public Worker |
| Search pages, and pages with a Latest entries or Site search section | `/v1` and `/v1/_search` | Dee Wan public Worker |
| Pages of a model that takes visitor comments | Comments from `/v1/_comments`. New comments and reactions go to `/v1/interactions/*`. | Dee Wan public and intake Workers |
| Form sections | Submissions go to `/v1/interactions/form.submit` | Dee Wan intake Worker. The admin Worker delivers them. |
| `/preview` | Drafts from `previewApiOrigin` | Dee Wan public API, only while it is set |
| An exported managed renderer, if you deploy it | `/v1` on every request | Dee Wan public Worker |

On these routes, rich text that holds an embed or a plugin block also reads `/v1/_embeds` or
`/v1/_rich-blocks`. Latest entries in a shared section shown in a region are pinned at generation
and read nothing.

A publish or unpublish in the CMS reaches these routes at once. It does not change the standalone
API or statically built pages until you regenerate and deploy.

Retiring the Dee Wan installation stops every route in the table. Check the
[list before you retire the CMS](/guides/detachment/#before-you-retire-the-cms).

## Two things to know

**A changed snapshot replaces the generated content tables.** Every deployment runs `data:load`.
When the committed snapshot differs from the one last loaded into that database, the load deletes
every row of each table the snapshot owns and writes the snapshot's rows. A row the snapshot does not
contain is gone, regardless of who wrote it. There is no refusal. This happens after a regeneration and after a
rollback to a commit with different content. Loading the same snapshot again changes nothing. Tables the
generator did not create are not in the snapshot and are never touched. Keep your own data in your
own tables, with your own migrations.

**Making an existing field required needs a backfill first.** Rebuilding the table fails on rows
that contain NULL, and the run refuses rather than lose data. Fill the empty values, then make the field
required.

## How updates reach it

Two separate things are involved:

- The **build webhook**, set in Dee Wan under **Settings → Source & delivery → Advanced — build webhook and deployment**, is the URL
  Dee Wan calls to start your repository's CI.
- The **Deploy** button, on the Standalone backend card in the same place, calls that webhook. Your
  CI then regenerates the generated files, applies migrations and deploys.

Nothing regenerates or deploys on its own. A later publish in the CMS reaches the standalone API and
statically built pages only through a new regeneration and deployment. It is a release, not a live
feed. The CMS public API and the routes in [What still depends on Dee Wan](#what-still-depends-on-dee-wan)
are different: a publish reaches them immediately.

## Stopping

Detaching is a supported outcome, not an emergency exit. To detach, remove the build webhook in Dee
Wan, stop pressing Deploy, and keep the repository.

What keeps working:

- the deployed Worker and its database.
- every route already generated.
- the migrations already applied.
- your code under `src/owned/` and your own tables.
- `deploy-from-repository.yml` and your CI. Deployment applies `migrations/` with `wrangler d1 migrations apply`, then runs `wrangler deploy`. Locally, `npm run db:init` applies the same migrations.
- the routes in [What still depends on Dee Wan](#what-still-depends-on-dee-wan), only while the Dee Wan installation still serves them.

What stops:

- new model definitions from the CMS.
- newly published CMS content in the standalone API and statically built pages.
- revocation of CMS-issued read tokens. Their digests stay in `access/read-tokens.json` until you remove them. See [Stop the CMS connection](/guides/detachment/#stop-the-cms-connection).

From then on, change the schema with your own SQL migration: add a file after the last one in
`migrations/`. A migration file does not change `prisma/schema.prisma` or the generated client.
Change the schema yourself and run `npm run prisma:generate`. Once nobody regenerates, you can edit
files in the `generated` zone freely. The zone rule only matters while Dee Wan still writes into
that tree.

<!-- dee-wan-docs page: /license/ -->

# License

Source: https://dee-wan-docs.pages.dev/license/

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.