# Checklists (/agents/checklists)

What done means for a coding agent handing a Meridian site back, as checklists with the command that proves each item, covering the project check, every route rendering, accessibility, content, SEO, performance, deploy configuration and secrets.

Work through every list before you say a site is finished. Each item names the command that proves it. When an item cannot be proved (no database, no running server, a decision only the person can make), say so in your report instead of ticking it.

## The project [#the-project]

- [ ] `engine-dmo check` exits 0.
- [ ] `engine-dmo check --strict` exits 0.
- [ ] The text output of `engine-dmo check` has no `warning:` line for a template, or each one left is explained. The summary, `--strict` and `--json` do not count template warnings, so read the lines.
- [ ] `engine-dmo seed verify` says the seed matches the schema, and `engine-dmo seed apply` on an empty database exits 0 (only `apply` checks field values).
- [ ] On `engine-dmo`, a site with no partner businesses has the member portal turned off (`portal: { mode: "off" }` in `config/portal/portal.yaml`).
- [ ] `engine-dmo schema plan` exits 0 with "No changes" (the database matches the files).
- [ ] No `id:` was typed by hand or copied; `git diff` shows ids only where a verb or `check --fix` wrote them.
- [ ] `AGENTS.md` and the skills were not edited by hand (regenerate them with `engine-dmo guide --out AGENTS.md` and `engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md` if in doubt).
- [ ] No file under `storage/`, `public/build/`, `node_modules/`, `.meridian/` or any `.env` is committed.

## Every route renders [#every-route-renders]

- [ ] `engine-dmo a11y audit --all` reports 0 failures on every site (`--site <key>` for each). It renders every page the sitemap would list, plus the home page, whether or not `seo.sitemap.enabled` is on, and fails any that does not answer 200.
- [ ] Pages outside the sitemap render: the search page with and without a query, each index page filtered by each facet, the last page of each paginated index, and the 404 page (`engine-dmo render /no-such-page --json` answers 404 with your template and empty `errors`).
- [ ] Every locale renders: `engine-dmo render <path> --locale <code> --json` for one page of each type.
- [ ] Every page that runs `query()` has rendered (a non-indexed field fails only at render).
- [ ] Every `render --json` shows `"errors": []` and `"status": 200`. A 301 still exits 0, with `kind: redirect` and a non-empty `a11y` (`a page has exactly one h1, this one has 0`), and `a11y audit --path` on one fails `html-lang` and `page-title`. Neither is a defect in the page: use the address it redirects to.

## Accessibility [#accessibility]

- [ ] `engine-dmo a11y audit --all` reports 0 warnings as well as 0 failures.
- [ ] `render --json` shows `"a11y": []` on each kind of page.
- [ ] Every page: `lang` and `dir` on `<html>`, one `h1`, a skip link to `<main id="main">`, labelled `<nav>` landmarks, `aria-current="page"` on the current menu item.
- [ ] Every form control has a visible label; errors are summarised and linked; required fields are marked in text, not colour alone.
- [ ] Every library image has alt text in every locale (or is marked decorative); `engine-dmo media stats` shows alt text coverage.
- [ ] Your CSS keeps text contrast at 4.5:1 (3:1 for large text and interface parts), shows a visible focus outline, and reflows at 320 CSS pixels wide.
- [ ] `engine-dmo a11y statement --out accessibility-statement.html` written for the person to complete, and a page for it in the footer menu.
- [ ] You told the person a manual pass (keyboard only, a screen reader, 200% and 400% zoom) is still needed: the automated checks are evidence, not conformance.

## Content [#content]

- [ ] Every routed type has published documents with realistic text, within each field's limits.
- [ ] Every page the navigation links to exists and is published in every locale it is linked from.
- [ ] Every string the templates print is in `config/strings/<locale>.yaml` for every enabled locale (`check` lists missing keys).
- [ ] Every label in the schema has every enabled locale (`check` warns otherwise).
- [ ] Every label `check` does not warn about has every enabled locale too: endpoint input labels in `endpoints.yaml`, navigation item labels in `seed/navigation/`, and the first option of each select.
- [ ] Every email template has its text in each enabled locale (email templates have no `t()`; see [Enquiry form](/agents/recipes/enquiry-form#emails-in-more-than-one-locale)).
- [ ] Photographs are the person's own, licensed and credited; none is a generated image presented as a real place.
- [ ] A staff user exists or the person knows how to create one: `engine-dmo user create --email ... --name ...`.

## SEO [#seo]

- [ ] `base.html` prints `{{ head() }}` once in `<head>` (title, description, canonical, hreflang, robots, Open Graph).
- [ ] `base.html` prints `{{ jsonld() }}` once in `<head>`. Prove it: `engine-dmo render <path> | grep -c 'application/ld+json'` prints 1 on an entry page and an index page. `check` warns only when a type has a `structured_data` block, and the warning does not fail it.
- [ ] Every routed type that is a place, an event or an article has a `structured_data` block, and `engine-dmo check --strict` passes with it ([SEO and structured data](/templates/seo-and-structured-data#mapping-a-type-to-schemaorg)).
- [ ] `seo.title_template` is set in `site.yaml`, so titles carry the site's name: `engine-dmo render <path> | grep '<title>'`.
- [ ] `seo.sitemap: { enabled: true }` is set. It defaults to off, when `/sitemap.xml` answers 404 and `a11y audit --all` still passes: `engine-dmo render /sitemap.xml --json` answers 200.
- [ ] `seo.robots: { enabled: true }` is set. It defaults to off, when `/robots.txt` answers 404: `engine-dmo render /robots.txt --json` answers 200 and names the sitemap.
- [ ] Each type's documents have a meaningful `summary` (used as the meta description), or the type has an `seo` field that is filled.
- [ ] `render --json` of an entry page shows a canonical on the site's configured domain and, on a multilingual site, `hreflang` for each published locale and `x-default`.
- [ ] Filtered index pages are `noindex` (the engine does this; check it is not overridden).
- [ ] `server.base_url` is the real public origin in production.

## Performance [#performance]

- [ ] Every library image goes through `img()`, `picture()` or `figure()` with a declared transform; only the main image of a page has `priority=true`.
- [ ] `render --json` `images` shows sensible `sizes` and no image downloads far wider than it displays; `engine-dmo dev status --json` lists oversized images when `dev up` has run.
- [ ] `render --json` `queries` does not grow with the number of items on the page. The engine's own work is a steady baseline: about 4 to 8 statements for a 404, about 20 for a plain page, 30 to 45 for a page with images, navigation or its own `query()`, and an index of 24 items ran 18, the same as an index of one. A count in those ranges is fine. The problem to look for is one `sql_summary` repeated once per item, or a count that rises when you add items: a `query()` inside a loop. Use `with()` or one query outside the loop.
- [ ] Stylesheets and scripts are linked through `assets.url()` so they carry a version; no inline executable scripts.
- [ ] Expensive repeated fragments use `{% cache %}` where the content allows ([Caching](/templates/caching)).

## Deploy configuration [#deploy-configuration]

- [ ] `ENVIRONMENT=production engine-dmo check --no-db` exits 0.
- [ ] `server.security.signing_key: ${SIGNING_KEY}`, `server.base_url` from the environment, `server.trusted_proxies` matching the reverse proxy (or `real_ip_header: ""`).
- [ ] A real mail driver (`smtp`, `postmark`, `ses` or `resend`) with `mail.from`; staff two-factor sign-in left on.
- [ ] Storage chosen for production (a persistent volume for `filesystem`, or `s3`) ([Storage and media](/deploying/storage-and-media)).
- [ ] A search service configured, or the person told the search page runs in browse mode.
- [ ] The deploy sequence written down for the person: back up, `migrate up`, `schema apply`, `serve`, `health --readiness --wait 60s`, `warm` ([Deploying](/deploying)).
- [ ] Extensions, if any, built for the production engine's exact build.

## Secrets [#secrets]

- [ ] `grep -rn` for passwords, keys and tokens under `config/` finds none: every secret is a bare `${VAR}` (`check` enforces this for known secret paths; check custom ones yourself).
- [ ] No secret in templates, seed files, `public/`, commit messages or your report.
- [ ] `.env` is in `.gitignore`; `.env.example` lists every variable with placeholder values only.
- [ ] Your report lists every environment variable the person must set for production, without values.

## The report [#the-report]

Tell the person what you built, how to run it (`engine-dmo dev up`, the URL, how to sign in), what you verified with which command, what you could not verify and why, the environment variables to set, and every decision left to them.


# Commands for agents (/agents/commands)

The engine commands a coding agent uses to read, change and verify a Meridian project (describe, guide, docs, help --json, the dev verbs, check, schema plan and apply, render --json, a11y audit, content, seed and mcp), what each returns, what it needs and when to use it.

Every command takes `--project <dir>` (default: the current directory) and `--json` for machine-readable output. Exit codes are the same everywhere:

| Exit | Meaning |
|---|---|
| `0` | Success |
| `1` | Error: the command could not do its work (a page that answered 400 or more, a database it could not reach) |
| `2` | Changes pending (`schema plan`, `migrate status`), or refused for want of confirmation (a destructive plan) |
| `3` | Configuration invalid, or a verb's argument that names something that does not exist (`--after names "slug", which is not a field`) |
| `4` | Degraded but running (`health`) |

An unknown command, an unknown flag or a missing argument exits 1, not 3, although `help --json` lists bad invocations under 3. Some `--help` texts cite design documents by file name or number (such as `07-auth-and-permissions.md` or `ADR-0019`); those are not in the handbook and you cannot open them. Search the handbook for the topic instead.

## What each command needs [#what-each-command-needs]

| Needs | Means | Commands |
|---|---|---|
| Nothing | Runs in any directory | `docs`, `help`, `version`, `describe fieldtypes`, `config schema` |
| The project | Reads the files; unset `${VAR}`s are accepted | `describe project`, `describe type`, `guide`, `template api`, `media transforms`, `check --no-db`, the `dev` verbs without `--scaffold` |
| Configuration | Every `${VAR}` without a default must be set; a placeholder is enough | `config render`, `config validate`, `describe template`, `seed verify`, `seed write`, `new`, `a11y statement`, `dev route add --scaffold`, `portal check` |
| A database | A migrated database with the schema applied | `check` (it fails when it cannot connect; use `check --no-db` without one), `schema plan`, `schema apply`, `render`, `describe route`, `a11y audit`, `seed apply`, `content`, `user`, `crm`, `mcp`, `api resolve` |

"A placeholder is enough" means any value of the right form: `DATABASE_URL=postgres://placeholder@localhost/placeholder`, and once `engine.yaml` names it, `SIGNING_KEY` of at least 32 characters (`server.security.signing_key must be at least 32 characters` otherwise). The engine never reads a `.env` file; export the variables.

Which command to reach for:

```mermaid
flowchart TD
  q{"What do you need?"} --> learn["To know a feature"]
  q --> proj["To know this project"]
  q --> chg["To change the project"]
  q --> ver["To prove a change"]
  learn --> docs["The handbook:<br/>llms.txt, then the page"]
  proj --> desc["guide, describe project,<br/>describe type"]
  chg --> verb{"Is there a dev verb?"}
  verb -- yes --> dev["dev ... --apply"]
  verb -- no --> yaml["Edit YAML, then check --fix"]
  ver --> db{"Database?"}
  db -- no --> nodb["check --no-db, seed verify"]
  db -- yes --> full["check, render --json,<br/>a11y audit"]
```

## Learn the engine and the project [#learn-the-engine-and-the-project]

| Command | Returns | Needs | Use it |
|---|---|---|---|
| `help --json` | Every command: `path`, `use`, `short`, `arguments`, `flags` (name, type, default, usage), plus `global_flags` and `exit_codes` | Nothing | Before running a command you have not used, to get its exact flags |
| `guide` | This project's rules, the authoring verbs, every site with its domains, locales, routes and endpoints, every type with its fields and ids, and the template globals and filters | The project | At the start of every session, and after changing the model. `--out FILE` writes it, `--skill` adds skill front matter |
| `describe project --json` | Networks, sites, locales, types, routes, endpoints, reports, tiers, partner roles and staff roles, with ids | The project | To find an element's key or id |
| `describe type <key> --json` | A type's fields at every depth: id, type, parameters, options, groups, blocks, sites, member rules. A core type lists its core fields marked `core` | The project | Before writing a template or seed file for the type |
| `describe fieldtypes --json` | Every field type: what it stores, its parameters, its default translate mode | Nothing | Before adding a field, to get its parameters right |
| `describe template <name>` | The file a template name resolves to on a site's chain, what it extends and includes, the type it renders | Configuration | When a site has its own template root and you are unsure which file wins |
| `describe route <path> --json` | Which route answers a path, the template, and the whole template `context` with real values, plus the `functions`, `filters` and `components` available | A database | Before writing a template: you see exactly what it receives |
| `template api --json` | Every global, filter, tag, field type, type, route and component of a site, with documentation (`--site`) | The project | To check a function's arguments |
| `config schema --file <kind>` | The JSON Schema of one configuration file kind: `engine`, `locales`, `strings`, `site`, `routes`, `endpoints`, `images`, `schema`, `memberships`, `portal` and the rest | Nothing | To check a key before writing it. The argument is the kind, not the file name |
| `config render` | The configuration as the engine resolved it, defaults filled, secrets redacted | Configuration | To see the value a key really has |
| `version` | Version, bundle and modules, the build used for extensions, contract versions | Nothing | To confirm the bundle |

## Change the project [#change-the-project]

### The dev verbs [#the-dev-verbs]

Each verb edits the configuration, keeping comments, writes the new element's id and checks the configuration, writing nothing when the configuration itself would be invalid. Two things it does not hold back:

- **Templates a new element names.** `dev route add` (with an `--index`) and `dev endpoint add` write a valid route or endpoint whose templates do not exist yet, and `check` fails until you write them.
- **A failure after the write.** `dev route add --scaffold` writes `routes.yaml`, then loads the whole configuration to write the template; with a `${VAR}` unset it exits 3 having written the route but not the template, and a second run says `nothing to change`. Write the template with `engine-dmo new template <type>/entry.html`.

So run `engine-dmo check` after every verb. Every verb takes `--dry-run` (print the diff, write nothing) and `--apply` (apply the schema plan afterwards when it is not destructive; a destructive plan exits 2 and is left for a person). After each change the verbs regenerate `AGENTS.md` and the agent skills when the project has them.

| Verb | Does | Key flags |
|---|---|---|
| `dev type add <key>` | A custom type with `title`, `slug` and `summary` | `--label`, `--plural`, `--site` (one site's own type), `--sites` |
| `dev field add <type> <name>` | A field | `--type`, `--label`, `--required`, `--index`, `--translate`, `--options a,b,c`, `--param key=value` (repeatable), `--group`, `--after`, `--help-text`, `--site`. On a core type, `--after` can name only a field in your `extends:` file, never a core field: added fields always follow the core ones |
| `dev field set <type> <name>` | A field's label, help text or a parameter | `--label`, `--help-text`, `--param` |
| `dev field rename <type> <old> <new>` | New handle, same id and values; the old handle stays an alias | `--no-alias` |
| `dev field remove <type> <name>` | Removes a field; values stay stored under its id | |
| `dev option add <type> <field> <value>` | An option on a select field, or a style on a link field | `--label`, `--class` |
| `dev group add <type> <key>` | An editor group | `--label`, `--fields` |
| `dev route add <type> <uri>` | A route | `--index <path>`, `--site`, `--scaffold` (writes `entry.html`, never `index.html`; needs configuration) |
| `dev site add <key>`, `dev site rename <old> <new>` | A site directory with `site.yaml` and `routes.yaml`; a rename keeps the id and redirects old URLs | `--name`, `--domain`, `--locales`, `--network` |
| `dev locale add <code>` | A locale in `locales.yaml`, enabled on a site | `--label`, `--fallback`, `--site` |
| `dev config set <file> <path> <value>`, `dev config unset <file> <path>` | One value in one file, path relative to `config/`, such as `dev config set engine.yaml search.driver meilisearch`. List indexes are not supported | |
| `dev endpoint add <key>` | A declared endpoint from a recipe | `--from recipe:enquiry` or `recipe:newsletter`, `--subject <type>`, `--site` |
| `dev network add <key>` | A network of sites sharing organisations and partners | `--name`, `--site` |
| `dev source rename`, `dev importer rename`, `dev webhook rename` | Rename an outbound declaration, keeping its id | `--site` |
| `dev tier add <key>`, `dev tier rename` | A membership tier (`engine-dmo`) | `--after`, `--label` |
| `dev role add <key>` | A partner role (`engine-dmo`) | `--label`, `--can` |
| `dev portal screen add <key>`, `dev portal action add <subject.verb>` | A portal screen or action (`engine-dmo`) | See [Partner portal](/agents/recipes/partner-portal) |
| `dev slot add <key>` | A promotion slot (`engine-dmo`) | `--types`, `--capacity`, `--price`, `--currency` and more |
| `dev up` | Serves the project in development mode and, on every configuration change, writes missing ids, checks, plans, applies a safe plan and reloads | `--listen`. Long-running: run it in the background or not at all |
| `dev status --json` | What `dev up` last found: the check, the plan, live aliases, the address, oversized images | Exits 1 when `dev up` has not run in the project |

With `--json`, a verb that fails prints an object with `command`, `exit` and `error`.

### Scaffolding [#scaffolding]

| Command | Writes |
|---|---|
| `new type <key>` | A schema file and its template |
| `new template <name>` | A starter template, such as `walk/index.html`; `--from-shared` copies the shared template into a site's root |
| `new component <name>` | `templates/_shared/components/<name>/component.yaml`, `<name>.html` and `<name>.css` |
| `new block <key>` | A block template and the schema stub declaring it |

Each takes `--site <key>` for a site's own template root and `--force` to overwrite. Each needs configuration. The scaffolds are starting points: `new template <type>/index.html` writes an empty `body` block with no `h1`, which fails the accessibility checks until you fill it.

### Ids [#ids]

`check --fix` writes an id for every element that has none, keeping comments, then checks. Run it after any hand edit that adds an element.

## Verify [#verify]

| Command | Returns | Needs |
|---|---|---|
| `check` | Every problem in configuration, schema, templates and deployment, each at `file:line:col` with the source line, a caret, hints and an `MRD-` code. Exit 0 valid, 3 invalid. `--json` gives `valid`, `errors`, `warnings` and `diagnostics`. Template warnings are printed in the text output only: the summary's warning count and `--json` leave them out, so read the text | A database; `--no-db` skips the database checks (drift) |
| `check --no-db` | The same without a database; unset `${VAR}`s are accepted | The project |
| `check --strict` | Configuration warnings fail too (exit 3); template warnings still do not | As `check` |
| `ENVIRONMENT=production check --no-db` | The production rules | Nothing |
| `schema plan` | The changes `schema apply` would make, one per line with a mark (`+ ~ - > = !`) and `[DESTRUCTIVE: ...]` where data or access is lost. Exit 2 when changes are pending. `--json` gives `changes` (each `op`, `resource`, `key`, `detail`) and the plan's `digest` | A database |
| `schema apply` | Applies the plan in one transaction; refuses a destructive plan without approval | A database |
| `seed verify` | Whether the seed loads, names only fields and locales that exist, and names only documents the seed has. Field values are not checked: `seed apply` refuses a bad one | Configuration |
| `render <path>` | The page's HTML on standard output; status, image report and render errors on standard error. Exit 1 on a status of 400 or more or a render error, and exit 0 on a redirect. `--site`, `--locale` (the path is then unprefixed), `--host`, `--fragment` | A database |
| `render <path> --json` | `status`, `site`, `locale`, `request`, `kind` (`entry`, `index`, `redirect`, `not_found` ...), `template`, `html`, `errors` and `warnings` (each `file`, `line`, `column`, `severity`, `code`, `message`, `source`), `queries` (each statement's summary and time), `assets`, `a11y` (findings as sentences) and `images` (each image's transform, ladder, formats and derivatives). A 301 is rendered as a page: it exits 0 with a non-empty `a11y`, so read `status` first | A database |
| `a11y audit` | Renders 20 pages spread across the site's routes, or with `--all` every page the sitemap would list plus the home page (whether or not `seo.sitemap.enabled` is on), or the `--path` pages named (repeatable, query strings allowed), and checks each: a page that answers 400 or more is a failure. A `--path` that redirects is audited as a page and fails `html-lang` and `page-title`, so name the address it redirects to. Exit 1 on any failure. `--json` gives `pages` (each `path`, `status`, `findings`) | A database |
| `a11y statement` | An accessibility statement scaffold from `site.yaml` (`--out`, `--format`) | Configuration |
| `template test` | Renders the pages `tests/templates/*.test.yaml` name and checks each | A seeded database |
| `portal check` | The project's portal templates against the portal context (`engine-dmo`) | Configuration |
| `media transforms` | Each image transform resolved, with its width ladder and the formats this build serves | The project |
| `api resolve <path>` | What the content API answers for a path | A database |

## Content [#content]

| Command | Does | Needs |
|---|---|---|
| `content create --type <key> '<json>'` | Creates a document from field values by handle, validated as the admin validates a save; `--publish` publishes the locale through the publish checks; `--locale`, `--site`; `--data -` reads standard input. Prints the new id | A database |
| `content update <id> '<json>'` | Merges values over a locale's working revision; `null` clears a field; `--publish` | A database |
| `content publish --id <id>` | Publishes a locale (`--locale`) or every locale whose checks pass (`--all-locales`) | A database |
| `content get <id> --json` | A document's working and published values per locale | A database |
| `content list --type <key>` | One line per document and locale: id, type, locale, status, title | A database |
| `seed apply` | Loads `seed/` through the same validation and history as an editor; refuses a database that holds content | A database with the schema applied |
| `seed reset --confirm` | Removes all content, media and analytics; keeps users and configuration. Refused in production | A database |
| `seed generate --type <key> --count <n>` | Valid documents from word lists and placeholder images (`--publish`, `--locale`, `--site`, `--near lat,lng`, `--seed`) | A database |
| `user create --email <e> --name <n>` | A staff user and a single-use enrolment link (the first user goes into `administrators`) | A migrated database |
| `crm organisation create '<json>'`, `crm membership set <org-id> --tier <t>`, `crm invite` | An organisation, its tier on a site, a portal invitation (`engine-dmo`) | A database |

An error names the field and its code (`nonsense: type page has no field "nonsense" ... (unknown_field)`), so you can fix the JSON and run it again.

Two content operations have no command. Scheduling a publish for later is done in the admin, by the content MCP's publish tool with `publish_at`, or by a seed document's `schedule:`. Unpublishing with a redirect to another address is done through the content MCP; `content trash --redirect` removes a document and redirects its address.

## The content MCP [#the-content-mcp]

If your client speaks the Model Context Protocol, `engine-dmo mcp --as <staff email>` serves the content tools (read, create and update documents, upload media, publish) over standard input and output, acting as that staff user with exactly their permissions. It needs a database and a staff user, and is refused in production. `--drafts-only` keeps publishing out of reach; `--sites`, `--toolsets` and `--types` narrow it further. `engine-dmo mcp tools --json` lists the tools and their schemas without serving. See [Content MCP](/integrating/content-mcp).

The `dev` verbs, `check`, `render` and `describe` are not MCP tools: run them as shell commands.


# For agents (/agents)

Start here if you are a coding agent building or changing a Meridian website. What Meridian is, the golden rules, how to read the rest of the handbook from the binary, and the change, check, render loop.

This section is written for you, the coding agent. Read this page first, then [Rules](/agents/rules) and [Workflow](/agents/workflow). Every command below is real and every example has passed `engine-dmo check`. If something here disagrees with what the binary tells you, the binary wins: it is the engine you are running.

## What Meridian is [#what-meridian-is]

Meridian is a self-hosted content engine for place-based websites, shipped as one binary per bundle. `engine-cms` is the core content platform; `engine-dmo` is the core plus the destination-marketing modules (directory, organisations and memberships, the member portal, claims, promotions, landing pages, affiliates, paid listings, member reports). A project is a directory: YAML configuration under `config/`, Pongo2 templates under `templates/`, seed content under `seed/` and static files under `public/`. The binary reads the project, reconciles a PostgreSQL database with it, and serves the public sites, the staff admin (at `/studio`), the APIs and the background jobs from one process. You build a website by editing files and running engine commands. You never write Go for an ordinary site, and you never touch the database directly.

The commands on these pages use `engine-dmo`. `engine-cms` takes the same commands for every core feature; only the DMO modules are missing from it.

## The golden rules [#the-golden-rules]

1. **Change configuration with the engine, not around it.** Use the `engine-dmo dev` verbs (`dev type add`, `dev field add`, `dev route add` and the rest) where one exists, or edit the YAML and run `engine-dmo check --fix`. Never write SQL, never edit the database, never invent or copy an `id:`.
2. **Secrets are only ever `${VAR}`.** Passwords, keys and tokens never appear as literal values in any file under `config/`.
3. **Plan before you apply.** `engine-dmo schema plan` before `engine-dmo schema apply`. A destructive plan is a decision for a person, not for you.
4. **Templates are autoescaped and checked.** No `|safe`, no inline event handlers, no variables inside `<script>` except through `|json`, every link through `|url` or a link helper, every visible string through `t()`. The layout prints `{{ head() }}` and `{{ jsonld() }}`.
5. **One `h1` per page, a label for every control, alt text for every image, a skip link and a language on `<html>`.** Accessibility is part of done, not a later pass.
6. **Verify with the engine, not by reading your own output.** `engine-dmo check` after every change, `engine-dmo render <path> --json` for every route you touch, `engine-dmo a11y audit --all` before you hand back.
7. **Do not edit generated files.** `AGENTS.md`, `.claude/skills/meridian*/SKILL.md` and `.meridian/` are rewritten by the engine.
8. **Describe only what the engine does.** If a feature is not in this handbook or in `engine-dmo help --json`, it does not exist. Say so to the person rather than faking it in a template.

[Rules](/agents/rules) gives every rule with its reason and what breaks when you ignore it.

## How to read more [#how-to-read-more]

The handbook is on the web as Markdown, and the binary describes the project. You need no browser, but you need network access to read the handbook:

| Read | Gives you |
|---|---|
| `https://docs.cherwell.studio/llms.mdx/agents/rules/content.md` | One handbook page as Markdown. Any page's path works, such as `templates/filters` |
| `https://docs.cherwell.studio/llms.txt` | Every page by title, address and description |
| `https://docs.cherwell.studio/llms-full.txt` | The whole handbook as one Markdown file; search it for a word to find a page |
| `engine-dmo guide` | This project: its rules, sites, routes, types with field ids, template globals and filters, generated from the configuration |
| `engine-dmo describe project --json` | Sites, locales, types, routes, endpoints, tiers and roles, with their ids |
| `engine-dmo describe type <key> --json` | One type's fields at every depth, with ids, parameters and options |
| `engine-dmo describe fieldtypes --json` | Every field type, its parameters and what it stores |
| `engine-dmo template api --json` | Every global, function, filter, tag and component a site's templates may use |
| `engine-dmo help --json` | Every command with its arguments, flags and exit codes |
| `engine-dmo config schema --file <kind>` | The JSON Schema of one configuration file kind (`site`, `routes`, `schema`, `endpoints` and so on) |

Read [Commands for agents](/agents/commands) for what each returns and when to use it.

The handbook describes the current engine. If you cannot reach it, ask the person for its pages as files. If a page disagrees with the engine in the project, `help --json`, `describe` and `template api` come from the binary, so they are the source of truth for it; `engine-dmo version` says which engine that is.

Most read commands load the configuration, which means every `${VAR}` in it without a default must be set, even to a placeholder, before they run. The engine never reads a `.env` file. See [What each command needs](/agents/commands#what-each-command-needs).

## The loop [#the-loop]

Every change, however small, goes round the same loop:

1. **Change** one thing: a verb, a YAML edit or a template.
2. **Check**: `engine-dmo check`. Exit 0 means valid; exit 3 means invalid, with every problem listed at its file, line and column. Fix every error, and read every line it prints: the closing summary (`0 errors, 0 warnings`) counts configuration warnings only, so template warnings (a missing `head()`, a missing string, an uncredited image) are printed above a summary that says `0 warnings`, and `check --json` leaves them out altogether.
3. **Apply**, when configuration changed and a database is connected: `engine-dmo schema plan`, then `engine-dmo schema apply` (or pass `--apply` to the verb). Skip this when `engine-dmo dev up` is running in the project, since it applies safe plans itself.
4. **Render** every route the change can affect: `engine-dmo render <path> --json`. Read `status`, `errors`, `warnings` and `a11y`. Exit 1 means the page answered 400 or more, or failed to render.
5. **Repeat** until check is clean and every page renders with empty `errors` and `a11y`.

```mermaid
flowchart LR
  change["Change one thing<br/>(verb, YAML or template)"] --> check{"engine-dmo check<br/>exit 0?"}
  check -- "no: fix every error" --> change
  check -- yes --> apply["schema plan,<br/>then schema apply"]
  apply --> render{"render path --json:<br/>errors and a11y empty?"}
  render -- "no: fix" --> change
  render -- yes --> done["Next change, or<br/>Checklists"]
```

```bash
engine-dmo dev field add walk distanceKm --type number --label "Distance (km)" --param min=0 --apply
engine-dmo check
engine-dmo render /walks/cherwell-towpath --json
```

When something fails, look the message up in [Troubleshooting](/agents/troubleshooting). When you think you are finished, work through [Checklists](/agents/checklists).

## The pages in this section [#the-pages-in-this-section]

| Page | As Markdown | For |
|---|---|---|
| [Rules](/agents/rules) | `https://docs.cherwell.studio/llms.mdx/agents/rules/content.md` | Every rule, why, and what breaks |
| [Workflow](/agents/workflow) | `https://docs.cherwell.studio/llms.mdx/agents/workflow/content.md` | The order of work from a brief to a deployable site |
| [Commands for agents](/agents/commands) | `https://docs.cherwell.studio/llms.mdx/agents/commands/content.md` | What each command returns and needs |
| [Recipes](/agents/recipes) | `https://docs.cherwell.studio/llms.mdx/agents/recipes/content.md` | Checked examples of common tasks |
| [Troubleshooting](/agents/troubleshooting) | `https://docs.cherwell.studio/llms.mdx/agents/troubleshooting/content.md` | Each error message and its fix |
| [Checklists](/agents/checklists) | `https://docs.cherwell.studio/llms.mdx/agents/checklists/content.md` | What done means, with the command that proves each item |
| [The project skill and AGENTS.md](/agents/project-skill) | `https://docs.cherwell.studio/llms.mdx/agents/project-skill/content.md` | The generated guidance files |


# The project skill and AGENTS.md (/agents/project-skill)

The agent guidance files a Meridian project keeps (AGENTS.md, the meridian-project skill and the meridian skill), what writes and regenerates each, and the exact short section to paste into an AGENTS.md or skill a project already has.

A Meridian project carries three files for coding agents. All three are generated by the engine, so they always match the engine and the project; you keep them in version control and never edit them by hand.

| File | What it holds | Written by |
|---|---|---|
| `AGENTS.md` | This project: the rules, the authoring verbs, every site with its domains, locales, routes and endpoints, every type with its fields and ids, the template globals and filters | `engine-dmo guide --out AGENTS.md` |
| `.claude/skills/meridian-project/SKILL.md` | The same, with skill front matter | `engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md` |
| `.claude/skills/meridian/SKILL.md` | The engine: this section's [start page](/agents) (the golden rules, how to read more, the loop) and how to reach the rest of the handbook | `engine-dmo docs skill --out .claude/skills/meridian/SKILL.md` |

`engine-dmo init` writes all three when they are not already there (`--agents=false` writes none). After every change a `dev` verb makes, the engine rewrites `AGENTS.md` and both skills where the project has them (also under `.agents/skills/`), so they follow the configuration and the engine version. After an engine upgrade, or a change made by hand, regenerate them with the commands above. A project that has none of them (made with `--agents=false`, copied without them, or made by an engine that did not write them) gets them from the same three commands.

## What the skills say [#what-the-skills-say]

The project skill starts:

```markdown
---
name: meridian-project
description: How to change this Meridian project's configuration, content and templates by engine commands, with its own sites, types and routes. Use before editing anything under config/ or templates/.
---

# Working in this Meridian project

Generated by `engine-dmo guide` from engine v0.8.0 (template contract 1, the project declares 1). Regenerate it after changing the schema, the routes or the engine; do not edit it by hand.

## Rules
...
```

The engine skill says where the handbook is:

```markdown
---
name: meridian
description: How to build and change a website on the Meridian engine (engine-dmo): where the handbook is, with the rules, the order of work and the commands made for agents. Use before any work in a Meridian project, with the meridian-project skill for this project's own sites and types.
---

Generated by `engine-dmo docs skill` from engine v0.8.0. Do not edit it by hand.

# Working with Meridian

The handbook is at https://docs.cherwell.studio and is written for people and for agents. Read it before guessing how the engine works.

- https://docs.cherwell.studio/llms.mdx/agents/content.md: start here; the rules, the order of work, the commands made for agents and recipes for common tasks.
- https://docs.cherwell.studio/llms.txt lists every page; https://docs.cherwell.studio/llms-full.txt is the whole handbook as one Markdown file.
- https://docs.cherwell.studio/llms.mdx/<path>/content.md is one page as Markdown, such as `templates/filters`.
- `engine-dmo guide` describes this project: its sites, routes, types and fields.

The handbook describes the current engine. If this engine is older and a page disagrees with it, `engine-dmo check` and `engine-dmo describe` report what this binary does.
```

The version and the binary's name (`engine-dmo` or `engine-cms`) are those of the engine that wrote the file.

## When a project already has its own AGENTS.md [#when-a-project-already-has-its-own-agentsmd]

`init` never overwrites an `AGENTS.md`, so a repository that already has one (a monorepo, an agency's own conventions) does not get the generated file. Paste this section into it instead, with `engine-cms` in place of `engine-dmo` if the project runs on `engine-cms`:

```markdown
## Meridian

This project is a website on the Meridian engine. Before changing anything under
config/, templates/, seed/ or public/:

- Run `engine-dmo guide` for this project's sites, routes, types, fields and template
  surface, and read https://docs.cherwell.studio/llms.mdx/agents/content.md for the engine's rules and workflow.
- https://docs.cherwell.studio/llms.txt lists every other page of the handbook. `engine-dmo help --json` lists
  every command.
- Change configuration with the `engine-dmo dev` verbs, or edit YAML and run
  `engine-dmo check --fix`. Never write SQL, never type or copy an `id:`.
- Secrets are only ever `${VAR}` in config/.
- After every change: `engine-dmo check`, then `engine-dmo schema plan` and
  `engine-dmo schema apply`, then `engine-dmo render <path> --json` for each page affected.
  A destructive schema plan is for a person to approve.
- Before handing back: `engine-dmo a11y audit --all` and
  `ENVIRONMENT=production engine-dmo check --no-db`.
```

Then keep the generated guide beside it, where agents will find it, and point at it from the section:

```bash
engine-dmo guide --out docs/meridian-project.md
engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md
engine-dmo docs skill --out .claude/skills/meridian/SKILL.md
```

The two skill files are refreshed by the `dev` verbs; a guide written to another path is not, so regenerate it after changing the model.

## Agents that read neither AGENTS.md nor skills [#agents-that-read-neither-agentsmd-nor-skills]

Give the agent the start of a session in its own instructions file:

```markdown
Before any work, read https://docs.cherwell.studio/llms.mdx/agents/content.md and run `engine-dmo guide`, and follow them.
```


# Add a content type (/agents/recipes/add-a-content-type)

How an agent adds a custom content type to a Meridian project with dev type add and dev field add, what the generated schema file holds, and how to verify the type is applied and has an id for every field.

A content type is a kind of document (a walk, an event, a news story) with its own fields. Core types (`page`, `article`, `event`, `guide`, `collection`, and with `engine-dmo` `listing` and `area`) already exist; add a custom type only when none of them fits, and extend a core type when it nearly does (see [Add a field](/agents/recipes/add-a-field)).

## Steps [#steps]

<Steps>
<Step>
Check the name is free and see what exists:

```bash
engine-dmo describe project --json
```
</Step>
<Step>
Add the type. It gets `title`, `slug` (generated from the title) and `summary`:

```bash
engine-dmo dev type add walk --label Walk --plural Walks --apply
```

```text
wrote config/schema/walk.yaml
...
  + type        walk                             custom, 3 fields
  + field       walk.title                       text
  + field       walk.slug                        slug
  + field       walk.summary                     text

Plan: 3 add field, 1 add type.
applied
```

Without a database, leave out `--apply`; the file is still written and checked.
</Step>
<Step>
Add its fields, one verb each. Look up a type's parameters with `engine-dmo describe fieldtypes --json` first:

```bash
engine-dmo dev field add walk distanceKm --type number --label "Distance (km)" --param min=0 --apply
engine-dmo dev field add walk difficulty --type select --options easy,moderate,hard --label Difficulty --required --index --apply
engine-dmo dev field add walk photo --type asset --label Photo --apply
engine-dmo dev field add walk body --type portable_text --label "Route description" --apply
```

`--index` is what lets a listing page filter or sort on the field. `--required` makes the field required at publish.
</Step>
<Step>
Read the result:

```yaml
# config/schema/walk.yaml
key: walk
id: typ_bm5h7rk9j6
label: { en: Walk }
plural: { en: Walks }
ordering: { field: title, direction: asc }

fields:
  - { name: title, id: fld_4crq7vfgva, type: text, required: true, index: true }
  - { name: slug, id: fld_hbjpyckec7, type: slug, source: title, required: true }
  - { name: summary, id: fld_96fyjc4qs9, type: text, multiline: true, max: 280 }
  - { name: distanceKm, id: fld_azkam2rfyt, type: number, label: { en: Distance (km) }, min: 0 }
  - { name: difficulty, id: fld_8tvr5aq659, type: select, label: { en: Difficulty }, required: true, index: true, options: [{ value: easy, id: opt_z9ynd1s738 }, { value: moderate, id: opt_9kkqg3nqew }, { value: hard, id: opt_c5mcqxkfct }] }
  - { name: photo, id: fld_crnr761s22, type: asset, label: { en: Photo } }
  - { name: body, id: fld_yms2apxswc, type: portable_text, label: { en: Route description } }
```

Your ids will differ: they are minted for your project. Never copy these.
</Step>
<Step>
Give the type a route and templates: [Add a route and its template](/agents/recipes/add-a-route).
</Step>
</Steps>

## Writing the file by hand [#writing-the-file-by-hand]

When you need options the verbs do not offer (option labels, editor groups, `structured_data`, validation rules), write the schema file yourself without ids and let the engine add them:

```yaml
# config/schema/walk.yaml
key: walk
label: { en: Walk }
plural: { en: Walks }
fields:
  - { name: title, type: text, required: true, index: true }
  - { name: slug, type: slug, source: title, required: true }
  - { name: summary, type: text, multiline: true, max: 280 }
```

```bash
engine-dmo check --fix
```

`check --fix` writes `typ_` and `fld_` ids into the file, keeping your comments. [Content types](/content-modelling/types) lists every key a type file takes.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo schema plan        # exits 0, "No changes", after apply
engine-dmo describe type walk
```

`describe type` prints every field with its id and its translate mode (`translate locale` for text that differs per locale, `translate none` for values shared by every locale).

## Options of dev type add [#options-of-dev-type-add]

| Flag | Effect |
|---|---|
| `--label <name>` | The type's name in the source locale |
| `--plural <name>` | Its plural, used as the index page's title |
| `--site <key>` | A type of one site only, in that site's schema directory |
| `--sites <a,b>` | Limit a shared type to these sites |
| `--dry-run` | Print the diff, write nothing |
| `--apply` | Apply the schema plan when it is not destructive |

The type key is lowercase letters, digits and underscores (`walk`, `tour_operator`); `tourOperator` and `tour-operator` are refused. Field names may be camel case (`distanceKm`). Field names `id`, `type`, `uri`, `url`, `status`, `locale`, `tags`, `seo`, `noindex`, `author`, `organisation`, `createdAt`, `updatedAt`, `publishedAt`, `redirectFrom` and `translations` are reserved.


# Add a field (/agents/recipes/add-a-field)

How an agent adds, labels, changes, renames and removes fields on custom and core Meridian types, including select options with labels, relations and boolean filters, with the commands, the YAML they write and the pitfalls of each verb.

A field is one value of a document: a number, a select, a relation, a photo, rich text. Fields are declared in the type's schema file under `config/schema/`. Add them with `engine-dmo dev field add`; it writes the field with its id, checks the project and, with `--apply`, applies the schema.

## Add a field [#add-a-field]

```bash
engine-dmo dev field add walk distanceKm --type number --label "Distance (km)" --param min=0 --apply
```

```yaml
# written into config/schema/walk.yaml
  - { name: distanceKm, id: fld_azkam2rfyt, type: number, label: { en: Distance (km) }, min: 0 }
```

| Flag | Effect |
|---|---|
| `--type <type>` | The field type. `engine-dmo describe fieldtypes` lists them: `text`, `slug`, `number`, `money`, `boolean`, `select`, `date`, `datetime`, `recurrence`, `geo`, `geo_shape`, `address`, `phone`, `opening_hours`, `asset`, `link`, `video`, `relation`, `portable_text`, `blocks`, `repeater`, `seo`, `form` |
| `--label <text>` | The label in the source locale |
| `--help-text <text>` | Help shown under the field in the editor |
| `--required` | Required at publish |
| `--index` | Projected for listing, filtering and sorting. Needed for `query().where()`, `orderBy()` and index page facets |
| `--translate <mode>` | `none`, `locale`, `language` or `group`. Leave it out for the type's default (`describe fieldtypes` shows it) |
| `--options a,b,c` | A select's option values, each given an id |
| `--param key=value` | Any parameter of the type, in YAML (`max=280`, `multiline=true`, `to=area`, `multiple=true`). Repeatable |
| `--after <field>` | Place it after this field. On a core type it can name only a field of your own `extends:` file |
| `--group <key>` | Put it in an editor group (`dev group add` makes one) |
| `--site <key>` | A field only this site offers, on a shared type |

### A core type [#a-core-type]

On a core type (`page`, `article`, `event`, `guide`, `collection`, `listing`, `area`) the verb writes an `extends:` file the first time:

```bash
engine-dmo dev field add page contactForm --type form --label "Form on this page" --apply
```

```yaml
# config/schema/page.yaml
extends: page
fields:
  - { name: contactForm, id: fld_n65eek1b0r, type: form, label: { en: Form on this page } }
```

An `extends:` file adds fields after the core ones; it cannot remove or change them. `--after title` on a core type exits 3 with `--after names "title", which is not a field in schema/page.yaml`: a core field cannot be an anchor. The core fields of each type are in [Core types](/content-modelling#core-types); `engine-dmo describe type page` lists them marked `core`. The core `page` has only `title` and `slug`, so most sites add a summary and a body first:

```bash
engine-dmo dev field add page summary --type text --param multiline=true --param max=280 --label Summary --apply
engine-dmo dev field add page body --type portable_text --label Body --apply
```

### A select with labelled options [#a-select-with-labelled-options]

`--options` gives values without labels, and a template printing `.label` then shows the raw value. Give each option a label: start the field with one option, add the rest with `dev option add --label`, then add `label:` to the first option by hand, keeping its id:

```bash
engine-dmo dev field add walk difficulty --type select --options easy --label Difficulty --required --index --apply
engine-dmo dev option add walk difficulty moderate --label Moderate --apply
engine-dmo dev option add walk difficulty hard --label Hard --apply
```

Do not skip the hand edit: `check` does not warn about an option with no label at all (only about a label that lacks a locale), and the facet and `.label` then print `easy`. The result, after `label: { en: Easy }` is added to the first option by hand:

```yaml
  - { name: difficulty, id: fld_8tvr5aq659, type: select, label: { en: Difficulty }, required: true, index: true, options: [{ value: easy, id: opt_z9ynd1s738, label: { en: Easy } }, { value: moderate, id: opt_9kkqg3nqew, label: { en: Moderate } }, { value: hard, id: opt_c5mcqxkfct, label: { en: Hard } }] }
```

A select needs at least one option: `dev field add ... --type select` without `--options` is refused.

### A relation [#a-relation]

```bash
engine-dmo dev field add walk startsAt --type relation --param to=page --param multiple=true --label "Starts at" --apply
```

```yaml
  - { name: startsAt, id: fld_2bptk4rq2s, type: relation, label: { en: Starts at }, to: page, multiple: true }
```

Add `--index` when pages will query by it (`query('walk').where('startsAt', entry)`). See [Relations](/content-modelling/relations).

### A boolean filter [#a-boolean-filter]

```bash
engine-dmo dev field add walk accessible --type boolean --index --label "Step-free" --after difficulty --apply
```

## Change a field [#change-a-field]

```bash
engine-dmo dev field set walk distanceKm --param max=100 --apply
engine-dmo dev field set walk distanceKm --help-text "Round to one decimal place" --apply
```

`dev field set --label` replaces the whole label map with the source locale's label, dropping its translations. On a multilingual project, change a label by editing the YAML instead.

## Rename a field [#rename-a-field]

```bash
engine-dmo dev field rename walk distanceKm lengthKm --apply
```

The handle changes, the id and every stored value stay, and the old handle stays as an alias (`aliases: [distanceKm]`) so templates keep working. `check` then warns at each template still using the old handle; update them and retire the alias with `engine-dmo schema alias retire walk.distanceKm`. `--no-alias` drops the alias at once.

## Remove a field [#remove-a-field]

```bash
engine-dmo dev field remove walk accessible --apply
```

Values stay stored under the field's id (kept under `_orphaned`), and the plan says how many documents hold one. If any do, the plan is destructive: `--apply` exits 2 and a person must approve it with `engine-dmo schema apply --allow-destructive`. Remove every template use of the field first, or `check` fails.

`dev field remove` cannot edit a field written in block style (one key per line); it reports `the edit would not parse`. Delete those lines from the YAML by hand, then run `engine-dmo check` and `engine-dmo schema plan`.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo schema plan
engine-dmo describe type walk
```

Then render a page that prints the field: `engine-dmo render /walks/cherwell-towpath --json`. A field added after content exists is empty on every document until edited or reseeded; a new `--required` field blocks publishing those documents until it is filled.


# Add a route and its template (/agents/recipes/add-a-route)

How an agent gives a content type addresses on a site with dev route add, writes the entry and index templates a route needs, and verifies them with describe route and render.

A route gives a type's documents addresses on one site: an entry page per document (`/walks/{slug}`) and, optionally, an index page listing them (`/walks`). A route with no template is refused by `check`, so the route and its templates land together.

The recipe touches these files, and the engine reads them in this order when a request comes in:

```mermaid
flowchart LR
  req["GET /walks/cherwell-towpath"] --> routes["config/sites/main/routes.yaml<br/>uri /walks/{slug}"]
  routes --> doc["The published walk<br/>with that slug and locale"]
  doc --> chain{"walk/entry.html in<br/>templates/main/?"}
  chain -- yes --> site["templates/main/walk/entry.html"]
  chain -- no --> shared["templates/_shared/walk/entry.html"]
  site --> base["extends base.html"]
  shared --> base
```

## Steps [#steps]

<Steps>
<Step>
Add the route. `--scaffold` writes the entry template from the type's fields. It loads the whole configuration to do so, so export every `${VAR}` first (`DATABASE_URL`, and `SIGNING_KEY` once `engine.yaml` names it): with one unset, the verb writes `routes.yaml`, exits 3 without the template, and a second run says `nothing to change`. Recover with `engine-dmo new template walk/entry.html`.

```bash
engine-dmo dev route add walk "/walks/{slug}" --index /walks --scaffold --apply
```

```yaml
# config/sites/main/routes.yaml
routes:
  - type: page
    id: rte_ajdbyvntec
    uri: "/{slug}"
  - { type: walk, id: rte_34agwcmxkh, uri: "/walks/{slug}", index: /walks }

home: { type: page, slug: home }
```
</Step>
<Step>
Write the index template, which `--scaffold` does not:

```bash
engine-dmo new template walk/index.html
```

Until it exists, `check` fails with `type "walk" has an index route and no walk/index.html on site main`. The scaffold is an empty `body` block with no `h1`, so `render /walks --json` reports `a page has exactly one h1, this one has 0` until you write it ([Listing page](/agents/recipes/listing-page)).
</Step>
<Step>
Replace the scaffolds with real templates. The entry template receives the document as `entry` and under the type's key (`walk`):

```jinja
{# templates/_shared/walk/entry.html #}
{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ walk.title }}</h1>
  {{ walk.photo.figure("hero", priority=true) }}
  {% if walk.summary %}<p>{{ walk.summary }}</p>{% endif %}
  <dl>
    <dt>{{ t('walks.difficulty') }}</dt><dd>{{ walk.difficulty.label }}</dd>
    {% if walk.distanceKm %}<dt>{{ t('walks.length') }}</dt><dd>{{ t('walks.distance', 'km', walk.distanceKm|number) }}</dd>{% endif %}
  </dl>
  {% if walk.body %}<div class="prose">{{ walk.body|ptext }}</div>{% endif %}
</article>
{% endblock %}
```

```yaml
# config/strings/en.yaml
strings:
  walks.difficulty: Difficulty
  walks.length: Length
  walks.distance: "{km} km"
```

`figure("hero")` needs a `hero` transform in `config/images.yaml` ([Responsive images](/agents/recipes/responsive-images)). An empty asset field prints nothing through `figure()`, `img()` and `picture()`, so the call needs no `{% if %}` of its own; wrap it only when you add markup around it. Write the index template next: [Listing page](/agents/recipes/listing-page).
</Step>
</Steps>

## Verify [#verify]

```bash
engine-dmo check
engine-dmo describe route /walks/cherwell-towpath
engine-dmo render /walks/cherwell-towpath --json
engine-dmo render /walks --json
```

`describe route` says which route and template answered, and `--json` adds the whole context with real values. `render --json` must show `"status": 200`, `"errors": []` and `"a11y": []`. A path that matches no published document answers 404 with `kind: not_found`.

## Route options [#route-options]

Edit `routes.yaml` by hand for anything `dev route add` does not set; `check --fix` keeps the ids.

| Key | Use it for |
|---|---|
| `uri` | The entry path. One string for every locale, or a map per locale: `{ en: "/walks/{slug}", cy: "/teithiau/{slug}" }` |
| `index` | The index path, one string or per locale. Needs `<type>/index.html` |
| `paginate` | Entries per index page |
| `facets` | Indexed fields the index can be filtered by (`?difficulty=easy`) |
| `nest: true` | Entries nest under their parent's path (`/about/our-history`) |
| `priority` | Orders two patterns of one shape, lowest first. Two routes of one shape and priority are refused as `ambiguous`. Each keeps answering for its own documents, so the number settles the check and hides nothing ([DMO directory](/agents/recipes/dmo-directory#route-listings-and-areas)) |
| `feed`, `calendar` | An RSS, Atom and JSON feed, or an iCalendar feed, of the route |

`home: { type: page, slug: home }` names the home page (or `home: { type: homepage }` for a singleton type). `special: { search: /search }` routes the search page. [routes.yaml](/reference/configuration/routes) lists every key.

## Where templates live [#where-templates-live]

Templates resolve along the site's chain: `templates/<site>/` first, then `templates/_shared/`. Put templates every site uses in `_shared`, and a site's own version of one in `templates/<site>/` (`engine-dmo new template walk/entry.html --site town --from-shared` copies it). `engine-dmo describe template walk/entry.html --site town` says which file wins.

| Template | Rendered for |
|---|---|
| `<type>/entry.html` | A document's page |
| `<type>/index.html` | The route's index |
| `<type>/landing.html` | A landing page (`engine-dmo`), falling back to `index.html` |
| `search.html` | The search route |
| `errors/404.html`, `errors/500.html` | Errors |
| `base.html` | The layout every page extends (a convention, not a requirement) |


# Claims (/agents/recipes/claims)

How an agent lets a business claim its listing on engine-dmo, seeding an organisation for each listing, writing the claim link that has no helper, reading the verification mail, and verifying the form from a script.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A claim is how a business with no portal account takes control of its entry: someone fills in a form, proves their email address, and staff approve. The engine draws the whole flow under `/members/claim/`. Your work is to give each listing an organisation and to link to the form. This recipe follows the [DMO directory](/agents/recipes/dmo-directory), and its examples use the locale code `en`: replace it with your source locale.

```mermaid
sequenceDiagram
  participant C as Claimant
  participant E as Engine
  participant S as Staff
  C->>E: GET /members/claim/(organisation id)
  C->>E: POST the form
  E-->>C: Mail with a confirm link
  C->>E: Follow the link: pending becomes verified
  S->>E: Approve in the admin
  E-->>C: Mail with a portal invitation
```

## Seed an organisation for each listing [#seed-an-organisation-for-each-listing]

A claim is always of an existing organisation; it never makes one. So a listing can only be claimed if it has an organisation, and a directory of unclaimed businesses seeds one per listing. A name is enough:

```yaml
# seed/organisations/ferry-cafe.yaml
name: The Ferry Cafe
```

```yaml
# seed/documents/listing/ferry-cafe.yaml
organisation: ferry-cafe
locales:
  en:
    title: The Ferry Cafe
    slug: ferry-cafe
    summary: Tea and cake by the old ferry steps.
    location: { lat: 51.8120, lon: -2.7150, precision: rooftop }
    primaryTag: { id: eat-drink.cafe, type: tag }
    category: eat-drink
    area: { id: monmouth, type: area }
publish: [en]
```

`organisation:` is the organisation's file name, and sits at the top level, not under `locales:`. Give an `email` or `website` where you know them: they are what the automatic signals compare the claimant's address with. See [Organisations and people](/content-modelling/seeding-and-importing#organisations-and-people) for the file's other keys. An organisation with no membership holds the `none` tier in `member_editable`.

## Link to the form [#link-to-the-form]

There is no helper for this address, which makes it the one exception to the rule that links come from helpers ([Rules](/agents/rules#templates)). Write it out in the listing's template:

```jinja
{# in templates/_shared/listing/entry.html, inside the article #}
{% if entry.organisation %}
<p><a href="/members/claim/{{ entry.organisation.id }}">{{ t('listing.claim') }}</a></p>
{% endif %}
```

```yaml
# config/strings/en.yaml (add to the file's strings:)
strings:
  listing.claim: Is this your business?
```

`check` accepts this `href` as it is, with the variable after a fixed path. Use the site's portal path in place of `/members` if `server.portal_path` or the site's `portal.yaml` moves it. `entry.organisation` is set only for the page's own entry, so this link belongs on the entry page and cannot go on a card in a list. The form answers not found if `auth.member.registration` is `invite_only`, and the portal must not be `mode: "off"`.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo seed verify
engine-dmo seed reset --confirm && engine-dmo seed apply
engine-dmo render /places/ferry-cafe | grep -o '/members/claim/[^"]*'
```

The last prints the link. The form itself is the portal's, so `render` cannot show it. With `engine-dmo dev up` running:

```bash
curl -s -o claim.html -w '%{http_code}\n' http://localhost:8080/members/claim/<organisation id>
TS=$(grep -o 'name="_ts" value="[^"]*"' claim.html | cut -d'"' -f4)
curl -s -o /dev/null -w '%{http_code}\n' -X POST --data-urlencode "_ts=$TS" \
  -d 'name=Sam&email=sam@ferrycafe.example&role=Owner' http://localhost:8080/members/claim/<organisation id>
engine-dmo crm claims list --status pending
```

Both answer 200 and the claim is listed as `pending`. To carry it on you need the mail, whose confirm link is `/members/claim/verify/<token>` on the address you posted to ([Read the mail](/agents/recipes/partner-portal#read-the-mail)). Following it makes the claim `verified` and puts it in the admin's **Claims** queue, where a person decides it. If you cannot read mail or sign in as staff, say the rest is the person's.

The form's challenge differs from an [enquiry form's](/agents/recipes/enquiry-form#post-it-from-a-script). It is in the page's `_ts` field, with no fetch and no minimum fill time. Its proof of work is a decimal number in `_pow` that makes `sha256(_ts + number)` start with 16 zero bits, about 65,000 tries, where a declared form asks for 8. It is optional here too: a claim with no proof is accepted, and is only never approved automatically.

See [Claims](/dmo/claims) for the signals, the score, the review queue and the settings.


# DMO directory (/agents/recipes/dmo-directory)

How an agent builds a destination directory on engine-dmo, extending the core listing and area types, loading the tag vocabulary, routing areas beside pages at /{slug}, filtering by place facets, printing structured data, seeding complete listings with hours, address and phone, and verifying it all.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A directory is the core `listing` type (a business or place with a title, summary, point and primary tag) extended with your fields, and the `area` type (a place with a boundary) that listings belong to. A listing filtered by area matches listings related to the area, to any area within it, and listings with no area whose point falls inside its boundary.

Every example here uses the locale code `en`, the one `init` writes. **Replace `en` with your project's source locale in every label, slug, string and seed file.** If you moved a UK site to `en-GB` in [Set the basics](/agents/workflow), that means `en-GB` here too. Pasted with the wrong code, labels fail `check --strict` with `the label of field priceRange has no translation for en`, and landing slugs only warn and are then not used.

## Set the country [#set-the-country]

In `config/sites/main/site.yaml`, give the site its country:

```yaml
site:
  id: site_0s14b7ndg9            # keep the id init wrote
  name: { en: "Visit the Wye Valley" }
  domains: [localhost, "localhost:8080"]
  default: true
  country: GB
```

`country` is what the admin's editors start from: the region a phone number typed without `+` is read in, and the country an address form offers first. `seed apply` and `content create` do not read it, so a bare national number in a seed file is refused with `Enter the number with its country code, starting with +`. Give the region in the value (below), or `region: GB` on the field.

## Extend the types [#extend-the-types]

Write the files by hand, without ids, then let `check --fix` add them:

```yaml
# config/schema/listing.yaml
extends: listing
label: { en: Listing }
plural: { en: Places to stay and visit }
fields:
  - name: description
    type: portable_text
    label: { en: Description }
  - name: heroImage
    type: asset
    label: { en: Main photo }
  - name: address
    type: address
    label: { en: Address }
  - name: phone
    type: phone
    label: { en: Phone }
  - name: website
    type: link
    kinds: [{ of: url }]
    label: { en: Website }
  - name: openingHours
    type: opening_hours
    holiday_calendar: uk-england-wales
    label: { en: Opening hours }
  - name: priceRange
    type: text
    max: 8
    label: { en: Price range }
  - name: area
    type: relation
    to: area
    index: true
    label: { en: Area }
  - name: category
    type: select
    index: true
    label: { en: Category }
    options:
      - { value: stay, label: { en: Places to stay } }
      - { value: eat-drink, label: { en: Eat and drink } }
      - { value: see-do, label: { en: Things to do } }
structured_data:
  type: LocalBusiness
  subtype:
    field: category
    values: { stay: LodgingBusiness, eat-drink: Restaurant }
  map:
    description: summary
    image: heroImage
    geo: location
    address: address
    telephone: phone
    sameAs: website
    openingHoursSpecification: openingHours
    priceRange: priceRange
```

```yaml
# config/schema/area.yaml
extends: area
label: { en: Place }
plural: { en: Places to go }
fields:
  - name: parent
    type: relation
    to: area
    label: { en: Part of }
```

```yaml
# config/images.yaml
transforms:
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
```

The core listing fields (`title`, `slug`, `summary`, `location`, `primaryTag`) and area fields (`title`, `slug`, `summary`, `boundary`, `centre`) cannot be removed or changed. Give every label a value in every locale the site enables.

The `structured_data` block is what turns a listing into a `LodgingBusiness` or `Restaurant` in the page's JSON-LD; `jsonld()` in the layout prints it ([Print the structured data](#print-the-structured-data)). Leave a listing's `priceRange` out of the mapping and `check` warns, and `check --strict` fails: see [Troubleshooting](/agents/troubleshooting#configuration) for how to choose.

## Load the tag vocabulary [#load-the-tag-vocabulary]

`primaryTag` is required on every listing, and must name a tag in the vocabulary, so a listing cannot be published without this file:

```yaml
# config/tags/vocabulary.yaml
tags:
  - key: stay
    kind: topic
    public: true
    label: { en: Places to stay }
    children:
      - key: stay.hotel
        label: { en: Hotels and inns }
      - key: stay.campsite
        label: { en: Campsites }
  - key: eat-drink
    kind: topic
    public: true
    label: { en: Eat and drink }
    children:
      - key: eat-drink.pub
        label: { en: Pubs }
      - key: eat-drink.cafe
        label: { en: Cafes }
```

| Rule | Detail |
|---|---|
| Loading it | `seed apply` loads the file; `engine-dmo tags import` loads it into a database without seeding. Existing keys are left alone, and from then on staff own the vocabulary in the admin |
| A child's key | The full dotted key: `stay.hotel`, never `hotel`. A key not under its parent stops `seed apply` with `the vocabulary has 1 problems` |
| `kind` | `topic` (what a place is), `audience`, `operational` or `internal`. It defaults to `topic` at the top level, and a child takes its parent's. `primaryTag` is for `topic` tags |
| `public` | Whether the tag is listed to the public, in the content API's tag list. It defaults to `true` at the top level, and a child takes its parent's. Set `public: false` on staff working tags |
| Two levels | Write two. The admin's picker for `primaryTag` offers only `topic` tags at the second level, so a flat vocabulary leaves editors nothing to choose. `seed apply` does not hold you to this: it refuses only a key not in the vocabulary (`nope is not a vocabulary tag`) |

`primaryTag` and the `category` select look alike and do different jobs:

| | `category` select | `primaryTag` |
|---|---|---|
| Lives in | `config/schema/listing.yaml`, changed by a schema change | The vocabulary, changed by staff in the admin |
| Shape | A short flat list you choose | A tree, as fine as "Pubs" |
| Used for | Route facets and landing pages. A landing's `category` may be a select, and may not be a tag | What the listing is: its label in the editor, and the group a [member report](/dmo/member-reports) compares a business with |
| Needed | Only if you want it | Always: it is a core field |

So a pub has `category: eat-drink` for the visitor's filter and `primaryTag: { id: eat-drink.pub, type: tag }` for what it is.

## Route listings and areas [#route-listings-and-areas]

`init` routes `page` at `/{slug}`, and an area wants the same shape. Two routes of one shape with one priority are refused: `routes "/{slug}" (page@en) and "/{slug}" (area@en) are ambiguous: same shape and priority; give one a priority`. Keep the page route and add `priority:`:

```yaml
# config/sites/main/routes.yaml
routes:
  - type: page
    id: rte_rabyc471nc            # keep the id init wrote
    uri: "/{slug}"
    priority: 10
  - type: listing
    uri: "/places/{slug}"
    index: "/places"
    paginate: 24
    facets: [area, category]
  - type: area
    uri: "/{slug}"
    nest: true
    index: "/areas"

home: { type: page, slug: home }
```

```bash
engine-dmo check --fix
engine-dmo schema plan
engine-dmo schema apply
```

`check --fix` writes the `fld_`, `opt_` and `rte_` ids. With `nest: true` and a `parent` relation, a village sits under its valley (`/wye-valley/monmouth`). `check` keeps failing with `no template found for type "listing"` until the templates below exist; `schema plan` and `schema apply` work meanwhile.

`priority` settles the shape check, and it does not make one type hide the other: a document's address is stored when it is published and the engine looks the path up by that, so `/about` reaches the page and `/monmouth` the area whichever route has the higher number. The price is that one address holds one document. Publishing a page and an area with the same slug is refused, and `seed apply` stops with `duplicate key value violates unique constraint "document_site_uri_path_idx"`: keep their slugs apart, or route areas under a word of their own (`uri: "/towns/{slug}"`, `index: "/towns"`), which needs no `priority` and cannot collide.

## Print the structured data [#print-the-structured-data]

`templates/_shared/base.html` must print `{{ jsonld() }}` straight after `{{ head() }}`, as the [workflow's layout](/agents/workflow) does. Without it the mapping above is never printed, and only a `warning:` line that the summary does not count says so.

## Write the templates [#write-the-templates]

```jinja
{# templates/_shared/area/entry.html #}
{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ entry.title }}</h1>
  {% if entry.summary %}<p>{{ entry.summary }}</p>{% endif %}
  {{ entry.boundary.centroid.staticMap(width=640, zoom=12) }}
  {% set places = query('listing').where('area', entry).orderBy('title').limit(24).all() %}
  {% if places %}
  <h2>{{ t('area.places') }}</h2>
  <ul>{% for p in places %}<li><a href="{{ p.uri|url }}">{{ p.title }}</a></li>{% endfor %}</ul>
  {% endif %}
</article>
{% endblock %}
```

```jinja
{# templates/_shared/area/index.html #}
{% extends "base.html" %}
{% block body %}
<h1>{{ t('areas.title') }}</h1>
<ul>{% for area in items %}<li><a href="{{ area.uri|url }}">{{ area.title }}</a></li>{% endfor %}</ul>
{% endblock %}
```

```jinja
{# templates/_shared/listing/index.html #}
{% extends "base.html" %}
{% block body %}
<h1>{% if page.landing %}{{ landing.heading }}{% else %}{{ t('places.title') }}{% endif %}</h1>
{% if facets %}
<nav aria-label="{{ t('facets.label') }}">
  {% for facet in facets %}
  <h2>{{ facet.label }}</h2>
  <ul>
    {% for v in facet.values %}<li><a href="{{ v.url|url }}"{% if v.selected %} aria-current="true"{% endif %}>{{ v.label }} ({{ v.count }})</a></li>{% endfor %}
  </ul>
  {% if facet.selected %}<p><a href="{{ facet.clearUrl|url }}">{{ t('facets.clear') }}</a></p>{% endif %}
  {% endfor %}
</nav>
{% endif %}
<ul class="cards">
  {% for listing in items %}
  <li data-mrd-impression="{{ listing.id }}">
    {% if listing.heroImage %}{{ listing.heroImage.img("card", alt="") }}{% if listing.heroImage.credit %}<small>{{ listing.heroImage.credit }}</small>{% endif %}{% endif %}
    <h2><a href="{{ listing.uri|url }}">{{ listing.title }}</a></h2>
    <p>{{ listing.summary }}</p>
  </li>
  {% endfor %}
</ul>
{{ impressions() }}
{% endblock %}
```

A complete listing page, with its photograph, address, phone, website and hours. `reveal()` and `track()` count the clicks towards the business's [member report](/dmo/member-reports), and both go through `|url` like any variable in an `href`:

```jinja
{# templates/_shared/listing/entry.html #}
{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ entry.title }}</h1>
  {% if entry.heroImage %}{{ entry.heroImage.figure("hero", priority=true) }}{% endif %}
  <p>{{ entry.summary }}</p>
  {% if entry.description %}{{ entry.description|ptext }}{% endif %}

  <h2>{{ t('listing.contact') }}</h2>
  {% if entry.address %}
  <address>{% for line in entry.address.formatted %}{{ line }}{% if not forloop.Last %}<br>{% endif %}{% endfor %}</address>
  {% endif %}
  {% if entry.phone %}<p><a href="{{ reveal(entry, 'phone', entry.phone)|url }}">{{ entry.phone.display }}</a></p>{% endif %}
  {% if entry.website.url %}<p><a href="{{ track(entry, 'website', entry.website.url)|url }}" rel="noopener">{{ t('listing.website') }}</a></p>{% endif %}

  {% set hours = entry.openingHours %}
  {% if hours and not hours.isEmpty %}
  <h2>{{ t('listing.hours') }}</h2>
  <p>{% if hours.isOpenAt(now) %}{{ t('listing.open_now') }}{% else %}{{ t('listing.closed_now') }}{% endif %}</p>
  <table>
    <caption>{{ t('listing.hours_caption') }}</caption>
    <thead><tr><th scope="col">{{ t('listing.day') }}</th><th scope="col">{{ t('listing.times') }}</th></tr></thead>
    <tbody>
      {% for day in hours.week(now) %}
      <tr{% if day.isToday %} aria-current="date"{% endif %}><th scope="row">{{ day.label }}</th><td>{{ day.periodsLabel }}</td></tr>
      {% endfor %}
    </tbody>
  </table>
  {% if hours.note %}<p>{{ hours.note }}</p>{% endif %}
  {% endif %}
</article>
{% endblock %}
```

```yaml
# config/strings/en.yaml (add to the file's strings:)
strings:
  a11y.skip: Skip to content
  area.places: Places here
  areas.title: Towns and villages
  places.title: Places to stay and visit
  facets.label: Filter these places
  facets.clear: Clear
  listing.contact: Find and contact
  listing.website: Visit the website
  listing.hours: Opening hours
  listing.hours_caption: Opening hours this week
  listing.day: Day
  listing.times: Times
  listing.open_now: Open now
  listing.closed_now: Closed now
```

To add a form that asks the business a question, follow [Enquiry form](/agents/recipes/enquiry-form#a-form-about-a-listing); for a "this is my business" link, [Claims](/agents/recipes/claims).

## Maps [#maps]

`staticMap()` draws a map image on the server from your tile provider and serves it from the site's own origin, with the provider's credit, so the visitor's browser never contacts the provider. Configure the provider; the key is a secret:

```yaml
# config/engine.yaml
maps:
  tiles: https://tiles.example.org/{z}/{x}/{y}.png?key={key}
  key: ${MAP_TILES_KEY}
  attribution: "© Example Maps © OpenStreetMap contributors"
```

| Value | Map call |
|---|---|
| A listing's point | `{{ listing.location.staticMap(width=480, zoom=15) }}` |
| An address's point | `{{ listing.address.geo.staticMap() }}` |
| An area | `{{ entry.boundary.centroid.staticMap(zoom=12) }}` |

The map's alt text is "Map showing where `<title>` is" unless you pass `alt=`. Without `maps.tiles` it prints nothing. An area's derived `centre` (when the editor left it empty) prints no map: use the boundary's `centroid`.

## Seed areas and listings [#seed-areas-and-listings]

```yaml
# seed/documents/area/monmouth.yaml
locales:
  en:
    title: Monmouth
    slug: monmouth
    summary: The market town where the Monnow meets the Wye.
    boundary:
      type: Polygon
      coordinates: [[[-2.75, 51.80], [-2.68, 51.80], [-2.68, 51.84], [-2.75, 51.84], [-2.75, 51.80]]]
publish: [en]
```

A complete listing. Each file holds every locale's values under `locales:`; `organisation:` is top-level, and names the file below:

```yaml
# seed/documents/listing/old-bridge-inn.yaml
organisation: old-bridge-inn
locales:
  en:
    title: The Old Bridge Inn
    slug: old-bridge-inn
    summary: A riverside inn with six rooms and a kitchen open every day.
    location: { lat: 51.8112, lon: -2.7163, precision: rooftop }
    primaryTag: { id: stay.hotel, type: tag }
    category: stay
    area: { id: monmouth, type: area }
    heroImage: { asset: old-bridge }
    priceRange: "££"
    address:
      country: GB
      components:
        line1: 4 Wye Bridge Street
        locality: Monmouth
        postal_code: NP25 3DY
      geo: { lat: 51.8112, lon: -2.7163 }
    phone: { raw: "01600 712345", region: GB }
    website: { of: url, url: "https://oldbridgeinn.example" }
    openingHours:
      timezone: Europe/London
      regular:
        - { day: mon, periods: [{ open: "11:00", close: "23:00" }] }
        - { day: tue, periods: [{ open: "11:00", close: "23:00" }] }
        - { day: wed, periods: [{ open: "11:00", close: "23:00" }] }
        - { day: thu, periods: [{ open: "11:00", close: "23:00" }] }
        - { day: fri, periods: [{ open: "11:00", close: "23:30" }] }
        - { day: sat, periods: [{ open: "10:00", close: "23:30" }] }
        - { day: sun, periods: [{ open: "12:00", close: "17:00" }] }
      holiday_calendar: uk-england-wales
      holiday_behaviour: normal
      notes: { en: Food is served until 21:00. }
publish: [en]
```

The photograph is a file with a YAML file of the same name beside it. Use the person's own photographs; `seed/assets/old-bridge.jpg` goes with:

```yaml
# seed/assets/old-bridge.yaml
title: The Old Bridge Inn from the river
alt: { en: A stone inn beside an arched bridge over a wide river }
credit: Photograph by A. Walker
```

The organisation is the business behind the listing, with its contact and membership ([every key](/content-modelling/seeding-and-importing#organisations-and-people)). Skip this file and `organisation:` above if the brief has no members or claims:

```yaml
# seed/organisations/old-bridge-inn.yaml
name: The Old Bridge Inn
status: active
email: stay@oldbridgeinn.example
website: https://oldbridgeinn.example
contacts:
  - name: Sam Owner
    email: sam@oldbridgeinn.example
    role: General manager
    partner_role: owner
    is_primary: true
```

## Verify [#verify]

```bash
engine-dmo seed verify
engine-dmo seed reset --confirm && engine-dmo seed apply
engine-dmo check
engine-dmo check --strict
engine-dmo render /monmouth --json
engine-dmo render /places/old-bridge-inn --json
engine-dmo render '/places?category=stay' --json
engine-dmo render /areas --json
engine-dmo render /places/old-bridge-inn | grep -o 'application/ld+json'
```

Each `--json` answers 200 with empty `errors` and `a11y`; the last prints `application/ld+json`. The area page lists its listings and, with `maps.tiles` set, a `<figure class="mrd-map">`. See [Directory](/dmo/directory) for the rest of the template surface and [Landing pages](/agents/recipes/landing-pages) for clean place-and-category pages.

One gap to know: the JSON-LD `PostalAddress` carries the locality, postal code and country of a seeded address but not `streetAddress`, because `components.line1` does not reach it in this version. The printed `<address>` has every line.


# Enquiry form (/agents/recipes/enquiry-form)

How an agent adds a contact form or a form about one listing to a Meridian site with dev endpoint add, writes the response, error and email templates the endpoint names, places the form on a page, and verifies it with check, render and a scripted post.

A form is a declared endpoint: a path, its inputs with their rules and labels, spam defences, and the steps run on a valid submission (store it, send mail, subscribe). No code is written. The form a visitor sees is drawn from the declaration, with labels, errors and CSRF handling.

What happens when a visitor posts the form:

```mermaid
sequenceDiagram
  participant V as Visitor
  participant E as Engine
  participant M as Mail queue
  V->>E: GET /contact (the page with the form)
  E-->>V: page, form drawn from endpoints.yaml
  V->>E: POST /contact (or /cy/contact)
  E->>E: rate limit, CSRF, spam defences
  alt input invalid
    E-->>V: on_error: the form again, with errors
  else input valid
    E->>E: store: the enquiry
    E->>M: mail: contact-to-staff
    E->>M: mail: enquiry-receipt
    E-->>V: fragment: enquiry-sent.html
  end
```

## Declare the endpoint [#declare-the-endpoint]

```bash
engine-dmo dev endpoint add contact --apply
```

```yaml
# config/sites/main/endpoints.yaml
endpoints:
  - key: contact
    id: end_4n96ztbdf6
    path: /contact
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    spam: { proof_of_work: true, honeypot: true, min_fill_time: 3s }
    input:
      name:    { type: text, max: 120, required: true, autocomplete: name, label: { en: Your name } }
      email:   { type: text, format: email, required: true, autocomplete: email, label: { en: Your email address } }
      message: { type: text, multiline: true, max: 2000, required: true, label: { en: Your message } }
    steps:
      - store: { as: enquiry, retention: 90d }
      - mail:  { template: enquiry-receipt, to: $email }
    respond:
      fragment: partials/enquiry-sent.html
      on_error: partials/enquiry-form.html
```

The recipe (`--from recipe:enquiry`, the default) writes the endpoint even though the templates it names do not exist yet, and says so: `the recipe's templates (partials/enquiry-sent.html and the rest) are the site's to write`. `check` fails until you write them, reporting each at the endpoint's line with column 0:

```text
endpoint "contact" responds with partials/enquiry-sent.html, which no template root has
endpoint "contact" responds with partials/enquiry-form.html, which no template root has
endpoint "contact" mails enquiry-receipt, which is not under templates/emails/
```

"Under templates/emails/" means an `emails/` folder in any template root on the site's chain: `templates/_shared/emails/` for every site, or `templates/<site>/emails/` for one. This recipe uses `_shared`.

The endpoint's `path: /contact` and a page with the slug `contact` share an address on purpose: the engine answers a `GET` with the page and a `POST` with the endpoint. In another locale the form posts to the endpoint's path under that locale's prefix (`/cy/contact`) whatever the page's own slug there (`/cy/cysylltu`); `enquiryForm()` and `render()` write that `action` for you.

To send each enquiry to staff too, add a second mail step to an address in the site's settings:

```yaml
    steps:
      - store: { as: enquiry, retention: 90d }
      - mail:  { template: contact-to-staff, to: settings.contact_inbox }
      - mail:  { template: enquiry-receipt, to: $email }
```

A mail step's `reply_to:` does not set the message's `Reply-To` header: it only passes the address to the template as `replyTo`, and the header is always the site's or the install's `mail.reply_to`. Staff cannot answer the visitor by replying, so the staff email prints the visitor's address as a link. A mail step's `subject:` is not used either; the subject comes from the template's `subject` block.

```yaml
# config/sites/main/site.yaml
settings:
  contact_inbox: hello@example.org
```

## Write the templates [#write-the-templates]

```jinja
{# templates/_shared/partials/enquiry-sent.html: replaces the form after a good post #}
<div id="form-{{ endpoint.key }}" role="status" tabindex="-1">
  <h2>{{ t('contact.sent.title') }}</h2>
  <p>{{ t('contact.sent.body') }}</p>
</div>
```

```jinja
{# templates/_shared/partials/enquiry-form.html: the form again, with errors, after a bad post #}
{{ enquiryForm(endpoint.key) }}
```

The root element of both partials must have the id `form-<endpoint key>`: an in-place post replaces the form by that id. The drawn form already has it, and `endpoint.key` lets these two partials serve every endpoint, the [listing form below](#a-form-about-a-listing) included.

What a response partial sees is the base page context plus `errors`, `values` and `endpoint`, and after a success `submission`. It has no `entry`, no `page` values and no type variable such as `listing`: the post is not a page view, so the page it makes has the site's name as its title, no canonical and, on a plain post, no `h1` of yours.

```jinja
{# templates/_shared/emails/enquiry-receipt.html #}
{% extends "emails/_layout.html" %}
{% block subject %}We have your message{% endblock %}
{% block preheader %}A copy of what you sent us.{% endblock %}
{% block body %}
<h1>Thank you, {{ name }}</h1>
<p>We will reply to {{ email }} as soon as we can.</p>
<blockquote>{{ message }}</blockquote>
{% endblock %}
```

```jinja
{# templates/_shared/emails/contact-to-staff.html #}
{% extends "emails/_layout.html" %}
{% block subject %}New message from {{ name }}{% endblock %}
{% block preheader %}A message from the contact form.{% endblock %}
{% block body %}
<h1>New message from {{ name }}</h1>
<p>Reply to <a href="mailto:{{ email }}">{{ email }}</a>.</p>
<blockquote>{{ message }}</blockquote>
{% endblock %}
```

An email template sees the submitted inputs by name, plus `site.name`, `site.url`, `recipient` and `locale` (the locale's code as a string). `emails/_layout.html` is the engine's own layout. Both emails are written in the locale of the page the form was posted from, the staff one included.

### Emails in more than one locale [#emails-in-more-than-one-locale]

Email templates have no `t()`: a call prints nothing, and `check` does not flag it. On a multilingual site, branch on `locale` inside each block:

```jinja
{# templates/_shared/emails/enquiry-receipt.html #}
{% extends "emails/_layout.html" %}
{% block subject %}{% if locale == "cy" %}Mae eich neges gyda ni{% else %}We have your message{% endif %}{% endblock %}
{% block preheader %}{% if locale == "cy" %}Copi o'r hyn a anfonoch.{% else %}A copy of what you sent us.{% endif %}{% endblock %}
{% block body %}
{% if locale == "cy" %}
<h1>Diolch, {{ name }}</h1>
<p>Byddwn yn ateb {{ email }} cyn gynted ag y gallwn.</p>
{% else %}
<h1>Thank you, {{ name }}</h1>
<p>We will reply to {{ email }} as soon as we can.</p>
{% endif %}
<blockquote>{{ message }}</blockquote>
{% endblock %}
```

Check what an email renders without a running server: `engine-dmo mail test --template enquiry-receipt --locale cy --to you@example.org`. With the development `log` driver it sends nothing and prints the subject; an empty subject fails with `no subject`.

## Put the form on a page [#put-the-form-on-a-page]

Let editors choose the form with a `form` field on the page type:

```bash
engine-dmo dev field add page contactForm --type form --label "Form on this page" --apply
```

```jinja
{# templates/_shared/page/entry.html #}
{% extends "base.html" %}
{% block body %}
<h1>{{ entry.title }}</h1>
{% if entry.contactForm %}
<section aria-labelledby="contact-heading">
  <h2 id="contact-heading">{{ t('contact.title') }}</h2>
  {{ entry.contactForm.render() }}
</section>
{% endif %}
{% endblock %}
```

```yaml
# config/strings/en.yaml
strings:
  contact.title: Send us a message
  contact.sent.title: Thank you
  contact.sent.body: We have your message and will reply soon.
  form.contact.submit: Send
  form.leave.blank: Leave this field empty
```

`form.<key>.submit` is the button text; `form.leave.blank` labels the hidden honeypot field (without it the label prints as its key). Seed the contact page with the endpoint's id, which `engine-dmo describe project` prints:

```yaml
# seed/documents/page/contact.yaml
locales:
  en:
    title: Contact us
    slug: contact
    contactForm: end_4n96ztbdf6
publish: [en]
```

A template that always shows the same form can print `{{ enquiryForm('contact') }}` instead of using a field. `check` does not check the key passed to `enquiryForm()`: a wrong one prints nothing, so render the page. `enquiryForm()` has no `render()`, whatever `template api` says: print it as it is.

The drawn form has text, email, URL and telephone inputs, text areas and checkboxes. It does not draw a select or radio buttons from an input's options; for those, write the form's markup yourself with `csrfInput()` ([Forms in templates](/templates/forms)).

## A form about a listing [#a-form-about-a-listing]

A form that asks one business a question has a subject: the endpoint takes the document from its path. A form field cannot draw one, so print `enquiryForm()` with the subject, on `engine-dmo`:

```bash
engine-dmo dev endpoint add enquire --subject listing --apply
```

```yaml
# config/sites/main/endpoints.yaml (written)
  - key: enquire
    id: end_ns1qvdwjgx
    path: /enquire/{listing}
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    spam: { proof_of_work: true, honeypot: true, min_fill_time: 3s }
    input:
      listing: { type: relation, to: [listing], from: path, required: true }
      name:    { type: text, max: 120, required: true, autocomplete: name, label: { en: Your name } }
      email:   { type: text, format: email, required: true, autocomplete: email, label: { en: Your email address } }
      message: { type: text, multiline: true, max: 2000, required: true, label: { en: Your message } }
    steps:
      - store: { as: enquiry, retention: 90d, subject: $listing }
      - mail:  { template: enquiry-receipt, to: $email }
    respond:
      fragment: partials/enquiry-sent.html
      on_error: partials/enquiry-form.html
```

**Keep `on_error`.** An endpoint that takes a value from its path is not treated as a form, so with no `on_error` a failed post answers 422 with the `fragment`, and the visitor reads "Thank you" over a message that was never sent. The partial has no `listing` to pass, and needs none: `{{ enquiryForm(endpoint.key) }}` in an answer to a post takes the address from the post that failed, and draws the errors and a fresh challenge.

```jinja
{# in templates/_shared/listing/entry.html #}
<section aria-labelledby="enquire-heading">
  <h2 id="enquire-heading">{{ t('listing.enquire') }}</h2>
  {{ enquiryForm('enquire', entry) }}
</section>
```

Add `listing.enquire`, `form.enquire.submit`, `form.leave.blank` and `form.problems` (the heading of the error summary, which prints as its key without it, plural-aware with `{count}`) to your strings. To reach the business itself, add `share_with_organisation: true`, the mail step to `$listing.organisation.enquiryContacts` and the `analytics` step that [Directory](/dmo/directory#enquiries-to-the-business) shows. See also [Forms in templates](/templates/forms#enquiryform-and-subscribeform).

## Verify [#verify]

```bash
engine-dmo check
engine-dmo render /contact --json
```

The rendered form has `id="form-contact"`, a labelled input per declared input with `required` and `autocomplete`, the hidden honeypot, a `_csrf` field and the submit button, and `a11y` is empty.

The `_csrf` value is empty there, and it stays empty on a running server for an anonymous visitor, with no cookie set. The token exists only for a signed-in member or staff user, whose page has one bound to their session. An anonymous post is checked by where it comes from instead: a post with a cross-site `Origin` answers 403, and one from a script with neither header passes that check and goes on to validation.

### Post it from a script [#post-it-from-a-script]

A submission needs a running server (`engine-dmo dev up`). A plain `curl` of the fields does not get through with this endpoint's spam settings:

| Post | Answer |
|---|---|
| No `_ts` token, because `min_fill_time` is set | 422, the form drawn again, carrying a token. A browser with no script posts twice for this reason |
| A token younger than `min_fill_time` | 422, the form drawn again |
| A token, old enough, invalid input | 422 with the errors |
| A token, old enough, valid input | 200 and `respond.fragment` |
| More than `rate_limit` in the hour (`5/hour/ip`) | 429. Raise it while you test |

So fetch a challenge first. `GET /_e/challenge/<endpoint key>` answers:

```json
{ "field": "_ts", "token": "contact.1793656928.1l2h...", "minFill": 3000, "proofField": "_pow", "proofBits": 8 }
```

Post `token` in the field `field`, at least `minFill` milliseconds later. A token works once. The proof of work is optional: a post without `_pow` is accepted, and a wrong one is refused. To send one, find the number `n` for which `sha256(token + n)`, with `n` written in decimal, starts with `proofBits` zero bits.

```bash
TOKEN=$(curl -s http://localhost:8080/_e/challenge/contact | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')
sleep 4
curl -s -o /dev/null -w '%{http_code}\n' -X POST --data-urlencode "_ts=$TOKEN" \
  -d 'name=Sam&email=sam@example.org&message=Hello' http://localhost:8080/contact
```

That prints 200. Turning the defences off on the endpoint does not help: an endpoint may tighten them and not loosen them, so `proof_of_work: false` on it fails `check` with `an endpoint may add abuse controls and may not remove one the install default sets`, and a lower `min_fill_time` is ignored. In development you can lower the install's default instead, with `endpoints: { defaults: { spam: { min_fill_time: 0s } } }` in `engine.yaml` and no `min_fill_time` on the endpoint, and any post with valid fields goes through; put it back before you hand over. Then see the stored enquiry in the admin. To read the mail it sent, see [Read the mail](/agents/recipes/partner-portal#read-the-mail): the `log` driver writes only the address, subject and tag unless `logging.level` is `debug`.

The [claim form](/agents/recipes/claims) has a challenge of its own, in a hidden field of its page.

## Endpoint keys you will change [#endpoint-keys-you-will-change]

| Key | Meaning |
|---|---|
| `input.<name>` | `type` (`text`, `boolean`, `relation`, ...), `required`, `max`, `format: email`, `multiline`, `autocomplete`, `label` per locale, `required_value: true` for a consent box |
| `validation` | Rules across inputs, each with a `message` per locale |
| `spam` | `proof_of_work`, `honeypot`, `min_fill_time` |
| `rate_limit` | Such as `5/hour/ip` |
| `steps` | `store`, `mail`, `subscribe`, `audit`, `analytics` and more, in order |
| `respond` | `fragment` after success, `on_error` after a bad post |

`recipe:newsletter` declares a sign-up that subscribes with double opt-in. See [Forms and submissions](/features/forms-and-submissions) and [endpoints.yaml](/reference/configuration/endpoints).


# Extension (/agents/recipes/extension)

When an agent should write a Meridian extension (a Go plugin adding template filters, globals, routes or commands), the minimal filter extension, how it must be built to load, how to name it in engine.yaml and how to verify it.

An extension is a Go plugin (`.so`) the engine opens at start when `engine.yaml` names it. It can add template filters and globals, HTTP routes, commands, an asset resolver and a development server. Reach for one only when configuration and templates cannot express the need: most sites never have one.

## Before you write one [#before-you-write-one]

- **Check it is needed.** A filter for formatting, a component for markup, a declared endpoint for a form, and a webhook for telling another system all exist already. Search the handbook first: https://docs.cherwell.studio/llms-full.txt.
- **Check you can build it.** A plugin loads only into the exact build it was made for. You need the Go toolchain version the engine names, the same OS and architecture, cgo, and the `github.com/wrux/meridian-extend` module source at the engine's version. Read the requirements from the binary:

```bash
engine-dmo version
```

```text
  extensions: built with go1.27.3 darwin/arm64, GOARM64=v8.0, cgo, -trimpath, meridian-extend v0.0.0-00010101000000-000000000000
```

If the line says the engine is a pure Go build, or you do not have the toolchain or the module source, stop: tell the person what the extension would do and that it needs a cgo engine (the `-vips` image) and a build environment. Extensions do not load on Windows.

The module source is the hard part. `github.com/wrux/meridian-extend` is not published to a Go module proxy: the engine records it at the zero version `v0.0.0-00010101000000-000000000000`, so `go get` cannot fetch it, and nothing in the binary or the images carries it. An extension can be built only where the person has the module's source at the engine's exact version (from the Meridian source repository) to point a `replace` at. Without it, stop and say so. Every engine release means rebuilding every extension against the new version; there is no compatibility window between releases.

## A filter [#a-filter]

```go
// extensions/shout/shout.go
package main

import (
	"context"
	"strings"

	extend "github.com/wrux/meridian-extend"
)

type shout struct{}

func (shout) Manifest() extend.Manifest {
	return extend.Manifest{ID: "shout", Name: "Shout", Version: "1.0.0"}
}

// Register declares the filter, so engine-dmo check admits it in templates.
func (shout) Register(r extend.Registrar) error {
	return r.Filter("shout", "value|shout: the value in capitals")
}

// Init attaches the filter's function once the engine is running.
func (shout) Init(_ context.Context, h extend.Host) error {
	return h.Filter("shout", func(_ extend.Render, in, _ extend.Value) (any, error) {
		return strings.ToUpper(in.String()), nil
	})
}

// Extension is the symbol the engine looks up.
var Extension extend.Extension = shout{}

func main() {}
```

```go
// extensions/shout/go.mod
module example.com/shout

go 1.26.0

toolchain go1.27.3

require github.com/wrux/meridian-extend v0.0.0-00010101000000-000000000000

replace github.com/wrux/meridian-extend => ../../../meridian-extend
```

Use the toolchain and `meridian-extend` version your `engine-dmo version` prints, not the ones above, and point `replace` at wherever the person keeps the module source. Keep the extension to the standard library: any module it shares with the engine must match the engine's version exactly.

## Build and name it [#build-and-name-it]

```bash
cd extensions/shout
GOWORK=off CGO_ENABLED=1 go build -trimpath -buildmode=plugin -o ../shout.so .
```

For a Linux container image, build in the official Go image of the engine's toolchain (see [Extensions](/extending/extensions#building)).

```yaml
# config/engine.yaml
extensions:
  - extensions/shout.so
```

```jinja
<h2>{{ entry.title|shout }}</h2>
```

## Verify [#verify]

```bash
engine-dmo check
engine-dmo version
engine-dmo render / --json
```

`check` opens the plugin and reports any mismatch at its line in `engine.yaml` (`does not match this engine (...)`, followed by each difference and what to change), and admits `|shout` in templates. `version` lists `shout` among the modules. `Init` runs only when the engine serves, so `render` is the test that the filter works.

Rebuild every extension for every engine release, and never load a `.so` you did not build from source you control: an extension runs inside the engine with all its privileges. First-party extensions, such as `vite`, are named by bare name (`extensions: [vite]`) and ship with the engine; see [First-party extensions](/extending/first-party-extensions).


# Recipes (/agents/recipes)

Complete, checked examples of the tasks an agent meets most when building a Meridian site, from adding a content type to a DMO directory, a partner portal and an extension, each with the commands, the files and how to verify them.

Each recipe is a complete change: the commands to run, every file to write, and how to prove it works. Every configuration and template snippet on these pages has passed `engine-dmo check` in a scratch project, and those that render without a running server were rendered with `engine-dmo render`.

The core recipes continue one example, a walking site started with `engine-dmo init`: a `walk` type with a distance, a difficulty, a photo and a route description, routed at `/walks/{slug}` with an index at `/walks`. The DMO recipes start from a project with the core `listing` and `area` types. Replace the names with your own.

| Recipe | Use it to |
|---|---|
| [Add a content type](/agents/recipes/add-a-content-type) | Create a custom type with its fields |
| [Add a field](/agents/recipes/add-a-field) | Add, change, rename or remove a field, including selects and relations |
| [Add a route and its template](/agents/recipes/add-a-route) | Give a type addresses and pages |
| [Listing page with filters and pagination](/agents/recipes/listing-page) | An index page with facets, a count, cards and a pager |
| [Navigation menu](/agents/recipes/navigation-menu) | Header and footer menus editors can change |
| [Responsive images](/agents/recipes/responsive-images) | Image transforms, `img()`, `figure()`, credits and seeded photographs |
| [Enquiry form](/agents/recipes/enquiry-form) | A contact form that stores and mails submissions |
| [Multilingual site](/agents/recipes/multilingual-site) | A second locale with its own paths, strings and translations |
| [Search page](/agents/recipes/search-page) | A search route and its template |
| [DMO directory](/agents/recipes/dmo-directory) | Listings with areas, categories, place facets and a map |
| [Partner portal](/agents/recipes/partner-portal) | Tiers, member editing rules, a portal screen and an invitation |
| [Landing pages](/agents/recipes/landing-pages) | Place and category pages at clean addresses |
| [Claims](/agents/recipes/claims) | A "this is my business" link on a listing, and seeding what it needs |
| [Extension](/agents/recipes/extension) | A template filter written in Go, when templates cannot do it |

Before each recipe, run `engine-dmo guide` to see the project as it is, and after it, follow the loop: `engine-dmo check`, `engine-dmo schema plan`, `engine-dmo schema apply`, `engine-dmo render <path> --json`.


# Landing pages (/agents/recipes/landing-pages)

How an agent declares place-and-category landing pages on an engine-dmo listing route, what makes a page live, the optional landing template, and how to verify the configuration and the pages.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A landing page is a listing index filtered by a place and a category, at a clean address with its own title and description: "Places to stay in Monmouth" at `/monmouth/places-to-stay` instead of `/places?area=...&category=stay`. The engine counts the published results of every pairing and publishes each page with at least `min_results`, lists it in the sitemap, and leaves a redirect when a page goes away.

Start from the [DMO directory](/agents/recipes/dmo-directory): a listing route with an `index:`, `area` and `category` in its `facets:`, and a routed `area` type. As there, the examples use the locale code `en`: replace it with your source locale everywhere, because a slug under a locale the site does not enable only warns (`slug for locale en-GB, which site main does not enable`), and the page is then served at the raw option value (`/monmouth/stay`).

## Declare the landings [#declare-the-landings]

Add `landings:` to the listing route. Leave the rest of the file as it is, the `page` route with its `priority:` included:

```yaml
# config/sites/main/routes.yaml
routes:
  - type: page
    id: rte_rabyc471nc            # keep the ids the file already has
    uri: "/{slug}"
    priority: 10
  - type: listing
    id: rte_fggnn9hxs9
    uri: "/places/{slug}"
    index: "/places"
    paginate: 24
    facets: [area, category]
    landings:
      - key: by-place
        place: area
        category: category
        uri: "{place}/{category}"
        slugs:
          stay: { en: places-to-stay }
          eat-drink: { en: food-and-drink }
          see-do: { en: things-to-do }
        min_results: 3
        title: { en: "{category} in {place}" }
        description: { en: "{count} {category_lower} in {place}, including {examples}." }
  - type: area
    id: rte_e3nyk9a1s7
    uri: "/{slug}"
    nest: true
    index: "/areas"

home: { type: page, slug: home }
```

```bash
engine-dmo check --fix
engine-dmo schema plan
engine-dmo schema apply
```

`check --fix` writes the landing's `lnd_` id. Give `slugs`, `title` and `description` a value for every locale the site enables; each slug is one path segment. `check` refuses a landing whose `place` or `category` is not in the route's `facets`, a route without `index:`, or a place type not routed on the site.

| Key | Meaning |
|---|---|
| `place` | A facet that is a single relation to a place type (`area`) |
| `category` | A facet that is a select or a relation |
| `uri` | `"{place}/{category}"` puts the page under the place's own address; `"{category}"` alone makes a category page under the index; `"{month}"` with `month:` a month page for events |
| `min_results` | The fewest published results for a page to be live (default 3) |
| `title`, `description` | Patterns with `{place}`, `{category}`, `{category_lower}`, `{count}`, `{examples}` |
| `content` | A type editors fill in for each page, adding their own copy |

## The template [#the-template]

A landing page renders `listing/landing.html` when the site's chain has one, otherwise `listing/index.html`, with everything an index page has plus `landing` (`title`, `heading`, `description`, `content`, `breadcrumbs`, `siblings`, `jsonld` and more). `page.title` is the generated title and `head()` prints it, with the description, so an index template whose `h1` allows for a landing already works (`{% if page.landing %}{{ landing.heading }}{% else %}...`, as the [directory's](/agents/recipes/dmo-directory#write-the-templates) does).

A landing page's own template, when it should differ from the index, needs its one `h1`, its breadcrumbs and its results:

```jinja
{# templates/_shared/listing/landing.html #}
{% extends "base.html" %}
{% block body %}
<nav aria-label="{{ t('crumbs.label') }}">
  <ol>{% for c in landing.breadcrumbs %}<li>{% if c.current %}<span aria-current="page">{{ c.title }}</span>{% else %}<a href="{{ c.uri|url }}">{{ c.title }}</a>{% endif %}</li>{% endfor %}</ol>
</nav>
<h1>{{ landing.heading }}</h1>
{% if landing.description %}<p>{{ landing.description }}</p>{% endif %}
<ul class="cards">
  {% for listing in items %}
  <li data-mrd-impression="{{ listing.id }}">
    <h2><a href="{{ listing.uri|url }}">{{ listing.title }}</a></h2>
    <p>{{ listing.summary }}</p>
  </li>
  {% endfor %}
</ul>
{{ impressions() }}
{% if landing.siblings %}
<h2>{{ t('landing.more') }}</h2>
<ul>{% for s in landing.siblings %}<li><a href="{{ s.uri|url }}">{{ s.title }}</a> ({{ s.count }})</li>{% endfor %}</ul>
{% endif %}
{% endblock %}
```

Add `crumbs.label` and `landing.more` to every locale's strings. There is no `{% block title %}` to fill: `head()` prints the title, and [the workflow's layout](/agents/workflow) has only a `body` block.

To link from an area to its landing pages:

```jinja
{% if entry.landings %}
<h2>{{ t('area.explore') }}</h2>
<ul>{% for l in entry.landings %}<li><a href="{{ l.url|url }}">{{ l.title }}</a></li>{% endfor %}</ul>
{% endif %}
```

## When pages appear [#when-pages-appear]

Pages are counted by a background job of the running server: at every start, whenever published content on the site changes, and when routes move. `engine-dmo render` runs no jobs, so right after `schema apply` and `seed apply` a landing address answers 404 until a server (`engine-dmo dev up` or `engine-dmo serve`) has started once against the database. The job runs in the background just after the server starts, under a second on a small seed, so allow a moment and poll rather than trusting the first 404:

```bash
LISTEN_ADDR=127.0.0.1:8091 BASE_URL=http://localhost:8091 engine-dmo dev up &
until curl -sf -o /dev/null http://localhost:8091/monmouth/places-to-stay; do sleep 1; done
```

`LISTEN_ADDR` chooses the port on a new project, because its `engine.yaml` reads `${LISTEN_ADDR:-127.0.0.1:8080}`; `dev up --listen` does the same. `dev up` also binds `127.0.0.1:9090` for its metrics, and a second server on one machine stops at start with `MRD-3003: metrics listen on 127.0.0.1:9090: bind: address already in use`. For a second project at once, set `telemetry.metrics.bind` in its `engine.yaml` to another port. Stop the server when you have your answer; the counts stay in the database, so `render` then sees them.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo render /monmouth/places-to-stay --json     # after a server has run
engine-dmo a11y audit --all                            # live landing pages are in the sitemap
```

A live landing answers 200 with the generated title. A pairing with fewer than `min_results` results answers 404, which is correct. See [Landing pages](/dmo/landing-pages) for month pages, editors' copy and redirects.


# Listing page with filters and pagination (/agents/recipes/listing-page)

How an agent builds a type's index page in Meridian with route facets for filtering, a translated result count, cards and an accessible pager, and verifies the first, last and filtered pages with render.

A listing page is a route's index: the type's published documents on the site in the request locale, a page at a time, filtered by the facets the route declares. Filtering and paging are done by the engine from the query string (`?difficulty=easy&page=2`), so the page works without JavaScript and every filtered state has its own address.

```mermaid
flowchart LR
  req["GET /walks?difficulty=easy&page=2"] --> route["routes.yaml<br/>index /walks"]
  route --> filter["Published walks in the locale,<br/>filtered by the facets"]
  filter --> page["Page 2 of paginate: 12"]
  page --> ctx["items, facets,<br/>pagination"]
  ctx --> tpl["walk/index.html"]
```

## Configure the route [#configure-the-route]

Every facet must be a field declared `index: true` on the type.

```yaml
# config/sites/main/routes.yaml
routes:
  - type: walk
    id: rte_34agwcmxkh            # keep the id the verb wrote
    uri: "/walks/{slug}"
    index: /walks
    paginate: 12
    facets: [difficulty]
```

## Write the strings [#write-the-strings]

```yaml
# config/strings/en.yaml
strings:
  walks.title: Walks in the valley
  walks.count:
    one: "{count} walk"
    other: "{count} walks"
  walks.none: No walks match these filters.
  walks.distance: "{km} km"
  facets.label: Filter these walks
  facets.clear: Clear
  pager.label: Pages
  pager.previous: Previous
  pager.next: Next
  pager.page_of: "Page {page} of {pages}"
```

## Write the template [#write-the-template]

```jinja
{# templates/_shared/walk/index.html #}
{% extends "base.html" %}
{% block body %}
<h1>{{ t('walks.title') }}</h1>
{% if facets %}
<nav aria-label="{{ t('facets.label') }}">
  {% for facet in facets %}
  <h2>{{ facet.label }}</h2>
  <ul>
    {% for v in facet.values %}<li><a href="{{ v.url|url }}"{% if v.selected %} aria-current="true"{% endif %}>{{ v.label }} ({{ v.count }})</a></li>{% endfor %}
  </ul>
  {% if facet.selected %}<p><a href="{{ facet.clearUrl|url }}">{{ t('facets.clear') }}</a></p>{% endif %}
  {% endfor %}
</nav>
{% endif %}
<p>{{ t('walks.count', pagination.total) }}</p>
<ul class="cards">
  {% for walk in items %}
  <li>
    {% if walk.photo %}{{ walk.photo.img("card", alt="") }}{% if walk.photo.credit %}<small>{{ walk.photo.credit }}</small>{% endif %}{% endif %}
    <h2><a href="{{ walk.uri|url }}">{{ walk.title }}</a></h2>
    {% if walk.summary %}<p>{{ walk.summary }}</p>{% endif %}
    {% if walk.distanceKm %}<p>{{ t('walks.distance', 'km', walk.distanceKm|number) }}</p>{% endif %}
  </li>
  {% empty %}
  <li>{{ t('walks.none') }}</li>
  {% endfor %}
</ul>
{% if pagination.pages > 1 %}
<nav aria-label="{{ t('pager.label') }}">
  {% if pagination.prev %}<a rel="prev" href="{{ pagination.prev|url }}">{{ t('pager.previous') }}</a>{% endif %}
  <span>{{ t('pager.page_of', 'page', pagination.page, 'pages', pagination.pages) }}</span>
  {% if pagination.next %}<a rel="next" href="{{ pagination.next|url }}">{{ t('pager.next') }}</a>{% endif %}
</nav>
{% endif %}
{% endblock %}
```

Points that matter:

- The card image is `alt=""` because the linked title beside it names the walk; an image that carries information gets its library alt text instead (leave `alt` out).
- Print numbers through `|number` before passing them to `t()`; a raw decimal prints as `6.500000`.
- Link with `walk.uri|url` (a path on the current origin). `walk.url` is the absolute address on the site's configured domain.
- `pagination.prev` and `pagination.next` keep the selected facets; `v.url` and `facet.clearUrl` keep the rest of the query. `pagination.range` holds page numbers only, with no addresses: a numbered link written as `href="?page={{ n }}"` drops the selected facets, and `check` does not notice. Use `prev` and `next`, as here, on a filtered index.
- The `h1` comes from `t()`. On an index, `page.title` is the type's plural label, an admin word such as "Walks", and printing it makes that word the page's public heading. See [The index page's title](#the-index-pages-title).
- Facets are one `<nav>` named from `t()`, holding a heading (`facet.label`, the field's label) and a list of links for each facet. The values are links, not form controls, so they take no `<fieldset>`, and one landmark keeps a page with several facets from adding a landmark for each.
- A facet value's `label` is its option's label in the request locale. An option with no `label` prints its raw value (`easy`), and `check` does not warn about it: label every option ([Add a field](/agents/recipes/add-a-field#a-select-with-labelled-options)).
- A filtered index is `noindex` and its canonical is the unfiltered index; `head()` writes both.
- For a component per card, see [Components](/templates/components): `{% component 'walk-card' walk=walk %}`.

## The index page's title [#the-index-pages-title]

An index has no document behind it, so it has no fields of its own, and a route has no key for a title or a description.

| | What an index gets |
|---|---|
| `page.title` | The type's `plural` label in the request locale |
| `<title>`, from `head()` | The same, through `seo.title_template` |
| Meta description | None. `head()` prints no description on an index |

So write the `plural` label as words you would accept in a search result, because it is the `<title>` whatever the `h1` says, and take the `h1` from `t()`. For a page with an editor-written title and description, either use a [landing page](/agents/recipes/landing-pages), which has both, or route the index elsewhere and make a `page` document at the address, listing the documents with `query()` ([below](#lists-that-are-not-an-index)). A document at an index's own address replaces the index, so its facets and pager go with it.

## Verify [#verify]

```bash
engine-dmo render /walks --json
engine-dmo render '/walks?difficulty=easy' --json
engine-dmo render '/walks?page=2' --json
```

Quote paths with `?` in your shell. Each must answer 200 with empty `errors` and `a11y`. Render a filtered page past the first too (`'/walks?difficulty=easy&page=2'`) and check its `rel="prev"` link still carries `difficulty=easy`. Generate enough documents to see the pager: `engine-dmo seed generate --type walk --count 14 --publish`.

## Lists that are not an index [#lists-that-are-not-an-index]

A list inside another page (the three newest walks on the home page, the walks in an area) is a query, not an index:

```jinja
{% set latest = query('walk').orderBy('publishedAt', 'desc').limit(3).all() %}
{% for w in latest %}<a href="{{ w.uri|url }}">{{ w.title }}</a>{% endfor %}
```

`query()` filters and sorts only on `index: true` fields (and `title`, plus sorting on `createdAt`, `updatedAt` and `publishedAt`). A non-indexed field fails the render, not `check`, so render every page that queries. See [Querying content](/templates/queries).


# Multilingual site (/agents/recipes/multilingual-site)

How an agent adds a second locale to a Meridian site with dev locale add, gives routes per-locale paths, translates interface strings and labels, seeds translated documents, adds a language switcher and verifies hreflang and the translated pages.

Each document has one shared structure and per-locale text. Fields that hold text (`text`, `slug`, `portable_text`) differ per locale; values such as numbers, selects, places and relations are shared by every locale and written once. A locale's URLs carry a prefix (`/cy/...`) by default, and each route may give each locale its own path words.

An asset field is both: `describe type` shows it as `translate locale` because its per-use alt text and caption are per locale, but the chosen image and its focal point are shared. A `cy` block does not repeat the field, and giving it a different asset there replaces the image for every locale. For a different image per locale, declare the field with `structure: per_locale` ([Localisation](/content-modelling/localisation)).

Adding a locale touches these files. When you forget one, `check` warns about those under "check warns" and says nothing about those under "check is silent":

```mermaid
flowchart LR
  add["dev locale add cy"] --> loc["config/locales.yaml"]
  add --> site["sites/main/site.yaml"]
  subgraph warned["check warns"]
    labels["schema labels"]
    strings["strings/cy.yaml<br/>(once the file exists)"]
  end
  subgraph silent["check is silent"]
    ep["endpoints.yaml<br/>input labels"]
    nav["seed/navigation<br/>item labels"]
    mail["email templates"]
    rt["routes.yaml paths"]
  end
  site --> you["You translate"]
  you --> warned
  you --> silent
```

## Add the locale [#add-the-locale]

```bash
engine-dmo dev locale add cy --label Cymraeg --fallback en --site main --apply
```

```yaml
# config/locales.yaml (written)
    - { code: cy, id: loc_0vb8pv7bqm, label: Cymraeg, fallback: [en] }
```

```yaml
# config/sites/main/site.yaml (written)
locales:
  enabled: [en, cy]
  default: en
```

The site's `locales.strategy` decides the addresses: `prefix` (the default: every locale but the default under `/<code>/`), `prefix-all`, or `domain` with a host per locale in `locales.domains`. Set the new locale's `timezone` and `currency` in `locales.yaml` if they differ from the source locale's.

After this, `check` warns at every schema label without a `cy` translation ("the label of field photo has no translation for cy"). Add them: `label: { en: Photo, cy: Llun }`. Give the site's name too:

```bash
engine-dmo dev config set sites/main/site.yaml site.name.cy "Croeso Banbury"
```

`dev config set` rewrites the map in key order (`{ cy: ..., en: ... }`), which is harmless.

## Give routes per-locale paths [#give-routes-per-locale-paths]

```yaml
# config/sites/main/routes.yaml
routes:
  - type: walk
    id: rte_34agwcmxkh            # keep the id
    uri: { en: "/walks/{slug}", cy: "/teithiau/{slug}" }
    index: { en: /walks, cy: /teithiau }
    paginate: 12
    facets: [difficulty]

special:
  search: { en: /search, cy: /chwilio }
```

A route given per locale needs a value for every locale the site enables.

## Translate the interface strings [#translate-the-interface-strings]

Copy `config/strings/en.yaml` to `config/strings/cy.yaml` with the same keys. `check` says nothing about a locale with no strings file at all; it lists missing keys only once `cy.yaml` exists, so create the file first:

```yaml
# config/strings/cy.yaml
strings:
  a11y.skip: Neidio i'r prif gynnwys
  nav.main: Prif
  nav.footer: Troedyn
  walks.count:
    zero: "{count} taith"
    one: "{count} daith"
    two: "{count} daith"
    few: "{count} taith"
    many: "{count} taith"
    other: "{count} taith"
```

Plural strings take the locale's CLDR categories (`zero`, `one`, `two`, `few`, `many`, `other`); Welsh uses all six, English `one` and `other`. `check` warns with the list of keys a locale is missing (`cy is missing 14 of 18 strings: ...`); a missing key falls back down the locale's chain. Translate every key before handing back. Never machine-translate without telling the person.

## Seed translated documents [#seed-translated-documents]

```yaml
# seed/documents/walk/cherwell-towpath.yaml
locales:
  en:
    title: Cherwell towpath
    slug: cherwell-towpath
    summary: A flat riverside walk along the canal towpath from the town centre.
    distanceKm: 6.5
    difficulty: easy
  cy:
    title: Llwybr tynnu Cherwell
    slug: llwybr-tynnu-cherwell
    summary: Taith wastad ar hyd llwybr tynnu'r gamlas o ganol y dref.
publish: [en, cy]
```

The `cy` block gives only the translated text: `distanceKm`, `difficulty` and the photo are shared. A locale not in `publish` stays a draft, and its page does not exist in that locale.

The home page keeps the slug `routes.yaml` names in `home:` in every locale. With `home: { type: page, slug: home }`, the Welsh home page is the `cy` block with `slug: home`, served at `/cy/`; a `cy` slug such as `hafan` makes it an ordinary page at `/cy/hafan`, and `/cy/` answers 404.

```yaml
# seed/documents/page/home.yaml
locales:
  en:
    title: Welcome
    slug: home
  cy:
    title: Croeso
    slug: home
publish: [en, cy]
```

Add the locale to `seed/seed.yaml` as well (`locales: [en, cy]`). That list limits only the analytics `seed apply` generates; documents load in every locale they give either way.

## Translate what check does not [#translate-what-check-does-not]

- **Form labels.** Each endpoint input's `label` in `config/sites/<site>/endpoints.yaml`, and each `message` in its `validation`: `label: { en: Your name, cy: Eich enw }`. Without one the Welsh form shows the English label.
- **Menu labels.** Each item in `seed/navigation/*.yaml`: `label: { en: Walks, cy: Teithiau }`.
- **Emails.** Email templates have no `t()`: it prints nothing there. Branch on `locale` inside each block ([Enquiry form](/agents/recipes/enquiry-form#emails-in-more-than-one-locale)).
- **Select options.** An option with no `label` at all prints its value in every locale.

## Add a language switcher [#add-a-language-switcher]

```jinja
{# in templates/_shared/base.html, inside the header #}
{{ localeSwitcher() }}
```

`localeSwitcher()` prints a labelled `<nav>` of the locales the current page is published in, the current one with `aria-current="page"` and each link with `hreflang` and `lang`; it prints nothing on a page that exists in one locale. Label it with the string `nav.language`. `head()` writes the `hreflang` alternates and `x-default`, and `<html lang>` comes from `locale.code`.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo schema apply
engine-dmo seed reset --confirm && engine-dmo seed apply
engine-dmo render /cy/teithiau/llwybr-tynnu-cherwell --json
engine-dmo render /teithiau/llwybr-tynnu-cherwell --locale cy --json
```

Then render the Welsh home page and a form page: `engine-dmo render /cy/ --json` and `engine-dmo render /cy/cysylltu --json`, and read the `<label>`s in `html`.

The page answers 200 with `"locale": "cy"`, `<html lang="cy">`, a canonical on `/cy/teithiau/...`, `hreflang` alternates for `en`, `cy` and `x-default`, and the Welsh strings. `--locale` takes the unprefixed path and adds the prefix for you. Run `engine-dmo a11y audit --all`, which covers every locale's pages in the sitemap. See [Localisation](/content-modelling/localisation).


# Navigation menu (/agents/recipes/navigation-menu)

How an agent adds header and footer menus to a Meridian site with navigation slots in site.yaml, a seeded navigation set and the nav tag in the layout, marking the current page and hiding an empty menu.

Menus are navigation sets that fill slots. The project declares the slots; editors fill them in the admin's Navigation screen; you seed the first version so the site works from day one. A menu item that points at a document drops out by itself when the document is unpublished.

```mermaid
flowchart LR
  slot["site.yaml nav: main<br/>(the slot)"] --> set["seed/navigation/main.yaml<br/>(the set, assigned)"]
  set --> admin["Editors change it<br/>in the admin"]
  set --> tag["base.html<br/>nav tag on nav.main"]
  admin --> tag
```

## Declare the slots [#declare-the-slots]

```yaml
# config/sites/main/site.yaml
nav:
  main: { label: { en: Header }, depth: 2 }
  footer: { label: { en: Footer }, depth: 1 }
```

```bash
engine-dmo check --fix
```

`check` refuses a slot without an id (`nav slot "main" has no id`); `check --fix` writes `nav_` ids. `depth` is how deep items may nest, 1 to 5.

## Seed the menus [#seed-the-menus]

```yaml
# seed/navigation/main.yaml
site: main
slot: main
name: Header
assigned: true
items:
  - label: { en: Walks }
    index: walk
  - label: { en: Contact }
    document: page/contact
```

```yaml
# seed/navigation/footer.yaml
site: main
slot: footer
name: Footer
assigned: true
items:
  - label: { en: Accessibility }
    document: page/accessibility
  - label: { en: Search }
    url: /search
```

| Item key | Links to |
|---|---|
| `document: <type>/<seed key>` | A seeded document, in the visitor's locale |
| `index: <type>` | The type's index page |
| `url: /path` or `url: https://...` | A path on the site (locale-prefixed) or an external address |
| `asset: <seed key>` | A library file |
| none, with `children:` | A heading grouping its children |

Each item may add `suffix: "#anchor"` and `children:` (up to the slot's depth). Every document an item names must exist in the seed.

```bash
engine-dmo seed verify
engine-dmo seed reset --confirm
engine-dmo seed apply
```

`seed verify` loads the navigation files with the rest and fails on an item that names a document not in the seed (`seed/navigation/main.yaml: document page/nosuch is not in the seed`), or a slot `site.yaml` does not declare. Its summary line counts documents and assets only, so a menu that loads is silent there. Only `seed apply` counts the menus: it reports `navigation: 2 sets, 4 items`. Without a database, a clean `seed verify` is the evidence that the menus will load.

On a multilingual site give each item's `label` every locale (`label: { en: Walks, cy: Teithiau }`); `check` does not warn about a missing one, and the item shows its source-locale label.

## Render the menus in the layout [#render-the-menus-in-the-layout]

```jinja
{# in templates/_shared/base.html #}
<nav aria-label="{{ t('nav.main') }}">
  <ul>{% nav item in nav.main %}<li><a href="{{ item.url|url }}"{% if item.isCurrent %} aria-current="page"{% endif %}>{{ item.label }}</a>{% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}</li>{% endnav %}</ul>
</nav>
...
<footer>
  {% if nav.footer %}<nav aria-label="{{ t('nav.footer') }}">
    <ul>{% for item in nav.footer %}<li><a href="{{ item.url|url }}">{{ item.label }}</a></li>{% endfor %}</ul>
  </nav>{% endif %}
</footer>
```

```yaml
# config/strings/en.yaml
strings:
  nav.main: Main
  nav.footer: Footer
```

- `{% nav %}` renders a tree: `{% ifchildren %}` renders only when the item has children and `{% children %}` repeats the body one level down. A flat menu needs only `{% for %}`.
- Mark the current page with `aria-current="page"` from `item.isCurrent`; `item.isActive` is true on the trail above it.
- Wrap a menu that may be empty in `{% if nav.<slot> %}` so the page has no empty landmark.
- A heading item (`item.kind == "heading"`) has an empty `url`: print it as text.

## Verify [#verify]

```bash
engine-dmo render /walks --json
```

The `html` holds both menus, the Walks item carries `aria-current="page"`, and `a11y` is empty. See [Navigation](/features/navigation) for every item property and breadcrumbs.


# Partner portal (/agents/recipes/partner-portal)

How an agent sets up the member portal on engine-dmo for partner businesses, declaring membership tiers, the member_editable rules that say what each tier may change, an extra portal screen, an organisation with a membership and an invitation, and how to verify each part.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The portal is where a partner business's people sign in (with a link sent by email, or a passkey) to edit their listings, see their enquiries and their report, and manage their membership. It is served by the engine under `/members` on each site's own host and works out of the box with the engine's reference screens. Your work is to say who may change what, add any screens the brief needs, and invite the first partners.

Start from the [DMO directory](/agents/recipes/dmo-directory), whose `listing` has the fields named below. Examples use the locale code `en`; replace it with your source locale.

## Declare the tiers [#declare-the-tiers]

Tiers are ranked lowest first:

```bash
engine-dmo dev tier add standard --label Standard --apply
engine-dmo dev tier add silver --after standard --label Silver --apply
engine-dmo dev tier add gold --after silver --label Gold --apply
```

```yaml
# config/memberships.yaml
tiers:
  - key: standard
    id: tier_qxgx1sr7ff
    label: { en: Standard }
  - { key: silver, id: tier_brwtq46ckb, label: { en: Silver } }
  - key: gold
    id: tier_q9nx12bh8p
    label: { en: Gold }
```

`none` is reserved for an organisation without an active membership; rules may name it.

## Say what members may edit [#say-what-members-may-edit]

Without a `member_editable` rule, members cannot edit documents of the type. Add one to the type's schema file:

```yaml
# config/schema/listing.yaml (top level, after fields:)
member_editable:
  tiers:
    none:
      fields: [phone, website, openingHours]
      approval: required
    standard:
      fields: [summary, description, phone, website, openingHours, heroImage]
      approval: required
    gold:
      fields: "*"
      except: [slug, area, category]
      approval: auto
      review_window: 24h
      always_review: [primaryTag]
```

`approval: required` sends every change to the admin's moderation queue; `auto` publishes at once and staff review within `review_window`. Every field named here is on the directory's `listing`, or is core. `check` reports an unknown field or tier, so name only your own type's fields. `engine-dmo describe type listing` prints the rules.

## Add a portal screen [#add-a-portal-screen]

The reference screens (dashboard, organisation, listing edit, photos, hours, enquiries, report, people, membership and more) need nothing from you. Add a screen of your own with a verb:

```bash
engine-dmo dev portal screen add offers --nav-order 30 --min-tier silver \
  --data 'listings=documents type=listing states=draft,published sort=-updatedAt limit=20' \
  --scaffold --apply
```

```yaml
# config/sites/main/portal.yaml (written)
screens:
  - { key: offers, id: scr_yry1y0gjkw, path: "/organisations/{org}/offers", template: offers.html, nav: { group: business, order: 30 }, tiers: { min: silver }, data: { listings: { documents: { type: listing, states: [draft, published], sort: -updatedAt, limit: 20 } } } }
```

`--scaffold` writes `templates/main/portal/offers.html`, a complete page using the portal's stylesheet with `data.listings.items` in a list. Edit it; give the page one `h1`. Forms posting to the portal are declared as actions (`engine-dmo dev portal action add <subject.verb>`); see [Portal screens and actions](/dmo/portal-screens-and-actions). To restyle every portal screen, `engine-dmo portal scaffold --site main` copies the reference templates into the project. Always pass `--site`: without it the command writes to `templates/portal/`, which is on no site's template chain, so nothing there renders and `check` warns that it is unused.

```bash
engine-dmo portal check
engine-dmo portal status
```

`portal check` checks your portal templates against the portal context; `portal status` lists every screen with its path and whether the engine or your project supplies its template.

## Add a partner and invite them [#add-a-partner-and-invite-them]

In a seed, an organisation is a file under `seed/organisations/` with its contacts, memberships and invitations, and a listing names it with a top-level `organisation: <key>`. [Organisations and people](/content-modelling/seeding-and-importing#organisations-and-people) has the file format, with an example. On a running database:

```bash
engine-dmo crm organisation create '{"name":"The Wharf Hotel","email":"stay@wharf.example","status":"active"}'
engine-dmo crm membership set <organisation-id> --tier gold --reason "Joined at the spring trade fair"
engine-dmo crm invite --organisation <organisation-id> --email owner@wharf.example --name "Sam Owner" --role "General manager"
```

`organisation create` prints the new id; `membership set` starts an active membership on the default site (`--site` for another); `invite` links the person as the organisation's owner and queues the invitation mail. It prints no link. Linking an existing listing to an organisation is done in the admin's document editor (the Organisation panel) or in the seed.

## Verify [#verify]

```bash
engine-dmo check
engine-dmo portal check
engine-dmo schema plan
engine-dmo describe type listing
```

The portal's screens need a signed-in member, so `render` cannot show them. To see one you need the sign-in mail, and how you read it depends on your mail settings.

### Read the mail [#read-the-mail]

The `log` driver, the default, writes `to`, `subject` and `tag` at the `info` level, with no body and no link. Choose one of these in development:

```yaml
# config/engine.yaml, to read the body in the server log
logging:
  format: ${LOG_FORMAT:-text}
  level: debug
```

```yaml
# config/engine.yaml, to send to a local SMTP catcher such as Mailpit on port 1025
mail:
  driver: smtp
  from: hello@example.org
  smtp:
    host: localhost
    port: 1025
    tls: none
```

If you can do neither, say so and leave this step to the person.

### Sign in [#sign-in]

The invitation does not carry a token. Its link goes to `/members/login`, on the site's first domain without a port, so in development it reads `http://localhost/members/login` and goes nowhere: open `/members/login` on your server's own address. There the person asks for a sign-in link, and only that second mail has a token (`/members/auth/<token>`, on the address they asked from). It lasts 15 minutes.

A sign-in link works only in the browser that asked for it, which holds a `__Host-mrd_link` cookie. Opened anywhere else it answers 200 with `Open this link in the browser where you requested it`, and signs nobody in. So from a shell, keep one cookie jar across both requests:

```bash
curl -s -c jar -b jar -o /dev/null -X POST -d 'email=owner@wharf.example' http://localhost:8080/members/login
# read the /members/auth/<token> link from the mail, then:
curl -s -c jar -b jar -o /dev/null -w '%{http_code} %{redirect_url}\n' 'http://localhost:8080/members/auth/<token>'
curl -s -b jar http://localhost:8080/members
```

The second command answers 303 to `/members`. `POST /members/login` answers the same page whether or not the address is known, so an address that is not a person's gets no mail and no error. See [Partners and the portal](/dmo/partners-and-portal).


# Responsive images (/agents/recipes/responsive-images)

How an agent declares image transforms in config/images.yaml, prints asset fields with img(), picture() and figure() so every image has srcset, sizes, dimensions, alt text and its credit, seeds real photographs, and reads the image report from render.

Every image a template prints goes through a named transform. You declare the transforms once; the engine writes `srcset`, `sizes`, `width`, `height`, `alt` and the loading attributes, and generates each size the first time it is requested. Never write an `<img>` for a library image by hand.

## Declare the transforms [#declare-the-transforms]

```yaml
# config/images.yaml
breakpoints:
  md: 48rem
  lg: 64rem

transforms:
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
    sizes: "100vw"
```

`sizes` names breakpoints from the same file. A template asking for a transform the file does not declare fails `check`. `engine-dmo media transforms` prints each transform's width ladder and the formats this build encodes; the `-vips` image encodes AVIF and WebP, the standard build JPEG and PNG. A transform with no `formats:` asks for AVIF and WebP, so on the standard build `check` prints `note: the image transforms name avif and webp, which this build cannot encode`. The note is harmless: that build serves JPEG and the `-vips` image serves all three. `formats: [jpeg]` on every transform silences it, but also stops the `-vips` image serving the smaller formats, so leave it unless the person asks.

A transform takes `widths: { min, max }` for a ladder the engine fills in, or `width:` for one fixed size (an Open Graph image at 1200 pixels, say); [Images](/templates/images) has both.

## Print images [#print-images]

```jinja
{# the page's main image: eager, high priority, preloaded, with caption and credit #}
{{ walk.photo.figure("hero", priority=true) }}

{# a card image beside a linked title: decorative here, credit printed #}
{% if walk.photo %}
  {{ walk.photo.img("card", alt="") }}
  {% if walk.photo.credit %}<small>{{ walk.photo.credit }}</small>{% endif %}
{% endif %}
```

| Method | Prints |
|---|---|
| `img(transform, ...)` | One `<img>` with `srcset`, `sizes`, `width`, `height`, `alt`, `loading="lazy"`, `decoding="async"` |
| `picture(transform, ...)` | A `<picture>` with a `<source>` per format, then the `<img>` |
| `figure(transform, ...)` | The picture in a `<figure>` with the caption and credit in `<figcaption>` |
| `url(transform, width=, absolute=)` | One derivative's address, for a CSS background or a meta tag |

Options: `priority=true` (once per page, for the main image), `sizes=`, `loading=`, `alt=` (`alt=""` for a decorative use), `placeholder=`, and any HTML attribute (`class="card__img"`). An empty asset field prints nothing, so `{% if %}` is needed only around your own markup.

Rules `check` enforces: the transform must exist; only one `priority=true` per page; `src`, `srcset`, `width`, `height` and `style` belong to the helper. It warns when an image is printed with `img()` or `picture()` and its credit appears nowhere in the template: use `figure()`, or print `.credit`.

## Seed real photographs [#seed-real-photographs]

Put each photograph and a YAML file of the same name under `seed/assets/`:

```yaml
# seed/assets/towpath.yaml   (beside seed/assets/towpath.jpg)
title: Wildflowers beside the towpath
alt: { en: Wildflowers in bloom along a grassy path }
credit: Photograph by A. Walker
```

```yaml
# seed/documents/walk/cherwell-towpath.yaml
locales:
  en:
    title: Cherwell towpath
    slug: cherwell-towpath
    summary: A flat riverside walk along the canal towpath from the town centre.
    difficulty: easy
    photo: { asset: towpath }
publish: [en]
```

Write alt text that says what the image shows, in every locale the site runs. Use only photographs the person has the right to use, and never a generated image presented as a real place. `seed apply` runs every file through the same pipeline as an upload and strips location metadata.

## Verify [#verify]

```bash
engine-dmo render /walks/cherwell-towpath --json
```

The `images` array lists each image printed: its transform, `sizes`, the width ladder, the formats and every derivative's address and size. Check that the main image has `priority: true` and the rest do not, and that `a11y` is empty. `engine-dmo a11y audit` fails a page with an `<img>` that has no `alt`. See [Images](/templates/images) for art direction and focal points.


# Search page (/agents/recipes/search-page)

How an agent adds a search page to a Meridian site with the special search route and search.html, what browse mode returns without a search service, how to connect one, and how to verify the page renders and is accessible.

Search is a special route that renders `search.html` with a `results` object. With no search service configured, the page answers in browse mode over published content; connect Meilisearch, Elasticsearch or OpenSearch for ranked, matched results. The template is the same either way.

## Route it [#route-it]

```yaml
# config/sites/main/routes.yaml
special:
  search: /search
```

Per locale: `search: { en: /search, cy: /chwilio }`. `check` refuses a site that routes search without a `search.html`, and warns while no backend is configured.

## Write the template [#write-the-template]

```jinja
{# templates/_shared/search.html #}
{% extends "base.html" %}
{% block body %}
<h1>{{ t('search.title') }}</h1>
<form method="get" action="{{ request.path|url }}" role="search">
  <label for="q">{{ t('search.field') }}</label>
  <input id="q" type="search" name="q" value="{{ results.query }}">
  <button type="submit">{{ t('search.go') }}</button>
</form>
{% if results.degraded %}<p role="status">{{ t('search.browse_notice') }}</p>{% endif %}
{% if results.items %}
<p>{{ t('search.count', results.total) }}</p>
<ol>
  {% for item in results.items %}{% if item.title %}
  <li>
    <h2><a href="{% if item.clickUrl %}{{ item.clickUrl|url }}{% else %}{{ item.uri|url }}{% endif %}">{{ item.title }}</a></h2>
    {% if item.highlight %}<p>{{ item.highlight }}</p>{% elif item.summary %}<p>{{ item.summary }}</p>{% endif %}
  </li>
  {% endif %}{% endfor %}
</ol>
{% if results.pagination.next %}<a rel="next" href="{{ results.pagination.next|url }}">{{ t('pager.next') }}</a>{% endif %}
{% elif results.query %}
<p>{{ t('search.none') }}</p>
{% endif %}
{% endblock %}
```

```yaml
# config/strings/en.yaml
strings:
  search.title: Search
  search.field: What are you looking for?
  search.go: Search
  search.browse_notice: Results are filtered, not ranked.
  search.count:
    one: "{count} result"
    other: "{count} results"
  search.none: Nothing matched. Try a shorter phrase.
```

- The form is a plain `GET`, so search works without JavaScript and every result page has an address.
- `{% if item.title %}` leaves out results with no title (a singleton home page, for example), which would otherwise print an empty link that fails the accessibility audit.
- If you print the type facet (`results.facets.type`), label each value with `f.label|default:f.value`: in browse mode the labels can be empty.
- `searchForm()` prints a search box for the header: a `GET` form to this route, and nothing on a site that routes no search.

## Connect a search service [#connect-a-search-service]

Browse mode lists published documents in the locale and does not rank or match words, so tell the person it is a fallback. For real search, run a backend and point the engine at it:

```bash
engine-dmo dev config set engine.yaml search.driver meilisearch
```

The connection settings and keys (always `${VAR}`) are in [Search](/features/search). Then `engine-dmo search rebuild` indexes every published document and `engine-dmo search test "towpath"` shows what a query returns.

## Verify [#verify]

Search pages are not in the sitemap, so name them:

```bash
engine-dmo render '/search?q=towpath' --json
engine-dmo a11y audit --path /search --path '/search?q=towpath'
```

Both must answer 200 with no findings.


# Rules (/agents/rules)

Every rule a coding agent must follow in a Meridian project, why it exists and exactly what breaks when it is ignored, covering configuration, ids, secrets, schema changes, content, templates, accessibility, generated files and production.

These rules come from the engine itself: most are enforced by `engine-dmo check`, `schema apply` or the renderer, and the rest protect data the engine cannot protect for you. Each says what to do, why, and what happens otherwise.

## Configuration [#configuration]

### Change configuration through files and engine commands [#change-configuration-through-files-and-engine-commands]

Everything a site is (types, fields, sites, locales, routes, endpoints, navigation slots, roles, tiers, portal screens) lives in YAML under `config/`. The database holds a reconciled copy that `engine-dmo schema apply` writes. Content lives in the database and is written by the admin, `engine-dmo content`, `engine-dmo seed` or the APIs.

- **Do** use a `dev` verb where one exists: it edits the file keeping its comments, writes the new element's id and checks the configuration, and writes nothing when the configuration itself would be invalid. It does not wait for templates: a route or endpoint it adds names templates you must then write, and `check` fails until you do. Run `engine-dmo check` after every verb.
- **Do** edit YAML by hand when no verb fits, then run `engine-dmo check --fix`.
- **Never** write SQL, connect to the database with `psql`, or change a table. The engine keeps revisions, search, projections, caches and audit records consistent only through its own writes. A row you insert is invisible to them, and a schema change you make by hand is undone or refused by the next `schema apply`.

### Unknown keys are errors [#unknown-keys-are-errors]

Every configuration file is decoded strictly. A misspelt key is an error with a suggestion (`unknown field "pagniate"`, `did you mean "paginate"?`), not a silent no-op. Look the key up with `engine-dmo config schema --file <kind>` rather than guessing.

### Secrets are only ever `${VAR}` [#secrets-are-only-ever-var]

Configuration is committed to version control. A password, API key, token or signing key is written as a bare `${VAR}` and the value comes from the environment:

```yaml
mail:
  smtp:
    password: ${SMTP_PASSWORD}
```

A literal in a secret path fails `check` with `MRD-1004` ("is a secret and must be an environment interpolation, not a literal"). If you ever wrote a real secret into a file, tell the person: it must be rotated, because it is in the history. A non-secret value may carry a default, `${LISTEN_ADDR:-127.0.0.1:8080}`; a secret cannot (`check` refuses `${SIGNING_KEY:-}` with `MRD-1004`). The engine never reads a `.env` file: the variables must be in the process environment, so export them in the shell, the CI job or the deployment. Keep any `.env` you use with your own tooling out of version control (the starter's `.gitignore` lists it).

### Interpolation fills strings only [#interpolation-fills-strings-only]

`${VAR}` works in string values. A boolean or number (`require_mfa`, `port`) cannot come from the environment; write it in the file.

## Stable ids [#stable-ids]

Every configuration element (type, field, option, site, locale, route, endpoint, navigation slot, landing, tier, portal screen and the rest) carries an `id:` beside its handle, such as `typ_bm5h7rk9j6` or `fld_azkam2rfyt`. The database stores everything by id, so a renamed handle keeps its data.

| Rule | Why | What breaks otherwise |
|---|---|---|
| Never invent an id | `check` accepts any well-formed id, so a made-up one is not caught | Two projects or two elements can collide, and data binds to the wrong element |
| Never copy an id from another element or project | An id belongs to one element | `check` reports `id fld_... is written on two elements`; if it reaches a database, `schema plan` marks the element `!` (replace) |
| Let a verb or `check --fix` write ids | They mint ids that cannot collide | |
| Rename with `dev field rename`, `dev site rename`, `dev tier rename` and the other rename verbs | The id stays, the old field handle stays as an alias, an old site's URLs redirect | Deleting and re-adding loses every stored value under the old id |
| Never change an existing id | The id is the identity | The plan replaces the element; its values are left behind |

When you copy a block of YAML to make a new element, delete the copy's `id:` line and run `engine-dmo check --fix`. Field names `id`, `type`, `uri`, `url`, `status`, `locale`, `tags`, `seo`, `noindex`, `author`, `organisation`, `createdAt`, `updatedAt`, `publishedAt`, `redirectFrom` and `translations` are reserved by the engine and refused. See [Stable ids](/concepts/stable-ids).

## Schema changes [#schema-changes]

### Plan before apply [#plan-before-apply]

`engine-dmo schema plan` is read-only and exits 2 when changes are pending. Read every line before `engine-dmo schema apply`:

| Mark | Meaning | What you do |
|---|---|---|
| `+` | Add | Apply |
| `~` | Change | Apply |
| `>` | Rename: same id, new handle | Apply; values are kept |
| `-` | Remove | Check nothing still needs it |
| `!` | Replace: an existing handle has a new id | Almost always a copied id or a hand-edited one. Put the stored id back. Never pass `--replace` unless the person asked for a new element |
| `[DESTRUCTIVE: ...]` | Loses data or access | Stop and ask the person |

### Destructive plans are a person's decision [#destructive-plans-are-a-persons-decision]

`schema apply` refuses a destructive plan (a removed field that documents hold values in, a grant whose removal takes a permission from active users) unless it is approved with an approval file or `--allow-destructive`. A verb with `--apply` exits 2 and writes the configuration but leaves such a plan unapplied. Do not approve it yourself: tell the person what the plan removes and let them run `engine-dmo schema apply --allow-destructive`. Removed values are kept under `_orphaned` in each revision, but anything that read them stops working.

### The plan never runs in production by itself [#the-plan-never-runs-in-production-by-itself]

`dev up` and `--apply` apply only non-destructive plans, and only outside production. In production the deploy runs `migrate up` then `schema apply` as explicit steps ([Deploying](/deploying)).

## Content [#content]

- **Write content with `engine-dmo content create|update|publish`, `engine-dmo seed` or the admin**, never with SQL. Every write goes through the field validation, the revision history and the publish checks an editor's save does.
- **`seed apply` is not an upsert.** It refuses a database that already holds documents or media. In development, `engine-dmo seed reset --confirm` empties content, media and analytics first; it is refused in production. Never run `seed reset` against a database with content the person cares about without asking.
- **Seed files never contain database ids.** Documents, assets and navigation name each other by seed key (`{ id: banbury, type: area }`, `{ asset: towpath }`, `page/home`). A configuration element's id (an endpoint's `end_...` in a `form` field, a field's `fld_...`) comes from `config/` and is the same in every database, so a seed may name one; copy it from `engine-dmo describe project`. Database ids (UUIDs such as `01a19a3d-...`) never go in a seed.
- **Write realistic content.** Real-sounding titles, summaries within the field's limits, alt text that describes the image. Never generate a photograph of a real place and present it as real: use the person's own photographs or the placeholders `seed generate` makes, and say which is which.

## Templates [#templates]

Templates are Pongo2 (Django-style) and autoescaped. `engine-dmo check` lints every template against the project's schema and the template contract; the renderer enforces the same rules again.

| Rule | Enforced by | What happens |
|---|---|---|
| Print only variables the context has | `check`, partly | `"x" is not in the template context`; `entry has no field "subtitle"`, with a suggestion. Fields are checked on `entry`, the type's own key and the context's named values only. A field on a loop variable (`{% for w in items %}{{ w.photo }}`), on a related document or on a component's typed prop is not checked and prints nothing when misspelt: render the page and read it |
| An included partial reads only the page's context | `check` | `{% include "x.html" with name=value %}` fails with `"name" is not in the template context`. Make a template that takes values a component (`engine-dmo new component`) or a macro |
| No `\|safe` | `check` and the compiler | Refused unless `templates.allow_unescaped: true` in `site.yaml`. Values the engine produces as markup (`\|ptext`, `\|markdown`, `head()`, `img()`) print as they are; `\|raw` accepts only those typed safe values |
| No `{% autoescape %}` | `check` | Refused for the same reason |
| No `\|truncatechars_html` or `\|truncatewords_html` | Nobody | They print their input as unescaped markup, even with `allow_unescaped` off, and `check` does not flag them. Use `\|truncatechars` or `\|truncatewords` |
| A variable inside `<script>` goes through `\|json` | `check` | `a variable inside <script> must go through \|json` |
| A variable in `href`, `src`, `action` and other URL attributes goes through `\|url` (or comes from a link helper) | `check` | `a variable inside href must go through \|url`. `\|url` refuses `javascript:` and `data:` |
| No variable in an inline event handler, a `style` attribute or a `<style>` element | `check` | Refused: put values in `data-*` attributes or classes |
| Quote every attribute value that holds a variable | `check` | Refused |
| No inline executable scripts | The site's content security policy | When `server.security.csp` is set, `script-src` may not include `'unsafe-inline'`, so an inline script never runs. Put scripts in files under `public/` or the frontend build. JSON-LD (`type="application/ld+json"`) is data and is fine |
| Every visible string through `t('key')` | `check` warns | A missing key renders as the key itself; a locale without it falls back down its chain |
| Links from helpers | Convention, and `\|url` | Use `path('/')`, `path('walk')`, `entry.uri\|url`, `item.url\|url` from navigation. A document's `uri` is its path on the current origin, the one to use for links inside the site; its `url` is the absolute address on the site's configured domain, for a canonical, a share link or an email. Both pass `\|url`. A hand-written path breaks under a locale prefix or a renamed route. The one exception is the claim form, `/members/claim/{{ entry.organisation.id }}`, which has no helper ([Claims](/agents/recipes/claims)) |
| The layout prints `head()` and `jsonld()` | `check`, partly | `check` warns about a head with no `head()`, and about no `jsonld()` only when a type has a `structured_data` block. Neither warning fails it. Without `jsonld()` the site has no structured data and every check passes: grep a render for `application/ld+json` |
| Forms from declarations | Convention | Draw forms with a `form` field's `render()`, `enquiryForm()` or `subscribeForm()`, and print `csrfInput()` in any form you write yourself |
| Queries filter and sort on `index: true` fields only | `render` | `check` does not catch this: the page answers 500 with `is not declared index: true`. Render every page that queries |
| A query names one type | `render` | `query('walk', 'page')` and `query(['walk', 'page'])` return nothing and log a database error. Run one query per type |
| Only one `priority=true` image per page | `check` | Two compete for bandwidth |
| Print an image's credit | `check` warns | Use `figure()`, which prints it, or print `.credit` beside `img()` and `picture()` |

See [The template language](/templates/language), [Links and URLs](/templates/links) and [Forms in templates](/templates/forms).

## Accessibility [#accessibility]

Public sites must meet WCAG 2.2 AA. The engine checks what it can; you are responsible for the rest. Every page you write:

- has `lang` and `dir` on `<html>` from `locale.code` and `locale.direction`;
- has exactly one `h1`, and headings in order below it;
- has a skip link to `<main id="main">` as the first focusable element;
- names every landmark `<nav>` with `aria-label` from `t()` when there is more than one;
- gives every form control a visible `<label for>` (a placeholder is not a label), and every error a link from an error summary;
- gives every informative image alt text (in the media library or `alt=`), and decorative images `alt=""`;
- uses no positive `tabindex`, no duplicate `id`, and no `aria-labelledby` or `for` pointing at an id that is not on the page;
- marks the current navigation item with `aria-current="page"`;
- never conveys meaning by colour alone, and keeps text contrast at 4.5:1 (your CSS; the engine cannot check it).

`engine-dmo check` warns about several of these in templates, `engine-dmo render --json` lists findings in `a11y`, and `engine-dmo a11y audit --all` renders every page and fails on them. Passing the automated checks is evidence, not conformance: tell the person a manual check with a keyboard and a screen reader is still needed. See [Accessibility](/features/accessibility).

## Generated files [#generated-files]

Do not edit these by hand. The engine rewrites them, and your changes are lost or contradict the configuration:

| File | Written by | Regenerate with |
|---|---|---|
| `AGENTS.md` | `init`, every `dev` verb | `engine-dmo guide --out AGENTS.md` |
| `.claude/skills/meridian-project/SKILL.md` | `init`, every `dev` verb | `engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md` |
| `.claude/skills/meridian/SKILL.md` | `init`, every `dev` verb | `engine-dmo docs skill --out .claude/skills/meridian/SKILL.md` |
| `.meridian/` | `init`, `config schema --write`, `dev up` | It is local state; it is in `.gitignore` |
| `id:` values | verbs, `check --fix` | |
| `storage/` | the media pipeline | Local media; never commit it |
| `public/build/` | the frontend build | `engine-dmo build` |

Put project-specific notes for future agents in your own file (for example `NOTES.md`), not in `AGENTS.md`.

## Production [#production]

- `ENVIRONMENT=production engine-dmo check --no-db` must pass before a deploy. It is the only guard for the mail rules: an engine started in production on the `log` driver does not refuse to start. It requires `server.security.signing_key` (32 characters or more, from `${SIGNING_KEY}`), `server.base_url`, `server.trusted_proxies` when a real IP header is used, a real mail driver and `mail.from`, and refuses `auth.staff.local.require_mfa: false`.
- The `dev` verbs, `engine-dmo mcp` and `docs serve` are refused in production, and `seed reset` too.
- Never run `serve --dev` in production.
- Never put production credentials in the project; the deployment's environment holds them.

See [Configuration and secrets](/deploying/configuration-and-secrets).

## Honesty [#honesty]

- Use only what the engine has. If the brief asks for something the engine does not do, say so and propose what it can do. Do not imitate a missing feature with client-side script or hard-coded markup.
- Report what you verified and what you could not (a page you could not render, a step that needs a person, such as approving a destructive plan or setting a secret).
- Never claim a page is accessible because the automated checks pass.


# Troubleshooting (/agents/troubleshooting)

The errors a coding agent meets in a Meridian project (from check, the dev verbs, schema plan and apply, seed, render, the accessibility audit and server start), what each message means and the exact fix, with the MRD error codes.

Read the whole output before fixing anything. `check` reports every problem in one run, each at `file:line:col` with the source line, a caret, one or more `=` hints and an `MRD-nnnn` code. Fix the first error in each file first: a file that fails to load can cause later errors that are only consequences (an unknown key in `routes.yaml` also produces "home type page has no route"). Then run the command again. [Error codes](/reference/error-codes) has every code's cause and fix.

## How to read a diagnostic [#how-to-read-a-diagnostic]

```text
config/sites/main/routes.yaml:5:76: unknown field "pagniate"
    5 |   - { type: walk, id: rte_34agwcmxkh, uri: "/walks/{slug}", index: /walks, pagniate: 12 }
      |                                                                            ^
      = did you mean "paginate"?
      = error code MRD-1006
```

The path, line and column; the source line; the caret under the problem; hints (`=`), the first usually the fix; the code. A line with `warning:` does not fail `check` (except under `--strict`), but most warnings are real defects on a public site: fix them.

Quirks of the output to expect:

- Template warnings are not counted. `check` prints them (`_shared/base.html:3:1: warning: ...`) and then a summary such as `0 errors, 0 warnings`; `--strict` does not fail on them and `--json` leaves them out. Read every line, not the summary.
- A template error is printed twice, once as `_shared/page/entry.html:3:5: error: ...` and once as `templates/_shared/page/entry.html:3:5: ...` with the source line. It is one problem.
- Problems in `endpoints.yaml` are reported at the endpoint's line with column 0 (`endpoints.yaml:2:0`), not at the key that is wrong. Read the message for the key.
- Commands that start the engine (`render`, `describe route`, `seed apply`, `mail`) print log lines (`level=INFO ... database connected`) on standard error before their result. With `--json` the result is on standard output alone; a command that fails prints its error after the log lines.
- Hints sometimes cite design documents by file name (such as `27-frontend-toolkit.md`). They are not in the handbook: search https://docs.cherwell.studio/llms-full.txt for the topic.

## Configuration [#configuration]

| Message | Code | Meaning and fix |
|---|---|---|
| `environment variable DATABASE_URL is not set` | MRD-1005 | The configuration names `${DATABASE_URL}` and it is unset. Export it; commands that need no database (`seed verify`, `new`, `config render`) accept a placeholder: `DATABASE_URL=postgres://placeholder@localhost/placeholder`. `check --no-db`, `describe` and the `dev` verbs run with it unset. A following `database.url is required` is a consequence. The engine never reads `.env`: export the variable in the shell |
| `environment variable SIGNING_KEY is not set` | MRD-1005 | `engine.yaml` names `${SIGNING_KEY}` (added for production), and every command that loads the configuration now needs it, in development too. `export SIGNING_KEY="$(openssl rand -hex 32)"`. The same goes for every other secret, such as `${SMTP_PASSWORD}`: export a placeholder |
| `server.security.signing_key must be at least 32 characters` | MRD-1006 | The value you exported is too short. Use 32 characters or more |
| `<path> is a secret and must be an environment interpolation, not a literal` | MRD-1004 | Write `${VAR}` and set the variable. If the literal was a real secret, tell the person to rotate it. A default (`${SIGNING_KEY:-}`) counts as a literal: a secret takes a bare `${VAR}` |
| `unknown field "x"` with `did you mean "y"?` | MRD-1006 | A misspelt or invented key. Use the suggestion, or look the file up with `engine-dmo config schema --file <kind>` |
| `A configuration file is not valid YAML` | MRD-1002 | A tab used for indentation, an unclosed quote or bracket, or a value starting with `@`, `%` or a backtick. Quote the value |
| `route "page" has no id`, `nav slot "main" has no id`, `field "x" has no id` | MRD-1006 | An element added by hand. Run `engine-dmo check --fix`; never type an id |
| `id fld_... is written on two elements` | MRD-1006 | A copied block kept its id. Delete the copy's `id:` line and run `check --fix` |
| `"id" is an engine-managed field and cannot be declared` | MRD-1006 | A reserved field name (`id`, `type`, `uri`, `url`, `status`, `locale`, `tags`, `seo`, `noindex`, `author`, `organisation`, `createdAt`, `updatedAt`, `publishedAt`, `redirectFrom`, `translations`). Choose another |
| `type key "tourOperator" must be lowercase letters, digits and underscores` | MRD-1006 | Use `tour_operator` |
| `type "walk" has an index route and no walk/index.html on site main`, `no template found for type "walk" on site main` | MRD-1006 | `engine-dmo new template walk/index.html` and `engine-dmo new template walk/entry.html`. `schema plan` and `schema apply` work until you have written them |
| `routes "/{slug}" (page@en) and "/{slug}" (area@en) are ambiguous: same shape and priority; give one a priority` | MRD-1006 | Two types at one address shape. Keep both and add `priority: 10` to the `page` route, or route the other under its own word (`/towns/{slug}`). Lookups go by each document's stored address, so both keep answering, whichever has the higher number ([DMO directory](/agents/recipes/dmo-directory#route-listings-and-areas)) |
| `endpoint "contact" responds with partials/enquiry-sent.html, which no template root has` | MRD-1006 | Write the template the endpoint names ([Enquiry form](/agents/recipes/enquiry-form)) |
| `endpoint "contact" mails enquiry-receipt, which is not under templates/emails/` | MRD-1006 | Write `templates/_shared/emails/enquiry-receipt.html` |
| `home type "page" has no route on site main` | MRD-1006 | The home page's type is not routed, or `routes.yaml` failed to load: fix the error above it first |
| `the label of field X has no translation for cy` (warning) | | Add the locale to the label map: `label: { en: Photo, cy: Llun }`. Saying `for en` on a one-locale site means the labels were pasted under another code (`en-GB`): use your source locale's code. `--strict` fails on it |
| `slug for locale en-GB, which site main does not enable`, `landing by-place has no slug for stay in en, ...; the value itself is used` (warning) | | The landing's maps name the wrong locale, so the page is served at the raw value (`/monmouth/stay`). Use your source locale's code. `--strict` fails on it |
| `the structured_data mapping of listing has no priceRange, which the local business panel recommends` (warning) | | The type is a `LocalBusiness`, and search engines' guidance recommends a price range. `check --strict` fails on it. If the businesses charge, add a text field and map it: `priceRange: priceRange` under `structured_data.map`, with a value such as `££` on each document. If a whole type has no price, such as a directory of walks or viewpoints, make it `type: TouristAttraction`, which has no such recommendation. Do not map one fixed `{ value: "££" }`: it silences the warning with a claim that is false for most businesses |
| `type listing maps structured data, and its page on site main calls no jsonld(), so the mapping is never emitted` (warning) | | Print `{{ jsonld() }}` in `base.html` after `{{ head() }}`. `--strict` does not fail on it |
| `cy is missing 14 of 18 strings: ...` (warning) | | Add the listed keys to `config/strings/cy.yaml` |
| `site main routes search and no backend is configured` (warning) | | The search page runs in browse mode. Expected in development; tell the person |
| `the image transforms name avif and webp, which this build cannot encode` (note) | | Harmless. A transform with no `formats:` asks for AVIF and WebP; this binary serves JPEG and PNG, and the `-vips` image serves all of them. `formats: [jpeg]` on every transform silences the note, at the cost of the modern formats on the `-vips` image too, so leave it unless the person asks |
| `--after names "slug", which is not a field in schema/page.yaml` | | On a core type, `--after` can name only a field of your own `extends:` file. Leave `--after` out: added fields follow the core ones |

## Templates [#templates]

| Message | Fix |
|---|---|
| `entry has no field "subtitle" in this project's schema` with `did you mean entry.title?` | Use a field the type has (`engine-dmo describe type <key>`), or add the field |
| `"x" is not in the template context (contract 1)` | A variable that does not exist here. Print the real context with `engine-dmo describe route <path> --json` |
| `x() is not a template function` | Check the name in `engine-dmo template api` |
| `\|safe is not allowed in this site's templates` and `Usage of filter 'safe' is not allowed (sandbox restriction active)` | Print engine markup as it is (`{{ entry.body\|ptext }}`, `{{ head() }}`); never mark your own strings safe |
| `a variable inside <script> must go through \|json` | Put the value in a `data-*` attribute that a script file under `public/` reads. Inside a `<script type="application/ld+json">` block, print it as `{{ value\|json }}` |
| `a variable inside href must go through \|url` | `href="{{ walk.uri\|url }}"`. The same for `src`, `action` and other URL attributes, and for helpers: `href="{{ track(entry, 'website', entry.website.url)\|url }}"` |
| `a link to listing.website, a member's own destination, does not go through track()` (warning), with the hint `href="{{ track(listing, 'website', listing.website.url) }}"` | The hint leaves out `\|url`, and following it as written fails with the error above. Write `{{ track(entry, 'website', entry.website.url)\|url }}` |
| `a variable inside an inline event handler is not allowed`, `a variable inside a style attribute is not allowed` | Move the value to a `data-*` attribute or a class |
| `an attribute value with a variable must be quoted` | `class="{{ x }}"`, never `class={{ x }}` |
| `x.y is the field's old handle; it is now x.z` (warning) | A field was renamed. Use the new handle, then `engine-dmo schema alias retire x.y` |
| `t("x") is not in the string catalogue and renders as its id` (warning) | Add `x` to `config/strings/<locale>.yaml` |
| `this head has no head() and its own tags miss a meta description` (warning) | Print `{{ head() }}` in `<head>` |
| `x is rendered with picture() and its credit is printed nowhere in this template` (warning) | Use `figure()`, or print `{{ x.credit }}` beside the image |
| `this template writes more than one h1` (warning) | Make later headings `h2` and below |
| `this control is named only by its placeholder` (warning) | Add `<label for="...">` matching the control's `id` |
| `x.y(...): the site has no transform "z"` | Declare the transform in `config/images.yaml` |
| `a second priority=true on the page` | Only the page's main image takes `priority=true` |
| `required prop x is missing from the call to y`, `slot "x" is not declared in this component's contract` | Match the call to the component's `component.yaml` |
| `x belongs to the y module, which this bundle does not compile` | A DMO feature used on `engine-cms`. Remove it or use `engine-dmo` |

## The dev verbs [#the-dev-verbs]

| Message | Meaning and fix |
|---|---|
| `the change would leave the configuration invalid; nothing was written` | The diagnostics printed above it say why. Common cause: a select with no `--options` |
| `dev route add --scaffold` printed `wrote config/sites/main/routes.yaml`, then `environment variable ... is not set`, exit 3 | The route is written; the template is not. Export the variable, then `engine-dmo new template <type>/entry.html`. Running the verb again only says `nothing to change` |
| `there is no type "walk"; did you mean "page"?` | Add the type first (`dev type add`) |
| `the edit would not parse: mapping key "id" already defined` | The verb cannot edit a field written in block style (one key per line), as `dev field remove` does on such files. Make the change by hand in the YAML, then `engine-dmo check` |
| `0.timezone does not exist under locales.available; set it from the top or edit the file` | `dev config set` does not take list indexes. Edit the file by hand |
| `error: engine-dmo dev up has not run in this project` | From `dev status`. Start `dev up`, or use `--apply` on the verbs instead |
| Exit 2 after a verb with `--apply` | The plan is destructive and was not applied. The file is written. Ask the person to review `engine-dmo schema plan` and run `engine-dmo schema apply --allow-destructive` |

Some verbs write a valid change that leaves follow-up work: `dev endpoint add` writes an endpoint whose templates you must then write, `dev route add` without `--scaffold` a route whose templates are missing, and `dev route add --index` with `--scaffold` still leaves `index.html` to `engine-dmo new template <type>/index.html`. Run `engine-dmo check` after every verb.

## Schema plan and apply [#schema-plan-and-apply]

| Symptom | Meaning and fix |
|---|---|
| `schema plan` exits 2 | Changes are pending. Normal: read them, then `schema apply` |
| A line marked `!` | An element's handle has a new id: a copied or hand-edited id. Put the stored id back (`engine-dmo describe type` on the old configuration, or `git diff`). Never `--replace` unless the person asked for a new element |
| `[DESTRUCTIVE: ...]` | Data or access would be lost. Stop and ask the person |
| A line under `NOT YET` | This engine version cannot apply that change. Undo it in the files to apply the rest |
| `schema apply` refuses to leave nobody with the `owner` role | Keep a grant of `owner` in `config/access/grants.yaml` |
| `Applying the schema plan failed` | MRD-2005. Run `schema plan` for the step and its reason |

## Seeding and content [#seeding-and-content]

| Message | Fix |
|---|---|
| `duplicate key value violates unique constraint "document_site_uri_path_idx"` | Two documents want one address, usually a page and an area at `/{slug}` with the same slug. Change one slug, or route one type under its own word, then `seed reset --confirm` and `seed apply` |
| `publish en refused: phone: Enter the number with its country code, starting with +` | A bare national number with no region. Write `{ raw: "01600 712345", region: GB }`, or `region: GB` on the field. A seed does not read `site.country` |
| `primaryTag: nope is not a vocabulary tag` | Add the tag to `config/tags/vocabulary.yaml`, by its full dotted key, or name one that is there |
| `tags: invalid: the vocabulary has 1 problems` | From `seed apply`, which does not say which. Usually a child key not under its parent (`hotel` instead of `stay.hotel`) or a tag with no label. `engine-dmo tags import` lists them |
| `organisation "x" is not in organisations/` | From `seed verify`. The value is the organisation's file name with no extension, under `seed/organisations/`. List the folder to see the keys |
| `the database already holds N documents and M assets; run engine-dmo seed reset first` | In development: `engine-dmo seed reset --confirm`, then `seed apply`. Never on a database with real content without asking |
| `no en content (the source locale)` | Every seed document needs the source locale's values |
| `publish en refused: distanceKm: Must be 0 or more; difficulty: "trivial" is not one of the options` | The value breaks the field's rules. `seed verify` does not check values, so this shows only at `seed apply`. The documents before this one were written: run `engine-dmo seed reset --confirm`, fix the value, and `seed apply` again |
| `init` says the seed imports photographs from a media library that is not there | The copied seed's `library.dir` points outside the project. Fetch the library as `init` says, or replace those photographs with files under `seed/assets/` |
| `nonsense: type page has no field "nonsense" ... (unknown_field)` | From `content create` or `update`: name fields by handle (`engine-dmo describe type page`) |

## Render [#render]

| Symptom | Meaning and fix |
|---|---|
| Exit 1 and `status 404`, `kind: not_found` | Nothing published answers that path in that locale: a wrong slug, an unpublished document, a locale prefix missing (`/cy/...`), or a landing page not yet counted. `engine-dmo content list --type <key>` shows what is published |
| Exit 1 and `status 500` with `errors` | A template failed. Each error has `file`, `line`, `column` and `message`. Common: `query().where("summary"): summary is not declared index: true, so it cannot be queried`: add `--index` to the field (`dev field set <type> <field> --param index=true`) or filter on another field |
| `site main does not enable locale "fr"` | Use a locale the site enables, or add it ([Multilingual site](/agents/recipes/multilingual-site)) |
| `host x resolves to site a, not b` | Pass `--host` with one of the site's domains, or leave `--site` out |
| `fragment x did not render on this page` | The fragment name is wrong, or its region sits inside a false condition |
| A page renders but something is empty | `engine-dmo describe route <path> --json` shows the context: is the value there? Unrelated rows from a database error in a query are logged and return an empty list |
| Numbers print as `6.500000` | Pass them through `\|number` before `t()` |
| A select prints its raw value | Its options have no labels: add `label:` to each option. `check` does not warn about an option with no label at all, only about a label missing a locale, so the first option of a select made with `--options` passes silently |
| A field prints nothing, with no error | A misspelt field on a loop variable or a component prop (`{{ w.phto }}`), which `check` does not hold to the schema. Compare with `engine-dmo describe type <key>` |
| A form's `_csrf` value is empty | Expected for an anonymous visitor, under `render` and on a running server, with no cookie set. Only a signed-in member or staff user has a token; an anonymous post is checked by its origin ([Enquiry form](/agents/recipes/enquiry-form#verify)) |
| `status: 301`, exit 0, and `a11y` lists `a page has exactly one h1, this one has 0` | The address redirects, and its small redirect body was checked as a page. Render the address it redirects to, shown in the `html` |
| A form post from a script answers 422 with valid input, or 429 | No challenge token, or a token too new (422), or over the endpoint's `rate_limit` (429). See [Post it from a script](/agents/recipes/enquiry-form#post-it-from-a-script) |
| `form.problems` prints as its key above a form's errors | Add `form.problems` to the strings, with `one` and `other` |
| A sign-in link answers `Open this link in the browser where you requested it` | A sign-in link works only with the cookie of the browser that asked. In a script use one cookie jar for both requests ([Partner portal](/agents/recipes/partner-portal#sign-in)) |

## Accessibility audit [#accessibility-audit]

`engine-dmo a11y audit` exits 1 on any failure. Each finding names its rule:

| Rule | Fix |
|---|---|
| `status` | The page did not answer 200: render it to see why |
| `image-alt` | An `<img>` with no `alt`. Use `img()`/`figure()` and give the asset alt text, or `alt=""` for a decorative use |
| `control-name` | A link or button with no text: an empty link (a search result with no title, an icon link). Add text or `aria-label` from `t()` |
| `placeholder-name` | A control named only by its placeholder. Add a `<label for>` |
| `missing-reference` | `for`, `aria-labelledby` or `aria-describedby` names an id not on the page |
| `duplicate-id` | Two elements share an `id`. Derive ids from the item (`f-{{ fld.name }}`) |
| `positive-tabindex` | Remove `tabindex` values above 0 |
| `one-h1` | A page has exactly one `h1` |
| `html-lang` with `page-title` on a `--path` | Usually an address that redirects: its redirect body has neither. `render <path> --json` shows `status: 301`. Name the address it redirects to |

## Server start (dev up and serve) [#server-start-dev-up-and-serve]

| Message | Code | Fix |
|---|---|---|
| The database has migrations the binary has not applied | MRD-2001 | `engine-dmo migrate up` |
| The schema in the database differs from the configuration | MRD-2004 | `engine-dmo schema plan`, then `schema apply` |
| The database is newer than this binary | MRD-2003 | Use the engine version that migrated it; migrations never go back |
| The engine cannot reach the database | MRD-3001 | Check `DATABASE_URL` and that PostgreSQL 14 or later answers |
| The engine cannot listen on its address | MRD-3003 | Another process holds the port: `dev up --listen 127.0.0.1:8081`. If the message says `metrics listen on 127.0.0.1:9090`, it is another Meridian server's metrics port: set `telemetry.metrics.bind` in this project's `engine.yaml` to another port |
| The templates failed the linter at boot | MRD-3004 | Run `engine-dmo check` and fix each finding |

## Production check [#production-check]

`ENVIRONMENT=production engine-dmo check --no-db` reports in groups, so fix and run it again until it passes. Typical findings: `server.security.signing_key is required in production` (add `security: { signing_key: ${SIGNING_KEY} }` under `server:`), `a real IP header is configured but server.trusted_proxies is empty` (list the proxy's addresses, or `real_ip_header: ""` with nothing in front), `the log driver is development only` (configure `smtp`, `postmark`, `ses` or `resend` with `mail.from`), and `require_mfa: false` refused. See [Configuration and secrets](/deploying/configuration-and-secrets).

## Extensions [#extensions]

`check` reports each loader problem at its line in `engine.yaml`. The common ones: `this engine is a pure Go build, which cannot load extensions` (run a cgo build such as the `-vips` image), and `does not match this engine (...)` followed by each difference (Go version, platform, `-trimpath`, `meridian-extend` version). The full list is in [Extensions](/extending/extensions#errors).

## When you are stuck [#when-you-are-stuck]

```mermaid
flowchart TD
  start["Something failed"] --> read["Read every line of<br/>engine-dmo check"]
  read --> see["Print what the engine sees:<br/>describe route, describe type,<br/>config render"]
  see --> search["Search the handbook for<br/>words from the message"]
  search --> fix["Smallest change<br/>that could fix it"]
  fix --> loop{"Loop passes?"}
  loop -- yes --> done["Carry on"]
  loop -- "no, and the engine<br/>cannot do it" --> tell["Tell the person;<br/>doctor --out doctor.txt"]
  loop -- "no, another idea" --> fix
```


1. Run `engine-dmo check` and read every line.
2. Print what the engine sees: `describe route <path> --json`, `describe type <key>`, `config render`.
3. Search the handbook for a few words of the message: https://docs.cherwell.studio/llms-full.txt.
4. Make the smallest change that could fix it and run the loop again.
5. If the engine cannot do what is needed, say so to the person with the message and what you tried. `engine-dmo doctor --out doctor.txt` writes a support bundle they can send on.


# Workflow: from a brief to a running site (/agents/workflow)

The order of work for a coding agent turning a written brief into a working, accessible, deployable Meridian site, step by step, with the exact command for each step and how to verify it before moving on.

Follow these steps in order. Each ends with a check; do not start the next step until it passes. The examples build a small walking-and-places site; replace the names with the brief's.

```mermaid
flowchart TD
  brief["1. Brief and plan"] --> bundle["2. Choose the bundle"]
  bundle --> init["3. init the project"]
  init --> basics["4. Locales and site"]
  basics --> db["5. migrate, schema apply,<br/>seed apply"]
  db --> model["6. Types, fields, routes"]
  model --> seed["7. Seed content"]
  seed --> tpl["8. Templates"]
  tpl --> fe["9. Frontend"]
  fe --> checkall["10. check, check --strict,<br/>seed verify"]
  checkall --> renderall["11. a11y audit and render"]
  renderall --> a11y["12. Accessibility pass"]
  a11y --> deploy["13. Production check"]
  deploy --> report["Hand back"]
```

You need the engine binary on the `PATH` (`engine-dmo version` answers), a PostgreSQL database you may write to, and its URL in `DATABASE_URL`. There is no standalone download of the binary: a release publishes Linux container images of `engine-dmo`, and [Install](/getting-started/install) says how to run commands through one. The example projects are in the Meridian source repository only, so `init --from` works only on a project directory you have.

### Without a database [#without-a-database]

You can still do steps 1 to 4, 6, 9 and 10 with `engine-dmo check --no-db`; say in your report that nothing was rendered. `render`, `describe route`, `a11y audit`, `schema plan` and `seed apply` need a real database; nothing renders without one.

Set every `${VAR}` the configuration names without a default, even to a placeholder, before you run anything else. The starter needs only `DATABASE_URL`; once you add production secrets (step 13) they need values too, and `SIGNING_KEY` must be at least 32 characters. The engine does not read a `.env` file, so export them in the shell:

```bash
export DATABASE_URL='postgres://placeholder@localhost/placeholder'
export SIGNING_KEY="$(openssl rand -hex 32)"
```

`check --no-db` and the `dev` verbs (except `--scaffold`) run with them unset; `check`, `seed verify`, `new`, `config render` and `a11y statement` do not. [What each command needs](/agents/commands#what-each-command-needs) has the full list.

<Steps>
<Step>
## Read the brief and write a plan [#read-the-brief-and-write-a-plan]

Before touching a file, turn the brief into a short plan, and keep it in your notes:

| Decide | Examples |
|---|---|
| Sites and domains | One site, or a county site and a town site sharing content |
| Locales | `en-GB` only, or `en-GB` and `cy-GB`; each locale's time zone and currency |
| Content types and their fields | Walk: title, slug, summary, distance, difficulty, photo, route description |
| Routes | `/walks/{slug}` with an index at `/walks`, filtered by difficulty, 12 per page |
| Pages and navigation | Home, About, Contact; header and footer menus |
| Forms | A contact form, a newsletter sign-up, an enquiry to a business |
| Search | A search page, with or without a search service |
| DMO features | A directory of businesses, areas, landing pages, a member portal |
| Look and feel | Colours, type, logo; plain CSS or an existing frontend build |

Map every requirement to an engine feature using the handbook (https://docs.cherwell.studio/llms.txt lists its pages). Anything with no feature is a gap: write it down and tell the person, rather than inventing a workaround.

**Verify:** every item in the plan names the handbook page that covers it.
</Step>

<Step>
## Choose the bundle [#choose-the-bundle]

Use `engine-dmo` when the brief needs any of: a directory of businesses or places (`listing`, `area`), organisations and their people, membership tiers, a partner or member portal, ownership claims, paid promotions, landing pages for place and category, affiliate links, member reports. Otherwise use `engine-cms`. A project written for `engine-cms` runs on `engine-dmo` unchanged, so `engine-dmo` is the safe choice when unsure. Its DMO modules add nothing to the public site until you configure them, with one exception: the member portal is on by default at `/members` (`describe project` shows `portal /members, both`). On a site with no partner businesses, turn it off:

```yaml
# config/portal/portal.yaml
portal:
  mode: "off"
```

`describe project` then shows `portal /members, off`.

```bash
engine-dmo version
```

**Verify:** the `bundle` line lists the modules the plan needs.
</Step>

<Step>
## Create the project [#create-the-project]

```bash
engine-dmo init my-site
cd my-site
```

`init` writes the starter: one locale (`en`), one site (`main`) answering on `localhost`, the core `page` type routed at `/{slug}`, a home page in the seed and four templates (`base.html`, `page/entry.html`, `errors/404.html` and `errors/500.html` under `templates/_shared/`), plus `AGENTS.md` and two agent skills. If `AGENTS.md` or `.claude/skills/` is missing (a project made with `--agents=false`, or by an engine that did not write them), write them with the three commands in [The project skill and AGENTS.md](/agents/project-skill). To start from an existing project instead (an agency starter, an example the person gave you), use `engine-dmo init my-site --from <dir>`; it copies the project and gives every element new ids.

Every later command reads the project in the current directory, or the one `--project <dir>` names.

**Verify:** `engine-dmo check --no-db` exits 0. It also prints `warning: this head has no head() and its own tags miss a meta description` for the starter's `base.html`, above a summary that says `0 warnings`. That is expected: the starter layout is a placeholder, and step 8 replaces it with one that prints `head()`.
</Step>

<Step>
## Set the basics [#set-the-basics]

Edit `config/locales.yaml` so the source locale has the right code, time zone and currency (the starter has `en`, `Etc/UTC` and `EUR`):

```yaml
locales:
  available:
    - code: en
      id: loc_3990wq8rss          # keep the id init wrote
      label: English
      source: true
      default: true
      timezone: Europe/London
      currency: GBP
```

**Choose the locale code.** `init` writes `en`, which names a language and no country. For a UK site use `en-GB`, because the code decides what a visitor sees:

| | `en` | `en-GB` |
|---|---|---|
| `<html lang>` and `og:locale` | `en` and `en` | `en-GB` and `en_GB` |
| First day of `openingHours.week(now)` | Sunday | Monday |
| A UK phone's `display` | `+44 1600 712345` | `01600 712345` |
| A date in mail | December 2, 2026 | 2 December 2026 |

To change it now, before step 5: edit `code:` in `config/locales.yaml` (keep the `id`), `locales.enabled`, `locales.default` and the key of `site.name` in `site.yaml`, and the locale key and `publish:` in `seed/documents/page/home.yaml`. On a project with labels, rename `config/strings/en.yaml` to `en-GB.yaml` and change the key in every label too. `schema plan` then shows `rename locale`.

The recipes' examples use `en`, the code `init` writes. Replace it with your code wherever you paste one. The wrong code is not always refused: a label fails only `check --strict` (`the label of field priceRange has no translation for en`), and a landing's slugs only warn, then the raw option value is used in the address.

Set the site's name, domains and country in `config/sites/main/site.yaml`:

```yaml
site:
  id: site_0s14b7ndg9            # keep the id init wrote
  name: { en: "Visit Banbury" }
  domains: [localhost, "localhost:8080"]
  default: true
  country: GB
```

`country` is what the admin starts from: the region a phone number typed without `+` is read in, and the country an address form offers first. It also sets the financial year in reports. Seed files and `content create` do not read it, so a seeded phone needs its own region (`{ raw: "01600 712345", region: GB }`) or `region: GB` on the field.

`dev config set` changes one value and checks the result:

```bash
engine-dmo dev config set sites/main/site.yaml site.name.en "Visit Banbury"
```

Then the search engine settings, which all default to off. Nothing fails without them, so set them now:

```yaml
# config/sites/main/site.yaml
seo:
  title_template: "{{ title }} | {{ site.name }}"
  sitemap: { enabled: true }
  robots: { enabled: true }
```

Without them, `/sitemap.xml` and `/robots.txt` answer 404 and page titles carry no site name.

Add more locales with `engine-dmo dev locale add` ([Multilingual site](/agents/recipes/multilingual-site)) and more sites with `engine-dmo dev site add <key> --name "..." --domain town.localhost`.

**Verify:** `engine-dmo check --no-db` exits 0.
</Step>

<Step>
## Put it in the database [#put-it-in-the-database]

```bash
export DATABASE_URL='postgres://user:password@localhost:5432/my_site?sslmode=disable'
engine-dmo migrate up
engine-dmo schema plan
engine-dmo schema apply
engine-dmo seed apply
```

`migrate up` creates the engine's tables, `schema apply` writes your configuration into the database, and `seed apply` loads `seed/`.

**Verify:** `engine-dmo schema plan` prints "No changes" and exits 0, and `engine-dmo render /` exits 0 and prints the home page.
</Step>

<Step>
## Model the content [#model-the-content]

The core `page` type has only `title` and `slug`. Before seeding About or Contact pages, give it a summary (which `head()` uses as the meta description) and a body:

```bash
engine-dmo dev field add page summary --type text --param multiline=true --param max=280 --label Summary --apply
engine-dmo dev field add page body --type portable_text --label Body --apply
```

Fields added to a core type always follow its core fields; `--after` can name only a field in your own `config/schema/page.yaml`. [Core types](/content-modelling#core-types) lists the core fields of every core type.

For each type in the plan, add the type, its fields and its route with the `dev` verbs. `--apply` applies the schema plan when it is not destructive, so you need no long-running process:

```bash
engine-dmo dev type add walk --label Walk --plural Walks --apply
engine-dmo dev field add walk distanceKm --type number --label "Distance (km)" --param min=0 --apply
engine-dmo dev field add walk difficulty --type select --options easy,moderate,hard --label Difficulty --required --index --apply
engine-dmo dev field add walk photo --type asset --label Photo --apply
engine-dmo dev field add walk body --type portable_text --label "Route description" --apply
engine-dmo dev route add walk "/walks/{slug}" --index /walks --scaffold --apply
engine-dmo new template walk/index.html
```

`--scaffold` loads the whole configuration to write `walk/entry.html`, so every `${VAR}` must be set first. If one is unset, the verb has already written the route to `routes.yaml` when it exits 3, and running it again says `nothing to change`: write the template with `engine-dmo new template walk/entry.html` instead. `--scaffold` never writes `index.html`, which is why `new template walk/index.html` follows; that scaffold is an empty block with no `h1`, so it fails the accessibility checks until you write it ([Listing page](/agents/recipes/listing-page)).

Mark `--index` every field a listing page will filter or sort on. Options given with `--options` have no labels, so templates print the raw value: label them as [Add a field](/agents/recipes/add-a-field#a-select-with-labelled-options) shows. Look up a field type's parameters with `engine-dmo describe fieldtypes --json` before you use it. The recipes [Add a content type](/agents/recipes/add-a-content-type), [Add a field](/agents/recipes/add-a-field) and [Add a route](/agents/recipes/add-a-route) cover every option.

If you can keep a background process running, `engine-dmo dev up` does the apply for you on every change and reloads the server; read what it found with `engine-dmo dev status --json`.

**Verify:** `engine-dmo schema plan` exits 0 with no changes, and `engine-dmo describe type walk` lists every field with an id. `engine-dmo check` exits 0 only once every routed type has its templates. A route written with `--scaffold` still lacks `index.html`, and a route written by hand lacks both, so `check` exits 3 with `no template found for type "listing" on site main` and `type "listing" has an index route and no listing/index.html on site main` until you write them (`engine-dmo new template listing/entry.html`, `engine-dmo new template listing/index.html`, or step 8). `schema plan` and `schema apply` do not need the templates, so carry on; `check` is the gate for step 8.
</Step>

<Step>
## Seed realistic content [#seed-realistic-content]

Write seed files so every template has something real to render: at least two documents of every routed type, enough to fill a listing page past its first page when it paginates, and every page the navigation links to.

```yaml
# seed/documents/walk/cherwell-towpath.yaml
locales:
  en:
    title: Cherwell towpath
    slug: cherwell-towpath
    summary: A flat riverside walk along the canal towpath from the town centre.
    distanceKm: 6.5
    difficulty: easy
    photo: { asset: towpath }
publish: [en]
```

Photographs go under `seed/assets/` with a YAML file of the same name holding the alt text and credit. Use the person's own photographs; never present a generated or stock image as a photograph of a real place. For volume, `engine-dmo seed generate --type walk --count 20 --publish` writes valid documents with placeholder images.

```bash
engine-dmo seed verify
engine-dmo seed reset --confirm
engine-dmo seed apply
```

`seed apply` refuses a database that already holds content, which is why `seed reset --confirm` runs first in development. See [Seeding and importing](/content-modelling/seeding-and-importing).

`seed verify` checks that every file loads, that each field it names exists on the type, and that every document a navigation item names is in the seed. It does not check values: a select value that is not an option, or a number below its `min`, passes `verify` and is refused by `seed apply`. `seed apply` stops at the first refused document after writing the ones before it, so after a failure run `seed reset --confirm`, fix the file and apply again.

**Verify:** `seed verify` says "Matches the schema", and `seed apply` exits 0 and reports the documents, assets and navigation you expected.
</Step>

<Step>
## Write the templates [#write-the-templates]

Start from the layout, `templates/_shared/base.html`. It must print `head()`, `jsonld()`, the language and direction, a skip link and the navigation:

```jinja
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
  {{ jsonld() }}
  <link rel="stylesheet" href="{{ assets.url('css/site.css') }}">
</head>
<body>
  <a class="skip" href="#main">{{ t('a11y.skip') }}</a>
  <header>
    <a href="{{ path('/') }}">{{ site.name }}</a>
    <nav aria-label="{{ t('nav.main') }}">
      <ul>{% nav item in nav.main %}<li><a href="{{ item.url|url }}"{% if item.isCurrent %} aria-current="page"{% endif %}>{{ item.label }}</a>{% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}</li>{% endnav %}</ul>
    </nav>
    {{ localeSwitcher() }}
  </header>
  <main id="main">{% block body %}{% endblock %}</main>
</body>
</html>
```

`head()` prints the title, description, canonical, hreflang, robots and Open Graph tags. `jsonld()` prints the page's structured data, without which a site ships none and every check still passes. A type adds its own entity to that data with a `structured_data` block in its schema file ([SEO and structured data](/templates/seo-and-structured-data#mapping-a-type-to-schemaorg)).

Then, for each route, write the type's `entry.html` and, for an index, `index.html`. Before writing one, print the real context it will receive:

```bash
engine-dmo describe route /walks/cherwell-towpath --json
```

Put every visible string in `config/strings/<locale>.yaml` and print it with `t()`. Make anything you would copy between templates a component (`engine-dmo new component walk-card`). Follow [Listing page](/agents/recipes/listing-page), [Navigation menu](/agents/recipes/navigation-menu) and [Responsive images](/agents/recipes/responsive-images).

`check` holds `entry`, the type's own key (`walk`) and the context's named variables to the schema, so `{{ walk.subtitle }}` fails. It does not check fields on a loop variable (`{% for w in items %}{{ w.photo }}`), on a related document, or on a component's typed prop: a misspelt field there prints nothing. `render --json` is the only check for those.

**Verify:** `engine-dmo check` exits 0 and prints no `warning:` lines for templates (the summary does not count them), `engine-dmo render <path> --json` shows `"errors": []` for each template you wrote, and `engine-dmo render <path> | grep -c 'application/ld+json'` prints 1.
</Step>

<Step>
## Add the frontend [#add-the-frontend]

Without internet access, prefer plain CSS and small script files under `public/`, linked with `assets.url()`, which adds a version for cache busting:

```jinja
<link rel="stylesheet" href="{{ assets.url('css/site.css') }}">
```

If the project already has a `package.json` and its `node_modules/`, `engine-dmo build` runs its `build` script and then `check`. Do not add a build that needs packages you cannot install. See [Frontend build](/templates/frontend-build).

**Verify:** `engine-dmo render / --json` lists your stylesheet in `assets`.
</Step>

<Step>
## Check everything [#check-everything]

```bash
engine-dmo check
engine-dmo check --strict
engine-dmo seed verify
```

`--strict` turns configuration warnings into errors (a missing translation of a label, a missing string). It does not count template warnings, which still pass under `--strict`: read the `warning:` lines `check` prints for templates (a missing `head()`, an uncredited image, two `h1`s) and fix them by hand.

**Verify:** all three exit 0.
</Step>

<Step>
## Render every page [#render-every-page]

`a11y audit --all` renders through the real pipeline every page the site's sitemap would list, plus the home page, and fails on any page that does not answer 200, as well as on accessibility findings. It builds that list whether or not `seo.sitemap.enabled` is on, so a clean audit says nothing about `/sitemap.xml`, which answers 404 until you enable it in step 4. Pages outside the list (the search page, filtered index pages, pages under a second site) need naming:

```bash
engine-dmo a11y audit --all
engine-dmo a11y audit --path /search --path '/search?q=towpath' --path '/walks?difficulty=easy'
engine-dmo render /walks --json
```

Name a page's own address. An address that redirects is reported as a page with no language or title ([Troubleshooting](/agents/troubleshooting#accessibility-audit)). Run the audit once per site with `--site <key>`. Then render each kind of page with `--json` and read `errors` (template failures), `warnings` (template advisories), `a11y` (accessibility findings) and `images` (what each image downloads). An index page needs rendering on its last page too (`'/walks?page=2'`).

**Verify:** the audit reports "0 failures" on every site, and every rendered page has empty `errors` and `a11y`.
</Step>

<Step>
## Accessibility pass [#accessibility-pass]

Beyond the automated checks, go through the [accessibility rules](/agents/rules#accessibility) template by template: one `h1`, labelled controls and landmarks, alt text, focus order, the current page marked, and colour contrast in your CSS. Write the accessibility statement scaffold for the person to complete:

```bash
engine-dmo a11y statement --out accessibility-statement.html
```

The statement's enforcement section names the United Kingdom's regulator and regulations whatever the site's country: tell the person to replace it for a site outside the UK.

**Verify:** `engine-dmo a11y audit --all` reports no failures and no warnings, and you have listed for the person what still needs a manual check (keyboard, screen reader, contrast).
</Step>

<Step>
## Prepare the deploy [#prepare-the-deploy]

Make the project pass the production rules without a database or secrets:

```bash
ENVIRONMENT=production engine-dmo check --no-db
```

It reports the production requirements in groups, so run it again after each fix: `server.security.signing_key: ${SIGNING_KEY}`, `server.trusted_proxies` (or `real_ip_header: ""` when nothing sits in front of the engine), a real `mail.driver` with `mail.from`, and two-factor sign-in for staff.

Each secret you add this way (`${SIGNING_KEY}`, `${SMTP_PASSWORD}`) must now be set in every shell that runs `check`, `seed verify`, `new` or `dev up`, in development too, or they stop with `environment variable SIGNING_KEY is not set`. Export a local value of 32 characters or more (`export SIGNING_KEY="$(openssl rand -hex 32)"`) and a placeholder for each other secret. A secret cannot take a `${VAR:-default}`. The mail rules are checked only by `check`: a production engine started on the `log` driver runs and writes every message to its log, so this check is the only guard. Then follow [Deploying](/deploying): the container image or the single-node setup, and the deploy sequence (back up, `migrate up`, `schema apply`, `serve`, `health --readiness`).

**Verify:** the production check exits 0, and the [Checklists](/agents/checklists) are complete.
</Step>
</Steps>

## When you hand back [#when-you-hand-back]

Tell the person, in this order: what you built, how to run it locally (`engine-dmo dev up` and the URL), the staff sign-in (`engine-dmo user create --email ... --name ...` prints an enrolment link), what you verified and how, what you could not verify, the secrets they must set, and any decisions left to them (a destructive schema change, a missing feature).


# Documents, revisions and publishing (/concepts/documents-revisions-and-publishing)

How Meridian stores content as documents with a shared revision chain and one chain per locale, the per-locale workflow states, what publishing checks and does, scheduling, the trash, and revision retention.

Every piece of content is a **document** of one content type. A document has a draft and a published state **per locale**, a full revision history, and an owner site. Saving never overwrites: it adds a revision. Publishing never copies: it moves a pointer to a revision.

## Documents [#documents]

| | |
|---|---|
| Identity | A UUID that never changes, whatever happens to the title, slug or type's configuration |
| Type | One content type: a core type, a module's type or one of yours |
| Owner site | The site the document belongs to. It can be shared to other sites, and has an address on each site whose routes route its type |
| Locales | Each locale the document has is published, drafted, scheduled or archived on its own: Welsh can be in review while English is live |

Templates, the public pages and the content API's public reads see published revisions only. Editors work on the working revisions.

## Two kinds of revision chain [#two-kinds-of-revision-chain]

A document's values are split by how they translate, and each part has its own chain of revisions:

- **The shared chain** holds what is the same in every locale: fields with `translate: none` (a number, a date, a map pin, a select's value) and the **structure** of repeater and blocks fields (which items exist, their order, their types and their non-text settings).
- **One chain per locale** holds that locale's translated values: text, rich text, slugs, and the text inside each repeater item or block, keyed to the item it belongs to.

Reading a document in a locale walks the shared structure and fills each item from the locale's values, falling back along the locale's chain where a value is missing.

What this means for editors:

| An editor... | Happens |
|---|---|
| Adds a block in the source locale | It exists in every locale's draft at once, untranslated. On the public site an untranslated item is left out (or shows the source text, where the field says `fallback: inherit`) |
| Reorders or removes blocks | The change applies to every locale; a removed block's translations are kept in history |
| Changes a non-text setting (a layout, a list's limit) | It changes everywhere, because it is structure |
| Translates | The translator edits only the text; they cannot add, remove or reorder blocks |

Rich text (`portable_text`) is the exception: each locale holds its own whole rich text value, since a translator must be free to merge and split paragraphs.

When one document genuinely needs a different structure in each locale, `engine-dmo content structure --id <id> --field <field> --mode per_locale --reason "..."` makes that field per-locale for that document only, and records the reason in the audit log. `structure: per_locale` on a field does the same for every document of the type. [Localisation](/content-modelling/localisation) covers the field settings.

### Working and published revisions [#working-and-published-revisions]

Each chain has a **working revision** (the draft an editor sees) and a **published revision** (what the public sees). Saving writes a new revision to whichever chains changed and moves their working pointer. Publishing a locale moves that locale's published pointer to its working revision.

When the shared chain has unpublished changes, the admin shows a shared draft banner naming the locales the change reaches. Publishing a locale offers to publish the shared draft with it; a locale can be published without it, in which case new items in the shared draft are not rendered until the structure is published. Publishing the shared chain needs `content.publish` on the source locale.

```bash
engine-dmo content publish --id <document id> --locale cy            # publishes cy and the shared draft
engine-dmo content publish --id <document id> --locale cy --no-shared # publishes cy only
engine-dmo content publish --id <document id> --all-locales           # the source first, then every locale whose checks pass
```

## Workflow states [#workflow-states]

A locale of a document is always in one of five states:

| State | Means |
|---|---|
| `draft` | Being written; not public (or public at an earlier published revision, if it was published before) |
| `in_review` | An author has asked for review. Reviewers are notified and it appears in the site's approvals queue |
| `scheduled` | Will publish at a set moment. A live locale keeps serving its published revision until then |
| `published` | Live |
| `archived` | Taken out of circulation, unpublished and hidden from lists, with its history kept |

Each locale of a document moves between them on its own:

```mermaid
stateDiagram-v2
  [*] --> draft: create
  draft --> in_review: request review
  in_review --> draft: return with a note
  draft --> published: publish
  in_review --> published: publish
  draft --> scheduled: schedule
  in_review --> scheduled: schedule
  published --> scheduled: schedule a new revision
  scheduled --> published: the moment passes, checks pass
  scheduled --> draft: cancel, not live
  scheduled --> published: cancel, live
  published --> draft: unpublish
  draft --> archived: archive
  in_review --> archived: archive
  scheduled --> archived: archive
  published --> archived: archive
  archived --> draft: unarchive
```

Saving a published locale does not change its state: the new working revision waits as a draft beside the live published revision until you publish again. A scheduled locale whose checks fail at the moment stays `scheduled`, marked as failed.

| Transition | Who | What happens |
|---|---|---|
| Save | `content.edit` | A new revision in the chains that changed |
| Request review (`draft` to `in_review`) | `content.edit` without `content.publish` | Notifies everyone who may publish it; the author can keep editing |
| Return (`in_review` to `draft`) | `content.publish` | Needs a note, which the author is shown |
| Publish | `content.publish` | Runs the publish checks, then publishes (below) |
| Schedule | `content.publish` | Runs the publish checks now, and again at the moment |
| Unpublish | `content.publish` | The locale is taken down and returns to `draft`, its address released, and the search index updated |
| Archive / unarchive | `content.publish` | Archive unpublishes, drops a schedule and returns a pending review; unarchive returns it to `draft` |
| Trash / restore | `content.delete` / `content.restore` | See [The trash](#the-trash) |

Permissions can be scoped by state, so an author's grant can cover `draft` and `in_review` only. See [Users, roles and permissions](/concepts/users-roles-and-permissions). There are no custom workflow states or multi-step approval chains.

## What publishing does [#what-publishing-does]

Publishing a locale is one transaction, followed by background jobs.

<Steps>
<Step>
### The publish checks [#the-publish-checks]

Every path that publishes runs the same checks: the admin, the scheduler, `engine-dmo content publish`, bulk publish, restoring from the trash, the content MCP and member submissions approved automatically. Errors refuse the publish; warnings are reported with it.

- Fields hidden by `visible_when` lose their value.
- `required`, `required_in` and `required_when`.
- Each field type's own validation, and the type's validation rules, including those marked `on: publish`.
- Alt text, and the rights on every image used: an image whose rights have expired is an error; one whose rights end while the page is live is a warning naming the date.
- Tags that are not in the vocabulary, a parent that would make a cycle, and `unique` values.
- Relations to documents that are not live in the locale: a warning naming the fallback locale that stands in, or that the target is left out.
</Step>
<Step>
### The pointers move [#the-pointers-move]

The locale's published pointer moves to its working revision (and the shared chain's, when published with it), a publish event is recorded for each chain, the audit log is written, and the state becomes `published`.
</Step>
<Step>
### Addresses resolve [#addresses-resolve]

The document's address is resolved on every site it is on. When a live address changes, the old address redirects (301) to the document, unless a rule already answers it. Declining that redirect needs a reason: `engine-dmo content publish --no-redirect "reason"`, which is audited. Documents nested under a moved one get their own redirects.
</Step>
<Step>
### Jobs follow [#jobs-follow]

The published projection used for listing, filtering and sorting is rewritten, the search index is updated per site and locale, caches are invalidated, and translations of changed fields are marked stale. A failed job never unpublishes; it retries.
</Step>
</Steps>

The result also names any statutory locale on the document's sites that is not yet live; that is a prompt, never a block.

## Scheduling [#scheduling]

A locale can be scheduled to publish at a moment, and a live locale can have an `unpublish_at` moment. Both are set in the admin beside the publish controls, through the content MCP's publish tool with `publish_at`, or in seed data with `schedule:` and `unpublish_at:`.

- The publish checks run when you schedule, and again at the moment.
- A scheduler task runs every minute and publishes what is due as the system, naming the person who scheduled it in the audit log.
- If the checks fail at the moment (an image's rights expired, a related page was unpublished), the locale stays `scheduled` and is not retried, the person who scheduled it is notified, and the approvals queue shows it. Nothing half-publishes.
- Cancelling a schedule returns a locale that was not live to `draft`; a live locale stays published.
- `unpublish_at` must be in the future. When it passes, the locale is unpublished exactly as the admin would.

There is no command-line route to these: `engine-dmo content` has `publish` but no schedule, unpublish, archive or review command. From a terminal, schedule through the content MCP's publish tool with `publish_at` ([The content MCP](/integrating/content-mcp)), or set `schedule:` on a seed document before `seed apply`. To take a document down from the command line, `content trash --redirect` does it, with a redirect.

The scheduler runs on one process at a time, whichever process holds the leader role, so a schedule fires once however many replicas you run.

## The trash [#the-trash]

Deleting a document moves it to the trash; nothing is hard deleted straight away.

| Command | Does |
|---|---|
| `engine-dmo content trash --id <id> --redirect parent` | Soft delete. When any locale is live, `--redirect` is required: `parent`, a path, or `none` |
| `engine-dmo content restore --id <id>` | Reinstate it: its addresses are re-resolved and what was live is republished through the publish checks. `--slug-on-conflict suffix` (the default) or `fail` |
| `engine-dmo content hold --id <id>` | Keep a trashed document until someone decides; `--until <date>` to purge on a date, `--release` to restart the retention window |
| `engine-dmo content purge --id <id> --yes` | Hard delete, irreversible. `--expired` runs the nightly sweep now |
| `engine-dmo content legal-hold --id <id> --reason "..."` | Keep every revision and refuse purging until released (`--release`, `--until`) |
| `engine-dmo content list --trashed` | List the trash |

A trashed document is purged `content.trash_retention` after it was trashed (`30d` by default), unless it is held.

## Revision retention [#revision-retention]

Revisions are pruned by a daily task, and only when nothing keeps them. A revision is always kept if it was ever live, is pointed to, is the head of its chain, or is the shared pair of a kept locale revision. Beyond that, `content.revisions` in `engine.yaml` decides:

```yaml
content:
  trash_retention: 30d
  revisions:
    prune: true        # false: never prune
    keep_all: 90d      # every revision younger than this
    keep_last: 20      # and the newest 20 of each chain
    keep_monthly: true # and the newest of each calendar month of each chain, forever
```

| Key | Default | Limits |
|---|---|---|
| `prune` | `true` | `false` leaves the task unregistered and makes `content prune-revisions` refuse |
| `keep_all` | `90d` | A retention period such as `90d`, `13m` or `7y`; at least `1d` |
| `keep_last` | `20` | At least 1; counted per chain (each locale and the shared chain separately) |
| `keep_monthly` | `true` | |

A type can override any key with its own `revisions:` block in its schema file, such as `revisions: { prune: false }` for a type covered by a records schedule. `engine-dmo content prune-revisions --dry-run` prints what the next run would delete.

## Working with documents from the command line [#working-with-documents-from-the-command-line]

| Command | Does |
|---|---|
| `content create --type <key> --data '{...}'` | Create a document from field values, validated as an admin save (`--locale`, `--site`, `--publish`) |
| `content update <id> --data '{...}'` | Merge values over a locale's working revision; only the fields given change, and `null` clears one (`--locale`, `--publish`) |
| `content get <id>` | The working and published values by field handle, and the status per locale |
| `content list --type <key> --status draft` | One line per document (`--site`, `--locale`, `--status`, `--trashed`) |
| `content clone --id <id>` | A copy as a new draft, every locale in `draft` (`--site`, `--title`, `--no-tags`) |
| `content export`, `content import` | JSON or CSV of a type's working values; import creates drafts, never publishes, and `--dry-run` writes nothing |

Content is only ever written through these commands, the admin, the content MCP, the APIs or a seed; never with SQL. [CLI reference](/reference/cli) lists every flag.


# Concepts (/concepts)

The ideas every Meridian project rests on (sites, locales, routes, documents and publishing, modules and bundles, stable ids, users and permissions) and how they fit together.

Read this section before you model content or write templates. Each page explains one idea, shows the configuration that expresses it, and links to the full reference.

## The model in one paragraph [#the-model-in-one-paragraph]

An **install** is one engine, one database and one project directory. It declares its **locales** once and serves one or more **sites**; each site enables some of the locales and answers on its own domains. **Content types** are shared by every site unless limited, and each site's **routes** decide which types have pages on it and at which URLs. Content is stored as **documents**: each has a draft and a published state per locale, a revision history, and a structure shared by every locale with the text translated per locale. **Modules**, compiled into the binary as a **bundle**, add types, configuration files, screens and commands to this core. Every element of the configuration carries a **stable id** beside its name, so renaming it keeps its data. **Staff** sign in to the admin and act through **roles** granted to their groups under a **scope**; **members** of the public realm sign in to the member portal (`engine-dmo`) and never hold staff permissions.

The same model as a diagram of what relates to what:

```mermaid
erDiagram
  INSTALL ||--|{ LOCALE : declares
  INSTALL ||--|{ SITE : serves
  SITE }o--|{ LOCALE : enables
  SITE ||--o{ ROUTE : has
  CONTENT_TYPE ||--o{ ROUTE : "is routed by"
  CONTENT_TYPE ||--o{ DOCUMENT : "is the type of"
  SITE ||--o{ DOCUMENT : owns
  DOCUMENT ||--|| SHARED_CHAIN : "has one"
  DOCUMENT ||--|{ LOCALE_CHAIN : "has one per locale"
  GROUP ||--o{ GRANT : "is given"
  ROLE ||--o{ GRANT : "is granted by"
```

## Pages [#pages]

<Cards>
  <Card title="Sites, locales and routes" href="/concepts/sites-locales-and-routes">
    One install, several sites; locales declared once and enabled per site; how a request finds its site, locale and document.
  </Card>
  <Card title="Documents, revisions and publishing" href="/concepts/documents-revisions-and-publishing">
    Drafts and published revisions per locale, the shared structure and per-locale chains, the workflow states, scheduling and the trash.
  </Card>
  <Card title="Modules and bundles" href="/concepts/modules-and-bundles">
    What core provides, what each module adds, which bundle compiles which module, and what happens when a project uses a module the binary lacks.
  </Card>
  <Card title="Stable ids" href="/concepts/stable-ids">
    The id beside every handle: who writes it, why renames keep data, and how to recover from a copied or lost id.
  </Card>
  <Card title="Users, roles and permissions" href="/concepts/users-roles-and-permissions">
    Staff users and groups, the built-in roles, your own roles, scoped grants, and how members differ from staff.
  </Card>
</Cards>

## Where each concept lives in a project [#where-each-concept-lives-in-a-project]

| Concept | Files | Commands |
|---|---|---|
| Locales | `config/locales.yaml` | `engine-dmo dev locale add`, `engine-dmo locale` |
| Sites | `config/sites/<key>/site.yaml` | `engine-dmo dev site add`, `engine-dmo dev site rename` |
| Routes | `config/sites/<key>/routes.yaml` | `engine-dmo dev route add`, `engine-dmo describe route` |
| Content types | `config/schema/`, `config/sites/<key>/schema/` | `engine-dmo dev type add`, `engine-dmo dev field add`, `engine-dmo describe type` |
| Documents | The database; `seed/documents/` to load some | `engine-dmo content`, `engine-dmo seed` |
| Modules | Compiled into the binary | `engine-dmo version` |
| Stable ids | Every configuration file, as `id:` | `engine-dmo check --fix`, `engine-dmo schema plan` |
| Roles and grants | `config/access/roles.yaml`, `config/access/grants.yaml` | `engine-dmo user`, `engine-dmo access matrix` |


# Modules and bundles (/concepts/modules-and-bundles)

What the core platform provides, what each Meridian module adds and requires, which modules the engine-cms and engine-dmo bundles compile, and what happens when a project uses a module its binary lacks.

Meridian is a core content platform plus **modules**. A **bundle** is the core and a fixed list of modules compiled into one binary: `engine-cms` and `engine-dmo`. You choose a bundle by choosing the binary; you cannot add or remove a module from a binary, and nothing in a project's configuration switches one on.

Your own code is not a module. It is an extension, a Go plugin the engine loads at start; see [Extending](/extending).

## The core [#the-core]

Every bundle has the core platform:

- the five core document types `page`, `article`, `event`, `guide` and `collection`, and your custom types;
- every field type, validation, relations, localisation and entry variants;
- documents, revisions, the publishing workflow, scheduling and the trash;
- multiple sites and locales, routes, redirects, feeds, calendars and sitemaps;
- the media library and image pipeline;
- search, navigation, tags and smart lists;
- declared endpoints, sources, importers, outbound webhooks and plugins;
- analytics, dashboards and content health;
- the admin, staff users, roles and grants;
- the content API and the content MCP;
- the template language and its tooling.

## The modules [#the-modules]

| Module | Adds | Requires | `engine-cms` | `engine-dmo` |
|---|---|---|---|---|
| AI (`ai`) | AI assistance in the admin with your own provider: suggestions, alt text, a review queue, a budget and the activity log; the `ai:` section of `engine.yaml`; `engine-dmo ai` | | Yes | Yes |
| Forms (`forms`) | The `store` step of declared endpoints and the submissions it keeps, their inbox in the admin, the drawn forms (`enquiryForm()`, `subscribeForm()`) and their abuse controls; the `forms:` section | | Yes | Yes |
| Newsletter (`newsletter`) | Subscribers and their consent, double opt-in, campaigns built from live content, the deliverability wizard, the preference centre; `engine-dmo newsletter` | | Yes | Yes |
| Translation (`translation`) | Translation jobs and the Translations workspace, translation memory, the glossary, adding a locale to existing content; `engine-dmo translate`; the `translation:` section | | Yes | Yes |
| Directory (`directory`) | The `listing` and `area` types, landing pages, and the embeddable widgets | | | Yes |
| CRM (`crm`) | Organisations and people, their custom fields (`config/crm/`), partner roles (`config/portal/roles.yaml`), broadcasts to member contacts, the import and the merge; `engine-dmo crm`, `engine-dmo broadcast` | Forms | | Yes |
| Memberships (`memberships`) | Membership tiers (`config/memberships.yaml`), which tiers each site sells, memberships with renewals and reminders; the `membership:` section | CRM | | Yes |
| Member portal (`portal`) | The member realm: invitations and sign-in, the member portal and the member API (`config/portal/`, each site's `portal.yaml`); `engine-dmo portal` | CRM, Memberships | | Yes |
| Claims (`claims`) | A person claiming an organisation, the checks and the decision, the staff queue and the portal's claim flow | CRM, Memberships, Member portal | | Yes |
| Promotions (`promotions`) | Promotion slots (each site's `promotions.yaml`), members' requests for them, the staff queue, and `promoted()` in templates | CRM, Memberships, Member portal | | Yes |
| Member report (`memberreport`) | The member report in the portal, the member API, as a PDF and as a digest; `config/analytics/reports.yaml` | CRM, Memberships, Member portal | | Yes |
| Affiliates (`affiliates`) | Affiliate programmes, tracked links marked sponsored, conversion imports and postbacks; `engine-dmo affiliates` | CRM | | Yes |
| Paid listings (`paidlistings`) | Prices for tiers and promotions, orders, payment through a provider's hosted checkout or a staff invoice; `config/paidlistings.yaml` | CRM, Memberships, Member portal, Promotions | | Yes |

The modules that require others form one chain. Each arrow points at a module it requires, and a module also requires what that one requires (Paid listings needs Promotions, so it needs the Member portal, Memberships, CRM and Forms too). AI, Newsletter, Translation and Directory require nothing.

```mermaid
flowchart RL
  crm["CRM"] --> forms["Forms"]
  memberships["Memberships"] --> crm
  affiliates["Affiliates"] --> crm
  portal["Member portal"] --> memberships
  claims["Claims"] --> portal
  promotions["Promotions"] --> portal
  memberreport["Member report"] --> portal
  paidlistings["Paid listings"] --> promotions
```

The [DMO section](/dmo) documents the modules only `engine-dmo` has. The AI, Forms, Newsletter and Translation modules are documented under [Features](/features) because both bundles have them.

## What a module contributes [#what-a-module-contributes]

A module can add any of these, and they exist only in a binary that compiles it:

| Contribution | Where you meet it |
|---|---|
| Content types | `listing` and `area` from Directory. A project can extend them in `config/schema/` |
| Configuration files | Such as `config/memberships.yaml` or a site's `promotions.yaml` |
| A section of `engine.yaml` | Such as `ai:`, `forms:`, `portal:` or `membership:` |
| Database tables | Each module has its own migration stream, named in `engine-dmo migrate status` and `migrate to <module>/<version>` |
| Permissions | Staff permission verbs, granted to built-in roles (below) |
| Admin screens, CLI commands, template functions, content MCP tools and seed sections | Each listed by `engine-dmo help --json`, `engine-dmo template api` and `engine-dmo describe` |

## Using a module the binary does not have [#using-a-module-the-binary-does-not-have]

A project that uses a module's file, section or type on a binary that does not compile it is refused at the place it is used, naming the module, by `check` and at boot. On `engine-cms`:

```text
config/memberships.yaml:1:1: memberships.yaml belongs to the memberships module, which this bundle (cms) does not compile
    1 | tiers:
      | ^
      = use a bundle that compiles memberships, such as the DMO platform's bin/engine-dmo, or remove it
      = error code MRD-1006
```

```text
config/engine.yaml:22:1: portal: belongs to the portal module, which this bundle does not compile
   22 | portal:
      | ^^^^^^
      = use a bundle that compiles portal, or remove the section
      = error code MRD-1006
```

```text
config/schema/listing.yaml:1:10: "listing" is not a core type; core types are page, article, event, guide, collection
    1 | extends: listing
      |          ^^^^^^^
      = to declare a custom type use key: instead of extends:
      = error code MRD-1006
```

The reverse always works: every module of `engine-cms` is in `engine-dmo`, so an `engine-cms` project runs on `engine-dmo` unchanged. A database that `engine-dmo` has migrated can be opened by `engine-cms`; the DMO modules' migrations are reported in the log as belonging to modules this bundle does not compile, and their tables are left alone.

## Modules you do not use [#modules-you-do-not-use]

Every compiled module is present whether or not your project uses it, so choosing `engine-dmo` for a site that needs none of the DMO modules costs one thing worth knowing: the member portal is on. `engine-dmo describe project` shows it on each site, as `portal /members, both`, and the portal answers under `/members`, where a visitor is redirected to its sign-in.

Turn it off for the whole install in `config/portal/portal.yaml`:

```yaml
# config/portal/portal.yaml
portal:
  mode: "off"
```

`describe project` then shows `portal /members, off`, and nothing is served under the portal path. A site's own `portal.yaml` can do the same for one site ([Partners and the portal](/dmo/partners-and-portal)). Quote `"off"`: YAML reads it unquoted as well, but quoted it cannot be mistaken for a boolean.

The other DMO modules do nothing until you configure them: the `listing` and `area` types exist but have no pages until a route names them, and there are no tiers, slots or programmes until their files declare some. If your site uses none of them, `engine-cms` is the smaller binary, but no published image contains it ([Install](/getting-started/install#getting-the-engine)).

## Permissions a module adds [#permissions-a-module-adds]

Each module's verbs join core's in `config/access/roles.yaml`, and some are given to built-in roles. The `owner` role holds every verb of every compiled module.

| Module | Verbs | Built-in roles that hold them |
|---|---|---|
| AI | `ai.use`, `ai.bulk`, `ai.generate_image`, `ai.configure` | `owner` only; grant them to your roles |
| Forms | `submissions.view` | `administrator`, `partnership-manager` |
| Newsletter | `newsletter.view`, `newsletter.manage`, `newsletter.draft`, `newsletter.send`, `newsletter.export` | `administrator` all; `editor` view and draft; `analyst` view |
| CRM | `broadcast.draft`, `broadcast.send`, `crm.import` | `administrator`, `partnership-manager` |
| Promotions | `promotions.decide` | `administrator`, `partnership-manager` |
| Affiliates | `affiliates.view`, `affiliates.manage` | `administrator` and `partnership-manager` both; `analyst` view |
| Paid listings | `paidlistings.manage` | `administrator`, `partnership-manager` |

A role naming a verb no compiled module declares is an error at its line, with the nearest known verb suggested. [Users, roles and permissions](/concepts/users-roles-and-permissions) explains roles and grants.

## Finding out what a binary has [#finding-out-what-a-binary-has]

```bash
engine-dmo version          # the bundle and its modules, one line
engine-dmo version --json   # the same, with each module's id and name
engine-dmo help --json      # every command, with its arguments and flags
engine-dmo describe project # the types, sites, roles and other elements the project has under this binary
```

```text
meridian v0.8.0 (pure-go) go1.27.3
  bundle dmo: modules ai directory forms crm affiliates memberships newsletter portal claims memberreport promotions paidlistings translation
```


# Sites, locales and routes (/concepts/sites-locales-and-routes)

How one Meridian install serves several sites in several locales, how locales are declared once and enabled per site, how routes give types URLs, and how a request finds its site, locale and document.

One install serves one or more **sites** from one database. The install declares its **locales** once; each site enables a subset and chooses how locales appear in its URLs. Each site's **routes** decide which content types have pages on it, and at which URI patterns.

## A minimal example [#a-minimal-example]

Two locales, one site that serves both, and two routed types:

```yaml
# config/locales.yaml
locales:
  available:
    - code: en
      label: English
      source: true
      timezone: Europe/London
      currency: GBP
    - code: cy
      label: Cymraeg
      fallback: [en]
```

```yaml
# config/sites/main/site.yaml
site:
  name: { en: "Visit Wyndmouth", cy: "Ymweld â Wyndmouth" }
  domains: [www.wyndmouth.example, localhost]
  default: true

locales:
  strategy: prefix
  enabled: [en, cy]
  default: en
```

```yaml
# config/sites/main/routes.yaml
routes:
  - type: page
    uri: "/{slug}"

  - type: article
    uri:
      en: "/news/{slug}"
      cy: "/newyddion/{slug}"
    index:
      en: "/news"
      cy: "/newyddion"
    paginate: 12

home: { type: page, slug: home }
```

Run `engine-dmo check --fix` after writing these by hand: it gives each locale, site and route its `id:` (see [Stable ids](/concepts/stable-ids)). The `engine-dmo dev locale add`, `dev site add` and `dev route add` verbs write the same configuration with ids for you.

With this configuration an English article is at `/news/<slug>` and its Welsh translation at `/cy/newyddion/<slug>`. The site needs `article/entry.html` and `article/index.html` on its template chain; `check` refuses the routes until they exist.

## Locales [#locales]

`config/locales.yaml` lists every locale the install knows, once. A site never redeclares a locale; it enables some of them.

```yaml
locales:
  available:
    - code: en-GB
      label: English
      source: true
      timezone: Europe/London
      currency: GBP
    - code: cy-GB
      label: Cymraeg
      fallback: [en-GB]
```

| Key | Default | Meaning |
|---|---|---|
| `code` | required | A BCP 47 tag such as `en-GB`, `cy` or `zh-Hans`. Declared once |
| `label` | required | The locale's name, as the admin and language switchers show it |
| `source` | `false` | The locale content is written in first and translated from. Exactly one locale must be the source |
| `default` | `false` | The install's default locale; at most one. Without one, the source locale is the default |
| `timezone` | the source locale's | An IANA time zone. Required on the source locale |
| `currency` | the source locale's | An ISO 4217 code. Required on the source locale |
| `fallback` | none | Locales to read a value from, in order, when this locale has none |
| `statutory` | `false` | A locale that must be published wherever the source is; publishing without it is a prompt, never a block |
| `translators` | none | The staff group translation jobs into this locale are assigned to by default |
| `machine_translation` | none | `assist` or `forbid`: whether machine translation may be offered for this locale |
| `derived_from` | none | A locale this one is derived from, such as `en-US` from `en-GB` |
| `direction` | from the script | `ltr` or `rtl` |
| `calendar`, `numbering`, `hour_cycle`, `first_day_of_week` | from CLDR for the locale | How dates, numbers and times are formatted |
| `collation` | from the tag | The database collation that sorts text in this locale |
| `slugs` | from the script | `native` keeps slugs in the locale's script; `transliterate` converts them to Latin |
| `fold_diacritics` | `true` | Whether search treats `é` as `e` |

`groups` (beside `available`) declares sets of locales that share values for fields translated per group. `engine-dmo check` reports a missing source locale, two source locales, two defaults, an unknown time zone or currency, a fallback to an unknown locale or to itself, and a locale in two groups, each at its line. [Localisation](/content-modelling/localisation) explains how fields are translated.

## Sites [#sites]

Each site is a directory under `config/sites/`, named by its key. An install with one site is no different from one with ten: the admin simply shows no site switcher.

```yaml
# config/sites/town/site.yaml
site:
  name: { en: "Larkwyn" }
  domains: [www.larkwyn.example, town.localhost]

templates:
  roots: [town, _shared]

locales:
  enabled: [en]
```

`templates/town/` must exist as a directory, since the chain names it; `check` refuses a root that does not.

The `site:` block:

| Key | Default | Meaning |
|---|---|---|
| `name` | required | The site's name per locale, read in templates as `site.name` |
| `short_name` | none | A shorter name per locale |
| `domains` | none | The host names the site answers, matched exactly (with or without the port) |
| `default` | `false` | The site that answers any host no site names. With one site it is the default; with several, exactly one must say `default: true` |
| `path_prefix` | none | A path the site is served under on a shared host, starting with `/` |
| `timezone`, `default_currency` | the default locale's | The site's own, where they differ |
| `country` | none | The site's country |
| `organisation` | the site name | The organisation behind the site, for structured data |
| `network` | `default` | The network the site belongs to (`config/networks.yaml`); sites in one network share organisations, people and partner accounts |
| `position` | `0` | The order sites are listed in; sites with the same position are ordered by key |

The rest of `site.yaml`:

| Block | Holds |
|---|---|
| `locales` | The locales the site enables, its default locale, its URL strategy and per-site fallback chains (below) |
| `templates` | `roots`, the template chain (default `[<key>, _shared]`); `allow_unescaped`, which permits unescaped output on this site |
| `seo` | Title template, default social image, sitemap, robots rules and structured data |
| `nav` | The site's navigation slots; their items are edited in the admin |
| `links` | How links to other websites behave |
| `accessibility` | The accessibility statement's path, conformance and contact |
| `embed` | The widget surface for embedding content in other sites (off by default) |
| `delivery` | `rendered` (the engine serves pages) or `headless` (a frontend reads the content API) |
| `assets` | The site's frontend build entries and size budgets |
| `mail` | The sender address the site's mail goes out as |
| `settings` | Free-form values templates read as `settings.<path>` |
| `memberships` | The membership tiers the site sells (`engine-dmo`) |

[site.yaml](/reference/configuration/site) has every key.

### What sites share and what they do not [#what-sites-share-and-what-they-do-not]

| Shared by every site | Per site |
|---|---|
| The locales declared, the content types, the media library, tags, staff users and roles | Domains, enabled locales, routes, templates (through the chain), navigation, SEO, endpoints, outbound webhooks |

A content type is on every site unless `sites:` in its schema file limits it, and a type or field declared in `config/sites/<key>/schema/` belongs to that site alone. A document has an owner site and can be shared to other sites, where it has its own URL from each site's routes. [Multisite templates](/templates/multisite) covers template chains and per-site overrides.

## A site's locales and URL strategy [#a-sites-locales-and-url-strategy]

```yaml
locales:
  strategy: prefix
  enabled: [en, cy]
  default: en
  fallback:
    cy: [en]
```

| Key | Default | Meaning |
|---|---|---|
| `enabled` | the source locale | The locales this site serves. Each must be declared in `locales.yaml` |
| `default` | the first enabled | The site's default locale |
| `strategy` | `prefix` | How a URL names its locale (below) |
| `domains` | none | With `strategy: domain`, the host for every enabled locale |
| `fallback` | the locale's own chain | A per-site fallback chain that replaces the locale's, using only locales this site enables |

| Strategy | The default locale | Other locales |
|---|---|---|
| `prefix` | No prefix: `/news` | Prefixed: `/cy/newyddion` |
| `prefix-all` | Prefixed too: `/en/news` | Prefixed: `/cy/newyddion` |
| `domain` | Its own host: `www.wyndmouth.example/news` | Their own hosts: `www.wyndmouth-cy.example/newyddion` |

The prefix is the locale's language subtag (`cy`) when no other enabled locale shares it, and otherwise the whole code in lower case (`en-gb`, `en-ie`).

```yaml
# strategy: domain
locales:
  strategy: domain
  enabled: [en, cy]
  default: en
  domains:
    en: www.wyndmouth.example
    cy: www.wyndmouth-cy.example
```

`check` refuses `strategy: domain` without a host for every enabled locale.

## Routes [#routes]

A route gives a content type pages on a site. Without a route a type's documents still exist and can be listed and related, but have no URL on that site, and `check` warns about a site with no `routes.yaml`.

```yaml
routes:
  - type: article
    uri:
      en: "/news/{publishedAt|date:'Y/m'}/{slug}"
      cy: "/newyddion/{publishedAt|date:'Y/m'}/{slug}"
    index:
      en: "/news"
      cy: "/newyddion"
    paginate: 12
    feed:
      formats: [rss, atom]
```

| Key | Meaning |
|---|---|
| `type` | The content type routed. A type has at most one route per site, and only on sites the type is on |
| `uri` | The URI pattern, one for every locale or one per locale. Placeholders name fields of the type: `{slug}`, or a value through a filter such as `{publishedAt|date:'Y/m'}` |
| `index` | The type's index page, listing its published documents in the type's order. Renders `<type>/index.html` |
| `paginate` | Documents per index page, read as `?page=N` |
| `priority` | A number, default `0`, that orders two patterns of one shape, lowest first. `check` refuses two routes of the same shape and priority (`routes "/{slug}" (page@en) and "/{slug}" (area@en) are ambiguous: same shape and priority; give one a priority`). It does not decide who answers: a document's address is stored when it is published and found by that, so each type answers for its own documents and one address holds one document |
| `facets` | Indexed fields that filter the index by query parameter |
| `feed` | RSS, Atom and JSON Feed of the newest documents |
| `calendar` | iCalendar files for a type with a recurrence field |
| `nest` | Documents of the type nest under each other: `/cotswolds/chipping-norton` |
| `parent` | Documents hang under a related document's address |
| `landings` | Landing pages: a category, optionally in a place, at a clean URL |

The rest of `routes.yaml`:

| Key | Meaning |
|---|---|
| `home` | The document served at `/`: `{ type: page, slug: home }` names a routed document by slug; `{ type: homepage }` names a singleton type |
| `redirects` | The site's structural redirects: `{ from, to, status, locale }`. `from` is an exact path, a prefix with a trailing slash, or a pattern with `*` captured as `{1}`, `{2}` in `to`. `status` is 301 (default), 302, 307, 308, or 410 with no `to` for content that is gone |
| `special` | Engine pages at a path per locale, such as `search: { en: "/search", cy: "/chwilio" }`, which renders `search.html` |

`home: { type, slug }` takes one slug for every locale: a document is the home page in a locale when its slug in that locale is exactly that value. Give the home page the same slug (`home`) in every locale. A Welsh translation slugged `hafan` is not the Welsh home page: `/cy/` is not found and the page is served at `/cy/hafan`. The home page answers `/` (or `/cy/`), and its slug path (`/home`) is not found.

Without `home`, a document of any routed type whose slug in a locale is exactly `__home__` answers `/` in that locale, so an editor can choose the home page. A site uses one mechanism or the other, and `check` refuses both together.

`check` validates redirects at their line: a 410 with a target, a status outside the five, a loop, and a target the site does not answer:

```text
config/sites/main/routes.yaml:29:13: redirect loop: /loop-a -> /loop-b -> /loop-a
config/sites/main/routes.yaml:31:25: redirect target /nowhere/at/all resolves to nothing on site main in cy, en
```

[routes.yaml](/reference/configuration/routes) has every key, and [Redirects and URLs](/features/redirects-and-urls) covers the redirects editors manage in the admin.

### Addresses are stored, not computed [#addresses-are-stored-not-computed]

When a locale of a document is published, its address on every site it is on is resolved from that site's route and stored. Requests are answered from the stored addresses, so a page's URL does not change because a field it does not use changed. When a published slug changes, the old address redirects (301) to the new one. When a route's pattern or parent changes, documents whose stored address no longer matches are moved when the engine next starts, each old address redirecting to the new one.

## How a request is answered [#how-a-request-is-answered]

A request passes through three choices, each made from the configuration and the stored addresses:

```mermaid
flowchart TD
  req["Request: host and path"] --> site{"Host in a site's domains?"}
  site -- yes --> s1["That site"]
  site -- no --> s2["The default: true site"]
  s1 --> loc{"strategy: domain?"}
  s2 --> loc
  loc -- yes --> l1["The host names the locale"]
  loc -- no --> l2{"First path segment<br/>a locale prefix?"}
  l2 -- yes --> l3["That locale"]
  l2 -- no --> l4["The site's default locale"]
  l1 --> page{"Rest of the path"}
  l3 --> page
  l4 --> page
  page -- "redirect rule" --> redirect["Redirect"]
  page -- "stored document address" --> doc["Document, rendered with<br/>type/entry.html on the site's chain"]
  page -- "index, feed, landing or special page" --> other["That page's template"]
  page -- "nothing" --> notfound["errors/404.html"]
```

<Steps>
<Step>
### The site [#the-site]

The request's host is matched against every site's `domains`, with and without the port. A site with a `path_prefix` matches only paths under it. With `strategy: domain`, each locale's host also names its site. A host no site names is answered by the `default: true` site.
</Step>
<Step>
### The locale [#the-locale]

With `strategy: domain`, the host names the locale. Otherwise the first path segment is compared with each enabled locale's prefix; when none matches, the request is in the site's default locale (under `prefix`, the default locale's own prefix is not a route).
</Step>
<Step>
### The page [#the-page]

The rest of the path is matched against the site's redirects, its stored document addresses, its index, feed, calendar and landing pages, and its special pages. A document renders with its type's template resolved along the site's template chain; nothing matching renders `errors/404.html`.
</Step>
</Steps>

`engine-dmo describe route <path>` shows which route answers a path, the template the chain resolved and the whole template context, and `engine-dmo render <path> --host <host> --locale <code>` renders it, both against a database.

## Commands [#commands]

| Command | Does |
|---|---|
| `engine-dmo dev locale add <code> --label Cymraeg --fallback en --site main` | Declare a locale and enable it on a site. Without `--label` the label is the code |
| `engine-dmo dev site add <key> --domain <host> --locales en,cy --name "..."` | Add a site directory with `site.yaml` and `routes.yaml` |
| `engine-dmo dev site rename <old> <new>` | Rename a site: its directory moves and its id and data stay |
| `engine-dmo dev route add <type> <uri> --index <uri> --site <key>` | Route a type on a site |
| `engine-dmo describe project` | Every site, locale and route with its id |
| `engine-dmo locale` | Locale coverage, what has drifted from the source, and adding a locale to existing content |


# Stable ids (/concepts/stable-ids)

The id written beside every named element in Meridian configuration, who writes it, why a rename keeps all stored data, how renames and aliases work, and how to fix a missing, copied or wrong id.

Every named element in a project's configuration carries an `id:` beside its handle. The handle (a key, name or code) is a label you can change at any time; the id is the element's identity. The database stores everything by id, so renaming a field, a type, a site or a route keeps every value stored under it.

```yaml
fields:
  - { name: lengthKm, aliases: [distance], id: fld_qvbnm6shzg, type: number }
```

Here the field was called `distance` and is now `lengthKm`. Its id did not change, so every document's value is still there, and the old handle still answers as an alias.

## The rules [#the-rules]

1. **Never type an id and never copy one.** The tooling writes ids. An element you add by hand gets one from `engine-dmo check --fix`, `engine-dmo dev up`, or the `engine-dmo dev` verb that adds it.
2. **Never edit an id.** A changed id is a different element: the plan replaces the stored one.
3. **Change the handle freely.** A changed handle beside an unchanged id is a rename.
4. **Ids are per project.** `engine-dmo init --from` gives a copied project new ids so the two can never be confused.

`check` cannot tell a typed id from a written one: any well-formed id passes, so rule 1 is yours to keep.

`schema plan` compares each element in the files with the stored one by id first, then by handle:

```mermaid
flowchart TD
  el["An element in the files"] --> hasid{"Has an id?"}
  hasid -- no --> fix["check refuses it:<br/>run check --fix"]
  hasid -- yes --> stored{"Id stored?"}
  stored -- yes --> samehandle{"Same handle?"}
  samehandle -- yes --> same["No change, or ~ change"]
  samehandle -- no --> rename["> rename: values kept"]
  stored -- no --> oldhandle{"Handle stored?"}
  oldhandle -- no --> add["+ add"]
  oldhandle -- "yes, with no id" --> bind["= bind"]
  oldhandle -- "yes, under another id" --> replace["! replace: refused<br/>without --replace"]
```

## What an id looks like [#what-an-id-looks-like]

A prefix naming the kind of element, an underscore, and ten characters from a lower-case base32 alphabet without `i`, `l`, `o` or `u`: `fld_qvbnm6shzg`. The prefix makes an id of the wrong kind an obvious error.

| Prefix | Element | Where |
|---|---|---|
| `site_` | A site | `site.id` in `sites/<key>/site.yaml` |
| `net_` | A network | `networks.yaml` |
| `loc_` | A locale | `locales.yaml` |
| `grp_` | A locale group, or a group of fields in a type's editor | `locales.yaml`, schema files |
| `typ_` | A content type | Schema files |
| `fld_` | A field, including custom CRM and staff user fields | Schema files, `crm/`, `access/users.yaml`, `portal/enquiries.yaml` |
| `blk_` | A block | `blocks/_index.yaml`, schema files |
| `opt_` | A select option, or a link style | Schema files: `{ value: mid, id: opt_... }` |
| `var_` | An entry variant | Schema files |
| `rte_` | A route | `routes.yaml` |
| `lnd_` | A landing page pairing | `routes.yaml` |
| `nav_` | A navigation slot | `site.yaml` |
| `end_` | A declared endpoint | `endpoints.yaml` |
| `src_`, `imp_`, `whk_` | A source, an importer, a webhook | `sources.yaml`, `importers.yaml`, `webhooks.yaml` |
| `role_` | A staff role or a partner role | `access/roles.yaml`, `portal/roles.yaml` |
| `rep_` | A report | `analytics/reports.yaml` |
| `met_` | An entered metric | `analytics/dashboards.yaml` |
| `tier_` | A membership tier | `memberships.yaml` |
| `scr_`, `act_` | A portal screen, a portal action | A site's `portal.yaml` |
| `slot_` | A promotion slot | A site's `promotions.yaml` |

A role that replaces a built-in role (same key) needs no id: it keeps the built-in role's.

## Writing ids [#writing-ids]

`check` refuses an element without an id:

```text
config/sites/main/routes.yaml:2:11: route "page" has no id
    2 |   - type: page
      |           ^^^^
      = run engine-dmo check --fix to write one; ids are written by the tooling, never by hand
      = error code MRD-1006
```

`check --fix` writes every missing id, keeping your comments and layout, then checks:

```bash
engine-dmo check --no-db --fix
```

```text
wrote 1 id in 1 file
```

```yaml
routes:
  - type: page
    id: rte_4rvbbqzx1m
    uri: "/{slug}"
```

`engine-dmo dev up` does the same on every save, and every `engine-dmo dev` verb writes the id of the element it adds. An element written as an empty map, such as a navigation slot `main: {}`, cannot take an id (`check --fix` says `nav.main is an empty mapping`); give it at least one setting first, such as `main: { depth: 1 }`.

## Renaming [#renaming]

Rename with a verb where there is one: it changes the handle, keeps the id, and rewrites every reference to the handle in your configuration.

```bash
engine-dmo dev field rename walk distance lengthKm
```

```text
wrote config/schema/walk.yaml
field.walk.lengthKm: fld_qvbnm6shzg
walk.distance answers as an alias until engine-dmo schema alias retire walk.distance
```

| Rename | Command | What else happens |
|---|---|---|
| A field | `dev field rename <type> <old> <new>` | The old handle is kept in `aliases:` so templates using it keep working. `--no-alias` drops it |
| A site | `dev site rename <old> <new>` | The site's directory moves; old admin and public URLs redirect |
| A source, importer or webhook | `dev source rename`, `dev importer rename`, `dev webhook rename` | Every endpoint step naming it is rewritten |
| Anything else | Edit the handle in the file, leave the id | `schema plan` shows it as a rename |

`schema plan` marks a rename with `>`, and applying it changes only the stored handle. `describe type` shows a field's old handle (`number [translate none, was distance]`).

### Field aliases [#field-aliases]

An alias keeps an old field handle working in templates (and, on `engine-dmo`, the member API). List and retire them when nothing uses the old handle:

```bash
engine-dmo schema alias list
engine-dmo schema alias retire walk.distance
```

`retire` refuses while a template still uses the alias. `engine-dmo dev status` lists the live aliases `dev up` found.

## Mistakes and how to fix them [#mistakes-and-how-to-fix-them]

| Problem | What `check` or the plan says | Fix |
|---|---|---|
| An element has no id | `route "page" has no id` | `engine-dmo check --fix` |
| The same id on two elements (usually a copied block) | `id fld_... is written on two elements: field "title" here and field "summary" at ...` | Delete the copy's id and run `check --fix` |
| An id of the wrong kind | `typ_... is a type id; a field id starts fld_` | Delete it and run `check --fix` |
| A malformed id | `"fld_abc" is not an id: after fld_ come 10 characters, not 3` | Delete it and run `check --fix` |
| An existing handle with a new id | The plan marks it `!` (replace) and `schema apply` refuses it | Put the stored id back (your version control history has it), or apply with `--replace <type>.<field>` when you mean a new element |

A replace drops the stored element and creates a new one, so the values stored under the old id are no longer read by the field. Treat every `!` in a plan as a mistake until you are sure.

## Databases made before ids [#databases-made-before-ids]

A database whose schema was applied from files that had no ids can take the ids the files now carry without changing anything else:

```bash
engine-dmo schema adopt-ids
```

It writes any missing ids (as `check --fix` does), then applies a plan that may contain only binds (`=`): each stored element takes the id its file gives it. A plan with any other change is refused; apply that first with `schema apply`.

## Ids in the rest of the engine [#ids-in-the-rest-of-the-engine]

- `engine-dmo describe project` and `describe type <key>` print every element with its id, as text or `--json`.
- `engine-dmo guide` lists each site, type and field with its id, so an agent working on the project can refer to them.
- Documents have UUIDs, not configuration ids. They are stored in the database and never appear in configuration or seed files.
- A seed file may hold a configuration id where a field's value is one: a `form` field stores its endpoint's id, so a seed writes `contactForm: end_srhmvkf6j3`, copied from `endpoints.yaml` or `describe project`. Copying an id that the tooling wrote into the value that refers to it is not inventing one.


# Users, roles and permissions (/concepts/users-roles-and-permissions)

How staff users, groups, built-in and custom roles, and scoped grants control what each person may do in Meridian; how to create users and explain a decision; and how members of the public realm differ from staff.

People who sign in to Meridian are in one of two separate realms. **Staff** sign in to the admin and act through roles granted to their groups. **Members** (on `engine-dmo`) sign in to the member portal on behalf of organisations and never hold staff permissions. The engine's own background work runs as the **system**.

Staff access is configuration: roles and grants are YAML in `config/access/`, reviewed and versioned like the rest of the project. Which groups a user is in is data, managed from the command line, the admin or your identity provider.

A staff user's permission comes through a chain: the user is in groups, a grant gives a group a role under a scope, and the role lists the permissions:

```mermaid
flowchart LR
  user["Staff user"] -->|is in| group["Group<br/>such as editors"]
  group -->|grants.yaml| grant["Grant"]
  grant --> role["Role<br/>built in or roles.yaml"]
  grant --> scope["Scope<br/>site, type, locale, state, owner, tag"]
  role --> perm["Permissions<br/>such as content.publish"]
  perm --> decision{"Allowed on<br/>this resource?"}
  scope --> decision
```

The user may act when any one grant's role holds the permission and that grant's scope covers the resource.

## A minimal example [#a-minimal-example]

```yaml
# config/access/grants.yaml
grants:
  - { group: administrators, role: owner }
  - { group: editors, role: editor }
  - group: welsh-team
    role: translator
    scope: { locale: [cy] }
  - group: town-editors
    role: editor
    scope: { site: [town] }
  - group: newsroom
    role: news-writer
    scope: { type: [article], state: [draft, in_review], owner: self }
```

```yaml
# config/access/roles.yaml
roles:
  - key: news-writer
    name: { en: News writer }
    permissions: [content.view, content.create, content.edit, media.view, media.upload]
```

Run `engine-dmo check --fix` to give the new role its id. A member of `newsroom` can create articles and edit their own drafts and articles in review, but cannot publish, see other people's drafts or touch other types. A member of `welsh-team` can edit and publish Welsh on any document. A member of `town-editors` has the editor role on the `town` site only.

## Staff users and groups [#staff-users-and-groups]

A staff user has an email address, a display name, a status (active or suspended) and a list of **groups**. Groups are plain keys such as `editors` or `welsh-team`; they need no declaration, and exist because a user is in them and a grant names them.

| Way in | How |
|---|---|
| `engine-dmo user create --email <address> --name "<name>" --group <key>` | Creates a local user and prints a single-use enrolment link, valid for 24 hours. The first user ever created goes into `administrators` when no `--group` is given. `--group` is repeatable |
| The admin's Users screen | An administrator invites a user and sets their groups (needs `users.manage`) |
| Single sign-on (OIDC) | A user signing in through your identity provider is created on first sign-in and put in groups mapped from a claim |
| `seed/users/*.yaml` | Development users with a password and an authenticator secret; never created in production |

Opening an enrolment link, the user sets a password and enrols an authenticator app in one step, then sees their recovery codes once.

```bash
engine-dmo user list                       # every user, --group <key> for one group
engine-dmo user suspend --email <address>  # suspend and revoke every session
engine-dmo user reset-mfa --email <address> --confirm # clear the second factor, revoke sessions, print a new enrolment link
```

### Local accounts [#local-accounts]

```yaml
# config/engine.yaml
auth:
  staff:
    local:
      enabled: true
      require_mfa: true
      password_min_length: 12
      breach_check: local
      allowlist: ${LOCAL_ACCOUNT_ALLOWLIST:-}
```

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `true` | Allow local accounts (email and password) |
| `require_mfa` | `true` | Require an authenticator code at sign-in. `false` is refused in production |
| `password_min_length` | `12` | At least 12 |
| `breach_check` | `local` | `local` checks passwords against a list of breached passwords shipped in the binary; `hibp` also asks the Have I Been Pwned range API; `off` |
| `allowlist` | empty | Comma-separated email addresses allowed to sign in locally; empty allows any |
| `argon2` | `{ memory_kb: 65536, time: 3, threads: 2 }` | Password hashing cost; refused below a floor |

### Single sign-on [#single-sign-on]

With `auth.staff.oidc.enabled: true`, staff sign in through an OpenID Connect provider. The provider says who the user is; your grants say what their groups may do. `group_claim` names the claim that lists a user's groups, and `group_map` maps each value in it to one or more Meridian group keys:

```yaml
auth:
  staff:
    oidc:
      enabled: true
      issuer: ${OIDC_ISSUER}
      client_id: ${OIDC_CLIENT_ID}
      client_secret: ${OIDC_CLIENT_SECRET}
      group_claim: groups
      group_map:
        "Web-Editors": editors
        "Web-Admins": administrators
        "Comms": [newsroom, welsh-team]
```

Each value is compared exactly. Every Meridian group a mapping names must be one `grants.yaml` grants a role to (or one `provision.groups` gives every user); `check` refuses a mapping that would grant nothing.

| Key | Default | Meaning |
|---|---|---|
| `issuer`, `client_id`, `client_secret` | required | Your provider's issuer URL and this client's credentials. `client_secret` is a secret: a bare `${VAR}` |
| `scopes` | `[openid, profile, email]` | Scopes requested |
| `required_acr` | none | An authentication context the provider must assert, such as one that requires a second factor |
| `group_claim` | `groups` | The claim listing the user's groups, read from the ID token, then from userinfo |
| `group_map` | none | Provider group value to one Meridian group key, or a list of them |
| `unmatched_groups` | `ignore` | `ignore` or `warn` for groups in the claim with no mapping |
| `no_mapped_group` | `refuse` | `refuse` or `provision` a user whose groups map to nothing |
| `auto_provision` | `true` | Create the user on their first successful sign-in |
| `link_existing_by_email` | `verified_only` | `verified_only` or `never`: adopt a local account with the same email address |
| `provision.display_name_claim`, `provision.locale_claim` | `name`, `locale` | Claims read when a user is created |
| `provision.groups` | none | Groups every provisioned user gets, whatever their claims |
| `deprovision_on` | `absent` | `absent` or `never` |

Custom fields on the staff user record are declared in `config/access/users.yaml`.

## Roles [#roles]

A role is a named list of permissions. Eight roles are built in, and a grant can name any of them without `roles.yaml` declaring it:

| Role | Holds |
|---|---|
| `owner` | Every permission, including those of every compiled module and any added in later releases. Its list cannot be edited |
| `administrator` | All content, media, CRM records, mail, analytics, settings, users, audit, cache, search, navigation, webhooks, API keys and the content MCP; not `content.legal_hold`, `media.rights`, `media.delete`, the CRM purges or `member.impersonate` |
| `editor` | View, create, edit, publish, delete, restore and clone content, content health, media view, upload and edit, CRM organisation view, claim review, analytics view, navigation and the content MCP |
| `author` | View, create and edit content; view and upload media |
| `translator` | View, edit and publish content; view media |
| `partnership-manager` | The CRM's organisations, people, memberships, tags, smart lists and claims; analytics view and export |
| `analyst` | Analytics view, export and entered figures; content and CRM organisation view |
| `auditor` | Read-only: content, media, CRM records, analytics, settings, users, the audit log, cache, search, webhooks, API keys and diagnostics |

Every list except `owner`'s is written out, so a permission added in a later release is denied to these roles until your `roles.yaml` grants it.

<Callout type="warn" title="Held by owner alone">

No built-in role but `owner` holds `media.rights` (recording an image's licence), `media.delete`, or any AI verb (`ai.use`, `ai.bulk`, `ai.generate_image`, `ai.configure`). Until `roles.yaml` grants them, administrators cannot record image rights or delete assets, and nobody but an owner sees the AI assistance. Grant them with a small role of your own beside the built-in one, rather than restating the built-in role's whole list:

```yaml
# config/access/roles.yaml
roles:
  - key: media-steward
    name: { en: Media steward }
    permissions: [media.view, media.rights, media.delete, ai.use]
```

```yaml
# config/access/grants.yaml
grants:
  - { group: administrators, role: owner }
  - { group: editors, role: editor }
  - { group: editors, role: media-steward }
```

</Callout>

Modules add their verbs to some built-in roles; see [Modules and bundles](/concepts/modules-and-bundles#permissions-a-module-adds).

### Your own roles [#your-own-roles]

`config/access/roles.yaml` declares roles of your own, and replaces built-in ones:

```yaml
roles:
  # A new role, with an id written by check --fix.
  - key: news-writer
    name: { en: News writer }
    permissions: [content.view, content.create, content.edit, media.view, media.upload]

  # Replaces the built-in editor role: this list is the whole of it.
  - key: editor
    name: { en: Editor }
    permissions: [content.view, content.create, content.edit, content.publish, media.view, media.upload, media.edit, nav.manage]
```

| Key | Meaning |
|---|---|
| `key` | Lower-case letters, digits and hyphens. The same key as a built-in role replaces it; that role needs no `id` and keeps the built-in one |
| `id` | Written by the tooling for a new role |
| `name` | The role's name per locale |
| `permissions` | The verbs it holds. An unknown verb is an error at its line with the nearest known one suggested |

The `owner` role can be renamed (its `name`) but given no `permissions` list.

### The permissions [#the-permissions]

Core's verbs, in both bundles:

| Area | Verbs |
|---|---|
| Content | `content.view`, `content.create`, `content.edit`, `content.publish`, `content.delete`, `content.restore`, `content.clone`, `content.purge`, `content.legal_hold`, `content.export`, `content.health` |
| Media | `media.view`, `media.upload`, `media.edit`, `media.rights`, `media.delete` |
| CRM records | `crm.organisation.view`, `crm.organisation.edit`, `crm.organisation.delete`, `crm.organisation.purge`, `crm.person.view`, `crm.person.edit`, `crm.person.delete`, `crm.person.purge`, `crm.membership.view`, `crm.membership.edit`, `crm.tag.manage`, `crm.smartlist.manage`, `crm.claim.review` |
| Mail | `mail.manage` |
| Analytics | `analytics.view`, `analytics.export`, `analytics.enter`, `analytics.configure` |
| Members | `member.impersonate` |
| Settings and users | `settings.view`, `settings.edit`, `users.view`, `users.manage` |
| API keys | `api.keys.view`, `api.keys.manage` |
| Audit and system | `audit.view`, `system.maintenance`, `system.diagnostics` |
| Cache and search | `cache.view`, `cache.purge`, `search.view`, `search.rebuild`, `search.purge`, `search.synonyms` |
| Webhooks | `webhooks.view`, `webhooks.replay` |
| Navigation | `nav.manage` |
| Content MCP | `mcp.connect` |

Each module the binary compiles adds its own verbs ([Modules and bundles](/concepts/modules-and-bundles#permissions-a-module-adds)). `engine-dmo access matrix` lists every active user's effective permissions, by group (`--site` for one site's view).

## Grants [#grants]

A grant gives a group a role under a scope. Every grant is in `config/access/grants.yaml`:

| Key | Meaning |
|---|---|
| `group` | The group key. Required |
| `role` | A built-in role or one from `roles.yaml`. An unknown role is an error with the nearest suggested |
| `scope` | What the grant covers. Omitted, it covers everything |

The scope's dimensions:

| Dimension | Values | Covers |
|---|---|---|
| `site` | Site keys | Resources on these sites |
| `type` | Type keys | Documents of these types |
| `locale` | Locale codes | These locales of a document |
| `state` | `draft`, `in_review`, `published`, `scheduled`, `archived` | Locales in these workflow states |
| `owner` | `any` (the default), `self`, `own_group` | `self`: documents the user created. `own_group`: documents created by anyone in the grant's group |
| `tag` | Tag keys, or `root.*` for every tag under `root` | Documents carrying one of these tags |

A dimension left out, empty or containing `"*"` means any value. The dimensions of one grant combine with AND; a user with several grants (through several groups, or several grants to one group) may do whatever any one of them allows.

Scope is applied inside the database queries, so a list in the admin or the content MCP shows only what the user's grants reach, and counts and pages are right.

### Applying role and grant changes [#applying-role-and-grant-changes]

Roles and grants are part of the schema plan. A change appears in `engine-dmo schema plan` and takes effect when it is applied (`dev up` applies it as you save, unless it is destructive):

- Removing or narrowing a grant that takes a permission from active users is **destructive**, marked with the number of users who lose it, and needs approval like any destructive change.
- A plan that would leave no active user able to manage users or holding the `owner` role is **refused**, even with `--allow-destructive`.

The admin's Access screen can draft a grant for you: it renders the YAML and a diff against `grants.yaml` for you to commit. It never writes the file itself.

## Explaining a decision [#explaining-a-decision]

```bash
engine-dmo user grant-explain --email sam@example.org --action content.publish --resource article:<document id>
```

`grant-explain` says whether the user may do it and why: each grant they hold, each dimension of its scope, and which one passed or failed. With `--resource type:<id>` it reads the site, type, locale, state, owner and tags from the document; without it, describe a hypothetical resource with `--site`, `--type`, `--locale`, `--state`, `--owner` and `--tag`. The admin's Access screen answers the same question.

## Members [#members]

On `engine-dmo`, the people behind organisations (a business owner, its marketing contact) sign in to the **member portal**, not the admin. Members are a separate realm:

- They never hold staff grants; nothing in `grants.yaml` applies to them.
- They sign in with a magic link or a passkey (`auth.member` in `engine.yaml`). Member passwords are not available.
- They join by a staff invitation or by claiming an organisation (`auth.member.registration: claim`, the default), or by invitation only (`invite_only`).
- What a member may do for an organisation is set by their **partner role** on it. `owner`, `manager`, `contact` and `billing` are built in; `config/portal/roles.yaml` adds your own or restates a built-in one.

A staff user with `member.impersonate` can see the portal as a member sees it. [Partners and the portal](/dmo/partners-and-portal) covers members, partner roles and the portal in full.


# Blocks and rich text (/content-modelling/blocks-and-rich-text)

Repeaters (a list of items with the same fields), blocks (a flexible page body of typed blocks, each with its own template), shared blocks, and Portable Text rich text with styles, lists, marks, link annotations and object blocks, and how each renders.

Three field types hold structured, ordered content:

| Type | Use it for | Each item is |
|---|---|---|
| `repeater` | A list of things of one shape: a walk's stages, a venue's rooms, questions and answers. | The same child fields. |
| `blocks` | A flexible page body an editor composes and reorders: text, a quote, a gallery, a grid of cards. | One of the declared blocks, each with its own fields and its own template. |
| `portable_text` | Formatted prose: headings, paragraphs, lists, links, bold and italic, with optional embedded objects. | A Portable Text block. |

## repeater [#repeater]

```yaml
fields:
  - name: stages
    type: repeater
    min: 1
    max: 20
    collapsed: true
    item_label: "{{ title }}"
    fields:
      - { name: title, type: text, required: true }
      - { name: distanceKm, type: number, min: 0, index: true }
      - { name: notes, type: portable_text, marks: [strong, em, link] }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `fields` | list | required | The child fields of every item, declared like any field. A child may itself be a repeater or blocks field. |
| `min` | whole number | none | The fewest items. Fewer than `min` but more than none is an error on save; none is an error at publish. |
| `max` | whole number | none | The most items. |
| `collapsed` | boolean | `false` | Starts every item closed in the editor, so a long list reads as an outline. |
| `item_label` | template | the first text-like value | The summary line of a collapsed item, such as `"{{ title }}"`. A rich text child gives its plain text. |

A repeater must declare at least one child field (`a repeater declares its item fields`).

## blocks [#blocks]

```yaml
fields:
  - name: body
    type: blocks
    collapsed: true
    blocks:
      - key: richText
        label: { en-GB: Text }
        description: { en-GB: A passage of formatted text }
        item_label: "{{ content }}"
        fields:
          - name: content
            type: portable_text
            styles: [normal, h2, h3]
            lists: [bullet, number]
            marks: [strong, em, link]
      - key: faq
        label: { en-GB: Questions and answers }
        fields:
          - name: items
            type: repeater
            item_label: "{{ question }}"
            fields:
              - { name: question, type: text, required: true }
              - { name: answer, type: portable_text, styles: [normal], marks: [strong, em, link] }
      - use: quote
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `blocks` | list | required | The block kinds an editor may add, in the order the block picker shows them. At least one. |
| `min`, `max` | whole number | none | The fewest and most blocks, as for a repeater. |
| `collapsed` | boolean | `false` | Starts every block closed; a block just added opens regardless. |
| `item_label` | template | | The collapsed summary when a block has none of its own. |

Each block declares:

| Key | Type | What it does |
|---|---|---|
| `key` | camelCase string | The block's handle, and the name of its template. Unique within the field. |
| `id` | string | Written by `check --fix` (`blk_...`). |
| `label` | locale map or string | Its name in the block picker. |
| `description` | locale map or string | One line under the label in the block picker. |
| `item_label` | template | Its collapsed summary, such as `"{{ heading }}"`. |
| `fields` | list | Its fields. |
| `use` | shared block key | Instead of all the above: include a shared block. |

### Shared blocks [#shared-blocks]

A block several `blocks` fields offer is declared once in `config/blocks/_index.yaml`, with `key:`, and included with `- use: <key>`:

```yaml
# config/blocks/_index.yaml
blocks:
  - key: quote
    label: { en-GB: Quote }
    description: { en-GB: A pull quote with its source }
    item_label: "{{ text }}"
    fields:
      - { name: text, type: text, multiline: true, required: true }
      - { name: cite, type: text }
```

A `use:` entry declares nothing else. A shared block is declared with `key:`, never `use:`, and once only.

### Block templates [#block-templates]

Each block renders through `blocks/<key>.html` in the site's template roots (for example `templates/_shared/blocks/quote.html`). The page template renders the whole field with the `blocks` tag:

```jinja
<div class="blocks">{% blocks entry.body %}</div>
```

Inside a block template, the block's fields are on `block`, with `blockIndex` (from zero) and `blockCount`, beside every global of the page:

```jinja
{# templates/_shared/blocks/quote.html #}
<blockquote class="quote">
  <p>{{ block.text|linebreaksbr }}</p>
  {% if block.cite %}<footer>{{ block.cite }}</footer>{% endif %}
</blockquote>
```

```jinja
{# templates/_shared/blocks/faq.html #}
<section class="faq">
  {% for item in block.items %}
  <details>
    <summary>{{ item.question }}</summary>
    {{ item.answer|ptext }}
  </details>
  {% endfor %}
</section>
```

`engine-dmo check` fails when a declared block has no template on a site: `block "quote" of page.body has no template for site main`, with the path to add. `engine-dmo new block <key>` writes a block template and the schema stub that declares it.

### Validation [#validation]

| Code | Message |
|---|---|
| `min_items` | Add at least N |
| `max_items` | No more than N |
| `block_type` | Block type "x" is not declared (blocks only) |
| `key` | Item has no key / Duplicate item key |

Child fields are validated like top-level fields, with paths such as `body[2].heading` and `stages[0].title`.

### Stored value and template value [#stored-value-and-template-value]

A repeater or blocks value is a list of items. Each item has a `_key`, unique within the field and stable across edits, which is how translations find their item; a block also has `_type`, its block key:

```json
[
  { "_key": "hm01", "_type": "richText", "content": [ ... ] },
  { "_key": "hm02", "_type": "quote", "text": "The best view in the valley.", "cite": "A visitor" }
]
```

In a template, a repeater is a list of items and a blocks field a list of blocks. Each item carries its child fields as properties, `key` (and `_key`), and for a block `type` (and `_type`). Relations inside items resolve to entries as top-level ones do.

```jinja
<ol>
  {% for stage in entry.stages %}
  <li id="stage-{{ stage.key }}"><h2>{{ stage.title }}</h2>{{ stage.notes|ptext }}</li>
  {% endfor %}
</ol>
```

With `index: true` on a child, its values are projected under a dotted key (`stages.distanceKm`), one row per item, so lists can filter documents by values inside items. In a document with several locales, which items exist and in which order is normally shared, and each locale writes its own text into them: see [Localisation](/content-modelling/localisation).

## portable_text [#portable_text]

Rich text is stored as [Portable Text](https://portabletext.org), a JSON array of blocks, never HTML. The schema says exactly which styles, lists and marks a field allows; the editor offers only those, and content pasted from Word, Google Docs or a web page is posted to the engine, converted and normalised to the field's schema, with a list of what changed.

```yaml
fields:
  - name: description
    type: portable_text
    styles: [normal, h2, h3, blockquote]
    lists: [bullet, number]
    marks:
      decorators: [strong, em, underline]
      annotations:
        - key: link
          kinds: [{ key: page, of: document, types: [page] }, { of: url }, { of: email }]
          attributes: [text, new_tab]
        - key: glossary
          label: { en-GB: Glossary term }
          fields:
            - { name: definition, type: text, required: true }
    blocks:
      - key: figure
        label: { en-GB: Image }
        fields:
          - { name: image, type: asset, required: true }
          - { name: caption, type: text }
    max: 5000
```

### Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `styles` | list | `normal`, `h2`, `h3`, `h4`, `blockquote` | The block styles allowed, from `normal`, `h2` to `h6` and `blockquote`. Leave `h1` to the page template. |
| `lists` | list | `bullet`, `number` | The list styles allowed. |
| `marks` | list or mapping | `strong`, `em` and `link` | The inline marks allowed. See below. |
| `blocks` | list | none | Object blocks an editor can insert between paragraphs, declared like the blocks of a `blocks` field (`key`, `label`, `description`, `fields`). |
| `max` | whole number | none | The most characters of text, counted as grapheme clusters. |

**Marks, short form.** A list of names. `strong`, `em`, `underline`, `code` and `strike-through` are decorators; `link`, `internalLink` and `mention` are annotations:

```yaml
marks: [strong, em, link]
```

**Marks, long form.** A mapping with `decorators` and `annotations`, where each annotation is `{ key, ... }`:

| Annotation | What it is |
|---|---|
| `{ key: link }` | A link with the [link field's](/content-modelling/fields/link) model. It takes `kinds`, `attributes` and `rel` and nothing else; a document target is stored by id, so the link survives a move. `nofollow` and `ugc` are always allowed for partners' links. |
| `{ key: internalLink, to: [page, article] }` | A reference to a document, picked from the given types (every type when `to` is left out). |
| `{ key: mention }` | A staff user, picked by typing `@`; renders as `<span class="mention">`. |
| `{ key: <yours>, label, fields }` | A custom annotation with fields of its own, validated like a block's fields. A custom annotation with no fields is applied as it is. |

### Validation [#validation-1]

Validation is against the field's schema, so a value never holds what the field does not allow:

| Code | Message |
|---|---|
| `style` | Style "h1" is not allowed here |
| `list` | List style "number" is not allowed here |
| `decorator` | Formatting "underline" is not allowed here |
| `annotation` | Annotation "x" is not allowed here |
| `link_marks` | Text can carry one link at a time |
| `block_type`, `inline_type` | Block type / Inline object "x" is not allowed here |
| `max_length` | Must be N characters or fewer |

A rich text field with `translate: none` gets a warning: it cannot then be translated at all.

### Stored value [#stored-value]

```json
[
  { "_type": "block", "_key": "b1", "style": "normal", "markDefs": [],
    "children": [
      { "_type": "span", "_key": "b1s0", "text": "Open every day except ", "marks": [] },
      { "_type": "span", "_key": "b1s1", "text": "Mondays", "marks": ["strong"] }
    ] },
  { "_type": "figure", "_key": "f1", "image": { "asset": "3c1e..." }, "caption": "The tower" }
]
```

A list item is a block with `listItem` (`bullet` or `number`) and `level`. A link is a `markDefs` entry referenced from a span's `marks`. Text is stored in Unicode NFC. An import may give a rich text value as `{ "html": "<p>...</p>" }`, converted by the same converter the editor's paste uses ([Seeding and importing](/content-modelling/seeding-and-importing)).

Rich text is translated whole: each locale holds its own complete value, so a translator can merge and split sentences.

### Rendering [#rendering]

| Filter | What it gives |
|---|---|
| `\|ptext` | The HTML. Every span is escaped. `h2` to `h4` headings carry ids. |
| `\|ptext:"compact"` | The HTML with the `compact` serialiser set for object blocks (below). |
| `\|toc` | A navigation list of the headings, linking to their ids. |
| `\|plain` | The text alone, for a meta description or a card; follow it with `\|truncate:160` or `\|excerpt:160` to shorten it. |

```jinja
<div class="prose">{{ entry.description|ptext }}</div>
<nav aria-label="On this page">{{ entry.description|toc }}</nav>
<meta name="description" content="{{ entry.description|plain|excerpt:160 }}">
```

**Object blocks** render through `ptext/<set>/<key>.html` in the site's template roots, where `<set>` is `default` unless the filter names one. The block's fields are on `node`, its position on `index`, beside every global of the page:

```jinja
{# templates/_shared/ptext/default/figure.html #}
{{ node.image.figure("card") }}
```

An object block with no template renders nothing on the public site (with `serve --dev`, a notice naming the template to add), and `engine-dmo check` warns: `object block "figure" of listing.description has no serialiser template for site main, so |ptext renders it as nothing`. Naming a serialiser set that has no templates at all is an error when the page renders.


# Asset (/content-modelling/fields/asset)

The asset field (one or several media library files: images, documents, audio or library videos) with kinds, file and image constraints, per-use alt text, captions and framing, the stored shape and the image value templates receive.

An asset field picks files from the media library: a hero image, a gallery, a PDF download, an audio guide. It stores the asset's id, never its URL, so replacing or renaming a file never breaks a page. Each use of an asset may carry its own alt text and caption (per locale) and its own focal point, hotspot and crop, over the asset's own values in the library.

```yaml
fields:
  - name: heroImage
    type: asset
    alt: required
    min_width: 1600
    aspect: "16:9"
    caption: true
  - name: gallery
    type: asset
    multiple: true
    min: 2
    max: 12
    caption: true
    tags: [gallery]
    upload: true
    upload_tags: [gallery]
  - name: download
    type: asset
    kinds: [document]
    accept: [pdf, application/vnd.ms-excel]
    max_size: 20MB
```

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `kinds` | list of `image`, `document`, `audio`, `video` | `[image]` | What may be chosen. `video` is a library video reference; for YouTube, Vimeo and files on a host, use a [`video`](/content-modelling/fields/video) field. |
| `multiple` | boolean | `false` | An ordered list of assets. |
| `min` | whole number | none | With `multiple`: the fewest assets to publish. |
| `max` | whole number | none | With `multiple`: the most assets. |
| `accept` | list | any of the kinds | Narrows the kinds by extension (`jpg`, `pdf`) or media type (`application/pdf`, `image/*`). |
| `max_size` | size | none | The largest file, in decimal units: `500kB`, `10MB`, `2GB`, or a number of bytes. |
| `min_width`, `min_height` | pixels | none | Images: the smallest size accepted. |
| `max_width`, `max_height` | pixels | none | Images: the largest size accepted. |
| `aspect` | `width:height` | none | Images: the proportion, such as `3:2`, within two percent. |
| `orientation` | `landscape`, `portrait` or `square` | none | Images: the orientation. Give `aspect` or `orientation`, not both. |
| `alt` | `inherit` or `required` | `inherit` | Images: `inherit` uses the asset's alt text from the library, which a use may override. `required` refuses an image with no alt text in the locale (per use or in the library) unless it is marked decorative. |
| `caption` | boolean | `false` | Offers a per-use caption, per locale. |
| `focal` | boolean | `true` for images | Images: offers a per-use focal point, hotspot and crop. |
| `tags` | list of tag keys | none | The picker shows assets with these tags. |
| `upload` | boolean | `false` | Lets an editor upload from the field; they still need the media upload permission. |
| `upload_tags` | list of tag keys | none | Tags an upload from the field receives. Needs `upload: true`. |

`engine-dmo check` reports a parameter that does not fit the kinds: `alt applies to images, and this field takes document`, `aspect and orientation are given together`, `min and max count the assets of a field with multiple: true`, `unknown asset kind "photo"` (with the four kinds listed), `"10XB" has an unknown unit; write B, kB, MB or GB`.

## Validation [#validation]

When an editor chooses a file, the field refuses one that does not fit, with the reason:

| Code | Message |
|---|---|
| `asset_kind` | This kind of file is not accepted here |
| `asset_type` | This type of file is not accepted here; choose PDF, ... |
| `asset_size` | Choose a file of 20 MB or less |
| `image_min_width` / `image_min_height` | Choose an image at least 1600 pixels wide / high |
| `image_max_width` / `image_max_height` | Choose an image no more than N pixels wide / high |
| `image_aspect` | Choose an image in the proportion 16:9 |
| `min_assets` / `max_assets` | Choose at least N / Choose no more than N |
| `asset_choose` | Choose a file from the library |
| `focal_offered`, `framing_offered`, `caption_offered` | This field does not take a focal point / a hotspot or a crop / a caption |

At publish the engine also checks each asset against the library:

| Code | Severity | When |
|---|---|---|
| `asset_missing` | error | The image is no longer in the library. |
| `rights_expired` | error at publish, warning on save | The asset's usage rights have ended. |
| `rights_expiring` | warning | The rights end while the page stays live. |
| `alt_needed` | error | `alt: required` and the image has no alt text in the locale (per use, in the library, or by fallback), and is not decorative. |
| `alt` | error at publish | The image has no alt text anywhere and `media.require_alt_text` is on (the default), and is not decorative. |
| `alt_fallback` | warning | The alt text shown comes from another locale. |
| `alt_fallback_blocked` | error | As above, on a site whose `accessibility.alt_fallback` refuses fallback alt text for the locale. |

## Stored value [#stored-value]

One asset:

```json
{ "asset": "6f1c0b0e-...", "focal": { "x": 0.42, "y": 0.35 }, "alt": "Boats in the harbour at dawn", "caption": "Clovelly harbour" }
```

With `multiple`, a list of the same, each with a `_key`. `focal` is `{ x, y }` and `hotspot` and `crop` are `{ x, y, w, h }`, all fractions of the image. The asset and its framing are shared by every locale; `alt` and `caption` are each locale's own. That is why `engine-dmo describe type` shows the field as `translate locale`. A locale that writes the field with a different asset changes it for every locale, and one that writes only `alt` empties the shared choice; use `structure: per_locale` for a different image per locale ([Links, assets and videos](/content-modelling/localisation#links-assets-and-videos)). In a seed file an asset is named by its seed key, `{ asset: harbour-dawn }` or just `harbour-dawn` ([Seeding and importing](/content-modelling/seeding-and-importing)).

With `index: true` each asset id is projected, so lists can find the documents that use an asset.

## Template value [#template-value]

The field is an image value (or, with `multiple`, a list of them). Printing it prints the original's URL.

| Property | What it is |
|---|---|
| `url` | The original's URL. |
| `alt`, `altLang` | The per-use alt text, else the asset's for the site and locale; `altLang` names the locale it came from when it is a fallback. |
| `decorative` | Whether an empty alt is intended. |
| `caption`, `captionLang` | The per-use caption, else the asset's. |
| `credit`, `creditRequired` | The credit line the licence requires, and whether a template must show it. |
| `width`, `height`, `aspect`, `orientation`, `dominant` | Images: size, proportion, orientation and dominant colour (`#rrggbb`). |
| `focal`, `hotspot`, `crop` | The per-use framing, else the asset's. |
| `id`, `kind`, `mime`, `extension`, `type`, `filename`, `title`, `bytes`, `size` | The file's facts; `type` is `PDF`, `JPG`; `size` is `2.1 MB` in the request locale. |

| Method | What it writes |
|---|---|
| `img(transform, ...)` | An `<img>` with `src`, `srcset`, `sizes`, `width`, `height`, `alt`, `loading` and `decoding`. |
| `picture(transform, ...)` | A `<picture>` with a source per format and art direction. |
| `figure(transform, ...)` | The picture in a `<figure>` with the caption and credit in `<figcaption>`. |
| `transform(name, width=)` | A transform object for custom markup. |
| `url(transform, width=, format=, absolute=)` | One derivative's address, for an Open Graph image or a CSS background. |
| `link(text=)` | A download link announcing the type and size: Annual report (PDF, 2.1 MB). |
| `audio()` | An `<audio controls>` for an audio asset. |

The image methods take `sizes=`, `priority=true` for the page's main image, `loading=`, `fetchpriority=`, `placeholder=`, `alt=`, and any other HTML attribute. A transform is a name from `config/images.yaml`.

```jinja
{% if entry.heroImage %}{{ entry.heroImage.figure("hero", priority=true) }}{% endif %}

<div class="gallery">
  {% for image in entry.gallery %}{{ image.figure("card") }}{% endfor %}
</div>

{% if entry.download %}<p>{{ entry.download.link() }}</p>{% endif %}
```

`engine-dmo check` warns when an image is printed with `img()` or `picture()` and its credit nowhere in the template; `figure()` writes it. See [Images](/templates/images) for transforms, sizes and art direction, and [Media](/features/media) for the library itself.


# Boolean and select (/content-modelling/fields/boolean-and-select)

The boolean field and the select field (one option or several from a declared list, each option with a stable id and per-locale label), with parameters, validation, stored values and what templates receive.

## boolean [#boolean]

True or false: dog friendly, step-free, featured. Held once for every locale.

```yaml
fields:
  - { name: dogFriendly, type: boolean, index: true, label: { en-GB: Dogs welcome } }
```

A boolean has no parameters of its own, and an unset boolean is false in a template. It has no validation of its own, and `required` on a boolean does not force it to be true: use a [validation rule](/content-modelling/validation) (`agreed == true`) for that.

The stored value is a JSON `true` or `false`, and a template receives the boolean:

```jinja
{% if entry.dogFriendly %}<p>Dogs welcome</p>{% endif %}
```

A boolean cannot be `unique`. In an expression it is compared with `true` or `false`: `dogFriendly == true`.

## select [#select]

One value, or several with `multiple: true`, from a list the schema declares.

```yaml
fields:
  - name: difficulty
    type: select
    required: true
    index: true
    options:
      - { value: easy, label: { en-GB: Easy, cy-GB: Hawdd } }
      - { value: moderate, label: { en-GB: Moderate, cy-GB: Cymedrol } }
      - { value: hard, label: { en-GB: Hard, cy-GB: Anodd } }
  - name: facilities
    type: select
    multiple: true
    index: true
    options:
      - { value: parking, label: { en-GB: Parking } }
      - { value: wifi, label: { en-GB: Wi-Fi } }
      - { value: stepFree, label: { en-GB: Step-free access } }
```

### Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `options` | list | required | The choices. Each is a mapping `{ value, label }`, or a bare string that is both value and label. |
| `options[].value` | string | | What is stored and what templates and expressions compare against. |
| `options[].label` | locale map | the value | What editors and visitors read, per locale. |
| `options[].id` | string | written by `check --fix` | The option's stable id (`opt_...`). A bare-string option is rewritten as `{ value, id }` by `check --fix`. |
| `multiple` | boolean | `false` | Holds a list of values. |

Give every option a label as a locale map. A template's `label` reads the label for the request locale from the map, and falls back to the value when there is none.

`engine-dmo check` warns when an option's label map lacks an enabled locale (`the label of option hard has no translation for cy`), but says nothing about an option with no `label` at all, or one whose label is a plain string. A plain-string label passes `check`, but a template's `.label` prints the value instead. `engine-dmo dev field add --options a,b,c` writes options with no labels; add `label: { en: ... }` to each, keeping its `id:`.

### Validation [#validation]

| Code | Message |
|---|---|
| `option` | "x" is not one of the options |

An expression that compares a select with a value it does not offer fails `engine-dmo check` with the options listed: `visible_when: "tlak" is not an option of kind`.

### Stored value [#stored-value]

Seed files, imports, the content API and templates use the option's `value`: a string, or a list of strings with `multiple`. Internally the engine stores the option's id, so renaming a value (keeping its id) keeps every document's choice, and the schema plan shows it as a rename. Removing an option that documents hold is a destructive change ([Schema changes](/content-modelling/schema-changes)).

### Template value [#template-value]

A single select is an option with `value` and `label`, or nothing when empty. A multiple select is a list of them, in the order chosen.

```jinja
<dd class="difficulty-{{ entry.difficulty.value }}">{{ entry.difficulty.label }}</dd>

{% if entry.facilities %}
<ul>{% for f in entry.facilities %}<li>{{ f.label }}</li>{% endfor %}</ul>
{% endif %}
```

`engine-dmo dev option add <type> <field> <value>` adds an option with its id. A `select` reads an old `text` value exactly when it is one of the options; a value that is not is kept and flagged for a person to decide.


# Dates and times (/content-modelling/fields/dates-and-times)

The date field (a calendar day), the datetime field (a wall-clock time in an IANA zone with its UTC instant) and the recurrence field (an event's repeating schedule and its occurrences), with parameters, stored shapes and template values.

All three are held once for every locale. Times are stored with the zone they belong to, so a 19:00 start stays 19:00 on both sides of a clock change.

## date [#date]

A calendar day with no time and no zone: an opening date, a deadline, a date of birth.

```yaml
fields:
  - { name: openedOn, type: date, min: "1800-01-01" }
  - { name: closesOn, type: date, index: true }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `min` | `YYYY-MM-DD` | none | The earliest day accepted. |
| `max` | `YYYY-MM-DD` | none | The latest day accepted. |

| Code | Message |
|---|---|
| `date` | Enter a date as YYYY-MM-DD |
| `min_date` | Must be on or after 1800-01-01 |
| `max_date` | Must be on or before ... |

**Stored value:** a string, `"2026-04-01"`. With `index: true` it is projected as that day at midnight UTC, so lists filter and sort by it.

**Template value:** a date value. Format it with `|date`, which writes the day in the request locale's words and order:

```jinja
<p>Open since {{ entry.openedOn|date:"long" }}</p>
<time datetime="{{ entry.openedOn.date }}">{{ entry.openedOn|date }}</time>
```

| Property | What it is |
|---|---|
| `date` | The day as `YYYY-MM-DD`. |
| `local`, `utc` | The day at midnight, as a time. |
| `iso` | RFC 3339 form. |
| `isAllDay` | Always true for a date. |
| `zone` | `UTC`. |

A `date` field reads an old `datetime` value lossily (its local day) and an ISO date in a `text` value exactly.

## datetime [#datetime]

A moment in time in the zone it happens in: a publication time, a start time, a deadline at noon in Paris.

```yaml
fields:
  - { name: doorsOpen, type: datetime, zone: Europe/London }
  - { name: launchAt, type: datetime, min: "2026-01-01T00:00:00Z", seconds: true }
  - { name: festivalDay, type: datetime, all_day: true }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `zone` | IANA zone | the site's, then the locale's, then `UTC` | The zone the editor offers first. A value may be in any zone. |
| `min` | RFC 3339 instant | none | The earliest instant accepted. |
| `max` | RFC 3339 instant | none | The latest instant accepted. |
| `all_day` | boolean | `false` | Offers an all-day switch. An all-day value renders no time. Without this parameter an all-day value is refused. |
| `seconds` | boolean | `false` | Edits to the second instead of the minute. |

| Code | Message |
|---|---|
| `zone_empty` | Choose a time zone |
| `zone_unknown` | Unknown time zone "X" |
| `datetime` | Enter a date and time |
| `min_date` / `max_date` | Must be on or after / before the bound |
| `all_day` | This field does not accept all-day values |

**Stored value:**

```json
{ "local": "2026-03-29T10:00", "zone": "Europe/Paris", "utc": "2026-03-29T08:00:00Z", "allDay": false }
```

The wall clock (`local`) and the zone are what the editor chose; the UTC instant is recomputed from them on every save. In a seed file or an import you may give `local` and `zone` alone, or a bare RFC 3339 string, which is read as UTC. With `index: true` the instant is projected, so lists sort by it.

**Template value:**

| Property | What it is |
|---|---|
| `local` | The wall-clock time in its own zone. |
| `utc` | The same instant in UTC. |
| `zone` | The IANA zone. |
| `iso` | The instant in RFC 3339. |
| `date` | The local day as `YYYY-MM-DD`. |
| `isAllDay` | Whether the editor chose all day. |
| `inZone(name)` | The instant in another zone. |

```jinja
<time datetime="{{ entry.doorsOpen|iso }}">{{ entry.doorsOpen|datetime:"long short" }}</time>
{% if entry.festivalDay.isAllDay %}{{ entry.festivalDay|date:"full" }}{% endif %}
```

`|date`, `|datetime`, `|time`, `|relative` and `|iso` all accept the value directly ([Filters](/templates/filters)). The article type's core `publishedAt` is a `datetime`.

## recurrence [#recurrence]

An event's schedule: a first start and duration in a zone, an optional repeat rule (RFC 5545 RRULE), extra dates, removed dates, and changes to single instances. The core `event` type's `occurrences` field is a recurrence, and a custom type may declare one too.

```yaml
# config/schema/event.yaml
extends: event
fields:
  - { name: occurrences, label: { en-GB: Dates and times } }   # restate the core field to relabel it
```

```yaml
# a custom type
fields:
  - { name: sessions, type: recurrence, zone: Europe/London, all_day: false }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `zone` | IANA zone | the site's | The zone the editor offers first. |
| `all_day` | boolean | `true` | Offers the all-day switch. |

The editor offers once, daily, weekly on chosen days, monthly on a date or an ordinal weekday, yearly, an end by date or count, and a custom rule for anything else, and shows the next instances as the rule is edited.

**Stored value:**

```json
{
  "start": "2026-03-13T19:00",
  "duration": "PT2H",
  "zone": "Europe/London",
  "allDay": false,
  "rrule": "FREQ=WEEKLY;BYDAY=FR",
  "rdates": ["2026-07-04T19:00"],
  "exdates": ["2026-04-03"],
  "overrides": {
    "5": { "status": "cancelled", "note": "Bank holiday" },
    "6": { "start": "2026-04-25T20:00" }
  }
}
```

| Key | What it is |
|---|---|
| `start` | The first start, wall clock `YYYY-MM-DDTHH:MM` in `zone`. Required. |
| `duration` | ISO 8601 duration, such as `PT2H`, `PT90M` or `P1D`. |
| `zone` | The IANA zone. Required. |
| `allDay` | Whether instances are whole days. |
| `rrule` | The RRULE value without the `RRULE:` prefix. Empty for a one-off. A rule with no end is expanded to the end of the window below. |
| `rdates` | Extra starts, wall clock. |
| `exdates` | Days removed entirely, `YYYY-MM-DD`. |
| `overrides` | Changes to single instances, keyed by the instance's number in the rule's own sequence (extra dates are numbered from 100000, so adding one renumbers nothing). Each takes `start`, `duration`, `status` (`cancelled` or `moved`) and `note`. |

Validation reports each problem at its part: `zone` (Choose a time zone), `start` (Enter the first date and time), `duration`, `rrule` (The repeat rule is not valid: ...), `rdates[n]`, `exdates[n]` and `overrides.<n>`.

**Occurrences.** On save the engine expands the schedule into individual occurrences in local time, then converts each to UTC, for a rolling window around today: 90 days back and 540 days ahead by default (`events.occurrence_window` in `engine.yaml`), rolled forward daily. A cancelled instance keeps its row and is marked cancelled; a removed date has none.

**Template value.** A template never sees the rule's expansion logic, only the materialised occurrences of the published document:

| Property | What it is |
|---|---|
| `next(n)` | The next `n` occurrences that have not ended, cancelled ones left out. |
| `upcoming()` | Every occurrence that has not ended, cancelled ones left out. |
| `past()` | Every occurrence that has ended, cancelled ones left out. |
| `between(a, b)` | Occurrences starting between two times, cancelled ones left out. |
| `all` | Every occurrence in the window, cancelled ones included. |
| `count` | How many there are in `all`. |
| `start`, `zone`, `isAllDay`, `rrule`, `duration`, `repeats` | The schedule's own facts; `repeats` is true when there is a rule or extra dates. |

Each occurrence has `startsAt`, `endsAt` (UTC), `local`, `localEnd` (wall clock), `zone`, `date` (`YYYY-MM-DD`), `isAllDay`, `isCancelled`, `isMoved`, `status`, `note` and `ord` (its number in the sequence).

```jinja
<ul>
  {% for o in entry.occurrences.next(5) %}
  <li><time datetime="{{ o.startsAt|iso }}">{{ o.local|datetime:"full short" }}</time>{% if o.note %} ({{ o.note }}){% endif %}</li>
  {% endfor %}
</ul>
```

Occurrences are read for a top-level recurrence field, and they are the document's: give a type one recurrence field. How event pages and lists read occurrences is covered in [Templates](/templates).


# Form (/content-modelling/fields/form)

The form field: lets an editor place one of the site's declared form endpoints on a page, with the endpoints it may offer, the checks, and the form value templates render.

A `form` field lets an editor choose which form appears on a page: a contact form, a newsletter sign-up, a booking request. The forms themselves are declared endpoints in a site's `endpoints.yaml` ([Forms and submissions](/features/forms-and-submissions)); the field stores the chosen endpoint's id, so renaming the endpoint's key keeps every page's choice. The value is the same in every locale, since the endpoint's own labels are already translated.

```yaml
fields:
  - name: signup
    type: form
    endpoints: [newsletter]
    label: { en-GB: Form on this page }
```

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `endpoints` | list of endpoint keys | every form endpoint of the site | The endpoints an editor may choose. |

An endpoint is a form endpoint when it takes a `post`, its access is `public` or `member`, it answers with HTML (not `json` or a stream), it declares at least one input from the form body, and its path takes no `{placeholder}` (a form field has no subject to fill one). `engine-dmo check` reports, at the field:

- `unknown endpoint "x"`, with a suggestion or the list of the form endpoints of the type's sites;
- `endpoint "x" is declared on <site>, which type <type> is not on`;
- `endpoint x on site main is not a form: it answers with JSON` (or one of the other reasons above);
- a warning when the field offers every form endpoint of a site that declares none.

At save the value must be a form endpoint of the document's site that the field offers (`form_endpoint`: Choose one of the forms this site declares).

## Stored value and template value [#stored-value-and-template-value]

The stored value is the endpoint's id, `"end_srhmvkf6j3"`. With `index: true` the id is projected. In a seed file, give the same id, as written in the site's `endpoints.yaml` or listed by `engine-dmo describe project`: `contactForm: end_srhmvkf6j3`. It is a configuration id, not a database id, so a seed may hold it.

Printing the value prints the address the form posts to. The value has:

| Property or method | What it is |
|---|---|
| `render(submit=, enhance=, ...)` | The whole form: the CSRF and abuse fields, the error summary after a failed post, each input with its label, help, error and ARIA wiring, and the submit button. It posts in place with script and as a plain post without. `submit` sets the button text (else the string `form.<key>.submit`, then `form.submit`); `enhance=false` makes it a plain post always; other keywords are the form element's attributes. |
| `id`, `key` | The endpoint's id and key. |
| `action`, `method` | Where and how it posts. |
| `inputs` | The declared inputs in order, each with `name`, `type`, `label`, `help`, `required`, `autocomplete`, `multiline`, `max`, `format` and `options`, for a form you write by hand. |
| `hidden` | The hidden fields the abuse controls need, name to value. |
| `honeypot`, `honeypotName` | Whether there is a honeypot, and its field name. |
| `member` | Whether the endpoint is for signed-in members. |

```jinja
{% if entry.signup %}{{ entry.signup.render(submit="Sign up", class="signup") }}{% endif %}
```


# Fields (/content-modelling/fields)

The keys every field takes (name, type, label, required, index, translate, visible_when and the rest), field groups, and a table of all 23 field types with links to each type's page.

A field is one entry in a type's `fields:` list. Every field has a `name` and a `type`; the other keys below are common to all field types, and any key that is not one of them is a parameter of the field type, checked against that type's parameter list.

```yaml
fields:
  - name: distanceKm          # the handle templates and the API use
    type: number              # one of the field types below
    label: { en-GB: Distance }
    help: { en-GB: The length of the whole route. }
    required: true            # needed to publish
    index: true               # projected for filtering and sorting
    min: 0.1                  # number parameters
    max: 200
    unit: km
```

## Keys every field takes [#keys-every-field-takes]

| Key | Type | Default | What it does |
|---|---|---|---|
| `name` | string | required | The handle: a lowercase letter then letters and digits (`distanceKm`, `heroImage`). Unique within its level of the type. Templates read it as `entry.<name>`. |
| `type` | string | required | A field type from the table below. |
| `id` | string | written by `check --fix` | The field's stable id, `fld_` and ten characters. Never written by hand; it is what keeps values through a rename. |
| `label` | locale map or string | the name | The editor's label. |
| `help` | locale map or string | | One line of guidance under the control. |
| `required` | boolean | `false` | The field must have a value to publish. A draft saves without it. See [Validation](/content-modelling/validation). |
| `required_in` | `source`, `all`, a locale code, or a list of them | `[source]` | With `required: true`, which locales must have the value to publish. |
| `required_when` | expression | | Required to publish when the expression is true ([Validation](/content-modelling/validation)). |
| `visible_when` | expression | | Shown in the editor only when the expression is true; a hidden field's value is dropped on save. |
| `recommended` | boolean | `false` | Advice only: an empty recommended field blocks nothing and lowers the page's content health score. |
| `index` | boolean | `false` | Projects the value into the query index, so lists, smart lists, filters and `ordering` can filter and sort by it. Inside a repeater or blocks field, a child with `index: true` is projected under a dotted key (`stages.distanceKm`). |
| `unique` | boolean | `false` | No two documents of the type may hold the same value (per locale for a translated field). Top-level `text`, `slug`, `number`, `select`, `phone` and `date` fields only. A warning on save, an error at publish. |
| `protected` | boolean | `false` | Any change to the field's storage (type, translate mode, parameters) or its removal is destructive in a schema plan, even when no document holds a value ([Schema changes](/content-modelling/schema-changes)). |
| `translate` | `none`, `locale`, `language` or `group` | per type, see below | How many values the field has across locales ([Localisation](/content-modelling/localisation)). |
| `translatable` | boolean | | Shorthand: `true` is `translate: locale`, `false` is `translate: none`. |
| `structure` | `shared` or `per_locale` | `shared` | Repeater, blocks, link, asset and video fields: whether the item list is shared by every locale or each locale's own ([Localisation](/content-modelling/localisation)). |
| `fallback` | `empty` or `inherit` | `empty` | On the public site, what a locale without its own value shows: nothing, or the source locale's value. |
| `site_overridable` | boolean | `false` | Top-level fields only: a site the document is shared to may hold its own value of this field. Not on `slug`, not inside a container. |
| `aliases` | list of names | | Old handles of a renamed field, still answered by templates and the content API with a warning until retired ([Schema changes](/content-modelling/schema-changes)). |
| `machine_translate` | `allow` or `forbid` | `allow` | `forbid` stops AI drafting a translation of this field. Has no effect without an AI provider. |
| `summary_of` | field name | | On a top-level `text` field: AI summarisation drafts it from the named top-level `text` or `portable_text` field. Has no effect without an AI provider. |
| `default` | any | | Recorded with the field. It is used when an older revision, written before the field existed, is restored. The editor does not prefill it on a new document. |
| `personal` | boolean | `false` | Only for custom fields of a person record in `config/crm/person.yaml` (engine-dmo): included in a subject access export and cleared by an erasure. On a document type it fails `check`. |
| `fields` | list | | The child fields of a `repeater`, or the sub-fields of every link of a `link` field. |
| `blocks` | list | | The blocks of a `blocks` field, or the object blocks of a `portable_text` field. |
| `use` | field group name | | Includes a field group instead of declaring a field ([Field groups](#field-groups)). |

A field may sit inside a `repeater` item or a block; the same keys apply there except `site_overridable`, `unique` and `summary_of`, which are top-level only.

## Field types [#field-types]

`engine-dmo describe fieldtypes` lists these with every parameter; `--json` gives the same as data. Both bundles have the same field types.

| Type | Stores | Default translate | Projected with `index: true` | Page |
|---|---|---|---|---|
| `text` | a string | `locale` | the string | [Text and slug](/content-modelling/fields/text-and-slug) |
| `slug` | a URL segment, per locale | `locale` | the string | [Text and slug](/content-modelling/fields/text-and-slug) |
| `number` | a number | `none` | the number | [Numbers and money](/content-modelling/fields/numbers-and-money) |
| `money` | a decimal amount and an ISO 4217 code | `none` | the amount, and the code under `<name>.currency` | [Numbers and money](/content-modelling/fields/numbers-and-money) |
| `boolean` | true or false | `none` | the boolean | [Boolean and select](/content-modelling/fields/boolean-and-select) |
| `select` | one option, or a list with `multiple` | `none` | each value | [Boolean and select](/content-modelling/fields/boolean-and-select) |
| `date` | a calendar day | `none` | the day at midnight UTC | [Dates and times](/content-modelling/fields/dates-and-times) |
| `datetime` | a wall-clock time, its IANA zone and the UTC instant | `none` | the instant | [Dates and times](/content-modelling/fields/dates-and-times) |
| `recurrence` | a start, duration, zone, repeat rule, extra and removed dates | `none` | nothing; occurrences are materialised separately | [Dates and times](/content-modelling/fields/dates-and-times) |
| `geo` | a latitude, longitude and precision | `none` | latitude and longitude | [Places](/content-modelling/fields/places) |
| `geo_shape` | a GeoJSON Polygon or MultiPolygon | `none` | nothing; the bounding box and centroid are kept for containment queries | [Places](/content-modelling/fields/places) |
| `address` | a country and its address components | `none` | country, locality, administrative area, postal code and point, as sub-keys | [Places](/content-modelling/fields/places) |
| `phone` | an E.164 number with its national form and region | `none` | the E.164 number | [Phone and opening hours](/content-modelling/fields/phone-and-opening-hours) |
| `opening_hours` | regular hours, seasons, exceptions and holidays | `none` | whether any hours are set | [Phone and opening hours](/content-modelling/fields/phone-and-opening-hours) |
| `asset` | one library asset, or a list with `multiple`, with per-use framing, alt text and caption | `locale` | each asset id | [Asset](/content-modelling/fields/asset) |
| `link` | one link, or a list with `multiple`, to a document, asset, URL, email, phone, site or anchor | `locale` | nothing; document and asset targets are tracked as references | [Link](/content-modelling/fields/link) |
| `video` | a YouTube, Vimeo, library or file video with poster, captions, title and transcript | `locale` | the poster and library asset ids | [Video](/content-modelling/fields/video) |
| `seo` | a search title and description and their social pair | `locale` | nothing | [SEO](/content-modelling/fields/seo) |
| `form` | one of the site's form endpoints, by id | `none` | the endpoint id | [Form](/content-modelling/fields/form) |
| `relation` | references to documents, tags, smart lists, assets, organisations or people | `none` | each target | [Relations](/content-modelling/relations) |
| `portable_text` | rich text as Portable Text | `locale` | nothing | [Blocks and rich text](/content-modelling/blocks-and-rich-text) |
| `repeater` | an ordered list of items with the same child fields | `locale` | children with `index: true` | [Blocks and rich text](/content-modelling/blocks-and-rich-text) |
| `blocks` | an ordered list of items, each one of the declared blocks | `locale` | children with `index: true` | [Blocks and rich text](/content-modelling/blocks-and-rich-text) |

There is no `file`, `image`, `colour`, `table`, `duration` or `daterange` field type. Use `asset` for files and images, and two `date` or `datetime` fields with a [validation rule](/content-modelling/validation) for a range.

## Field groups [#field-groups]

A field group is a named list of fields declared once in `config/schema/_shared.yaml` and included in any type, repeater or block with `- use: <name>`:

```yaml
# config/schema/_shared.yaml
field_groups:
  contact:
    - { name: email, type: text, format: email }
    - { name: phone, type: phone }
```

```yaml
# config/schema/venue.yaml
key: venue
label: Venue
fields:
  - { name: title, type: text, required: true }
  - use: contact
```

The group's fields become fields of the including type, exactly as if declared there. A group name is camelCase. A `use:` entry declares nothing else (no `name`, no `type`). A group may include another group, but not itself. A variant's fields cannot use a group.

Ids for a group's fields are written into `_shared.yaml` by `check --fix`, and a field id is unique by declaration, so every type that includes the group shares the same field ids.

## Errors you may see [#errors-you-may-see]

| Message | Cause |
|---|---|
| `field "<name>" has no id` | Run `engine-dmo check --fix`. |
| `field name "<name>" must be camelCase: a lowercase letter then letters and digits` | Rename it. |
| `field "<name>" is declared twice` | Two entries share a name at the same level. |
| `"<name>" is an engine-managed field and cannot be declared` | See [Reserved names](/content-modelling/types#reserved-names). |
| `unknown field type "<type>"` | The type is not in the table above; the message lists the known types. |
| `field type <type> does not accept a parameter "<key>"` | A misspelt or unsupported parameter; a close match is suggested. |
| `field type <type> requires the parameter "<key>"` | `select` needs `options`, `relation` needs `to`. |
| `field type <type> does not take child fields` | `fields:` or `blocks:` on a type that has none. |
| `unique applies to text, slug, number, select, phone and date fields, not <type>` | Remove `unique`. |
| warning: `a <type> field is rarely translated; translate: <mode> means one value per <mode>` | A field whose type defaults to `none` was given a translate mode; intended only if you really want one value per locale. |
| `unknown field group "<name>"` | No such group in `_shared.yaml`. |


# Link (/content-modelling/fields/link)

The link field (one link or a list) to a document, asset, URL, email address, phone number, site or anchor, with kinds and their settings, editor attributes, rel, named styles, sub-fields, the stored shape and the link value templates receive.

A link field holds a link an editor makes: a call to action, a booking link, a list of related pages. A link to a document, asset or site stores the target's id, never its URL, so moving or renaming the target never breaks the link. The web layer resolves every link of a page in one batch to the target's live address in the request locale, and a link whose target is not live renders nothing rather than a dead link.

```yaml
fields:
  - name: website
    type: link
    kinds: [{ of: url }]

  - name: cta
    type: link
    kinds:
      - { key: page, of: document, types: [page, walk], label: { en-GB: A page on this site } }
      - { key: file, of: asset, kinds: [document], accept: [pdf] }
      - { key: web, of: url, hosts: [example.org, www.example.org] }
      - { key: mail, of: email, subject: true }
      - { of: phone }
    attributes: [text, title, aria_label, new_tab, rel, suffix, style]
    text: required
    rel: [nofollow, sponsored]
    styles:
      - { key: primary, label: { en-GB: Primary button }, class: button button--primary }
      - { key: plain, label: { en-GB: Text link }, class: link }
    fields:
      - { name: icon, type: select, options: [arrow, download] }

  - name: related
    type: link
    multiple: true
    max: 5
    kinds: [{ of: document, types: [walk], sites: network }, { of: url, relative: true }]
```

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `kinds` | list | `url`, `email`, `phone`, `anchor` | The kinds of link offered, in order. Each is `{ key, of, label, ...settings }` (below). |
| `multiple` | boolean | `false` | An ordered list of links. |
| `min` | whole number | none | With `multiple`: the fewest links to publish. |
| `max` | whole number | none | With `multiple`: the most links. |
| `attributes` | list of `text`, `title`, `aria_label`, `new_tab`, `rel`, `suffix`, `style` | `[text, new_tab]` | What the editor may set on each link. |
| `text` | `required`, `optional` or `none` | `optional` | Whether the editor writes link text. `none` takes no text of its own; `required` needs `text` in `attributes`. |
| `rel` | list of rel tokens | none | The `rel` values the editor may choose: `alternate`, `author`, `bookmark`, `external`, `help`, `license`, `me`, `next`, `nofollow`, `noopener`, `noreferrer`, `prev`, `privacy-policy`, `search`, `sponsored`, `tag`, `terms-of-service`, `ugc`. Used with `rel` in `attributes`. |
| `styles` | list | none | Named styles: `{ key, label, class }`. The editor picks one; the template's link gets its class. Each style gets an `id` from `check --fix`. |
| `fields` | list | none | Sub-fields on every link, declared like any field (an icon, a short description for a card). |
| `structure` | `shared` or `per_locale` | `shared` | `per_locale` makes the whole link each locale's own. |

### Kinds [#kinds]

Each kind has `of`, the engine kind; `key`, your handle for it (defaults to `of`, and must be unique within the field); `label`, what the editor sees; and the settings its engine kind takes:

| `of` | Target | Settings |
|---|---|---|
| `document` | A document, by id | `types`: the type keys it may point at (default any). `sites`: `own` (the default, this site), `network` (any site of the network) or `any`. |
| `asset` | A media library asset, by id | `kinds`, `accept`, `tags`, as an [asset field](/content-modelling/fields/asset) takes them. |
| `url` | A web address | `hosts`: the host names allowed. `relative: true` also accepts a path starting with `/`. |
| `email` | An email address | `subject: true` offers a subject line. |
| `phone` | A telephone number | none |
| `site` | Another site of the network's home page, by id | none |
| `anchor` | An element id on the same page, without `#` | none |

`engine-dmo check` refuses an unknown `of`, a setting that belongs to another kind (`a url kind does not take "types"`), a key offered twice, an unknown attribute or rel token, a style with no class, and `min` or `max` without `multiple`.

## Validation [#validation]

| Code | Message |
|---|---|
| `kind` | Choose a link type: ... |
| `target` | Enter where the link goes |
| `document` | Choose a page to link to |
| `link_asset` | Choose a file to link to |
| `url` | Enter a full web address starting with http:// or https:// |
| `url_relative` | Enter a full web address starting with http:// or https://, or a path starting with / |
| `url_host` | Link to one of: ... |
| `email` | Enter an email address |
| `phone`, `region` | Enter a telephone number / Enter the number with its country code, starting with + |
| `site` | Choose a site of the network |
| `anchor` | An anchor is the id of an element on the page, without the # |
| `suffix`, `suffix_kind`, `suffix_offered` | A query and fragment only, such as `?tab=prices#booking`, on a page, web address or site link, when `suffix` is offered |
| `text_required`, `text_none` | Enter the link text / This link takes no text of its own |
| `label_in_name` | The accessible name should contain the visible text, so a person using speech can say what they see |
| `rel`, `link_style` | A rel or style the field does not offer |
| `new_tab_offered`, `title_offered`, `aria_label_offered`, `subject_offered` | A setting the field does not offer |
| `min_items` / `max_items` | Add at least / no more than N links |

At save and publish the engine also checks that a document target is of an allowed type and on an allowed site.

## Stored value [#stored-value]

```json
{
  "_key": "l1", "kind": "page", "of": "document", "document": "8a6e...",
  "suffix": "#booking", "new_tab": false, "rel": ["sponsored"], "style": "opt_3k9d0m2w1x",
  "text": "Book a table", "title": "", "aria_label": "",
  "fields": { "icon": "arrow" }
}
```

The target key follows `of`: `document`, `asset`, `url`, `email` (with `subject`), `phone` (with `region`), `site` (a site id) or `anchor`. With `multiple`, a list of these. `text`, `title` and `aria_label` are each locale's own; the target, style, rel and sub-fields are shared by every locale. In a seed file a document target is `document: <type>/<seed key>` and an asset target `asset: <seed key>`.

A link is not projected into the query index; document and asset targets are recorded as references, so the admin lists broken links and what links to a page.

## Template value [#template-value]

Printing the value prints its URL. With `multiple`, the field is a list of link values.

| Property | What it is |
|---|---|
| `url` | The resolved address with the suffix; empty when broken. A document on another site of the network is an absolute URL. |
| `text` | The editor's text, else the target's title, the asset's title, the URL's host and path, the address or the number. |
| `kind`, `of` | Your kind key and the engine kind. |
| `title`, `ariaLabel` | The editor's title and accessible name. |
| `newTab`, `target` | Whether a new tab was asked for, and `_blank` when it was. |
| `rel` | The chosen rel tokens, with `noopener` for a new tab. |
| `style`, `class` | The chosen style's key and class. |
| `isExternal` | Whether the link leaves the site. |
| `broken` | Whether the target is not live in the locale chain. |
| `document` | The target document as an entry. |
| `asset` | The target asset: `url`, `title`, `filename`, `mime`, `extension`, `bytes`, `size`. |
| `fields` | The sub-field values by name. |
| `isAffiliate`, `affiliate` | engine-dmo: whether the link goes through an affiliate programme, and which ([Affiliates](/dmo/affiliates)). |

| Method | What it writes |
|---|---|
| `link(text=, ...)` | The whole `<a>` with every attribute the editor set, the style's class merged with `class=`, and the new-tab and file-type announcements. Nothing when the link is broken or empty. `href` cannot be passed. |
| `attributes(...)` | The attributes alone, `href` included, for an element you write yourself. |

```jinja
{{ entry.cta.link() }}
{{ entry.cta.link(text="Book now", class="wide") }}

<a {{ entry.cta.attributes(class="card") }}>
  <h3>{{ entry.cta.text }}</h3>
  {% if entry.cta.fields.icon %}<span class="icon-{{ entry.cta.fields.icon.value }}"></span>{% endif %}
</a>

<ul>{% for l in entry.related %}<li>{{ l.link() }}</li>{% endfor %}</ul>
```

See [Links](/templates/links) for links in templates generally. The `link` annotation in rich text uses the same kinds, attributes and rel ([Blocks and rich text](/content-modelling/blocks-and-rich-text)).


# Numbers and money (/content-modelling/fields/numbers-and-money)

The number field (min, max, step, integer, display unit) and the money field (a decimal amount with its ISO 4217 currency, fixed or chosen), with parameters, validation, stored shapes and template values.

## number [#number]

A number: a distance, a capacity, a rating, a duration in minutes. Held once for every locale.

```yaml
fields:
  - { name: capacity, type: number, integer: true, min: 1, max: 5000, index: true }
  - { name: rating, type: number, min: 0, max: 5, step: 0.5 }
  - { name: walkMinutes, type: number, min: 0, unit: minutes }
```

### Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `min` | number | none | The smallest value accepted. |
| `max` | number | none | The largest value accepted. |
| `step` | number | none | The value must be a whole number of steps, counted from `min` when it is set and from zero otherwise. `min: 1, step: 2` accepts 1, 3, 5. |
| `integer` | boolean | `false` | Refuses fractions. |
| `unit` | string | none | A unit shown beside the control (`km`, `minutes`). It is never applied to the value and a template does not receive it. |

### Validation [#validation]

| Code | Message |
|---|---|
| `number` | Must be a number |
| `integer` | Must be a whole number |
| `min_value` | Must be N or more |
| `max_value` | Must be N or less |
| `step` | Must be a multiple of N |

### Stored value and template value [#stored-value-and-template-value]

A JSON number. A form may post a numeric string such as `"12"`; it is stored as a number. A string that is not a number is kept as posted and reported, never turned into zero.

A template receives a whole number when the field is `integer` or the value has no fraction, otherwise a decimal. Format it for the reader with `|number`, which uses the request locale's grouping and decimal separator; `|number:1` fixes one decimal place.

```jinja
<p>Capacity: {{ entry.capacity|number }}</p>
{% if entry.rating %}<p>Rated {{ entry.rating|number:1 }} out of 5</p>{% endif %}
```

A `number` reads an old numeric `text` value exactly and a `boolean` lossily when a schema change retypes it.

## money [#money]

An amount of money in a currency: an entry fee, a price from, a deposit. The amount is a decimal string, never a floating-point number, so `0.10` stays `0.10`. The currency is an ISO 4217 code carried on every value; it is never inferred from a locale.

```yaml
fields:
  - { name: entryFee, type: money, currency: GBP, min: 0, max: "250.00" }
  - { name: deposit, type: money, currencies: [GBP, EUR] }
  - { name: refund, type: money, currency: GBP, negative: true }
```

### Parameters [#parameters-1]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `currency` | ISO 4217 code | none | The one currency accepted, fixed in the editor. An amount given without a currency takes this one. |
| `currencies` | list of codes | the site's, then the source locale's | The currencies the editor offers, plus any the value already has. |
| `min` | decimal | none | The smallest amount, compared exactly as a decimal. |
| `max` | decimal | none | The largest amount, compared exactly as a decimal. |
| `negative` | boolean | `false` | Accepts amounts below zero. |

### Validation [#validation-1]

| Code | Message |
|---|---|
| `money_amount` | Enter an amount such as 12.50 (the amount is not a plain decimal: `12,50` and `1e3` are refused) |
| `money_currency_empty` | Choose a currency |
| `money_currency` | XXX is not an ISO 4217 currency code |
| `money_currency_fixed` | Must be in GBP |
| `money_currency_allowed` | Must be one of GBP, EUR |
| `money_precision` | JPY has 0 decimal places (more decimal places than the currency has) |
| `money_negative` | Must not be below zero |
| `min_value` / `max_value` | Must be N or more / Must be N or less |

### Stored value [#stored-value]

```json
{ "amount": "12.50", "currency": "GBP" }
```

On save the amount is padded to the currency's minor units: `12.5` in GBP is stored as `12.50`, `1250` in JPY as `1250`. The code is upper case. In a seed file or an import, a field with a fixed `currency` also accepts a bare amount (`12.50`).

With `index: true`, the amount is projected as a number under the field's name and the code as text under `<name>.currency`, so a query filters "under 50" within one currency. Amounts in different currencies are never compared, and there is no conversion between currencies.

### Template value [#template-value]

| Property | What it is |
|---|---|
| `amount` | The decimal amount as stored, such as `12.50`. |
| `currency` | The ISO 4217 code. |
| `formatted` | The amount formatted for the request locale, such as `£12.50`. |

```jinja
{% if entry.entryFee %}<p>Entry {{ entry.entryFee.formatted }}</p>{% endif %}
<p>Deposit {{ entry.deposit|money }}</p>
```

`|money` formats a money value for the request locale; `|currency:"EUR"` formats a plain number in a named currency ([Filters](/templates/filters)).


# Phone and opening hours (/content-modelling/fields/phone-and-opening-hours)

The phone field (an E.164 number parsed in a region, with accepted number types) and the opening_hours field (a weekly pattern, seasons, exceptions and public holidays), with parameters, validation, stored shapes and template values.

## phone [#phone]

A telephone number, parsed and checked for its region and stored in international E.164 form beside what the editor typed. Held once for every locale.

```yaml
fields:
  - { name: phone, type: phone, index: true }
  - { name: mobile, type: phone, region: GB, types: [mobile] }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `region` | ISO 3166 code | the site's country, in the admin's editor | The region a number typed without its country code is read in. A number typed with `+` needs none. A seed file and `content create` do not read the site's country, so there a bare national number needs this parameter, or `{ raw, region }` in the value. |
| `types` | list of `fixed_line`, `mobile`, `toll_free`, `premium_rate`, `voip` | any | The number types accepted. A number the dataset cannot tell between fixed line and mobile is accepted by either. |

| Code | Message |
|---|---|
| `region` | Enter the number with its country code, starting with + (no region to read it in) |
| `phone_empty` | Enter a telephone number |
| `phone_invalid` | This is not a valid telephone number |
| `phone_region` | This is not a valid telephone number for GB |
| `phone_type` | Must be a mobile number |

**Stored value:**

```json
{ "raw": "01295 123456", "region": "GB", "e164": "+441295123456", "national": "01295 123456", "type": "fixed_line" }
```

`raw` and `region` are what the editor typed and where; the rest is derived on save. In a seed file or import, `{ raw, region }` is enough, and a bare string is read in the field's `region` parameter (without one it must start with `+`). With `index: true` the E.164 form is projected.

**Template value:**

| Property | What it is |
|---|---|
| `display` | The number as a reader in this locale expects it: national inside the number's own region, international outside it. The locale's region decides, so a UK number shows as `01600 712345` under `en-GB` and `+44 1600 712345` under plain `en`. |
| `telHref` | `tel:` and the E.164 number, for a link. A variable in `href` must go through the `url` filter, which keeps `tel:`. |
| `e164` | `+441295123456`. |
| `national`, `international` | The two written forms. |
| `region` | The number's region. |
| `type` | `fixed_line`, `mobile`, `toll_free` and so on. |
| `valid` | Whether the number is valid. A number that cannot be parsed shows what was typed in `display` and has an empty `telHref`. |

```jinja
{% if entry.phone %}<a href="{{ entry.phone.telHref|url }}">{{ entry.phone.display }}</a>{% endif %}
```

## opening_hours [#opening_hours]

When a place is open: a regular week, seasons that replace it between two dates each year, exceptions for single days, behaviour on public holidays, a note per locale and a by-appointment flag. The structure is held once for every locale; only the notes are per locale, inside the value.

```yaml
fields:
  - name: openingHours
    type: opening_hours
    holiday_calendar: uk-england-wales
    timezone: Europe/London
    max_periods: 2
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `holiday_calendar` | calendar key | none | The public holiday calendar offered by default; a value may choose another. Built in: `uk-england-wales`, `uk-scotland`, `uk-northern-ireland`. |
| `timezone` | IANA zone | the site's, then the locale's | The zone offered by default. |
| `max_periods` | whole number | `3` | How many periods per day the editor offers. |

The editor takes one row per weekday with a closed switch and the periods as shorthand (`12:00-15:00, 18:00-23:00`; a close at or before the open runs into the next day), seasons and exceptions as rows, the holiday calendar and behaviour, and this locale's note.

**Stored value:**

```json
{
  "timezone": "Europe/London",
  "regular": [
    { "day": "mon", "periods": [{ "open": "09:30", "close": "16:30" }] },
    { "day": "sun", "closed": true }
  ],
  "seasons": [
    { "from": "11-01", "to": "02-28", "regular": [{ "day": "sat", "periods": [{ "open": "10:00", "close": "14:00" }] }] }
  ],
  "exceptions": [
    { "date": "2026-12-24", "periods": [{ "open": "09:30", "close": "12:00" }], "note": "Christmas Eve" }
  ],
  "holiday_calendar": "uk-england-wales",
  "holiday_behaviour": "closed",
  "notes": { "en-GB": "Tours at 11:00 and 14:00; booking essential." },
  "by_appointment": false
}
```

| Key | What it is |
|---|---|
| `timezone` | Required. The zone the times are in. |
| `regular` | The week: each day `mon` to `sun` at most once, `closed` or `periods` of `{ open, close }` in `HH:MM`. A period whose close is at or before its open runs past midnight. |
| `seasons` | Weeks that replace `regular` between `from` and `to`, each `MM-DD` and inclusive; a season may wrap the year end. |
| `exceptions` | Single dates, `YYYY-MM-DD`, either `closed` or with `periods` (not both), with an optional `note`. |
| `holiday_calendar` | A calendar key, as above. |
| `holiday_behaviour` | `closed`, `normal`, or `hours` with `holiday_periods`. |
| `notes` | A note per locale code. |
| `by_appointment` | Open by appointment. |

On save the value is normalised (Monday first, empty days dropped, exceptions sorted by date), so two edits that mean the same store the same bytes. Each problem is reported at its path with code `opening_hours`: `timezone: a time zone is required`, `seasons[0].from: must be MM-DD`, `exceptions[1]: closed and periods cannot both be set`, `regular[2].day: mon appears twice`, `holiday_behaviour: must be closed, normal or hours`, `holiday_calendar: unknown holiday calendar`.

With `index: true` the field projects one boolean, whether any hours are set, which is what a "places with no opening hours" list reads.

**Template value.** Methods take a time; pass the `now` global for the current moment.

| Property or method | What it is |
|---|---|
| `isOpenAt(t)` | Whether the place is open at `t`. |
| `closesAt(t)` | When the current period ends, or nothing. |
| `nextOpenAt(t)` | When it next opens, or nothing. |
| `nextChange(t)` | When it next opens or closes, or nothing. |
| `todayLabel(t)` | The day's hours in words for the request locale. |
| `week(t)` | The seven days from the locale's first day of the week (Monday under `en-GB`, Sunday under plain `en`), each with `date`, `weekday`, `label`, `isToday`, `closed`, `periods` (each `open`, `close`, `spansMidnight`), `periodsLabel`, `note` and `source` (`regular`, `season`, `exception` or `holiday`). |
| `jsonld(t)` | The schema.org `openingHoursSpecification` entries. |
| `note` | This locale's note, else one in the same language. |
| `notes` | Every note by locale. |
| `timezone`, `calendar`, `byAppointment`, `isEmpty` | As stored. |

```jinja
{% set hours = entry.openingHours %}
{% if hours and not hours.isEmpty %}
<p>{% if hours.isOpenAt(now) %}{{ t('hours.open_now') }}{% else %}{{ t('hours.closed_now') }}{% endif %}</p>
<table>
  <caption>{{ t('hours.caption') }}</caption>
  <thead><tr><th scope="col">{{ t('hours.day') }}</th><th scope="col">{{ t('hours.times') }}</th></tr></thead>
  <tbody>
    {% for day in hours.week(now) %}
    <tr{% if day.isToday %} aria-current="date"{% endif %}><th scope="row">{{ day.label }}</th><td>{{ day.periodsLabel }}</td></tr>
    {% endfor %}
  </tbody>
</table>
{% if hours.note %}<p>{{ hours.note }}</p>{% endif %}
{% endif %}
```


# Places (/content-modelling/fields/places)

The geo field (a point), the geo_shape field (an area boundary as GeoJSON) and the address field (a country-aware postal address), with parameters, validation, stored shapes and template values.

All three are held once for every locale: where a place is does not change with the language.

## geo [#geo]

A point on the map: where a listing is, where a walk starts. The core `event` and `listing` types have a required, indexed `location`, and `area` an optional `centre`.

```yaml
fields:
  - name: startPoint
    type: geo
    required: true
    index: true
    bounds: { min_lat: 49.8, min_lon: -8.7, max_lat: 60.9, max_lon: 1.8 }
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `bounds` | `{ min_lat, min_lon, max_lat, max_lon }` | none | The point must fall inside this box. |

| Code | Message |
|---|---|
| `geo` | Enter a latitude and a longitude |
| `lat` | Latitude must be between -90 and 90 |
| `lon` | Longitude must be between -180 and 180 |
| `precision` | Precision must be one of rooftop, street, locality, approximate |
| `bounds` | The point is outside the allowed area |

**Stored value:** `{ "lat": 52.0629, "lon": -1.3398, "precision": "rooftop" }`. `precision` is optional and one of `rooftop`, `street`, `locality` or `approximate`, from a geocoder's exact match down to a hand-placed pin. With `index: true` the latitude and longitude are projected, so lists can filter by a bounding box and by distance.

**Template value:**

| Property or method | What it is |
|---|---|
| `lat`, `lon` | The coordinates. |
| `precision` | As stored, or empty. |
| `derived` | True on an area-style `centre` the engine took from the type's boundary (below). |
| `distanceTo(other)` | The great-circle distance in kilometres to another point (any value with `lat` and `lon`). |
| `staticMap(...)` | A map image of the point drawn by the engine from the install's tile provider and served from the site's own origin, with the provider's credit. Prints nothing when `maps.tiles` is not set in `engine.yaml` ([maps](/reference/configuration/engine-content#maps)); a map is a core feature, in both bundles. Options: `width` and `height` (64 to 1280; 600 and two thirds of the width by default), `zoom` (15), `alt`, `name`, `marker` (true), and any HTML attribute for the figure. |

```jinja
{% for l in entry.nearbyListings %}
<p>{{ l.title }}, {{ entry.startPoint.distanceTo(l.location)|number:1 }} km away</p>
{% endfor %}
{{ entry.startPoint.staticMap(width=480, zoom=14) }}
```

Printing the value itself shows nothing useful: read `lat` and `lon`. `|distance` formats metres in the viewer's measurement system ([Filters](/templates/filters)).

## geo_shape [#geo_shape]

An area with an edge: a town, a national park, a council ward. The DMO bundle's core `area` type has a required `boundary` of this type, which is what "listings in this area" containment queries test against. Use a shape, not a point with a radius, wherever "in" matters.

```yaml
fields:
  - name: boundary
    type: geo_shape
    geometries: [Polygon, MultiPolygon]
    max_vertices: 10000
    simplify_m: 5
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `geometries` | list of `Polygon`, `MultiPolygon` | both | The geometry types accepted. Points and lines are never accepted. |
| `max_vertices` | whole number | `10000` | Above this, the shape is simplified on save until it fits. |
| `simplify_m` | number | none | A Douglas-Peucker tolerance in metres applied on every save. |

The editor takes pasted GeoJSON (a geometry, a Feature or a one-feature FeatureCollection) or an uploaded GeoJSON or KML file, and draws the shape for checking. On save the shape is normalised: rings closed, duplicate consecutive vertices dropped, coordinates rounded to six decimal places, shells counter-clockwise and holes clockwise.

| Code | Message |
|---|---|
| `geojson` | Not a usable shape: (the reason) |
| `geometry` | Must be a Polygon or MultiPolygon |
| `shape` | The polygon, ring and vertex that are wrong: too few vertices, coordinates off the globe, a self-intersection, a hole outside its shell |

**Stored value:** standard GeoJSON in WGS 84, coordinates as `[lon, lat]`:

```json
{ "type": "Polygon", "coordinates": [[[-1.36, 52.05], [-1.33, 52.05], [-1.33, 52.07], [-1.36, 52.07], [-1.36, 52.05]]] }
```

A shape is not written to the query index as such; its bounding box, centroid and area are kept for containment and distance queries.

**Template value:**

| Property or method | What it is |
|---|---|
| `type` | `Polygon` or `MultiPolygon`. |
| `geometry` | The GeoJSON, for a map script (`{{ entry.boundary.geometry|json }}`). |
| `vertices` | How many vertices it has. |
| `areaKm2` | Its area in square kilometres, to two places. |
| `bbox` | `{ minLat, minLon, maxLat, maxLon }`. |
| `centroid` | `{ lat, lon }`. |
| `contains(point)` | Whether a point (any value with `lat` and `lon`) is inside. |

**The centre of a shape.** A type with a `geo_shape` field and a `geo` field named `centre` gets a centre in templates even when the editor sets none: the shape's centroid, with `precision: approximate` and `derived: true`. A centre the editor sets always wins, since the centroid of an odd shape can fall in a field.

A derived centre has `lat`, `lon` and `distanceTo()`, but no `staticMap()`: `entry.centre.staticMap(...)` on it prints nothing, with no error from `check` or `render`. The shape's own `centroid` does have `staticMap()`, so draw the map from whichever exists:

```jinja
{% if entry.centre and not entry.centre.derived %}{{ entry.centre.staticMap(width=480) }}{% elif entry.boundary %}{{ entry.boundary.centroid.staticMap(width=480, marker=false) }}{% endif %}
```

## address [#address]

A postal address whose parts follow the country: the components, which are required, the order of lines and the postal code pattern come from a built-in country dataset, so no country is refused and none is assumed.

```yaml
fields:
  - name: address
    type: address
    index: true
    country: GB
    countries: [GB, IE]
    geo: true
```

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `country` | ISO 3166 code | the site's country | The country the editor offers first. |
| `countries` | list of codes | every country | Restricts the countries accepted. |
| `geo` | boolean | `false` | Offers a pin alongside the address. |

**Components.** The keys an address holds depend on the country. The common ones are `line1`, `line2`, `dependent_locality`, `locality`, `administrative_area`, `postal_code` and `sorting_code`; a country with no shipped data offers `line1` (required), `line2`, `locality`, `administrative_area` and `postal_code`. The editor shows each country's own labels (for the United Kingdom, "Postcode" and "Town or city").

| Code | Message |
|---|---|
| `country_empty` | Choose a country |
| `country_allowed` | Must be an address in GB, IE |
| `required` | (Label) is required, at the component |
| `postal_code` | (Value) is not a valid (postal code label) |
| `script` | (Code) is not a script code |

**Stored value:**

```json
{
  "country": "GB",
  "components": { "line1": "Brewery Lane", "locality": "Hook Norton", "administrative_area": "Oxfordshire", "postal_code": "OX15 5NY" },
  "formatted": ["Brewery Lane", "Hook Norton", "Oxfordshire", "OX15 5NY"],
  "geo": { "lat": 51.999, "lon": -1.499 }
}
```

`formatted` is computed on every save from the country's layout; you never write it. `variants` may hold the same address in another script, keyed by ISO 15924 code (`"Latn": { "components": { ... } }`), each formatted in its own layout. With `index: true` the country, locality, administrative area and postal code are projected as `address.country`, `address.locality`, `address.administrative_area` and `address.postal_code`, and the pin as `address.geo`, so "listings in Banbury" is an indexed query.

**Template value:**

| Property | What it is |
|---|---|
| `formatted` | The lines, in the country's order, as a list. |
| `oneLine` | The lines joined with commas. |
| `components` | The components by key. |
| `country`, `countryName` | The code and the country's name. |
| `script` | The script the lines are in. |
| `geo` | The pin as a geo value, or nothing. |

A page in a locale whose script differs from the country's, with a variant in that script, shows the variant: a Japanese address reads in Latin script on an English page when the editor gave a romanised form.

```jinja
<address>{% for line in entry.address.formatted %}{{ line }}{% if not forloop.Last %}<br />{% endif %}{% endfor %}</address>
```


# SEO (/content-modelling/fields/seo)

The seo field: a per-locale search title and description and their social-sharing pair, with length warnings, the stored shape, and how head() uses it.

An `seo` field holds the copy a search results page and a shared link show for a document: a title, a description, and optionally a different title and description for social sharing. It is translated per locale. Declare it under any name that is not reserved (`seo` itself is reserved): `meta` is conventional.

```yaml
fields:
  - name: meta
    type: seo
    title_max: 60
    description_max: 155
    label: { en-GB: Search and sharing }
```

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `title_max` | whole number | `60` | The title length a warning starts at. |
| `description_max` | whole number | `160` | The description length a warning starts at. |

A results page truncates rather than refuses, so these are warnings, never errors:

| Code | Path | When |
|---|---|---|
| `max_length` | `<name>.title` | The title is longer than `title_max`. |
| `max_length` | `<name>.description` | The description is longer than `description_max`. |
| `seo_description_short` | `<name>.description` | The description is under 50 characters. |

The editor shows a title input and a description box, with the social pair behind a disclosure that starts open when either is written.

## Stored value and template value [#stored-value-and-template-value]

```json
{ "title": "Hook Norton Brewery tours", "description": "A Victorian tower brewery...", "og_title": "", "og_description": "" }
```

A template receives `title`, `description`, `og_title` and `og_description`. You rarely print them yourself: `head()` writes the page's title, meta description and Open Graph and Twitter tags from the type's first `seo` field, each social value falling back to the search one on its own ([SEO and structured data](/templates/seo-and-structured-data)).

```jinja
<head>
  {{ head() }}
</head>
```

A document's own `seo` title and description replace the generated ones only where they are written; an empty one leaves the generated copy, which is the document's title and its `summary`. On an engine-dmo landing page, the content document's `seo` field gives the social pair. An `seo` field is not projected into the query index.


# Text and slug (/content-modelling/fields/text-and-slug)

The text field (single or multi-line, length limits, pattern, email format) and the slug field (a per-locale URL segment generated from another field), with parameters, validation and template values.

## text [#text]

A plain string: a title, a strapline, a reference number, an email address. Translated per locale by default. For formatted prose use [`portable_text`](/content-modelling/blocks-and-rich-text).

```yaml
fields:
  - { name: title, type: text, required: true, index: true }
  - { name: strapline, type: text, max: 120 }
  - { name: intro, type: text, multiline: true, min: 40, max: 400 }
  - name: reference
    type: text
    pattern: "^[A-Z]{2}[0-9]{4}$"
    unique: true
    help: "Two letters then four digits, such as BX1234."
  - { name: bookingEmail, type: text, format: email }
```

### Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `multiline` | boolean | `false` | A text area in the editor instead of a single line. The value keeps its line breaks. |
| `max` | whole number | none | The most characters, counted as grapheme clusters (what a reader sees as one character, so an emoji or an accented letter counts once). |
| `min` | whole number | none | The fewest characters, when the field is not empty. |
| `pattern` | regular expression | none | The value must match. The expression is Go's RE2 syntax and is not anchored: write `^` and `$` to match the whole value. Checked only when the field is not empty. |
| `format` | `email` or `url` | none | `email` requires an `@`. `url` is accepted but not checked; use a [`link`](/content-modelling/fields/link) field for addresses. |

### Validation [#validation]

| Code | Message | When |
|---|---|---|
| `max_length` | Must be N characters or fewer | longer than `max` |
| `min_length` | Must be at least N characters | shorter than `min`, and not empty |
| `pattern` | Does not match the required format | `pattern` does not match |
| `format` | Must be an email address | `format: email` and no `@` |

Each is an error, so it blocks the save as well as the publish. `required`, `unique` and the other common keys are on [Fields](/content-modelling/fields).

### Stored value and template value [#stored-value-and-template-value]

The value is a JSON string. A template receives the string, escaped when printed:

```jinja
<h1>{{ entry.title }}</h1>
{% if entry.intro %}<p>{{ entry.intro|linebreaksbr }}</p>{% endif %}
{% if entry.bookingEmail %}<a href="mailto:{{ entry.bookingEmail }}">{{ entry.bookingEmail }}</a>{% endif %}
```

Useful filters: `|truncate:n`, `|excerpt:n`, `|linebreaksbr`, `|upper`, `|lower`, `|length` ([Filters](/templates/filters)).

### Changing type [#changing-type]

A `text` field reads an old `slug` or `select` value exactly, and an old `portable_text` value lossily as plain text, which is how a schema plan judges a retype ([Schema changes](/content-modelling/schema-changes)).

## slug [#slug]

A URL segment, one per locale, which a route places in the address with `{slug}`. The admin generates it from a source field using the locale's slug mode from `config/locales.yaml` (transliterated or native script), and an editor may change it by hand.

```yaml
fields:
  - { name: title, type: text, required: true }
  - { name: slug, type: slug, source: title, max: 60, required: true }
```

### Parameters [#parameters-1]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `source` | field name | none | The field the slug is generated from in the editor. |
| `max` | whole number | none | The most characters, counted as grapheme clusters. |

### Validation [#validation-1]

| Code | Message | When |
|---|---|---|
| `slug` | Use lowercase letters, numbers and single hyphens | not a canonical slug |
| `max_length` | Must be N characters or fewer | longer than `max` |

A valid slug is lowercase where the script has case, in Unicode NFC, made of letters, marks and digits of any script joined by single hyphens. So `old-town-hall` and `hook-norton-jouzousho-tour` are valid, as is a slug in a non-Latin script that follows the same rules; `Old Town`, `old--town` and `-old` are not.

The reserved value `__home__` is valid as the whole slug and makes the document the site's home page, on a site whose `routes.yaml` does not name a `home:` ([Sites, locales and routes](/concepts/sites-locales-and-routes)).

The core types all have a required, indexed `slug` with `source: title`. A slug field cannot be `site_overridable`: it builds the document's address on every site.

### Stored value and template value [#stored-value-and-template-value-1]

A JSON string per locale. A template receives the string. To link to a document, use its `uri` or `url` rather than building an address from the slug ([Links](/templates/links)).


# Video (/content-modelling/fields/video)

The video field: a YouTube or Vimeo video, a media library video or an .mp4/.webm file on an allowed host, with poster, captions confirmation, title and transcript, rendered through a privacy facade.

A video field references one video. It never embeds a third party's player on page load: the template renders a facade, the poster and a play button naming the video, and loads the player only when the visitor activates it, from YouTube's no-cookie domain or with Vimeo's do-not-track flag.

```yaml
fields:
  - name: film
    type: video
    sources: [youtube, vimeo]
    poster: required
    captions: required
    transcript: true

  - name: backgroundLoop
    type: video
    sources: [file]
    hosts: [media.example.org, self]
    poster: required
    captions: none
```

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `sources` | list of `youtube`, `vimeo`, `library`, `file` | `[youtube, vimeo]` | What may be chosen. `library` is a video reference from the media library; `file` is an `.mp4` or `.webm` on an allowed host. |
| `hosts` | list of host names | none | Required with `file`: the hosts a file may come from. `self` allows a path to one of the project's own public files, such as `/video/harbour.mp4`. |
| `poster` | `required` or `optional` | `optional` | The still shown before playing: a library image, else the provider's thumbnail, which the server fetches once and keeps in the library. `required` makes publishing need one. |
| `captions` | `required`, `warn` or `none` | `warn` | Whether publishing asks the editor to confirm the video has captions: `required` refuses without the confirmation, `warn` publishes with a warning, `none` does not ask. |
| `transcript` | boolean | `false` | Offers a transcript, rich text per locale. |
| `structure` | `shared` or `per_locale` | `shared` | `per_locale` makes the whole video each locale's own (a different film per language). |

`engine-dmo check` refuses an unknown source, `file` without `hosts`, `hosts` without `file`, and values outside the lists above.

## Validation [#validation]

| Code | Message |
|---|---|
| `video_choose` | Paste a video's address or choose one from the library |
| `video_url` | Paste the address of a youtube, vimeo video |
| `video_source` | This field does not take vimeo videos |
| `video_id_youtube`, `video_id_vimeo` | This is not a YouTube / Vimeo video's address |
| `video_file` | A video file's address starts with https:// |
| `video_host` | Video files may only come from media.example.org |
| `video_file_type` | A video file is an .mp4 or a .webm |
| `video_library` | Choose a video from the library |
| `video_title` | Enter the video's title; it names the player for screen readers (in the source locale) |
| `video_start` | The start is a number of seconds from the beginning |
| `video_duration` | Write the duration as minutes and seconds, such as 3:33 |
| `video_poster`, `video_poster_choose` | Choose a poster image for the video (at publish, with `poster: required`) |
| `video_captions` | Confirm the video has captions before publishing (`captions: required`) |
| `video_captions_unconfirmed` | Warning: the video is not confirmed as captioned (`captions: warn`) |
| `transcript_offered` | This field does not take a transcript |

## Stored value [#stored-value]

```json
{
  "source": "youtube", "id": "aqz-KE-bpKQ", "start": 30,
  "title": "A walk along the harbour wall",
  "poster": { "asset": "3c1e..." },
  "captions": true,
  "duration": "PT3M33S",
  "transcript": [ { "_type": "block", "_key": "t1", "children": [ { "_type": "span", "text": "..." } ] } ]
}
```

A Vimeo video may carry `hash` (an unlisted video's), a file source has `url` instead of `id`, and a library source has `asset`. The editor pastes a watch page's address and the engine reads the id from it. `title` and `transcript` are each locale's own; everything else is shared by every locale. With `index: true` the poster and library asset ids are projected.

## Template value [#template-value]

Printing the value prints the watch page's URL.

| Property | What it is |
|---|---|
| `title` | The video's title, the player's accessible name. |
| `source`, `id` | `youtube`, `vimeo`, `library` or `file`, and the provider's id. |
| `start`, `duration` | Where playing starts in seconds, and the length as ISO 8601. |
| `captions` | Whether the editor confirmed captions. |
| `watchUrl`, `embedUrl` | The provider's page, and the player on its privacy domain. |
| `poster` | The poster as an image value, with `img`, `picture`, `figure`, `transform` and `url`. |
| `transcript` | The transcript as Portable Text. |

| Method | What it writes |
|---|---|
| `render(transform=, sizes=, priority=, element=)` | The facade: the poster and a play button naming the video, loading nothing from the provider until activated. `element` is `figure` (the default) or `div`. Other keywords are the wrapper's attributes. |
| `background(transform=)` | A muted, looping, inline file video for decoration, with a pause button. Refused without a poster, and never plays under reduced motion or Save-Data. |
| `link(text=)` | A plain link to the watch page, for a list or an email. |

```jinja
{% if entry.film %}
  {{ entry.film.render(transform="hero") }}
  {% if entry.film.transcript %}<details><summary>Transcript</summary>{{ entry.film.transcript|ptext }}</details>{% endif %}
{% endif %}
```

For a video that is not a field (a provider link pasted in rich text or a template's own embed), see `embed()` in [Globals](/templates/globals).


# Content modelling (/content-modelling)

How a content type is declared in YAML under config/schema, with a complete worked example from an empty file to a rendered page.

A content type is a YAML file under `config/schema/` that names the type, lists its fields and, optionally, its validation rules and editor layout. The engine reads every type file when it starts and when you run `engine-dmo check`, builds the admin's editor from it, stores each document's values against it, and gives templates a typed `entry` for each document of the type.

The model is configuration, not code: you never write a migration for a new field. You change the YAML, run `engine-dmo check`, then `engine-dmo schema plan` and `engine-dmo schema apply` to bring the database in line.

One type file feeds every part of the engine that touches the type's content:

```mermaid
flowchart LR
  file["config/schema/walk.yaml"] --> check["engine-dmo check<br/>ids, fields, rules, templates"]
  check --> plan["schema plan / apply"]
  plan --> db[("database:<br/>the applied model")]
  db --> admin["admin editor<br/>groups, labels, validation"]
  db --> store["stored values<br/>by field id"]
  store --> tpl["templates:<br/>a typed entry"]
  store --> api["content API, MCP, export"]
```

<Callout title="Both bundles">
Everything in this section works the same in `engine-cms` and `engine-dmo`. The DMO bundle adds two core types, `listing` and `area`, which are extended exactly as the other core types are.
</Callout>

## A worked example [#a-worked-example]

This example adds a `walk` type to a project: a route with a summary, a difficulty, a distance, a start point, stages and an accessibility rule.

<Steps>
<Step>

### Create the type file [#create-the-type-file]

Either write the file by hand or let the engine scaffold it with a template:

```bash
engine-dmo new type walk
```

`new type` writes `config/schema/walk.yaml` with a title, a slug and a summary (ids included), and `templates/_shared/walk/entry.html`. It reads the project's configuration first, so every `${VAR}` in `engine.yaml` without a default must be set, even with no database: `DATABASE_URL=postgres://unused engine-dmo new type walk` is enough when only `DATABASE_URL` is missing. `engine-dmo dev type add walk` writes the same type file without that requirement, but no template. Edit the type file so it reads:

```yaml
# config/schema/walk.yaml
key: walk
label: Walk
plural: Walks
ordering: { field: title, direction: asc }

fields:
  - { name: title, type: text, required: true, index: true }
  - { name: slug, type: slug, source: title, required: true }
  - { name: summary, type: text, multiline: true, max: 280, required: true }
  - name: difficulty
    type: select
    required: true
    index: true
    options:
      - { value: easy, label: { en: Easy } }
      - { value: moderate, label: { en: Moderate } }
      - { value: hard, label: { en: Hard } }
  - { name: distanceKm, type: number, min: 0.1, max: 200, unit: km, index: true }
  - { name: startPoint, type: geo, required: true }
  - { name: heroImage, type: asset }
  - name: stages
    type: repeater
    min: 1
    item_label: "{{ title }}"
    fields:
      - { name: title, type: text, required: true }
      - { name: directions, type: portable_text, styles: [normal], lists: [bullet], marks: [strong, em] }
  - { name: isAccessible, type: boolean, index: true }
  - { name: accessibility, type: portable_text, styles: [normal], marks: [strong, em, link] }

validation:
  - rule: "isAccessible == false or accessibility != empty"
    message: Describe the surfaces and gradients before marking the walk accessible.
    fields: [accessibility]
```

</Step>
<Step>

### Give it an address [#give-it-an-address]

A type has pages only where a site routes it. Add a route to the site's `routes.yaml`:

```yaml
# config/sites/main/routes.yaml
routes:
  - { type: walk, uri: "/walks/{slug}" }
```

See [Sites, locales and routes](/concepts/sites-locales-and-routes) for every route option.

</Step>
<Step>

### Write the ids [#write-the-ids]

Every type, field, block, select option and group carries a stable id. You never write one by hand: `check --fix` writes an id for every element that has none, keeping your comments and layout, then checks the project.

```bash
engine-dmo check --fix
```

After it runs, each element in the file has an `id:` such as `typ_vydpz07cy9` or `fld_0c6c697g4f`. Commit them with the file. An element without an id is an error (`field "stages" has no id`), so a project never reaches the database half identified. Ids are what let you rename a field later without losing its values: see [Schema changes](/content-modelling/schema-changes).

</Step>
<Step>

### Write the template [#write-the-template]

`templates/_shared/walk/entry.html` renders one walk. Each field is a property of `entry`:

```jinja
{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ entry.title }}</h1>
  {% if entry.heroImage %}{{ entry.heroImage.figure("hero", priority=true) }}{% endif %}
  <p>{{ entry.summary }}</p>
  <dl>
    <dt>Difficulty</dt><dd>{{ entry.difficulty.label }}</dd>
    {% if entry.distanceKm %}<dt>Distance</dt><dd>{{ entry.distanceKm }} km</dd>{% endif %}
  </dl>
  <ol>
    {% for stage in entry.stages %}
    <li>
      <h2>{{ stage.title }}</h2>
      {{ stage.directions|ptext }}
    </li>
    {% endfor %}
  </ol>
  {% if entry.isAccessible %}<section><h2>Accessibility</h2>{{ entry.accessibility|ptext }}</section>{% endif %}
</article>
{% endblock %}
```

`hero` is a transform declared in `config/images.yaml` ([Images](/templates/images)). `engine-dmo check` type-checks the template against the schema, so `{{ entry.difficultee }}` fails with `entry has no field "difficultee" in this project's schema` and a suggestion.

</Step>
<Step>

### Check, plan and apply [#check-plan-and-apply]

```bash
engine-dmo check
engine-dmo schema plan
engine-dmo schema apply
```

`check` validates the configuration and templates and needs no database with `--no-db`. Read every line it prints: its closing summary (`0 errors, 0 warnings`) counts configuration problems only, so a template warning printed above it, such as the starter layout's `this head has no head()`, is not in the count and does not change the exit code. `schema plan` prints what will change in the database (`+ type walk`, `+ field walk.title`, and so on) and exits with code 2 while changes are pending. `schema apply` applies them in one transaction. Both need a reachable database in `DATABASE_URL`; [Schema changes](/content-modelling/schema-changes) says what apply does with each kind of change. Under `engine-dmo dev up`, the development server does the check, plan and safe apply on every save.

</Step>
<Step>

### Add content [#add-content]

Editors now see Walks in the admin. To create content from the command line or a seed set, see [Seeding and importing](/content-modelling/seeding-and-importing).

</Step>
</Steps>

## Where type files live [#where-type-files-live]

| Location | What it holds |
|---|---|
| `config/schema/*.yaml` | Shared types, on every site unless the type says `sites:`. Files are read at any depth, so `config/schema/walk/fields.yaml` and `config/schema/walk/validation.yaml` can together declare one type. |
| `config/schema/_shared.yaml` | Field groups that several types include with `- use: <name>` ([Fields](/content-modelling/fields)). |
| `config/blocks/_index.yaml` | Blocks that several `blocks` fields include with `- use: <key>` ([Blocks and rich text](/content-modelling/blocks-and-rich-text)). |
| `config/sites/<site>/schema/*.yaml` | A site's own types, and fields a site adds to a shared type ([Content types](/content-modelling/types)). |

Files whose names start with `_` or `.` are not type files. Each file declares exactly one of `key:` (a custom type) or `extends:` (a core type, or from a site's directory a shared custom type).

## Core types [#core-types]

Some types are built in. Their core fields cannot be removed or retyped, but you add fields to them with `extends:`.

| Type | Bundle | Core fields (required ones in bold) |
|---|---|---|
| `page` | both | **`title`**, **`slug`** |
| `article` | both | **`title`**, **`slug`**, `summary` (max 280), **`publishedAt`**, **`body`** |
| `event` | both | **`title`**, **`slug`**, `summary` (max 280), **`occurrences`** (recurrence), **`location`** (geo) |
| `guide` | both | **`title`**, **`slug`**, `summary` (max 280), **`items`** (a repeater of a `document` relation and a `note`) |
| `collection` | both | **`title`**, **`slug`**, `summary` (max 280), **`smartList`** (a relation to a public smart list) |
| `listing` | engine-dmo | **`title`**, **`slug`**, **`summary`** (max 280), **`location`** (geo), **`primaryTag`** (a tag relation, two levels deep) |
| `area` | engine-dmo | **`title`**, **`slug`**, `summary` (max 280), **`boundary`** (geo_shape), `centre` (geo) |

The core `page` type has no summary and no body: a page you can write an About page in needs fields added with `extends: page` ([Extending page](/content-modelling/types#extending-page)). Until then `head()` has no description to print for a page.

Run `engine-dmo describe type <key>` to see any type's fields with their ids (for a core type it lists the core fields above plus the ones your files add), and `engine-dmo describe project` to list every type.

## Tools for working on the model [#tools-for-working-on-the-model]

| Command | What it does |
|---|---|
| `engine-dmo describe fieldtypes` | Every field type, what it stores, its parameters and its default translate mode. `--json` for a machine-readable copy. |
| `engine-dmo describe type <key>` | One type's fields at every depth, with ids, parameters, blocks, options and groups. |
| `engine-dmo config schema --write .meridian/schema` | JSON Schemas of every configuration file, so an editor completes and checks type files as you type. `engine-dmo init` writes them for you. |
| `engine-dmo new type <key>` | A type file and its entry template. Needs every `${VAR}` of `engine.yaml` set. |
| `engine-dmo dev type add <key>` | A type file with a title, slug and summary, ids included, and no template; `--sites` or `--site` places it. Runs without a database or `DATABASE_URL`. |
| `engine-dmo dev field add\|set\|rename\|remove` | Edit a field in place with its id, keeping comments; `--dry-run` prints the diff ([Schema changes](/content-modelling/schema-changes)). |
| `engine-dmo check --fix` | Write missing ids, then check. |

## Next [#next]

<Cards>
  <Card title="Content types" href="/content-modelling/types" />
  <Card title="Fields" href="/content-modelling/fields" />
  <Card title="Validation" href="/content-modelling/validation" />
  <Card title="Schema changes" href="/content-modelling/schema-changes" />
</Cards>


# Localisation (/content-modelling/localisation)

How fields are translated: the translate modes (none, locale, language, group), the shared skeleton and per-locale leaves of repeaters, blocks, links and assets, structure per_locale, and field fallback on the public site.

A document exists once and holds a version of its content per locale. The schema decides, field by field, what is translated and what is shared, so a translator never retypes a phone number and an editor never rebuilds a page body eleven times.

Locales, the source locale, fallback chains and the locales each site enables are configured in `config/locales.yaml` and each site's `site.yaml` ([Sites, locales and routes](/concepts/sites-locales-and-routes)).

## Translate modes [#translate-modes]

`translate:` sets how many values a field has across locales:

| Mode | One value per | Typical fields |
|---|---|---|
| `none` | document | Coordinates, relations, numbers, dates, opening hours, prices, select choices |
| `locale` | locale | Titles, prose, summaries, slugs, SEO copy, link text, alt text |
| `language` | language, ignoring region | Copy shared by `en-GB` and `en-IE`, by `fr-FR` and `fr-CA` |
| `group` | locale group | A market-level fact: a regional phone line, a disclaimer per market |

Each field type has a default: `text`, `slug`, `portable_text`, `asset`, `link`, `video`, `seo`, `repeater` and `blocks` are `locale`; every other type is `none` (see the table on [Fields](/content-modelling/fields)). `translatable: true` and `translatable: false` are shorthand for `locale` and `none`.

```yaml
fields:
  - { name: title, type: text }                                  # locale, the default
  - { name: phone, type: phone }                                 # none, the default
  - { name: legalNotice, type: portable_text, translate: language }
  - { name: helpline, type: phone, translate: group }
```

`engine-dmo check` warns when a field whose type defaults to `none` is given another mode (`a number field is rarely translated`), and when a rich text field is given `translate: none` (`cannot be translated at all`).

**Language** takes the language subtag of the locale code: `en-GB` and `en-IE` share the `en` value.

**Group** takes the locale's group from `config/locales.yaml`. A locale may be in one group only:

```yaml
# config/locales.yaml
locales:
  available:
    - { code: en-GB, label: English (UK), source: true, default: true, timezone: Europe/London, currency: GBP }
    - { code: en-IE, label: English (Ireland), timezone: Europe/Dublin, currency: EUR }
    - { code: fr-FR, label: Français, timezone: Europe/Paris, currency: EUR }
  groups:
    - { key: uk-ie, locales: [en-GB, en-IE] }
```

Values in `none`, `language` and `group` modes are held in the document's shared revision chain, so they change in every locale at once and an editor can change them from any locale.

## The shared skeleton and per-locale leaves [#the-shared-skeleton-and-per-locale-leaves]

A repeater, a blocks field, a link, an asset and a video are split in two:

- **The skeleton** is shared by every locale: which items exist, in what order, of which block type, and their untranslated values (a relation, a number, an image choice, a link's target, a video's id).
- **The leaves** are each locale's own: the translated values inside each item (headings, text, captions, alt text, link text, a video's title and transcript), keyed by the item's `_key`.

Here is one walk in two locales, with a repeater of stages and a hero image:

```mermaid
flowchart TB
  subgraph shared["Skeleton, shared by every locale"]
    sk1["stages: s1, s2 in this order"]
    sk2["heroImage: asset red-kite.jpg<br/>with its focal point"]
    sk3["difficulty: moderate<br/>(translate: none)"]
  end
  subgraph en["en leaves"]
    en1["s1.title, s2.title"]
    en2["heroImage alt, caption"]
  end
  subgraph cy["cy leaves"]
    cy1["s1.title, s2.title"]
    cy2["heroImage alt, caption"]
  end
  shared --> enpage["the en page"]
  en --> enpage
  shared --> cypage["the cy page"]
  cy --> cypage
```

So adding a block in the source locale adds it to every locale's draft at once, reordering reorders everywhere, and removing removes everywhere. A translator fills in the leaves; they never rebuild the structure. The skeleton and each locale's leaves have their own revision history.

```yaml
fields:
  - name: body
    type: blocks
    blocks:
      - key: imageBanner
        fields:
          - { name: image, type: asset }     # the image is skeleton; its alt and caption are leaves
          - { name: caption, type: text }    # a leaf
      - key: listingGrid
        fields:
          - { name: heading, type: text }    # a leaf
          - { name: listings, type: relation, to: [listing], multiple: true }   # skeleton
```

### Links, assets and videos [#links-assets-and-videos]

`engine-dmo describe type` shows a `link`, `asset` or `video` field as `translate locale`, its default mode. That means the field has per-locale leaves, not that each locale picks its own target:

| Field | Shared by every locale (skeleton) | Each locale's own (leaves) |
|---|---|---|
| `asset` | the chosen asset, its focal point, hotspot and crop | `alt`, `caption` |
| `link` | the kind, the target, new tab, `rel`, the suffix, the style | `text`, `title`, `aria_label` |
| `video` | the source, its id, the start, the poster, captions confirmation, duration | `title`, `transcript` |

A value written in any locale carries both parts, and its skeleton part replaces the shared one:

- A locale that writes a different asset (or link target, or video) does not get its own: every locale shows the new one. A seed file whose `cy` block gives `heroImage` a different asset changes the English page too.
- A locale that writes only the leaves, `heroImage: { alt: Llun }`, writes an empty asset into the skeleton, and the document then fails to publish in every locale (`Choose a file from the library`). A locale that writes the field at all repeats the same asset: `heroImage: { asset: red-kite, alt: Barcud coch }`.

For images the simplest rule is to put alt text and captions in the asset's own library record, per locale (a seed asset's `alt: { en: ..., cy: ... }`), and write only `heroImage: { asset: red-kite }` in the source locale. Every locale then shows the library's text in its language. In a seed file a locale that does not write the field starts from the source locale's value, per-use `alt` included, so an English per-use alt would also show on the Welsh page. To let each locale choose its own image, declare the field with `structure: per_locale`, below.

### structure: per_locale [#structure-per_locale]

```yaml
fields:
  - name: marketNotes
    type: repeater
    structure: per_locale
    fields:
      - { name: note, type: text }
```

`structure: per_locale` makes the whole value each locale's own: each locale has its own list of items, in its own order. Use it where the content genuinely differs per market. On a link, asset or video it makes the whole choice each locale's (a different video per language). It contradicts `translate: none`, which `check` warns about.

A single document can hold a field the other way from its schema, for one market-specific page, through an audited per-document override:

```bash
engine-dmo content structure --id <document id> --field body --mode per_locale --reason "Japanese edition has its own programme"
```

`--mode shared` returns it. The override applies to the working revisions and takes effect at the next publish.

### Rich text is whole [#rich-text-is-whole]

A `portable_text` field is translated whole: each locale holds its complete value, because a translator must be free to merge and split sentences. It has no skeleton.

## What the public site shows when a translation is missing [#what-the-public-site-shows-when-a-translation-is-missing]

`fallback:` on a field sets what a locale with no value of its own shows **on the public site**:

| `fallback` | A plain field with no value in this locale | A skeleton item whose leaves are untranslated |
|---|---|---|
| `empty` (the default) | Nothing: the field is left out. | The item is left out. |
| `inherit` | The source locale's value. | The item is shown with the source locale's leaves. |

```yaml
fields:
  - name: items
    type: repeater
    fallback: inherit      # show every item, in the source language where untranslated
    fields:
      - { name: document, type: relation, to: [listing] }
      - { name: note, type: text }
```

An item with no translatable leaves (only skeleton values) is never "untranslated". The admin and previews always show every item and mark what is untranslated, whatever `fallback` says. The core `guide` type's `items` uses `fallback: inherit`, so a translated guide shows every item with the source note until its own is written.

Field fallback is separate from the locale fallback chain, which decides which locale's published document a relation, a link or a navigation item shows when the target is not published in the request locale ([Relations](/content-modelling/relations)).

## Slugs and the home page [#slugs-and-the-home-page]

`slug` is translated by default, so each locale has its own address: `/walks/cherwell-valley` and `/cy/teithiau/taith-dyffryn-cherwell`. The home page is the exception. When a site's `routes.yaml` names it by slug (`home: { type: page, slug: home }`), a document is the home page in a locale only where its slug in that locale is `home`. Give the home document the slug `home` in every locale; a Welsh slug such as `hafan` makes it an ordinary page at `/cy/hafan`, and `/cy/` answers 404. A home page that is a [singleton](/content-modelling/types#singletons) (`home: { type: homepage }`) is the home page whatever its slug.

## Required in which locales [#required-in-which-locales]

`required: true` is checked when publishing in the source locale only, unless `required_in` says otherwise (`all`, or a list of locale codes). See [Validation](/content-modelling/validation#required-fields).

## Labels [#labels]

Every label, help text, option label, block label and validation message in the schema may be a locale map, and `engine-dmo check` reports the enabled locales that have none ([Content types](/content-modelling/types#locale-maps)). These are what editors and, for option labels, visitors read.

## AI drafting [#ai-drafting]

When an AI provider is configured, an editor can ask for a draft translation. `machine_translate: forbid` on a field stops drafting for that field in every locale; a locale's own `machine_translation: forbid` in `config/locales.yaml` stops it for every field in that locale.

## Changing a field's mode later [#changing-a-fields-mode-later]

Changing `translate:` on a field documents already hold moves values between chains and is a destructive change in the schema plan ([Schema changes](/content-modelling/schema-changes)). Choose deliberately at the start.

## Tools [#tools]

| Command | What it shows |
|---|---|
| `engine-dmo locale list` | Codes, the source, groups, fallbacks and coverage. |
| `engine-dmo locale coverage --site <key>` | Translation coverage by type and locale, as data. |
| `engine-dmo locale stale` | What has drifted in a locale since its source changed, by document and field. |
| `engine-dmo locale add <code>` | Seeds drafts of a new locale for the chosen types and creates a translation job. `--dry-run` counts first. |

All need a database.


# Relations (/content-modelling/relations)

The relation field: references from a document to other documents, tags, smart lists, assets, organisations or people, with targets, cardinality, tag filters, publish checks, stored shape, and how templates receive resolved entries.

A `relation` field points at other records by id: a walk's nearby places, an article's related articles, a listing's category tag, a page's featured list. A relation to a document becomes that document's entry in templates, in the visitor's locale, and a target that is not live is left out, so a page never links to nothing.

Use a relation when the template needs the target's fields (its title, image, address). Use a [link](/content-modelling/fields/link) when the editor is making a link with its own text.

```yaml
fields:
  - name: nearbyListings
    type: relation
    to: [listing]
    multiple: true
    max: 12
    index: true

  - { name: relatedArticles, type: relation, to: [article, page], multiple: true, max: 3 }

  - name: theme
    type: relation
    to: tag
    filter: { kind: topic, depth: 1 }

  - { name: featuredList, type: relation, to: smart_list }
```

These four fields, on a `walk` type, give this model. Each line is one relation field, read from the type that declares it; a `multiple` field points at many targets, a single one at one or none:

```mermaid
erDiagram
  walk }o--o{ listing : "nearbyListings (max 12)"
  walk }o--o{ article : "relatedArticles (max 3)"
  walk }o--o{ page : "relatedArticles (max 3)"
  walk }o--o| tag : "theme (topic, depth 1)"
  walk }o--o| smart_list : "featuredList"
  listing }o--|| tag : "primaryTag (core, depth 2)"
```

Relations point one way: a listing does not gain a field when a walk names it. To find the walks that name a listing, query by the relation ([below](#template-value)).

## Parameters [#parameters]

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `to` | a key or a list of keys | required | What may be chosen: document type keys (`listing`, `article`, a custom type), `tag`, `smart_list`, `asset`, and in engine-dmo `organisation` and `person`. |
| `multiple` | boolean | `false` | An ordered list of targets. |
| `min` | whole number | none | The fewest targets, when the field is not empty. Use `required` for "at least one". |
| `max` | whole number | none | The most targets. |
| `filter` | mapping | none | For `to: tag`: `{ kind, depth }` limits the picker to tags of a kind and an exact depth in the vocabulary (depth 1 is a top-level tag). Other targets accept `filter` but do not apply it. |

`engine-dmo check` does not check that the keys in `to` name real types: a misspelt type key gives a field whose picker offers nothing. Check the field in the admin, or with `engine-dmo describe type <key>`.

## What the editor picks from [#what-the-editor-picks-from]

| Target | The picker offers |
|---|---|
| Document types | Documents of those types on the site, in the editing locale, through the reference picker. |
| `tag` | The tag vocabulary as a tree, narrowed by `filter`. |
| `smart_list` | The public document lists of the site. |
| `asset`, `organisation`, `person` | No picker: a plain input that takes the record's id as `type:id`. Prefer an [asset field](/content-modelling/fields/asset) for media. |

## Validation [#validation]

| Code | Message |
|---|---|
| `multiple` | Choose one |
| `max_choices` | Choose 12 or fewer |
| `min_choices` | Choose at least 2 |
| `relation_type` | Must be one of listing |

At publish:

| Code | Severity | When |
|---|---|---|
| `tag` | error | A tag relation names a candidate tag or an unknown key: a candidate must be promoted into the vocabulary before it is published. |
| `relation_unpublished` | warning | A target is not published in this locale or its fallbacks; visitors will not see it. |
| `relation_fallback` | warning | A target is not published in this locale but is in a fallback locale, which visitors see. |
| `relation_missing` | warning | A target is in the trash or no longer exists. |

## Stored value [#stored-value]

```json
{ "id": "5b0c9d7e-...", "type": "listing" }
```

With `multiple`, a list of these in the editor's order. `type` is the target's type key, or `tag`, `smart_list`, `asset`, `organisation` or `person`. A tag and a smart list are named by their key (`{ "id": "eat-drink.brewery", "type": "tag" }`). When `to` names a single target, `type` may be left out of an imported or seeded value.

In a seed file, a document is named by its seed key and type, `{ id: hook-norton-brewery-tours, type: listing }` ([Seeding and importing](/content-modelling/seeding-and-importing)).

Every relation to a document is recorded as a reference, whether or not the field is indexed, which is how the engine knows what points at a document. With `index: true`, the targets are also projected (documents by id, tags and smart lists by key), so lists and `query()` can filter by them.

## Template value [#template-value]

A relation to a document becomes the target's entry: its fields, `title`, `uri`, `url` and the rest, as the target's own page would see it. `uri` is the target's path on this site with the locale prefix, and `url` the same address made absolute; link with `uri|url`, and keep `url` for addresses that must be absolute (a feed, an email). Both are empty when the target has no route on the site ([Links and URLs](/templates/links)).

- The entry is the target in the request locale, else in the first locale of the fallback chain where it is published on the site.
- A target that is not live anywhere in the chain, is trashed, or is not on the site is dropped. A single relation becomes nothing; a multiple relation becomes a shorter list.
- The target's own relations resolve when a template reads them, so `entry.nearbyListings[0].primaryTag` works without loading every relation of every target up front.
- Targets that are not documents (`tag`, `smart_list`, `asset`, `organisation`, `person`) arrive as references with `id` and `type`.

```jinja
{% if entry.nearbyListings %}
<h2>Nearby</h2>
<ul>
  {% for place in entry.nearbyListings %}
  <li><a href="{{ place.uri|url }}">{{ place.title }}</a>, {{ place.summary }}</li>
  {% endfor %}
</ul>
{% endif %}
```

To list the documents that point at this one, filter by the relation with `query()`, which needs `index: true` on the field:

```jinja
{% for w in query('walk').where('nearbyListings', entry.id).limit(5).all() %}
  <a href="{{ w.uri|url }}">{{ w.title }}</a>
{% endfor %}
```

See [Globals](/templates/globals) for `query()` and `nearby()`.

## Relations the engine adds [#relations-the-engine-adds]

- **Guides.** The core `guide` type's `items` is a repeater whose `document` relation may point at any type that has a route on some site.
- **Collections.** The core `collection` type's `smartList` is a relation to a public smart list.
- **Nesting.** A type routed with nesting carries a `parent` relation to its own type ([Sites, locales and routes](/concepts/sites-locales-and-routes)); templates read `entry.ancestors` and `entry.children`.
- **engine-dmo.** A listing's `primaryTag` is a relation to a topic tag at depth 2 (`filter: { kind: topic, depth: 2 }`), and listings belong to an organisation through the CRM, not a relation field ([Partners and the portal](/dmo/partners-and-portal)).


# Schema changes (/content-modelling/schema-changes)

How a change to the type files reaches the database: schema plan and schema apply, what is destructive and how to approve it, renames by id with aliases, removed fields kept under _orphaned, retyping and coercion, reprojection, and what apply refuses.

The type files are the source of truth; the database follows them. You never write a migration for a content change. Instead the engine compares the files with what the database last applied and shows you a plan; applying it changes the database's record of the model in one transaction. Stored content is never rewritten or deleted by a schema change: a value a change cannot carry is kept and flagged.

## The loop [#the-loop]

```bash
engine-dmo check --fix     # write ids for new elements, then validate
engine-dmo schema plan     # what would change; exit code 2 while changes are pending
engine-dmo schema apply    # apply it in one transaction
```

`check` needs no database (`--no-db` skips the checks that do). `schema plan` and `schema apply` need a reachable database in `DATABASE_URL`. Every command that loads the configuration, `check --no-db` aside, also needs each `${VAR}` in `engine.yaml` without a default to be set, and the engine does not read a `.env` file: export them in the shell. Once `engine.yaml` has `signing_key: ${SIGNING_KEY}` for production, set a development `SIGNING_KEY` of at least 32 characters locally too, or those commands fail with `server.security.signing_key must be at least 32 characters`.

The `dev field` verbs (`add`, `set`, `rename`, `remove`) run without a database or `DATABASE_URL`. Each checks the project after its edit and writes nothing when the result would be invalid (`the change would leave the configuration invalid; nothing was written`, exit code 3). That check is `check`'s, so what `check` does not catch, such as a relation `to:` naming a type that does not exist, is written. In development, `engine-dmo dev up` serves the site and, on every change to a file, writes missing ids, checks, plans and applies what is safe, then reloads; `engine-dmo dev status` shows what it last found.

## Reading a plan [#reading-a-plan]

An example plan:

```text
Plan for meridian <version>, project config at config

  + type        walk                             custom, 6 fields
  + field       walk.title                       text
  + field       article.heroImage                asset
  > field       listing.bookingLink              -> bookingUrl; handle only
  ~ field       event.price                      text -> money [no exact coercion for 3 of 41 values]  [DESTRUCTIVE: 3 documents hold a value]
  - field       listing.faxNumber                text; values are kept under _orphaned  [DESTRUCTIVE: 12 documents hold a value]
  ~ type        page                             presentation, validation or routing

Plan: 1 add type, 2 add field, ...
```

| Symbol | Operation |
|---|---|
| `+` | add |
| `~` | change |
| `-` | remove |
| `>` | rename (same id, new handle) |
| `=` | bind (an element taking the id the file gives it) |
| `!` | replace (a handle the file gives a different id) |

Resources include `locale`, `site`, `site_locale`, `type`, `field`, `block`, `option`, `variant`, `singleton` (a site's singleton document apply will create), and the roles, grants and groups of `config/access`. `engine-dmo schema plan --json` prints the changes with `op`, `resource`, `key`, `detail`, `destructive` and `affected`, and the plan's `digest`.

| Exit code | Meaning |
|---|---|
| 0 | No changes: the database matches the configuration. |
| 1 | An error, such as no database. |
| 2 | Changes are pending (plan), or apply refused for want of approval. |
| 3 | The configuration is invalid. |

## What apply does with a plan [#what-apply-does-with-a-plan]

```mermaid
flowchart TD
  start["engine-dmo schema apply"] --> valid{"configuration valid?"}
  valid -- no --> exit3["refused, exit 3"]
  valid -- yes --> diff{"any changes?"}
  diff -- no --> done0["nothing to do, exit 0"]
  diff -- yes --> outright{"handle reused under another id,<br/>a lockout, or NOT YET?"}
  outright -- yes --> refuse["refused: fix the files<br/>or pass --replace"]
  outright -- no --> destr{"destructive?"}
  destr -- no --> apply["applied in one transaction"]
  destr -- yes --> approved{"approval file digest matches,<br/>or --allow-destructive confirmed?"}
  approved -- yes --> apply
  approved -- no --> exit2["refused, exit 2"]
```

## What is destructive [#what-is-destructive]

A change is destructive when documents hold values it affects. The plan counts them (`[DESTRUCTIVE: 12 documents hold a value]`); the same change with no values affected is not destructive.

| Change | Destructive when |
|---|---|
| Remove a type | documents of it exist (trashed ones aside) |
| Remove a field, or a child field of a repeater or block | documents hold a value; always, if the field is `protected` |
| Remove a block from a `blocks` field | documents hold items of it ("items stay in the revisions") |
| Remove a select option | documents hold it |
| Retype a field (`text` to `money`) | some values have no exact coercion to the new type |
| `multiple: true` to single | documents hold more than one value |
| Change `translate:` | documents hold values (they move between the shared and per-locale chains) |
| Any storage change to a `protected` field | always |
| Remove a locale or a site | content is published in it |
| A grant change that takes a permission from active users | always (counted in users) |

Never destructive: adding a type, field, block, option or variant; a rename; labels, help, groups, validation rules, `visible_when`, ordering and templates (shown as `presentation, validation or routing`); turning `index` on or off (a reprojection job).

## Approving a destructive plan [#approving-a-destructive-plan]

`schema apply` refuses a destructive plan unless it is approved, in one of two ways:

- **Interactively:** `engine-dmo schema apply --allow-destructive` prints the plan and asks you to confirm on the terminal. In a script with no terminal, add `--yes`.
- **By file:** write the plan's digest (printed at the end of a destructive plan, and as `digest` in `--json`) to `config/schema/.destructive-approved` and commit it. Apply then accepts exactly that plan; any other plan is refused. The path is `schema.destructive_approval` in `engine.yaml`.

A refused apply prints the plan and `refused: write the digest above to config/schema/.destructive-approved, or pass --allow-destructive`, and exits with code 2.

## What apply refuses outright [#what-apply-refuses-outright]

| Refusal | Why | What to do |
|---|---|---|
| A handle reused under a different id | Usually a block or field copied with its `id:`; the file says one element, the database another | Put the stored id back to keep the element, or apply with `--replace <type.field>` for each to replace it. |
| A lockout | The access change would leave nobody able to manage users or holding the owner role | Change `config/access` so someone active still does. |
| `NOT YET: ...` | A change this build plans but cannot apply yet | Undo it in the files to apply the rest. |

Apply recomputes the plan inside its transaction under a lock, so two applies at once cannot double up. Every apply, refused or not, is recorded in the audit log.

## Renaming by id [#renaming-by-id]

Every type, field, block, option, group and variant has an `id:` in the file. The database keys content by those ids, so a handle is free to change: rename a field by changing its `name:` and keeping its `id:`. The plan shows `> field listing.bookingLink -> bookingUrl; handle only` and no stored value moves.

Templates and API clients may still use the old handle. Keep it answering, with a warning, by adding it to `aliases`:

```yaml
fields:
  - { name: bookingUrl, id: fld_7s2kq9m4xd, aliases: [bookingLink], type: link, kinds: [{ of: url }] }
```

`engine-dmo dev field rename` does all of this, and rewrites validation rules that name the field:

```bash
engine-dmo dev field rename listing bookingLink bookingUrl --dry-run   # print the diff
engine-dmo dev field rename listing bookingLink bookingUrl              # write it, keeping bookingLink as an alias
engine-dmo dev field rename listing bookingLink bookingUrl --no-alias   # or without an alias
```

When nothing uses the old handle any more, retire the alias:

```bash
engine-dmo schema alias list
engine-dmo schema alias retire listing.bookingLink
```

`retire` is refused while a template still uses the alias. A handle cannot be both an alias and a field: retire the alias before a new field takes the name. Renaming a select option's `value`, a block's `key` or a type's `key` works the same way: keep the `id:`.

If you remove an element's `id:` and run `check --fix`, it gets a new id and the plan treats it as a new element, not a rename. An id written on two elements fails `check`: `id fld_... is written on two elements: field "endDate" here and field "startDate" at ...`.

## Removing a field [#removing-a-field]

```bash
engine-dmo dev field remove listing faxNumber --dry-run
```

Removing a field never deletes data. Each document's value stays in its revisions under `_orphaned`, keyed by the field's id. In the admin, the editor's advanced issues panel lists a document's orphaned values and can recover one into an empty field of a compatible type, including a field re-added later with the same `id:`. `dev field remove` refuses while a validation rule or another element still names the field.

Removing a block keeps its items in the revisions too; switching a document's [variant](/content-modelling/types#variants) sets aside the fields the new variant lacks in the same way.

## Retyping a field [#retyping-a-field]

Changing a field's `type:` keeps its id, and the plan counts the values that have no exact coercion to the new type. Values are never converted in the database: each is read through the new type, and one that does not fit is kept as it was and reported to the editor, who can fix it.

| From | To | Coercion |
|---|---|---|
| `text`, `slug` | `text`, `slug` | exact |
| `select`, `text` | `select` | exact when the value is an option, otherwise kept and flagged |
| `portable_text` | `text` | lossy: the plain text |
| `text`, `select`, `slug` (numeric) | `number` | exact |
| `boolean` | `number` | lossy: 1 or 0 |
| `text`, `select` (`yes`, `no`, `true`, `false`, `1`, `0`, `on`, `off`), `number` | `boolean` | lossy |
| `text` (an ISO date) | `date` | exact |
| `datetime` | `date` | lossy: the local day |
| `date` | `datetime` | lossy: midnight, all day |
| `text` (an RFC 3339 instant) | `datetime` | exact |
| `number`, `text` | `money` | lossy |
| `text` (a URL, `mailto:`, `tel:`, an email address, a `+` number) | `link` | lossy |
| `link` | `link` | exact when the new field offers the kind |
| `repeater` to `repeater`, `blocks` to `blocks` | | child fields reconciled one by one |

Everything else is impossible: the value is kept and flagged. Restoring an old revision written under an earlier schema runs the same reconciliation and shows the editor a preview, field by field (carried, coerced, needs attention, orphaned, added).

## Reprojection [#reprojection]

When a change alters what is projected for queries (a field retyped, removed, indexed or unindexed, moved between chains, or an option removed), apply queues a reprojection job per type, which runs after the commit and resumes where it stopped. To run one by hand:

```bash
engine-dmo content reproject --type listing
```

## Applying on start [#applying-on-start]

When the server starts, it compares the files with the database. `schema.on_drift` in `engine.yaml` decides what happens when they differ:

| `on_drift` | On start with pending changes |
|---|---|
| `refuse` (the default) | The server does not start; run `schema apply` as a deploy step. |
| `apply` | Applies the plan. A destructive plan is applied only with an approval file whose digest matches; otherwise the server does not start. |
| `warn` | Applies the plan when it is not destructive. A destructive plan is logged, nothing is applied, and the server starts. |

Run `engine-dmo schema apply` as an explicit deploy step after `engine-dmo migrate up` ([Deploying](/deploying)).


# Seeding and importing (/content-modelling/seeding-and-importing)

Getting content into a project: seed sets (seed.yaml, documents per type and locale, assets, history and publishing states, references by seed key, verify, apply and reset), generated content, content create and update, and JSON export and import between environments.

There are four ways to put content into a project without typing it into the admin:

| Way | Use it for | Goes through |
|---|---|---|
| A seed set (`seed/`) | Development and demonstration content kept in the repository, applied to an empty database | The same validation, revisions and publish checks as an editor |
| `engine-dmo seed generate` | Many plausible documents of a type, for testing lists, search and performance | Each field's validation |
| `engine-dmo content create` and `content update` | A document or a change from a script | The admin's save checks, and the publish checks with `--publish` |
| `engine-dmo content export` and `content import` | Moving drafts between environments or through a spreadsheet-like round trip | The content store, as drafts, never published |

All of them write values in the stored shapes each field type's page describes. For moving a whole existing site from another CMS, see [Migration](/integrating/migration).

## Seed sets [#seed-sets]

A seed set is a directory, `seed/` by default, that describes content by key:

<Files>
  <Folder name="seed" defaultOpen>
    <File name="seed.yaml" />
    <Folder name="documents" defaultOpen>
      <Folder name="page">
        <File name="home.yaml" />
      </Folder>
      <Folder name="walk">
        <File name="cherwell-valley.yaml" />
      </Folder>
    </Folder>
    <Folder name="assets">
      <File name="valley-view.jpg" />
      <File name="valley-view.yaml" />
    </Folder>
    <Folder name="users">
      <File name="editor.yaml" />
    </Folder>
    <Folder name="navigation">
      <File name="main.yaml" />
    </Folder>
  </Folder>
</Files>

A project may hold several sets, as `seed/<name>/`, chosen with `--set <name>`.

### seed.yaml [#seedyaml]

```yaml
name: starter
description: The home page and three walks.
locales: [en-GB, cy-GB]
analytics:
  months: 13
  daily_views: 6
  seed: 42
profiles:
  core: [page/*, walk/cherwell-valley]
```

| Key | What it does |
|---|---|
| `name`, `description` | Shown by `seed list`. |
| `locales` | The locales the generated analytics cover. It does not limit the documents: a document may hold any locale the project configures. Add a new locale here when you add it to the project, so its pages get analytics too. |
| `schema_digest` | The schema digest the set was written against. When it differs from the current schema, apply warns and reconciles values as a restore would. Leave it out to accept any. |
| `analytics` | `months` of generated page-view history, `daily_views` per document at weight 1, a `seed` for the generator, `searches` (visitor queries, each with `site`, `locale`, `query`, `weight`, `results`) and `search_days` (default 120). Leave it out for none. |
| `profiles` | Named subsets: each a list of records as `kind/key`, with `*` patterns (`walk/*`, `organisation/harbour-*`). Applying a profile applies those records and everything they name. `profiles/*.yaml` add to the list. |
| `library` | A shared media library to import photographs from by name: `dir` (relative to the set), and `photos`, `categories` and `videos` to import. |

### A document [#a-document]

`documents/<type>/<key>.yaml`. The folder is the type and the file name the key, unless the file says `type:` or `key:`.

```yaml
# seed/documents/walk/cherwell-valley.yaml
site: main
locales:
  en-GB:
    title: The Cherwell valley walk
    slug: cherwell-valley-walk
    summary: Eight miles along the river and the canal, with a pub at the halfway point.
    difficulty: moderate
    distanceKm: 12.8
    startPoint: { lat: 52.0629, lon: -1.3398, precision: street }
    heroImage: { asset: valley-view }
    nearbyListings:
      - { id: hook-norton-brewery-tours, type: listing }
    stages:
      - _key: s1
        title: Banbury to Kings Sutton
        directions:
          - _type: block
            _key: s1p1
            style: normal
            markDefs: []
            children:
              - { _type: span, _key: s1p1s0, text: "Leave the town by the towpath.", marks: [] }
  cy-GB:
    title: Taith dyffryn Cherwell
    slug: taith-dyffryn-cherwell
    summary: Wyth milltir ar hyd yr afon a'r gamlas.
    stages:
      - _key: s1
        title: Banbury i Kings Sutton
publish: [en-GB, cy-GB]
tags: [walks.riverside]
history:
  - locale: en-GB
    note: First draft
    fields:
      title: Cherwell walk
      summary: A riverside walk.
```

| Key | What it does |
|---|---|
| `type`, `key` | The type and the seed key; default the folder and file name. |
| `site` | The owner site; the default site when left out. |
| `sites` | Other sites the document is shared to. |
| `variant` | The [variant](/content-modelling/types#variants) the document is created in. |
| `locales` | The field values per locale code, by field name, in each field's stored shape. The source locale is required (`no en-GB content (the source locale)` otherwise) and is written first. Every other locale starts from the source locale's values and replaces the ones it gives, so shared values (`translate: none`, a container's items) need only be written once; for a repeater or blocks field, a locale repeats the items with the same `_key`s and its own text. An asset, link or video field written in another locale replaces the shared choice for every locale, so repeat the same asset or leave the field out ([Links, assets and videos](/content-modelling/localisation#links-assets-and-videos)). |
| `publish` | The locales to publish, through every publish check. Left out, the document stays a draft. |
| `history` | Earlier states, applied before `locales` as revisions with a `note`, so the document has a history to compare and restore. |
| `pending` | A later working revision per locale, saved after publishing and not published: changes waiting. |
| `review` | Locales whose working revision is sent to the review queue. |
| `schedule` | Per locale, a time to publish at (the document waits until the scheduler runs). |
| `unpublish_at` | Per locale, a time to take it down. |
| `trash` | Puts the document in the trash once everything else is done. |
| `tags` | Vocabulary tag keys applied to the document. |
| `weight` | Popularity for the generated analytics, default 1. |
| `overrides` | Per-site values of `site_overridable` fields: site, then field, then a locale map for a translated field or the value itself. |
| `organisation`, `landing`, `partner`, `partner_edits` | engine-dmo: the organisation a listing belongs to, a landing page it is the content of, and partner-made changes ([Partners and the portal](/dmo/partners-and-portal)). |

Dates and times in `schedule`, `unpublish_at` and date-valued fields may be absolute (`2026-03-01`, `2026-03-01T09:30`) or relative to the day of applying (`+21d`, `-6m`, `+3d 09:00`), so a demonstration stays current.

A document of a [singleton](/content-modelling/types#singletons) type fills in its site's singleton rather than creating a second one.

The home page named by `home: { type: page, slug: home }` keeps the slug `home` in every locale: give the Welsh block `slug: home`, not a translated slug, or `/cy/` answers 404 ([Slugs and the home page](/content-modelling/localisation#slugs-and-the-home-page)).

### References by key [#references-by-key]

A seed never contains a database id (the UUID a record receives when it is created). Records name each other by seed key, in the shapes the fields store. Configuration ids are not database ids and are allowed: a [form field](/content-modelling/fields/form) is seeded with its endpoint's id from `endpoints.yaml`, `contactForm: end_srhmvkf6j3`.

| Field | In a seed |
|---|---|
| `relation` to a document | `{ id: <seed key>, type: <type> }` |
| `relation` to a tag or smart list | `{ id: <tag or list key>, type: tag }` (a vocabulary key, not a seed record) |
| `asset`, a video's `poster` | `{ asset: <seed key> }`, or just `<seed key>` |
| `link` to a document | `{ of: document, document: <type>/<seed key> }` |
| `link` to an asset | `{ of: asset, asset: <seed key> }` |
| a rich text link | the same, as the link mark's definition |

Apply creates records in dependency order and replaces each key with the id the record received. Two documents that name each other are both created, then completed.

### Assets [#assets]

Each asset is a file and a YAML file of the same name beside it under `assets/`, at any depth. Files may be `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.pdf`, `.svg` or `.gpx`. They go through the same upload pipeline as an editor's upload.

```yaml
# seed/assets/valley-view.yaml
title: The Cherwell valley from Crouch Hill
alt: { en-GB: Fields and hedgerows falling to the river under a wide sky, cy-GB: Caeau a gwrychoedd yn disgyn i'r afon }
caption: { en-GB: Looking south from Crouch Hill }
credit: Photograph by A. Walker
focal: { x: 0.5, y: 0.4 }
tags: [walks.riverside]
rights:
  holder: A. Walker
  licence: CC BY 4.0
  until: +2y
```

| Key | What it does |
|---|---|
| `key` | The seed key; default the file name. |
| `file` | The file, relative to the YAML's folder; default the file of the same name. |
| `title`, `alt`, `caption`, `decorative` | The library's title, alt text and caption per locale, and whether the image is decorative. |
| `credit`, `licence`, `licence_url`, `author`, `source`, `rights` | The credit line and rights record (`rights` takes `holder`, `licence`, `credit`, `source`, `licence_url`, `from`, `until`, `uses`, `territory`). |
| `focal`, `hotspot`, `crop` | The asset's own framing, as fractions. |
| `sites` | Per-site alt text and captions: site, then `alt` and `caption` maps. |
| `tags` | Vocabulary tag keys. |

### Other records [#other-records]

| Directory | Holds |
|---|---|
| `users/` | Development staff users: `email`, `name`, `groups`, `password`, `totp_secret`. Never created in production. |
| `navigation/` | Navigation sets: `key`, `site`, `slot`, `name`, `assigned`, and `items`, each with a `label` map and one of `document` (`<type>/<key>`), `asset`, `url` or `index`, an optional `suffix`, and `children`. |
| `organisations/`, `people/` | engine-dmo: CRM records with contacts, memberships and invitations ([below](#organisations-and-people)). |

Modules add their own directories in engine-dmo (claims, promotions, affiliates and others); see each module's page under [DMO](/dmo).

### Organisations and people [#organisations-and-people]

<Callout title="engine-dmo">These records are part of the DMO bundle (engine-dmo).</Callout>

`organisations/<key>.yaml` is a business, and `people/<key>.yaml` someone in the CRM in their own right. The file name is the key a document names with its top-level `organisation: <key>`, unless the file says `key:`. Both go through the CRM store, so a seeded record is validated as a saved one is. An unknown key in these files is ignored, not refused, so check the result with `seed apply`'s summary (`1 organisations, 2 people, 1 memberships`).

```yaml
# seed/organisations/old-bridge-inn.yaml
name: The Old Bridge Inn
legal_name: Old Bridge Inn Ltd
status: active
email: stay@oldbridgeinn.example
website: https://oldbridgeinn.example
phone: { raw: "01600 712345", region: GB }
address:
  country: GB
  line1: 4 Wye Bridge Street
  locality: Monmouth
  postal_code: NP25 3DY
tags: [stay.hotel]
contacts:
  - name: Sam Owner
    email: sam@oldbridgeinn.example
    role: General manager
    partner_role: owner
    is_primary: true
    started_on: -2y
  - person: pat-morgan
    role: Bookkeeper
memberships:
  - site: main
    tier: standard
    joined_on: -2y
    renews_on: +30d
    amount: "120.00"
    currency: GBP
    history:
      - { tier: gold, amount: "240.00", reason: Upgraded at the spring trade fair }
invitations:
  - email: alex@oldbridgeinn.example
    name: Alex Colleague
    role: Duty manager
    partner_role: contact
    site: main
    by: sam@oldbridgeinn.example
```

```yaml
# seed/people/pat-morgan.yaml
name: Pat Morgan
email: pat@example.org
marketing_consent: -1y
tags: [press]
```

An organisation:

| Key | What it does |
|---|---|
| `key` | The seed key; default the file name. |
| `name` | Required. |
| `legal_name`, `email`, `website` | As on the organisation's page. |
| `status` | `prospect`, `active` (the default), `lapsed` or `archived`. |
| `phone`, `address` | Maps, stored as given. |
| `custom` | The fields of `config/crm/organisation.yaml`, by handle. |
| `tags` | Vocabulary tag keys. |
| `network` | The network's key. Default: the network of the first membership's site, else the default site's. |
| `contacts`, `memberships`, `invitations` | The lists below. |
| `trash` | Puts the record in the trash once everything else is done. |

A contact is a person linked to the organisation. Each needs `person` or `name`.

| Key | What it does |
|---|---|
| `person` | A `people/` key or the email of a contact seeded earlier, for someone linked to more than one organisation. Without it the person is created from `name`, `email`, `phone` and `custom`. |
| `name`, `email`, `phone`, `custom` | The new person's details. |
| `role` | The job title, free text. |
| `partner_role` | The partner role by key, such as `owner` or `contact` (the default). See [partner roles](/dmo/partners-and-portal). |
| `is_primary` | The organisation's primary contact. |
| `started_on`, `ended_on` | Dates. `ended_on` makes a former contact. |

A membership is one organisation's tier on one site. It needs the memberships module and tiers in `config/memberships.yaml`.

| Key | What it does |
|---|---|
| `site`, `tier` | The site's key (default the default site) and the tier's key. |
| `status` | `pending`, `active` (the default), `lapsed` or `cancelled`. |
| `joined_on`, `renews_on`, `ended_on` | Dates. |
| `amount`, `currency`, `external_ref`, `notes` | The fee, as a quoted string, its currency, your own reference and staff notes. |
| `history` | Later changes, applied in order after the membership starts, which is what the churn and growth figures read. Each may set `tier`, `status`, `renews_on`, `ended_on`, `amount` and `reason`. So the membership's own keys are its first state. |

An invitation is someone asked to join the portal, sent through the portal itself, after the documents.

| Key | What it does |
|---|---|
| `email`, `name`, `role`, `partner_role` | Who is invited, their job title and their role. |
| `site` | The site. Default the default site. |
| `by` | Required: who invites them, by `people/` key or a contact's email. They must hold `people.invite`, as an `owner` does, or the apply stops. |
| `accepted` | The invitation is accepted at once, which makes the person a contact too. |

A person:

| Key | What it does |
|---|---|
| `key` | The seed key; default the file name. |
| `name`, or `given_name` and `family_name` | The display name, or the two parts it is made from. |
| `email`, `phone`, `custom`, `tags` | Their details, the fields of `config/crm/person.yaml` by handle, and vocabulary tag keys. |
| `marketing_consent` | When they consented to marketing. Left out, they have not. |
| `network` | The network's key. Default the default site's. |
| `trash` | Puts the record in the trash once everything else is done. |

Dates may be absolute or relative to the day of applying, as for documents. `seed verify` checks that a `person` and a document's `organisation` name a record in the set, that each date reads and that each site exists; it does not check `tier` or `partner_role`, which only `seed apply` does.

### Commands [#commands]

| Command | What it does | Needs a database |
|---|---|---|
| `engine-dmo seed list` | The sets and what each holds. | no |
| `engine-dmo seed verify [--set] [--profile]` | Checks the set loads and matches the current schema: every type, field, locale and site exists, every record a record names is in the set (navigation items included), every navigation slot is declared, every date reads. It does not check field values ([below](#what-seed-verify-does-not-check)). The check to run in CI after a schema change. | no |
| `engine-dmo seed apply [--set] [--profile] [--scale small\|medium\|large] [--timeout 30m]` | Applies the set through the same validation and revision machinery as an editor: vocabulary, assets, users, people, organisations, documents, navigation, then generated analytics. | yes |
| `engine-dmo seed reset --confirm` | Removes all content, media and analytics, keeping users and configuration. Never runs in production. | yes |
| `engine-dmo seed write [--check]` | Writes generated seed files from `seed/generate.yaml`; `--check` exits with code 3 when the files differ. | no |

`seed verify` and `seed write` never connect, but they load the configuration first, and every `${VAR}` in `engine.yaml` without a default must then be set. With no database, set `DATABASE_URL` to any value. Once `engine.yaml` reads `signing_key: ${SIGNING_KEY}`, set `SIGNING_KEY` too, to a development value of at least 32 characters (`server.security.signing_key must be at least 32 characters` otherwise), and likewise any other secret such as an SMTP password. The engine does not read a `.env` file; export the variables in the shell or the CI job:

```bash
export DATABASE_URL=postgres://unused SIGNING_KEY=$(openssl rand -hex 32)
engine-dmo seed verify
```

### What seed verify does not check [#what-seed-verify-does-not-check]

`seed verify` checks names, not values. A select value that is not an option (`difficulty: trivial`) or a number below the field's `min` passes it with `Matches the schema`. Values are checked when `seed apply` saves and publishes the document, through the field's validation:

- A document with `publish:` stops the apply at the first value that fails, naming the field: `publish en refused: difficulty: "trivial" is not one of the options`.
- A document without `publish:` is stored as a draft, and a value that would fail publishing is kept without an error. It shows up only when an editor or `content update --publish` publishes it.

`seed verify` reports a problem by file, with no line or column, and reports an unknown field once for each locale block it appears in. Its summary counts documents, assets and users, not navigation sets, though it checks them; `seed apply` reports the navigation it wrote (`navigation: 1 sets, 3 items`).

`seed apply` is not an upsert. It refuses when the database already holds documents or assets (`the database already holds N documents and M assets; run engine-dmo seed reset first`), and in production it refuses unless the database is empty and `--i-know-what-i-am-doing` is given.

A value that fails validation stops the apply with the field named, but what was written before it stays: the records applied earlier, and the failing document itself as a draft. The next `seed apply` then refuses because the database is not empty. Fix the file, then run `engine-dmo seed reset --confirm` and `engine-dmo seed apply` again.

Apply works in this order, each step naming the records of the steps before it by the ids they received. In engine-dmo the modules' own directories (claims, promotions and the rest) are applied after the step they depend on.

```mermaid
flowchart LR
  v["vocabulary"] --> a["assets"] --> u["users"] --> p["people and<br/>organisations<br/>(engine-dmo)"] --> d["documents<br/>history, publish,<br/>pending, schedule"] --> n["navigation"] --> t["invitations,<br/>then trash"] --> g["generated<br/>analytics"]
```

Example output:

```text
seeded starter: 4 documents, 6 revisions, 4 published, 1 assets, 1 users, 1840 analytics events
```

### Generated documents [#generated-documents]

```bash
engine-dmo seed generate --type walk --count 200 --near 52.06,-1.34 --publish
```

Writes documents of a type whose values pass each field's validation, from built-in word lists and placeholder images. `--seed` makes the run repeatable over the same database; `--locale` and `--site` choose where; `--near` places generated points around a latitude and longitude where a field has no `bounds`. A relation field needs documents or tags to point at, so generate the targets first.

`seed/generate.yaml` describes generated seed files as recipes with placeholders (`{pick LIST}`, `{int A B}`, `{point PLACE}`, `{relation RECIPE}`, `{pt NAME N}` and more), written into ordinary seed files by `seed write`. `engine-dmo seed write --help` lists every placeholder.

## Creating and updating from the command line [#creating-and-updating-from-the-command-line]

```bash
engine-dmo content create --type walk --locale en-GB --data '{
  "title": "Bloxham loop",
  "slug": "bloxham-loop",
  "summary": "A short circuit from the village green.",
  "difficulty": "easy",
  "startPoint": { "lat": 52.02, "lon": -1.37 }
}'

engine-dmo content update <document id> --locale cy-GB --data '{ "title": "Cylch Bloxham" }' --publish
```

| Command | Flags |
|---|---|
| `content create` | `--type` (required), `--data` (a JSON object of values by field name, or `-` for standard input; the values may also be the first argument), `--locale` (default the source locale), `--site` (owner site, default the default site), `--publish` |
| `content update <id>` | `--data`, `--locale` (default the source locale), `--publish`. Only the fields given change; `null` clears one. |

Both validate as the admin's save does and refuse on an error. `--publish` then runs the publish checks for that locale. Relations and links name documents and assets by their database ids here. `engine-dmo content get <id>` shows a document's working and published values by field name, and `content list` finds ids. All need a database.

## Export and import between environments [#export-and-import-between-environments]

```bash
engine-dmo content export --type walk --site main --out walks.json
engine-dmo content import --file walks.json --site main --dry-run
engine-dmo content import --file walks.json --site main --match slug
```

An export writes a type's documents on a site (or a selection with `--id` or `--ids-from`), with every locale's working values (or those named with `--locale`), as JSON or, with `--format csv`, a CSV with one row per document and locale for reading in a spreadsheet. Only JSON can be imported. Exports are audited.

The JSON file:

```json
{
  "format": "meridian.content.v1",
  "site": "main",
  "type": "walk",
  "exported_at": "2026-11-02T09:00:00Z",
  "documents": [
    {
      "id": "1b9f...",
      "type": "walk",
      "variant": "",
      "locales": {
        "en-GB": { "status": "published", "values": { "title": "Bloxham loop", "slug": "bloxham-loop" } }
      }
    }
  ]
}
```

| Rule | |
|---|---|
| Format | `format` must be `meridian.content.v1`; anything else is refused rather than half read. |
| Size | At most 2000 documents per file. |
| Matching | `--match id` (the default) updates the document with that id, or creates one under it, so a file moves between environments with its ids. `--match slug` matches the first locale's slug among the type's documents on the site, and creates a document under a new id when none matches. |
| Publishing | Never. Everything is imported as drafts; `status` in the file is information only. |
| Rich text | A `portable_text` value may be `{ "html": "<p>...</p>" }`, converted by the same converter as the editor's paste and normalised to the field; each adjustment is reported. An `<img src="asset:<id>">` becomes the field's image block pointing at that library asset; any other image is left out and counted, since an import never fetches a file. |
| Permissions | Every write goes through the content store with your grants; a locale you may not create or edit is rejected with the reason. |
| Dry run | `--dry-run` says what would happen to each locale and writes nothing. |


# Content types (/content-modelling/types)

Every key a type file takes (key, extends, label, ordering, template, singleton, variants, sites, groups, revisions and the rest), how to extend a core type, and the rules check enforces.

A type file declares one content type, or adds to one. This page is the reference for every key at the top level of a type file. Fields have their own page: [Fields](/content-modelling/fields).

## A custom type and an extension [#a-custom-type-and-an-extension]

A custom type is declared with `key:`:

```yaml
# config/schema/walk.yaml
key: walk
label: { en-GB: Walk, cy-GB: Taith gerdded }
plural: { en-GB: Walks, cy-GB: Teithiau cerdded }
ordering: { field: title, direction: asc }
fields:
  - { name: title, type: text, required: true, index: true }
  - { name: slug, type: slug, source: title, required: true }
```

A core type is extended with `extends:`. The file adds fields and may restate core fields to relabel or narrow them:

```yaml
# config/schema/article.yaml
extends: article
fields:
  - name: summary          # a core field: relabel, add help, narrow its parameters
    max: 200
    help: { en-GB: Shown on cards and in search results. }
  - { name: heroImage, type: asset }
groups:
  - key: main
    label: { en-GB: Main }
    fields: [title, slug, summary, body, heroImage]
```

## Type keys [#type-keys]

| Key | Type | Default | What it does |
|---|---|---|---|
| `key` | string | | The handle of a custom type: lowercase letters, digits and underscores, starting with a letter (`walk`, `landing_page`). Declare `key:` or `extends:`, never both. |
| `extends` | string | | The core type this file adds to (`page`, `article`, `event`, `guide`, `collection`, and in `engine-dmo` `listing` and `area`). From a site's schema directory it may also name a shared custom type declared in `config/schema/`. |
| `id` | string | written by `check --fix` | The type's stable id, `typ_` and ten characters. Written by the tooling, never by hand. A file that extends a type writes no id. |
| `label` | locale map or string | | The name editors see. A map gives one value per locale; a plain string is the same in every locale. |
| `plural` | locale map or string | | The plural name, used in the admin's navigation and lists. |
| `ordering` | `{ field, direction }` | | The default order of the type's lists and index pages. `field` is a field with `index: true`, or `createdAt`, `updatedAt` or `publishedAt`. `direction` is `asc` or `desc`; anything but `desc` sorts ascending. |
| `template` | string | `<type>/entry.html` | The template a document of the type renders with, relative to a template root. `engine-dmo check` fails when a routed type has no template on a site. |
| `singleton` | boolean | `false` | One document of the type per site ([Singletons](#singletons)). Custom types only. |
| `localisable` | boolean | `true` | `false` leaves the type's pages out of the translation signal in content health. It does not stop a document being written in several locales. |
| `fields` | list | | The fields ([Fields](/content-modelling/fields)). |
| `groups` | list | | The editor's layout ([Groups](#groups)). |
| `validation` | list | | Cross-field rules ([Validation](/content-modelling/validation)). |
| `variants` | mapping | | Named field sets a document chooses between ([Variants](#variants)). |
| `sites` | list of site keys | every site | The sites a shared type is on ([Types on some sites](#types-on-some-sites)). |
| `revisions` | mapping | the install's | Revision retention for this type ([Revision retention](#revision-retention)). |
| `structured_data` | mapping | | The type's schema.org entity and an optional FAQ mapping ([SEO and structured data](/templates/seo-and-structured-data)). |
| `embed` | mapping | | Which fields the embeddable widgets show of a document of the type: `image` (an asset field), `address` (an address field), `phone` (a phone field) and `website` (a link or text field). A role left out takes the type's first field of that type; `website` is shown only when named. Widgets are served when the site sets `embed.enabled` ([Site configuration](/reference/configuration/site)), and `engine-dmo export embeds` writes them for a static build ([export](/reference/cli/export)). |
| `member_editable` | mapping | | engine-dmo: what a partner may change at each membership tier ([Partners and the portal](/dmo/partners-and-portal)). |
| `icon` | string | | Accepted and stored; the admin does not show it today. |
| `searchable` | boolean | `false` | Accepted and stored; it does not change what search indexes today. |
| `uri` | string or locale map | | Accepted and stored; it does not give the type an address. Addresses come only from a site's `routes.yaml`. |

### Locale maps [#locale-maps]

Every label, plural, help text, block description, option label and validation message is either a plain string, used in every locale, or a map of locale code to text:

```yaml
label: { en-GB: Opening hours, cy-GB: Oriau agor, ja-JP: 営業時間 }
```

With a map, `engine-dmo check` reports each locale some site enables that has no value: a missing source locale is an error, any other locale a warning (the admin shows the source locale's label until one is added). `i18n.require_all: true` in `engine.yaml` makes every enabled locale an error; `false` checks the source locale only.

## Splitting a type across files [#splitting-a-type-across-files]

A type may be declared across several files in the same directory: `config/schema/walk/fields.yaml` with `key: walk` and `config/schema/walk/rules.yaml` with `key: walk` are one type. Fields, groups and validation rules from every file are combined. Every other key (`label`, `plural`, `ordering`, `template`, `variants`, `embed`, `structured_data`, `revisions`, `id` and so on) may be set in one file only; a second file setting it fails with `ordering of type "walk" is already set in config/schema/walk/fields.yaml`.

## Extending a core type [#extending-a-core-type]

`extends:` adds fields to a core type and lets you change how its core fields appear. The engine builds one type from the core definition, the shared extension and, on a site, that site's own extension:

```mermaid
flowchart LR
  core["core listing<br/>title, slug, summary,<br/>location, primaryTag"] --> merged["listing on site town"]
  shared["config/schema/listing.yaml<br/>extends: listing<br/>adds phone, website"] --> merged
  site["config/sites/town/schema/listing.yaml<br/>extends: listing<br/>adds parkingNotes"] --> merged
  merged --> other["listing on any other site:<br/>core + shared fields only"]
```

The rules:

- A core field's type is fixed. Restating `title` with `type: portable_text` fails: `core field "title" has type text and cannot be retyped to portable_text`.
- A core field's parameters may only narrow. A `max` may fall and a `min` rise; a list such as `options`, `to`, `kinds`, `styles`, `lists`, `accept`, `countries` or `geometries` may lose entries but not gain them; `multiple: true` may not be added. Anything else is refused with the reason: `core field "summary": max 400 is larger than the core 280`.
- A core field may be given a new `label` and `help`, and may be marked `index`, `unique`, `protected`, `recommended`, `site_overridable`, `machine_translate` or `summary_of`.
- A required core field cannot be made optional: restating it with `required: false` fails. Restating an optional core field with `required: true` has no effect; use a [validation rule](/content-modelling/validation) to require it.
- A restated core field writes no `id:`; it keeps the engine's.
- An added field must not reuse a name the type already has, and must not use an engine-managed name ([Reserved names](#reserved-names)).
- `engine-dmo dev field add <type> <name> --after <field>` on an extended type can only name a field written in your extending file. The core fields are not in it, so `--after slug` fails with `--after names "slug", which is not a field in schema/page.yaml`. Leave `--after` out and lay out the editor with [groups](#groups).

### Extending page [#extending-page]

The core `page` type has only `title` and `slug`. Give it a summary (which `head()` prints as the meta description), a body and an SEO field before you write any page with content:

```yaml
# config/schema/page.yaml
extends: page
fields:
  - { name: summary, type: text, multiline: true, max: 280 }
  - { name: body, type: portable_text, styles: [normal, h2, h3], lists: [bullet, number], marks: [strong, em, link] }
  - { name: meta, type: seo }
```

`seo` is a reserved name, so the SEO field is called something else (`meta` here). `engine-dmo check --fix` writes the three ids; `engine-dmo describe type page` then lists the core fields followed by these.

## Reserved names [#reserved-names]

These names are kept by the engine on every type and cannot be declared as top-level fields: `author`, `createdAt`, `id`, `locale`, `noindex`, `organisation`, `publishedAt` (except as the article's core field), `redirectFrom`, `seo`, `status`, `tags`, `translations`, `type`, `updatedAt`, `uri`, `url`. A type with variants also cannot have a field named `variant`.

A type routed with nesting on some site carries an implicit `parent` field, a single relation to its own type ([Sites, locales and routes](/concepts/sites-locales-and-routes)).

## Groups [#groups]

Groups lay out the editor. They never change storage, so regrouping is always safe.

```yaml
groups:
  - key: essentials
    label: { en-GB: Essentials }
    fields: [title, slug, summary, primaryTag, tags]
  - key: contact
    label: { en-GB: Contact }
    fields: [address, phone, website]
  - key: seo
    label: { en-GB: Search }
    fields: [meta, noindex]
    collapsed: true
```

| Key | Type | What it does |
|---|---|---|
| `key` | string | The group's handle. |
| `id` | string | Written by `check --fix` (`grp_...`). |
| `label` | locale map or string | The group's heading. |
| `fields` | list | The fields it holds, by name. Each must be a field of the type or an engine-managed field such as `tags` or `noindex`. |
| `collapsed` | boolean | Starts the group closed. |

`engine-dmo dev group add` adds a group to a type file with its id.

## Singletons [#singletons]

`singleton: true` on a custom type gives every site the type is on exactly one document of it: site settings, a home page's own copy, a footer line.

```yaml
# config/schema/site_settings.yaml
key: site_settings
label: { en-GB: Site settings }
singleton: true
fields:
  - { name: title, type: text, required: true }
  - { name: announcement, type: text, max: 160 }
```

- `singleton` belongs on a type declared with `key:`. On `extends:` it fails: `singleton is set on extends: event`.
- `engine-dmo schema apply` creates each site's singleton when it has none, as a draft in the site's default locale, with the type's label as its title and a slug from the title. Running apply again creates nothing, and an existing singleton is never touched. The plan names each one it will create.
- Making an existing type a singleton is refused by the plan while any site holds more than one document of it. Turning it off leaves the documents as ordinary ones.
- A singleton cannot be trashed, cloned or shared to another site. The admin opens it straight in the editor instead of showing a list.
- Templates read it as `singletons.<type>`, the current site's published document in the request locale, or nothing ([Globals](/templates/globals)). A site's `routes.yaml` can make a singleton its home page with `home: { type: homepage }`.
- A seed document of a singleton type fills in that site's singleton ([Seeding and importing](/content-modelling/seeding-and-importing)).

## Variants [#variants]

Variants are named field sets a document chooses between: an event that happens in a hall, one that is streamed, a festival with a line-up. They share the type's own fields, routes, lists and permissions; each adds fields of its own.

```yaml
# config/schema/event.yaml
extends: event
fields:
  - { name: price, type: money, currency: GBP }
variants:
  default: standard
  options:
    - { key: standard, label: { en-GB: Standard event } }
    - key: online
      label: { en-GB: Online event }
      fields:
        - { name: streamUrl, type: link, kinds: [{ of: url }], required: true }
    - key: festival
      label: { en-GB: Festival }
      template: event/festival.html
      fields:
        - name: lineup
          type: repeater
          fields:
            - { name: act, type: text, required: true }
```

| Key | Type | What it does |
|---|---|---|
| `variants.default` | string | The variant a new document starts in; the first option when left out. |
| `variants.options[].key` | string | The variant's handle: lowercase letters, digits and underscores. |
| `variants.options[].id` | string | Written by `check --fix` (`var_...`). |
| `variants.options[].label` | locale map or string | The name editors see. |
| `variants.options[].template` | string | Replaces the type's template for documents in this variant. |
| `variants.options[].fields` | list | Fields this variant adds. `use:` is not allowed here. |

Rules `engine-dmo check` enforces:

- A variant cannot redeclare one of the type's own fields; those are in every variant.
- A field two variants both want is declared identically in each, and is then one field whose value stays when a document moves between them. Declared differently, it fails.
- The type cannot have a field named `variant`; templates read `entry.variant`.

The variant belongs to the document, not to a locale. Required fields and validation rules are the variant's: a rule runs only in the variants that have every field it names. When an editor switches a document's variant, values of fields the new variant lacks are set aside under `_orphaned`, not deleted, and switching back restores them. `engine-dmo content variant set` moves documents between variants in bulk (`--dry-run` says what each move would set aside). Seed documents name theirs with `variant:`.

## Types on some sites [#types-on-some-sites]

On an install with several sites, a type is on every site unless it says otherwise. Core types are on every site.

- **A site's own type** is declared with `key:` in `config/sites/<site>/schema/`, and exists on that site only.
- **A shared type on some sites** is declared once in `config/schema/` with `sites: [town, county]`. Each listed site may extend it from its own schema directory with `extends:`, adding fields offered on that site only.

```yaml
# config/sites/town/schema/listing.yaml
extends: listing
fields:
  - { name: parkingNotes, type: text, multiline: true }
```

A type is refused wherever it is not on a site: the admin does not list it there, a route for it on another site fails `engine-dmo check`, and a document of it cannot be created, shared or cloned onto another site. A field added from a site's directory is offered in that site's editor only. `member_editable` (engine-dmo) may be set once in the shared file and once in each site's directory, where it replaces the shared rule on that site; every other type key is set once per type.

`engine-dmo dev type add <key> --sites town,county` writes a shared type limited to those sites; `--site town` writes a site's own type.

## Revision retention [#revision-retention]

Every save makes a revision. The install prunes old ones by `content.revisions` in `engine.yaml` (by default it prunes, keeping every revision younger than 90 days, the newest 20 of each chain, and the newest of each calendar month). A type can override any of these:

```yaml
revisions: { keep_all: 180d, keep_last: 50, keep_monthly: true }
```

```yaml
revisions: { prune: false }   # keep every revision of this type
```

| Key | Type | What it does |
|---|---|---|
| `prune` | boolean | `false` keeps every revision of the type. |
| `keep_all` | duration such as `90d` | Keep every revision younger than this. At least a day. |
| `keep_last` | whole number, at least 1 | And the newest N of each chain. |
| `keep_monthly` | boolean | And the newest of each calendar month (UTC). |

A key you leave out keeps the install's value.

## Errors you may see [#errors-you-may-see]

| Message | Cause |
|---|---|
| `<file> declares neither key: nor extends:` | Every type file needs one of the two. |
| `a schema file declares either extends (a core type) or key (a custom type), not both` | Remove one. |
| `"<name>" is not a core type; core types are ...` | `extends:` names a type that is not core. Use `key:` for a new type. In `engine-cms`, `listing` and `area` are not core. |
| `type "<key>" is already declared` | Two directories declare the same key, or a site declares a key the shared schema has. |
| `type key "<key>" must be lowercase letters, digits and underscores` | Fix the key. |
| `<attr> of type "<key>" is already set in <file>` | A type split across files sets the same attribute twice. |
| `ordering field "<name>" needs index: true, or the type cannot be sorted by it` | Add `index: true` to the field. |
| `group "<key>" references unknown field "<name>"` | A group lists a field the type does not have. |
| `type <key> has the id <id>; a file that extends it takes its id and writes none` | Remove `id:` from the extending file. |

Every problem is reported at once, each with the file, line and column. See [Error codes](/reference/error-codes) for the codes `check` prints.


# Validation (/content-modelling/validation)

When a document is checked (save and publish), required fields and required_in, visible_when and required_when, the expression language, cross-field validation rules with severity and timing, and the publish checks.

Every document is checked against its type on each save and on each publish. A problem is an **error**, which stops the action, or a **warning**, which is shown as advice and stops nothing. Each problem has a path (`stages[2].title`, `meta.description`) so the admin, the content API and the MCP point at the exact control, inside collapsed repeater items too.

## Save and publish [#save-and-publish]

A draft must be able to stop mid-work, so a save checks less than a publish.

| Check | On save | On publish |
|---|---|---|
| Each field type's own rules (a number is a number, a URL parses, a phone is valid) | error | error |
| `required`, `required_in`, `required_when` | not checked | error |
| A repeater's or blocks field's `min`, when it has fewer items but not none | error | error |
| A repeater's or blocks field's `min`, when it is empty | not checked | error |
| `unique` | warning | error |
| Validation rules without `on:` | as their severity | as their severity |
| Validation rules with `on: publish` | not run | as their severity |
| A link's target type and site, an asset's kind and constraints | error | error |
| Asset rights, alt text and missing assets ([Asset](/content-modelling/fields/asset)) | | error or warning |
| A tag relation names a vocabulary tag, not a candidate | | error |
| A nesting document is not placed under itself | | error |
| A relation's target is not published in this locale or its fallbacks | | warning |
| The reserved slug `__home__` where it cannot apply | error | error |

Publishing in one locale checks that locale's view of the document.

## Required fields [#required-fields]

```yaml
fields:
  - { name: title, type: text, required: true }
  - { name: summary, type: text, required: true, required_in: all }
  - { name: legalNotice, type: portable_text, required: true, required_in: [en-GB, cy-GB] }
```

`required: true` makes a field necessary to publish. `required_in` says in which locales, and applies only with `required: true`:

| `required_in` | The field is required when publishing |
|---|---|
| left out, or `source` | in the source locale only (the default) |
| `all` | in every locale |
| a locale code or a list | in the source locale if `source` is listed, and in each locale listed |

The default is deliberate: requiring every locale blocks publishing until everything is translated.

A value is empty when it is missing, a string of only spaces, an empty list, or an empty object. `false` is a value, so `required` on a boolean does not force it to be true. The message is `This field is required` with code `required`.

## Conditional fields [#conditional-fields]

```yaml
fields:
  - { name: bookingRequired, type: boolean }
  - name: bookingUrl
    type: link
    kinds: [{ of: url }]
    visible_when: "bookingRequired == true"
    required_when: "bookingRequired == true"
```

| Key | What it does |
|---|---|
| `visible_when` | The editor shows the field only while the expression is true, with no round trip to the server. On every save the server evaluates it too, and a hidden field's value is removed: a crafted post cannot keep a value for a field that should not be there. |
| `required_when` | The field is required to publish while the expression is true. |

They are separate on purpose: a field can be visible and optional, or required by a condition while visible for another. Both read sibling fields only: a top-level field reads other top-level fields, and a field inside a repeater item or a block reads the other fields of that item.

## The expression language [#the-expression-language]

`visible_when`, `required_when` and validation rules share one small language, parsed and type-checked when the configuration loads.

| Form | Example |
|---|---|
| Compare a field with a literal | `tier == 'gold'`, `capacity > 50`, `dogFriendly == true` |
| Compare two fields | `endDate >= startDate` |
| Emptiness | `heroImage == empty`, `accessibility != empty` |
| Membership | `difficulty in ['moderate', 'hard']`, `kind not in ['online']` |
| Length (rules) | `summary\|length >= 60` |
| Combine | `and`, `or`, `not`, and parentheses: `not (tier in ['gold', 'platinum']) or heroImage != empty` |

- Operators: `==`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not in`.
- Literals: strings in single or double quotes, numbers, `true`, `false`, and `empty` (with `==` and `!=` only). A list after `in` holds literals only.
- `|length` is the only filter: a string's length in characters, or a list's length. It compares with a number.
- No function calls, no arithmetic, no paths into other documents.

`engine-dmo check` type-checks every expression once all schema files are read:

| Message | Cause |
|---|---|
| `unknown field "x"` (with a suggestion) | The name is not a sibling. |
| `"tlak" is not an option of kind` (with the options listed) | A select compared with a value it does not offer. |
| `price is a number and is compared with a number, not "ten"` | The literal does not suit the field: a number needs a number, a boolean `true` or `false`, a text, slug, phone, date or datetime a quoted string. |
| `summary\|length compares with a number` | A length compared with something other than a number. |
| `heroImage is a asset field and can only be tested with == empty or != empty` | Structured fields (asset, link, video, geo, geo_shape, address, opening_hours, recurrence, seo, portable_text, repeater, blocks) are only tested for emptiness. |
| `x (number) is compared with y (text), which never match` | Two fields of different kinds. |
| `empty only works with == and !=`, `unterminated string`, `expected a list after in` | Syntax. |

Comparisons between two values are numeric when both are numbers and textual otherwise. Two `date` fields compare correctly as text (`YYYY-MM-DD`). A `datetime` is a structured value, so compare `datetime` fields only with `== empty` or `!= empty`, and use `date` fields where a rule must order two moments.

## Validation rules [#validation-rules]

Rules check several fields together. They sit in the type's `validation:` list:

```yaml
validation:
  - rule: "endDate == empty or endDate >= startDate"
    message: { en-GB: The end date must be on or after the start date. }
    fields: [endDate]

  - rule: "isAccessible == false or accessibility != empty"
    message: { en-GB: Describe the surfaces and gradients before marking the walk accessible. }
    fields: [accessibility]
    on: publish

  - rule: "summary == empty or summary|length >= 60"
    message: { en-GB: A summary under 60 characters reads poorly in search results. }
    fields: [summary]
    severity: warning
```

| Key | Type | Default | What it does |
|---|---|---|---|
| `rule` | expression | required | What must be true. A rule that is false produces its message. |
| `message` | locale map or string | | What the editor reads, in the locale being saved (else the source locale's). |
| `fields` | list of field names | the fields the rule reads | Where the message appears. Each must be a field of the type. |
| `severity` | `error` or `warning` | `error` | An error stops the save (or the publish, with `on: publish`); a warning is advice. |
| `on` | `save` or `publish` | every save and publish | `publish` runs the rule only when publishing, so a draft can be incomplete. |

Rules read the document's top-level fields. A type with [variants](/content-modelling/types#variants) runs a rule only in the variants that have every field it names. The code of a rule's problem is `cross_field`. Rules may be spread across the files of a type split over several files.

## What a problem looks like [#what-a-problem-looks-like]

Through the content API and the content MCP, each problem is reported with:

| Property | Example |
|---|---|
| `path` | `stages[2].title`, `address.postal_code`, `cta.fields.icon` |
| `code` | `required`, `max_length`, `cross_field`, `money_currency_fixed` |
| `severity` | `error` or `warning` |
| `message` | Localised text, such as `Must be 280 characters or fewer` |

Each field type's codes are on its page under [Fields](/content-modelling/fields).

## Checking without saving [#checking-without-saving]

`engine-dmo content create --type walk --data '{...}'` validates as the admin's save does and refuses on an error; add `--publish` to run the publish checks too. Both need a database. The content MCP can report a document's publish checks without publishing ([Content MCP](/integrating/content-mcp)).


# Backups and restore (/deploying/backups-and-restore)

What a complete Meridian backup contains (the database, the media store, the project and the signing key), scripts to take one and restore it, the order that keeps them consistent, and exporting one site as a standalone install.

A Meridian install is restored from four things. Lose any one and the restore is incomplete.

| What | Holds | How to keep it |
|---|---|---|
| The PostgreSQL database | Content and every revision, users, the CRM, analytics, the media library's records, the job queue | `pg_dump` (below), or your managed service's backups and point-in-time recovery |
| The media store | Every uploaded original and generated derivative | Archive the storage root, or rely on the bucket's versioning or replication |
| The project | Configuration, templates, public files | Your git repository, or the image you deploy |
| `server.security.signing_key` | The key staff second factors are encrypted with | Your secret store. A database restored under a different key leaves every staff authenticator unusable until reset |

The search index is not backed up. It is rebuilt from the database with `engine-dmo search rebuild`.

The engine has no backup or restore command of its own: a backup is a `pg_dump` of the database plus a copy of the media store, taken with your tools, in this order, and a restore puts them back in this order:

```mermaid
flowchart TD
  subgraph take["Taking a backup"]
    dump["pg_dump, custom format"] --> files["archive the storage root"]
    files --> off["copy both off the machine"]
  end
  subgraph back["Restoring"]
    stop["stop every replica"] --> db["recreate the database,<br/>pg_restore"]
    db --> store["restore the storage root"]
    store --> key["set the same SIGNING_KEY"]
    key --> mig["migrate up, schema apply"]
    mig --> boot["start, wait for readiness"]
    boot --> idx["search rebuild"]
  end
  off -.-> db
```

## Taking a backup [#taking-a-backup]

Dump the database first, then archive the store. Originals are named by their content and never rewritten, so a store copied after the dump holds every file the dump refers to.

```bash
pg_dump --format=custom --no-owner "$DATABASE_URL" > meridian-$(date -u +%Y%m%dT%H%M%SZ).dump
tar -czf storage-$(date -u +%Y%m%dT%H%M%SZ).tar.gz -C /srv/meridian/storage .
```

Use a `pg_dump` of the same major version as the server, or newer. Back up at least daily, keep copies off the machine and in another region, and keep enough history to recover from a mistake noticed late (30 days is a common minimum).

With the `s3` driver, turn on the bucket's versioning (or replicate it to a second bucket) rather than copying it on a schedule, and keep deleted versions for as long as you keep database backups.

### With Docker Compose [#with-docker-compose]

For the [single-node deployment](/deploying/single-node), `backup.sh` beside `compose.yaml` does both steps inside the stack:

```bash
#!/usr/bin/env bash
# Back up the database and the storage volume into BACKUP_DIR, keeping
# KEEP_DAYS of them. Copy BACKUP_DIR off the host afterwards.
set -euo pipefail
cd "$(dirname "$0")"
backup_dir=${BACKUP_DIR:-./backups}
keep_days=${KEEP_DAYS:-30}
project=${COMPOSE_PROJECT_NAME:-meridian}
stamp=$(date -u +%Y%m%dT%H%M%SZ)
mkdir -p "$backup_dir"

docker compose exec -T db pg_dump --format=custom --no-owner -U meridian meridian >"$backup_dir/meridian-$stamp.dump"
docker run --rm -v "${project}_storage:/storage:ro" -v "$(cd "$backup_dir" && pwd):/backup" busybox:1.37 \
	tar -czf "/backup/storage-$stamp.tar.gz" -C /storage .
find "$backup_dir" -name 'meridian-*.dump' -mtime +"$keep_days" -delete
find "$backup_dir" -name 'storage-*.tar.gz' -mtime +"$keep_days" -delete
echo "backed up to $backup_dir/meridian-$stamp.dump and storage-$stamp.tar.gz"
```

## Restoring [#restoring]

A restore replaces what is there. Rehearse it on a scratch machine before you need it, and after every engine upgrade.

<Steps>
<Step>
**Stop the engine** (every replica) so nothing writes during the restore.
</Step>
<Step>
**Recreate the database** with `UTF8` encoding and restore the dump into it:

```bash
dropdb --if-exists meridian
createdb -E UTF8 -T template0 meridian
pg_restore --exit-on-error --no-owner -d meridian meridian-20261102T031500Z.dump
```
</Step>
<Step>
**Restore the store**: empty the storage root and unpack the archive into it, owned by the engine's user.
</Step>
<Step>
**Set the same `SIGNING_KEY`** (and `MEDIA_SIGNING_KEY` if you set one) as the install the backup came from.
</Step>
<Step>
**Bring the database up to the binary.** A backup from an older engine needs its migrations: `engine-dmo migrate up`, then `engine-dmo schema apply`.
</Step>
<Step>
**Start the engine** and wait for `engine-dmo health --readiness`.
</Step>
<Step>
**Rebuild the search index**: `engine-dmo search rebuild`. Until it finishes, search answers from what the index held before.
</Step>
</Steps>

### With Docker Compose [#with-docker-compose-1]

`restore.sh` takes the two files `backup.sh` wrote and restores them into the running stack:

```bash
#!/usr/bin/env bash
# Restore from backup.sh's two files, replacing the database and the
# storage volume, then start the engine:
#   ./restore.sh backups/meridian-<stamp>.dump backups/storage-<stamp>.tar.gz
set -euo pipefail
cd "$(dirname "$0")"
dump=${1:?usage: restore.sh <meridian.dump> <storage.tar.gz>}
archive=${2:?usage: restore.sh <meridian.dump> <storage.tar.gz>}
project=${COMPOSE_PROJECT_NAME:-meridian}

docker compose stop engine caddy
docker compose exec -T db dropdb -U meridian --if-exists meridian
docker compose exec -T db createdb -U meridian -E UTF8 -T template0 meridian
docker compose exec -T db pg_restore --exit-on-error --no-owner -U meridian -d meridian <"$dump"
docker run --rm -i -v "${project}_storage:/storage" busybox:1.37 \
	sh -c 'find /storage -mindepth 1 -delete && tar -xzf - -C /storage && chown -R 65532:65532 /storage' <"$archive"
docker compose up -d
echo "restored; rebuild the search index with: docker compose exec engine /app/engine-dmo search rebuild --project /srv/project"
```

`docker compose up -d` runs the `migrate` and `schema` services before the engine, so a backup from an older engine is brought up to date on the way.

## Restoring under a running engine [#restoring-under-a-running-engine]

Never restore into the database a running engine is using. If it happens, the readiness check fails as soon as a migration the binary knows is missing from the restored database, and a load balancer stops sending traffic to it; restart the engine after `migrate up`.

## Exporting one site [#exporting-one-site]

On a multi-site install, one site can leave as a standalone install of its own: its database rows, its media and its configuration, verified by restoring the export into a scratch database and serving its home page.

```bash
engine-dmo site export --site wyndwold --plan
engine-dmo site export --site wyndwold --out ./wyndwold-export \
  --scratch-database-url "$SCRATCH_DATABASE_URL" \
  --signing-key-env NEW_INSTALL_SIGNING_KEY
```

| Flag | Meaning |
|---|---|
| `--site` | The site's key |
| `--out` | The directory to write, created with mode 0700; it must be empty or absent |
| `--plan` | Print what would be copied and stop |
| `--scratch-database-url` | A PostgreSQL server where the export may create two databases, and drop them, to verify itself |
| `--signing-key-env` | The environment variable holding the receiving install's signing key, to reseal staff second factors with; without it they are cleared |
| `--staff` | A staff user whose grants reach every site, by address, to copy as well. Repeatable |

`engine-dmo site retire --site <key>` then removes the site from this install (`--plan` first; it cannot be undone). The site export is not a substitute for backups: it carries one site, not the install. It keeps the site's audit rows without their [hash chain](/deploying/data-protection#a-site-leaving-the-install) links.

## Related [#related]

- [Database and migrations](/deploying/database-and-migrations)
- [Storage and media](/deploying/storage-and-media)
- [Upgrades](/deploying/upgrades): back up before every upgrade.


# Configuration and secrets (/deploying/configuration-and-secrets)

How one project runs in development, staging and production through engine.environment and environment variables, how ${VAR} interpolation and the secret rule work, and every rule production enforces.

The same project directory runs everywhere. What differs between your laptop, staging and production is the environment the engine starts in: `engine.environment` and the variables your `config/engine.yaml` interpolates. Configuration files are committed to git; secrets never are.

## A production-ready engine.yaml [#a-production-ready-engineyaml]

This is the shape most deployments start from. Every value that differs per environment is a variable, and every secret is a bare `${VAR}`:

```yaml
engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}

server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}
  trusted_proxies: ["172.30.0.0/24"]   # the range your reverse proxy connects from
  security:
    signing_key: ${SIGNING_KEY}

database:
  url: ${DATABASE_URL}

logging:
  format: ${LOG_FORMAT:-json}

storage:
  driver: filesystem
  filesystem:
    root: ./storage

mail:
  driver: smtp
  from: "Visit Example <hello@example.org>"
  smtp:
    host: ${SMTP_HOST}
    port: 587
    username: ${SMTP_USERNAME}
    password: ${SMTP_PASSWORD}
    tls: starttls
```

Check it the way production will read it, without a database:

```bash
ENVIRONMENT=production engine-dmo check --no-db
```

`check --no-db` accepts an unset variable in a secret path, so CI and an image build can check the project without the deployment's secrets. Every other unset variable is still an error.

## Environments [#environments]

`engine.environment` is `development` (the default), `staging` or `production`. Any other value is an error.

| | development | staging | production |
|---|---|---|---|
| Missing `server.base_url` | Allowed | Allowed | Error |
| Missing `server.security.signing_key` | Allowed, with a warning; a key is derived from the database URL | Allowed, with a warning | Error |
| `serve --dev` profiler, debug endpoints and admin asset reload | Work | Work | Off, even with `--dev` |
| Authoring commands (`engine-dmo dev field add` and the rest) | Run | Run only with `dev.authoring: true` | Refused |
| `engine-dmo mcp` over standard input and output, `docs serve` | Run | Run | Refused |
| `engine-dmo seed apply` | Runs | Runs | Refused over existing content; on an empty database only with `--i-know-what-i-am-doing`, and seed users are never created |
| `engine-dmo seed reset` | Runs | Runs | Refused |

Never run `serve --dev` in production: it reloads templates from disk on every request and starts the extensions' development servers. Set `ENVIRONMENT=production` on every production process, including the one-off `migrate up` and `schema apply` steps, so they read the configuration the server will.

## What production refuses [#what-production-refuses]

In production the engine refuses at boot (and `engine-dmo check` reports) each of these:

| Setting | Rule in production |
|---|---|
| `server.base_url` | Required: the public origin of the default site, used for absolute URLs, sitemaps and hreflang |
| `server.security.signing_key` | Required, at least 32 characters |
| `server.real_ip_header` with an empty `server.trusted_proxies` | Error. The default `real_ip_header` is `X-Forwarded-For`, so list your proxy's addresses in `trusted_proxies`, or set `real_ip_header: ""` when nothing sits in front of the engine |
| `auth.staff.local.require_mfa: false` | Error: a local staff account must carry a second factor |
| `search.log_queries: false` | Error: the zero-result report depends on the query log |
| `schema.on_drift: warn` | Error: use `refuse` (the default) or `apply` |
| `storage.s3.public_base_url` | Must be `https` |
| A headless site's `delivery.frontend.origin`, `preview_url` and frontend webhook URLs | Must be `https` |

`engine-dmo check` adds the mail rules, which a booting engine does not repeat:

| Setting | Rule in production |
|---|---|
| `mail.driver` | Must be `postmark`, `ses`, `resend` or `smtp`; the default `log` driver only writes messages to the log |
| `mail.from` | Required |
| `mail.postmark.webhook_token` | Required with the `postmark` driver |
| `mail.resend.api_key`, `mail.resend.webhook_secret` | Required with the `resend` driver; the webhook secret is the `whsec_` value the Resend dashboard shows |

Production also warns (it does not refuse) about `auth.staff.local.breach_check: off`, `template.strict: true`, `dev.authoring` (it has no effect), `admin.theme.contrast_check: warn`, a plain `http` S3 endpoint and a plain `http` OTLP endpoint on a public host.

<Callout type="warn" title="Run check with the production environment">
Because the mail rules live in `engine-dmo check` and not in the boot, an engine started in production with the `log` driver serves pages and writes every message to its log. Run `ENVIRONMENT=production engine-dmo check --no-db` in CI so that never reaches a deploy.
</Callout>

## Environment variables in configuration [#environment-variables-in-configuration]

The engine reads no fixed environment variables for its configuration. It reads the variables your `engine.yaml` (and the other configuration files) name:

| Form | Meaning |
|---|---|
| `${VAR}` | The variable's value. An unset variable is an error at load (`environment variable VAR is not set`). A variable set to the empty string gives the empty string |
| `${VAR:-default}` | The variable's value, or `default` when the variable is unset **or empty**, as in the shell and Compose |

Interpolation happens in values only, never in keys, and only in string-typed settings. A boolean or a number cannot come from a variable: `require_mfa: ${REQUIRE_MFA}` does not load. Where a setting must change per environment and is not a string, keep it the same everywhere or use a separate configuration directory with `--config`.

Several interpolations may be combined in one string, such as `base_url: https://${PUBLIC_HOST}`, except in secret paths (below). For a connection string assembled from parts, assemble it in the environment (Compose and most orchestrators can) and pass the whole string as `DATABASE_URL`.

The engine does not read `.env` files. Your shell, process manager, container runtime or orchestrator sets the variables. [Environment variables](/reference/environment-variables) lists the names the starter project and the examples use.

## The secret rule [#the-secret-rule]

A secret path must be exactly one bare interpolation, `${VAR}`, with no default and nothing around it. A literal value, or `${VAR:-something}`, is an error that names the file, line and column:

```text
config/engine.yaml:12:18: server.security.signing_key is a secret and must be an environment interpolation, not a literal
      = write signing_key: ${SIGNING_KEY} and set the variable in the environment
```

The secret paths in `engine.yaml`:

| Path | Holds |
|---|---|
| `database.url` | The PostgreSQL connection string, with its password |
| `server.security.signing_key` | The install's master key |
| `media.signing_key` | The key media derivative addresses are signed with |
| `auth.staff.oidc.client_secret` | The OpenID Connect client secret |
| `storage.s3.secret_access_key` | The object store's secret key |
| `mail.postmark.server_token`, `mail.postmark.webhook_token` | Postmark |
| `mail.ses.secret_access_key` | Amazon SES |
| `mail.resend.api_key`, `mail.resend.webhook_secret` | Resend |
| `mail.smtp.password` | The SMTP relay's password |
| `search.meilisearch.api_key`, `search.meilisearch.password` | Meilisearch |
| `search.elasticsearch.api_key`, `search.elasticsearch.password` | Elasticsearch |
| `search.opensearch.api_key`, `search.opensearch.password` | OpenSearch |
| `maps.key` | The map tile provider's key |
| `telemetry.errors.dsn` | The error reporter's DSN |
| Every value under `telemetry.otlp.headers` | Headers sent to the telemetry collector |
| `ai.azure_openai.api_key`, `ai.openai.api_key`, `ai.mistral.api_key`, `ai.openai_compatible.api_key`, `ai.anthropic.api_key` | The AI provider's key |

Other files hold secrets under the same rule: a headless site's frontend webhook `secret` in `site.yaml` (at least 16 characters), and `stripe.secret_key` and `stripe.webhook_secret` in `config/paidlistings.yaml` (`engine-dmo` only). A plugin's `env` in `plugins.yaml` gets nothing of the engine's own environment; a variable whose name looks like a credential (a key, token, secret or password) must be written as an interpolation there.

### Secrets in development [#secrets-in-development]

A secret path takes no default, so adding `signing_key: ${SIGNING_KEY}` (or any other secret) for production makes `SIGNING_KEY` required on every machine that loads the configuration, your laptop and CI included. `check --no-db`, `describe` and the `dev` verbs accept it unset; `config validate`, `seed verify`, `new`, `render`, `serve` and the rest refuse with `environment variable SIGNING_KEY is not set`. Set it in development to the empty string (the engine then derives a development key from the database URL, as when the key is absent) or to 32 or more random characters. A value of 1 to 31 characters is refused. [Commands and the environment](/reference/cli#commands-and-the-environment) lists which commands need what.

A secret whose variable is set to the empty string is treated as not configured. That is how a project runs a Meilisearch server with no key: write `api_key: ${MEILISEARCH_API_KEY}` and set `MEILISEARCH_API_KEY=` (empty).

## Where secrets show [#where-secrets-show]

Secrets are redacted wherever configuration is printed: `engine-dmo config render` prints `[redacted]` for every secret path, `engine-dmo doctor` reports the database as host and name only, and a recorded error that happens to quote a configured secret is scrubbed before it is stored.

```bash
engine-dmo config render          # the fully resolved engine.yaml, defaults included, secrets redacted
engine-dmo config render --json   # the same as JSON
engine-dmo config validate        # engine.yaml alone, no database
```

## Generating and rotating keys [#generating-and-rotating-keys]

Generate each key with a cryptographic random source:

```bash
openssl rand -base64 48
```

| Key | What it protects | Rotating it |
|---|---|---|
| `server.security.signing_key` | CSRF tokens, the encryption of staff second-factor secrets at rest, hashed rate-limit keys, and the keys derived from it (including the media key when `media.signing_key` is unset) | Every staff user's authenticator stops verifying and must be reset with `engine-dmo user reset-mfa`; open forms fail their CSRF check once. Plan it as an event, not a routine |
| `media.signing_key` | The addresses of image derivatives | Every derivative address changes, so cached pages and CDN copies point at addresses that are generated again on first request |
| Database, provider and API credentials | Access to that service | Rotate at the provider, set the new value in the environment, restart the engine |

Every replica of an install must have the same `signing_key`; replicas with different keys reject each other's forms and sessions.

## Related [#related]

- [engine.yaml reference](/reference/configuration/engine): every key, its type and default.
- [Environment variables](/reference/environment-variables): the variables the engine itself reads and sets.
- [Container images](/deploying/container-images): passing the environment to a container.


# Container images (/deploying/container-images)

The two published engine images (pure Go and -vips), their tags, what each contains, how to run one with your project mounted or baked into an image of your own, and the runtime constraints (non-root, no shell, read-only root).

Each release is published as two Linux container images of `engine-dmo`. Run the `-vips` one in production unless you have a reason not to: it encodes WebP and AVIF, reads HEIC, prints member reports as PDF and loads extensions.

```bash
docker run --rm ghcr.io/cherwell-studio/meridian:0.8-vips version
```

## What a release publishes [#what-a-release-publishes]

| Published | Not published |
|---|---|
| Two Linux container images of `engine-dmo`, at `ghcr.io/cherwell-studio/meridian` | A standalone binary to download, for any platform |
| `linux/amd64` and `linux/arm64` for the pure Go image; `linux/amd64` for `-vips` | An `engine-cms` image |
| The first-party extensions, inside the `-vips` image | A macOS or Windows build |
| | The example projects, the `meridian-extend` module source and the migration toolkit |

For a Linux host that runs the binary without containers (the [systemd setup](/deploying/single-node#without-containers-systemd)), copy it out of the pure Go image, which is statically linked:

```bash
docker create --name meridian-copy --platform linux/amd64 ghcr.io/cherwell-studio/meridian:0.8.0
docker cp meridian-copy:/app/engine-dmo ./engine-dmo
docker rm meridian-copy
./engine-dmo version
```

The `-vips` binary needs the libraries its image carries and does not run outside it. On a macOS or Windows workstation, run the engine from the image with your project mounted (see below), for example `docker run --rm -v "$PWD":/srv/project ghcr.io/cherwell-studio/meridian:0.8 check --no-db --project /srv/project`.

## The two images [#the-two-images]

| | `meridian:<version>` | `meridian:<version>-vips` |
|---|---|---|
| Base | Distroless static (no C library) | Distroless `cc` (glibc only) with the libraries below |
| Platforms | `linux/amd64`, `linux/arm64` | `linux/amd64` |
| `engine-dmo version` variant | `pure-go` | `vips` |
| Image encoding | JPEG and PNG | JPEG, PNG, WebP and AVIF, through libvips |
| HEIC uploads, ICC colour profiles | No | Yes |
| Member report as a tagged PDF | Built-in writer only | Through a bundled headless Chromium, with Noto fonts for Latin, Arabic, Thai, CJK and the other core scripts |
| Extensions (`extensions:` in `engine.yaml`) | Cannot load any: Go plugins need a cgo build | Loads them, and carries the first-party ones in `/app/extensions/` (the Vite integration is `/app/extensions/vite.so`) |
| Typical use | Small installs, a Node build stage that needs a static binary, `arm64` hosts | Production |

Both images contain `engine-dmo` only. A project written for `engine-cms` runs on `engine-dmo` unchanged, so the same images serve CMS projects.

### Tags [#tags]

| Tag | Points at |
|---|---|
| `0.8.0`, `0.8.0-vips` | That exact release. Pin this in production |
| `0.8`, `0.8-vips` | The newest patch release of 0.8 |
| `latest` | The newest pure Go release that is not a release candidate. There is no `latest-vips` |

The registry is `ghcr.io/cherwell-studio/meridian`. Check what you pulled with `docker run --rm <image> version`, which prints the version, bundle, modules, variant and what the image pipeline can encode. In an image build, `version --require` fails the build unless the image has what you depend on:

```dockerfile
RUN ["/app/engine-dmo", "version", "--require", "webp,avif,heic,icc,pdf,extension:vite"]
```

## What is inside [#what-is-inside]

| Path or property | Value |
|---|---|
| Binary and entrypoint | `/app/engine-dmo` |
| Default command | `serve` |
| Working directory | `/app`, which is also the default `--project` |
| User | `nonroot` (uid and gid 65532) |
| Exposed port | `8080` |
| Shell, package manager | None. Health checks and one-off commands call the binary directly |
| Writable paths the engine needs | The storage root (`storage.filesystem.root`) and `/tmp`. The `-vips` image points Chromium's and fontconfig's caches at `/tmp` (`XDG_CACHE_HOME=/tmp/.cache`, `XDG_CONFIG_HOME=/tmp/.config`) |

## Run it with your project mounted [#run-it-with-your-project-mounted]

The quickest route: mount the project read only, give the storage directory a volume, and pass the environment.

```bash
docker run -d --name meridian \
  --read-only --tmpfs /tmp \
  -p 8080:8080 \
  -v "$PWD":/srv/project:ro \
  -v meridian-storage:/srv/project/storage \
  -e ENVIRONMENT=production \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  -e BASE_URL=https://www.example.org \
  -e DATABASE_URL='postgres://meridian:secret@db:5432/meridian?sslmode=require' \
  -e SIGNING_KEY \
  ghcr.io/cherwell-studio/meridian:0.8.0-vips \
  serve --project /srv/project
```

Points to get right:

- **Listen on every interface.** A new project's `engine.yaml` listens on `${LISTEN_ADDR:-127.0.0.1:8080}`, which a container cannot be reached on. Set `LISTEN_ADDR=0.0.0.0:8080`.
- **The storage directory must exist in the project** (`mkdir storage`) when the project is mounted read only, so the volume has a mount point.
- **The volume must be writable by uid 65532.** A new named volume mounted over a path that does not exist in the image is owned by root. Change its owner once (`docker run --rm -v meridian-storage:/s busybox chown -R 65532:65532 /s`), or bake the directory into your own image with the right owner (below). The engine checks at boot that it can write to the storage root and refuses to start if it cannot.
- **Migrations and the schema are separate steps.** Run them with the same image and environment before `serve`:

```bash
docker run --rm --env-file prod.env -v "$PWD":/srv/project:ro \
  ghcr.io/cherwell-studio/meridian:0.8.0-vips migrate up --project /srv/project
docker run --rm --env-file prod.env -v "$PWD":/srv/project:ro \
  ghcr.io/cherwell-studio/meridian:0.8.0-vips schema apply --project /srv/project
```

## Build an image of your own [#build-an-image-of-your-own]

For anything beyond one machine, build an image that is the engine image plus your project, so a deploy is one tag and a rollback is the previous one. The project's files go in `/app`, the image's working directory and default project:

```dockerfile
# syntax=docker/dockerfile:1
ARG MERIDIAN_IMAGE=ghcr.io/cherwell-studio/meridian:0.8.0-vips
FROM ${MERIDIAN_IMAGE}
COPY config/ /app/config/
COPY templates/ /app/templates/
COPY public/ /app/public/

# The storage mount point, owned by the non-root user, so a new named
# volume mounted here starts writable. The image has no shell to mkdir.
COPY --chown=nonroot:nonroot <<EOF /app/storage/README
Uploaded media. Mount a volume here; never bake content into the image.
EOF

# Refuse to build a project that does not check: configuration, schema,
# routes, templates and the built frontend, with no database or secrets.
RUN ["/app/engine-dmo", "check", "--no-db", "--project", "/app"]
```

```bash
docker build -t registry.example.org/visit-example:2026-11-02 .
```

The image then runs with no arguments (`serve` in `/app`), and the one-off steps are `migrate up` and `schema apply` with no `--project`.

### With a frontend build [#with-a-frontend-build]

A project whose CSS and JavaScript are built with Vite builds them in a Node stage. The Vite plugin asks the engine for the project's asset manifest, so copy the static binary from the pure Go image of the same release into that stage and name it with `MERIDIAN_ENGINE`; the pure Go binary runs on any Linux base, the `-vips` one does not:

```dockerfile
# syntax=docker/dockerfile:1
ARG MERIDIAN_IMAGE=ghcr.io/cherwell-studio/meridian:0.8.0-vips
ARG MERIDIAN_STATIC_IMAGE=ghcr.io/cherwell-studio/meridian:0.8.0

FROM ${MERIDIAN_STATIC_IMAGE} AS engine

FROM node:24-trixie-slim AS assets
COPY --from=engine /app/engine-dmo /usr/local/bin/engine-dmo
WORKDIR /src
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund
COPY vite.config.js ./
COPY config/ config/
COPY templates/ templates/
COPY src/ src/
ENV MERIDIAN_ENGINE=/usr/local/bin/engine-dmo
RUN npm run build

FROM ${MERIDIAN_IMAGE}
COPY config/ /app/config/
COPY templates/ /app/templates/
COPY --from=assets /src/public/ /app/public/
COPY --chown=nonroot:nonroot <<EOF /app/storage/README
Uploaded media. Mount a volume here.
EOF
RUN ["/app/engine-dmo", "check", "--no-db", "--project", "/app"]
```

Use the same release for both build arguments. [The frontend build](/templates/frontend-build) covers the Vite configuration itself.

## Running constraints [#running-constraints]

| Constraint | Why |
|---|---|
| Run with a read-only root filesystem and a `tmpfs` on `/tmp` | The engine writes only its storage root and temporary files |
| Mount nothing over `/app` in your own image except the storage directory | The project files are part of the release |
| Do not run as root | The images are built to run as `nonroot`; nothing in them needs more |
| Pass the environment through your orchestrator | The engine does not read `.env` files |
| Health checks call the binary: `["CMD", "/app/engine-dmo", "health", "--readiness"]` | There is no shell and no `curl` in the image. Add `--project` when the project is not in `/app` |

`engine-dmo health` reads `server.listen` from the project's configuration and requests `/health` there, so it needs the same environment as the server (at least `LISTEN_ADDR` when the configuration interpolates it, and every variable without a default).

## Related [#related]

- [Single-node deployment](/deploying/single-node): the images under Docker Compose with Caddy, PostgreSQL and Meilisearch.
- [Configuration and secrets](/deploying/configuration-and-secrets): the environment the container needs.
- [Monitoring](/deploying/monitoring): health checks, metrics and logs.


# Data protection duties (/deploying/data-protection)

The data protection work that falls to whoever runs an install, answering a subject access request, generating the impact assessment, and turning on and verifying the audit log's hash chain, with what the chain cannot detect.

You hold the data, so you are its controller: the duties below are yours, and these commands do the mechanical part. All three are in both binaries; what they cover follows the modules your binary carries.

| Duty | Command | How often |
|---|---|---|
| Answer a subject access request | `engine-dmo sar` | When someone asks; the law allows a month |
| Keep an impact assessment | `engine-dmo dpia` | Once, then after any configuration change |
| Show the audit log has not been altered | `engine-dmo audit verify` | On a schedule you choose, with `audit.hash_chain` on |
| Erase a person | [`engine-dmo crm erase`](/dmo/crm#duplicates-merging-and-the-trash) | When someone asks (`engine-dmo` only) |

## Subject access requests [#subject-access-requests]

```bash
engine-dmo sar --email someone@example.com --out sar.zip
```

<Steps>
<Step>**Run it on the host,** with the same environment as the engine. `--out` must not exist yet. The address is trimmed and lower-cased before it is matched.</Step>
<Step>**Read the archive.** It is written readable by its owner only. An entry in the audit log or a note on a timeline can name other people as well, and what to do about those is your decision as controller.</Step>
<Step>**Hand it over** on a channel you trust, then delete your copy.</Step>
</Steps>

The archive holds a `README.txt` saying what each part holds, a `request.json` with the records the address was found to belong to and the counts, and one JSON file per section under `sections/`. A section exists only when your binary carries its module.

| From | What it holds |
|---|---|
| Every install | The staff account and its sessions; audit entries the person acted in, that are about one of their records or that name the address; timeline entries; notifications; revisions authored (not the content, which is the organisation's); mail sent (not the bodies, which are not kept); suppression; agent connections |
| CRM | The person's record with every custom field, their organisations, consents and broadcasts |
| Member portal | Sessions; passkeys (name and dates only); invitations; first-session steps; the enquiries they made or handled |
| Claims | Claims made by the address or naming the person, their checks and letters |
| Forms | Submissions whose data holds the address, or that the CRM person made |
| Newsletter | The subscriber, with consents, preferences and campaigns received |
| AI | Suggestions and assistance the staff account asked for or accepted, suggestions about one of the person's records, and usage by day: what, when and for which document, never the text |

No password, second factor, token or key is ever included. An address that matches nothing still produces a bundle of whatever names it. Each run writes `sar.export` to the audit log with the records found and the counts, never the address.

## The impact assessment [#the-impact-assessment]

```bash
engine-dmo dpia --out dpia.md
```

This writes a data protection impact assessment in the shape of the ICO's template, as Markdown. It reads `engine.yaml` and the binary's modules, never the database, and shows a configured address by its host, never a credential. Generate it again after a configuration change, since it states the retention periods and processors the install runs with.

| Filled in for you | Left for you, marked **To complete by the controller** |
|---|---|
| The personal data held and about whom, the typical lawful basis, each retention period, where it is stored | Why a DPIA is needed; scope; context; purposes |
| Each processor and what it receives | The contract and transfer mechanism for each processor; who you consulted |
| How the install supports each right | Why each kind of data is necessary, and why those periods suit it |
| The controls, including whether the audit log is hash chained | Each risk with its likelihood and severity; where backups are kept; sign off |
| An annex per module that has one, such as the AI data flow statement | |

Check each row against how you run the install before you rely on it: the lawful bases are typical ones, and yours are your own to confirm.

## The audit chain [#the-audit-chain]

The audit log is append-only to application code, but someone with access to the database could change it. The optional hash chain makes that detectable: each row takes the next link in its realm's chain (`staff`, `member` or `system`), and each link is a hash of the row and of the link before it.

### Turning it on [#turning-it-on]

```yaml
audit:
  hash_chain: true
```

Restart the engine on every replica. The engine writes the setting to the database when it starts, and rows are chained from then on; earlier rows stay outside the chain. It costs a lock: each realm's audit rows are written one transaction at a time, held until that transaction commits. It is off by default for that reason.

With the chain on, a daily `audit.anchor` task logs each realm's newest link as `audit chain head`, with `realm`, `seq` and `hash`. Ship your logs off the host and you hold a record of the chain outside the database ([Monitoring](/deploying/monitoring#logs)).

### Verifying it [#verifying-it]

```bash
engine-dmo audit verify
```

```mermaid
flowchart TD
  run["audit verify"] --> any{"Any chained rows?"}
  any -->|no| off["Exit 3: nothing is chained"]
  any -->|yes| walk["Walk each realm in link order"]
  walk --> ok{"Any break?"}
  ok -->|no| intact["Exit 0: intact<br/>keep the printed heads"]
  ok -->|yes| broken["Exit 1: each break listed"]
```

| What it prints | Means | What to do |
|---|---|---|
| Links starting above 1 | Retention pruned the oldest rows | Expected |
| `rewritten by erasure` | A person's erasure replaced their details with a tombstone. The row keeps its links | Expected |
| `written while the chain was off` | `audit.hash_chain` was off for a while. Those rows are not protected | Expected, if you turned it off |
| `BREAK content` | A row changed with the database trigger off | Treat as an incident |
| `BREAK rewrite` | A row rewritten in a transaction that recorded no erasure | Treat as an incident |
| `BREAK link` | A forged or recomputed link | Treat as an incident |
| `BREAK gap` | Rows deleted from inside the chain | Treat as an incident |

For an incident, keep the database and your logs as they are, and compare with your backups and the heads you recorded.

### What it cannot detect [#what-it-cannot-detect]

<Callout type="warn" title="Residual risk">
Someone with the database owner's rights can disable the triggers and rebuild the whole chain, and `audit verify` will then report it intact. Only a head recorded outside the database detects that: a later run or log line showing the same link with a different hash means the chain was rebuilt. Keep the `audit chain head` log lines, or a printout of `audit verify`, somewhere that person cannot reach.
</Callout>

### A site leaving the install [#a-site-leaving-the-install]

`engine-dmo site export` keeps the site's audit rows without their links, because a subset of a chain would report gaps for ever, and it does not carry the setting. The new install's chain starts at link 1 once its own `audit.hash_chain` is on.

## Related [#related]

- [`audit`](/reference/cli/audit), [`sar`](/reference/cli/sar) and [`dpia`](/reference/cli/dpia): the command reference
- [`audit.hash_chain`](/reference/configuration/engine#audit) and [`retention`](/reference/configuration/engine#retention): the keys
- [Backups and restore](/deploying/backups-and-restore)


# Database and migrations (/deploying/database-and-migrations)

What the engine needs from PostgreSQL, the connection pool settings, how engine migrations and schema apply run as deploy steps, what the engine refuses at boot, and how destructive schema changes are approved.

Meridian keeps everything except media files in one PostgreSQL database: content and its revisions, users, the CRM, analytics, the job queue and the scheduler's lease. Two kinds of change reach that database, and both are explicit deploy steps:

| Change | Comes from | Command |
|---|---|---|
| Engine migrations | A new engine version: changes to the engine's own tables | `engine-dmo migrate up` |
| The schema | Your configuration: types, fields, sites, locales, roles and the rest | `engine-dmo schema apply` |

```bash
engine-dmo migrate up      # the engine's tables, for this binary
engine-dmo schema apply    # your configuration, into the database
engine-dmo serve
```

## PostgreSQL requirements [#postgresql-requirements]

| Requirement | Detail |
|---|---|
| Version | 14 or later. The engine reads the server version before anything else and refuses an older server, naming the version it found |
| Encoding | `UTF8`. `migrate up` refuses any other encoding. Create the database with `--encoding=UTF8`, for example `POSTGRES_INITDB_ARGS="--encoding=UTF8 --locale=C.UTF-8"` in the official image |
| ICU collations | Recommended. Sorting text in a locale's own order uses the server's ICU collations; without ICU the engine runs, logs a warning and sorts in code point order |
| Privileges | The connecting role owns the database's objects: migrations create tables, indexes and partitions, and analytics creates a monthly partition ahead of each month |
| One database per project | Two projects must not share a database |

Managed services (Amazon RDS, Cloud SQL, Azure Database for PostgreSQL, Neon, Crunchy Bridge and others) work. Use `sslmode=require` or stricter in their connection strings.

Every session the engine opens runs in UTC (`timezone=UTC`) with `application_name` set to `meridian <version>`, so `pg_stat_activity` shows which version each connection belongs to.

## Connecting [#connecting]

```yaml
database:
  url: ${DATABASE_URL}
  max_connections: 20
  min_connections: 2
  max_conn_lifetime: 1h
  statement_timeout: 30s
```

```bash
export DATABASE_URL='postgres://meridian:secret@db.internal:5432/meridian?sslmode=require'
```

| Key | Default | Meaning |
|---|---|---|
| `database.url` | Required | A PostgreSQL URL or keyword/value connection string. A secret: always `${VAR}` |
| `database.max_connections` | `20` | The most connections one engine process holds |
| `database.min_connections` | `2` | Connections kept open when idle |
| `database.max_conn_lifetime` | `1h` | A connection is closed and replaced after this long |
| `database.statement_timeout` | `30s` | Set as the session's `statement_timeout`; a query running longer is cancelled. `0s` leaves the server's setting |
| `analytics.statement_timeout` | `10s` | A lower limit for report and dashboard queries, so reporting cannot starve the public site. Must be below `database.statement_timeout` |

Each replica opens its own pool, and every one-off command (`migrate up`, `schema apply`, `warm` and the rest) opens one too. Keep `replicas × max_connections`, plus a few for one-off commands, below the server's `max_connections`. With a connection pooler such as PgBouncer, use session pooling, not transaction pooling: the engine sets session parameters (time zone, statement timeout) and holds session-level advisory locks (for migrations and image derivative generation).

`engine-dmo doctor` reports the server's version, encoding, collation, whether ICU is present, the pool and the largest tables.

## Engine migrations [#engine-migrations]

A migration is a numbered SQL file compiled into the binary. They come in streams: the core stream, and one per module the bundle compiles (`crm`, `portal`, `ai` and the rest). A migration is named by its stream and number: `00023_mcp_bulk` in core, `crm/00001_baseline` in a module.

```bash
engine-dmo migrate status   # every migration, applied or pending; exits 2 when any is pending
engine-dmo migrate up       # apply every pending migration
engine-dmo migrate to 23    # apply core up to and including 23
engine-dmo migrate to crm/1 # apply a module's stream up to and including its 1
```

```text
applied 00022_asset_framing in 41ms (metadata)
applied 00023_mcp_bulk in 18ms (metadata)
```

How they behave:

| Property | Detail |
|---|---|
| Forward only | There are no down migrations. The way back is the backup you took before |
| One at a time | Every run takes one PostgreSQL advisory lock first, so two processes starting `migrate up` together (a rolling deploy) cannot race; the second waits and then finds nothing to do |
| One transaction each | Each file applies in its own transaction, and `migrate up` prints each one with how long it took and its class |
| Checksummed | The checksum of each applied file is recorded. A binary whose file differs from what was applied reports `DRIFT` and refuses to start |
| Classified | `metadata` changes only the catalogue or new tables and holds brief locks whatever the data size; `bounded` reads or rewrites existing rows under a lock (an index build, a validated constraint); `online` follows a plan written into the migration. The first migration of each stream is `baseline` |

`migrate status` also lists migrations recorded in the database for a module the binary does not compile (`not compiled`), such as a DMO database read by `engine-cms`. Their tables stay until you drop them by hand.

`migrate status --json` prints `applied`, `pending`, `drift` and `not_compiled` arrays, each row with `module`, `version` and `name`.

### What the server does with a pending migration [#what-the-server-does-with-a-pending-migration]

By default `engine-dmo serve` refuses to start while a migration is pending, lists them, and exits 2:

```text
2 migrations pending and migrate.on_boot is refuse:
  00022_asset_framing
  00023_mcp_bulk
run `engine-dmo migrate up` as the deploy step, or `engine-dmo serve --migrate` for a simple deployment
```

| Setting | Effect |
|---|---|
| `migrate.on_boot: refuse` | The default. Pending migrations stop the boot |
| `migrate.on_boot: apply` | Every boot applies pending migrations first |
| `engine-dmo serve --migrate` | Apply pending migrations, then serve, for this run only |

Applying on boot is convenient for a single small install. Avoid it with several replicas or a large database: the migration then runs inside a restart, under the orchestrator's start timeout, with no backup step before it.

While serving, the readiness check (`/health?readiness`) fails if any migration the binary knows is missing, for example after a restore from an older backup under a running engine.

## The schema [#the-schema]

Your configuration describes types, fields, sites, locales, networks, roles and the rest; the database records the version of it that was applied. `schema plan` shows the difference and `schema apply` makes it:

```bash
engine-dmo schema plan      # read only; exits 2 when there are changes
engine-dmo schema apply     # apply the plan in one transaction
```

At boot the engine compares the configuration with the database. What it does with a difference is `schema.on_drift`:

| Value | Effect |
|---|---|
| `refuse` | The default. The engine prints the plan and exits 2: `run engine-dmo schema apply as the deploy step` |
| `apply` | The engine applies the plan at boot. A destructive plan is applied only when the approval file holds its digest; otherwise the boot fails |
| `warn` | The engine applies a plan that is not destructive at boot; a destructive one is logged as a warning and left unapplied, and the engine starts. Refused in production |

### Destructive changes [#destructive-changes]

A change is destructive when it touches stored data: removing a type, site, locale, field, block or select option that documents use; changing a field so stored values no longer fit (a type change that loses values, multiple to single); changing a field's `translate` mode on documents that hold values; or any change to a protected field. The same change with no documents affected is not destructive. A removed field's values are kept under the document's orphaned values, and removed blocks stay in the revisions, but the plan still needs approval. `schema apply` refuses a destructive plan until someone approves that exact plan:

| Route | How |
|---|---|
| An approval file | `schema apply` prints the plan and its digest and refuses. Write the digest to the file `schema.destructive_approval` names (default `config/schema/.destructive-approved`), commit it, deploy. The next `schema apply` applies that plan, and only that plan |
| On a terminal | `engine-dmo schema apply --allow-destructive` shows the plan and asks for confirmation |
| In a script | `engine-dmo schema apply --allow-destructive --yes` applies without asking |

The approval file is the route for production: the approval is reviewed and committed with the change that needs it, and a different plan (a second change slipped in) has a different digest and is refused.

Other refusals, each with exit 2 and the plan printed:

| Refusal | Fix |
|---|---|
| The plan would leave nobody able to manage users, or nobody holding the owner role | Change `config/access` so someone active still does. This one exits 1 |
| An element's id in the files differs from the stored one under the same handle | Put the stored id back in the file, or name the handle with `--replace` (such as `--replace listing.priceRange`) to let the new element replace the stored one |
| The plan holds a change this engine cannot apply yet | Undo that change in the files to apply the rest |

Every `schema apply`, applied or refused, is written to the audit log.

### Databases from before stable ids [#databases-from-before-stable-ids]

`engine-dmo schema adopt-ids` gives a database made before configuration elements carried ids the ids the files now carry: it writes any missing ids into the files and binds them, and refuses a plan with any other change.

## Related [#related]

- [Upgrades](/deploying/upgrades): the whole sequence for a new engine version.
- [Backups and restore](/deploying/backups-and-restore).
- [Schema changes](/content-modelling/schema-changes): what each kind of configuration change does to stored content.


# Deploying (/deploying)

How a Meridian site runs in production, the parts of a deployment (engine, PostgreSQL, storage, optional search and mail), the deploy sequence, and which page covers each task.

A production Meridian install is the engine binary (or its container image), your project directory, a PostgreSQL database, a place to keep uploaded media, and optionally a search service and a mail provider. Nothing else runs beside the engine: the same process serves the public sites, the admin, the member portal and the APIs, runs the background jobs and runs the scheduled tasks.

## The parts of a deployment [#the-parts-of-a-deployment]

| Part | Required | What it is |
|---|---|---|
| The engine | Yes | `engine-dmo` (which also runs `engine-cms` projects), from one of the two container images. See [Container images](/deploying/container-images) and [What a release publishes](/deploying/container-images#what-a-release-publishes) |
| Your project | Yes | The directory with `config/`, `templates/` and `public/`. It is read only at run time. Mount it, copy it into an image of your own, or put it beside the binary |
| PostgreSQL | Yes | Version 14 or later, `UTF8` encoding. See [Database and migrations](/deploying/database-and-migrations) |
| Media storage | Yes | A writable directory (`storage.driver: filesystem`) or an S3-compatible bucket (`storage.driver: s3`). See [Storage and media](/deploying/storage-and-media) |
| A reverse proxy or load balancer | In practice | Terminates TLS and forwards to the engine's listener. The engine speaks plain HTTP |
| A search service | No | Meilisearch, Elasticsearch or OpenSearch. Without one, the search route serves browse mode |
| A mail provider | In production | Postmark, Amazon SES, Resend or an SMTP relay. `engine-dmo check` refuses the development `log` driver in production |

## The deploy sequence [#the-deploy-sequence]

Every deploy, first or fiftieth, runs the same steps in the same order. The engine never changes its own tables or your schema as a side effect of starting, unless you configure it to.

```mermaid
flowchart LR
  check["check --no-db<br/>in CI"] --> backup["back up<br/>the database"]
  backup --> migrate["migrate up"]
  migrate --> schema["schema apply"]
  schema -->|"exit 2: destructive"| review["review the plan"]
  review --> schema
  schema -->|"exit 0"| serve["serve"]
  serve --> ready["health --readiness"]
  ready --> warm["warm<br/>(optional)"]
```

<Steps>
<Step>
**Check the project.** `engine-dmo check --no-db` validates the configuration, schema, routes and templates without a database or the deployment's secrets. Run it in CI and in your image build. It exits 3 when anything is invalid.
</Step>
<Step>
**Back up the database.** Migrations only move forward; the way back from a bad upgrade is the backup you took before it. See [Backups and restore](/deploying/backups-and-restore).
</Step>
<Step>
**Apply migrations.** `engine-dmo migrate up` brings the engine's own tables up to the binary's version. It exits 0 when there is nothing to do.
</Step>
<Step>
**Apply the schema.** `engine-dmo schema apply` makes the database match your configuration (types, fields, sites, locales, roles). It refuses a destructive change unless you approve it.
</Step>
<Step>
**Start or restart the engine.** `engine-dmo serve`. It refuses to start while a migration is pending or while the configuration differs from the database, and says which command fixes it.
</Step>
<Step>
**Wait for readiness, then send traffic.** `engine-dmo health --readiness --wait 60s` exits 0 once the engine has started, the database answers and every migration is applied.
</Step>
<Step>
**Warm the caches (optional).** `engine-dmo warm` repairs the search index, requests the pages the page cache warms and reports each page's time.
</Step>
</Steps>

## Where to go next [#where-to-go-next]

<Cards>
<Card title="Configuration and secrets" href="/deploying/configuration-and-secrets" />
<Card title="Container images" href="/deploying/container-images" />
<Card title="Single-node deployment" href="/deploying/single-node" />
<Card title="Database and migrations" href="/deploying/database-and-migrations" />
<Card title="Storage and media" href="/deploying/storage-and-media" />
<Card title="Backups and restore" href="/deploying/backups-and-restore" />
<Card title="Data protection duties" href="/deploying/data-protection" />
<Card title="Upgrades" href="/deploying/upgrades" />
<Card title="Monitoring" href="/deploying/monitoring" />
<Card title="Scaling" href="/deploying/scaling" />
</Cards>

Every `engine.yaml` key is listed with its type and default in [engine.yaml](/reference/configuration/engine), and every command and flag in the [CLI reference](/reference/cli).


# Monitoring (/deploying/monitoring)

How to watch a running Meridian install, covering the /health liveness and readiness endpoint, the Prometheus metrics listener and its series, OpenTelemetry traces and metrics, Sentry error reporting, the JSON logs, the job queue and scheduler commands, and the doctor support bundle.

The engine reports on itself five ways: a health endpoint for load balancers, Prometheus metrics on a listener of their own, optional OpenTelemetry export and error reporting, structured logs on standard error, and `engine-dmo doctor` for a one-file snapshot.

## Health [#health]

Every site's host answers `GET /health`:

| Request | Answers 200 when | Body |
|---|---|---|
| `/health` | The process is up (liveness) | `{"status":"ok"}` |
| `/health?readiness` | Startup is complete, the database answers within 2 seconds, and every migration the binary knows is applied. Not while shutting down | `{"status":"ok","checks":{"database":"ok","migrations":"ok"}}` |

Otherwise `/health?readiness` answers 503 with `status` set to `starting` (still booting or warming the page cache), `stopping` (shutting down) or `degraded` (a check failed), and the failing check's error under `checks`. Responses are `Cache-Control: no-store`.

Use liveness for "restart it if it stops answering" and readiness for "send it traffic". Readiness turns false as soon as a shutdown begins, so a load balancer drains a replica before it stops; the engine then finishes in-flight requests for up to `server.shutdown_grace` (30 seconds by default).

From the command line, against the server this project's configuration describes:

```bash
engine-dmo health                     # liveness; prints the body
engine-dmo health --readiness         # exit 0 only when ready
engine-dmo health --readiness --wait 60s   # keep trying for 60 seconds, for a deploy step
```

`engine-dmo health` requests `http://<server.listen>/health`, so it runs on the same machine or in the same container as the server, with the same environment. It exits 4 when the server does not answer 200.

## Metrics [#metrics]

The engine serves Prometheus text metrics on a listener of its own, never on the public sites:

```yaml
telemetry:
  metrics:
    enabled: true          # default
    bind: 127.0.0.1:9090   # default: this machine only
    path: /_metrics        # default
```

```bash
curl -s http://127.0.0.1:9090/_metrics
```

To let a Prometheus on another host or container scrape it, bind to an interface that network reaches (`0.0.0.0:9090` inside a container network) and keep the port off the public internet. `bind` may not equal `server.listen`. Only `engine-dmo serve` opens the listener; one-off commands do not.

### Series [#series]

| Series | Type | Labels | Meaning |
|---|---|---|---|
| `meridian_http_requests_total` | Counter | `class`, `status` | Requests by route class (`public`, `admin`, `api`, `portal`, `endpoint`, `preview`, `static`, `beacon`, `health`, `other`) and status code |
| `meridian_http_request_duration_seconds` | Histogram | `class` | Request latency |
| `meridian_db_up` | Gauge | | 1 when the database answered at scrape time |
| `meridian_db_ping_seconds` | Gauge | | The database's round trip at scrape time |
| `meridian_db_pool_max_connections`, `_total_connections`, `_acquired_connections`, `_idle_connections` | Gauge | | The connection pool |
| `meridian_db_pool_acquires_total`, `_empty_acquires_total`, `_canceled_acquires_total`, `_empty_acquire_wait_seconds_total` | Counter | | How often, and how long, a request waited for a connection |
| `meridian_jobs_pending`, `meridian_jobs_running`, `meridian_jobs_dead` | Gauge | `queue` | The job queue |
| `meridian_jobs_oldest_runnable_age_seconds` | Gauge | `queue` | How long the oldest runnable job has waited |
| `meridian_job_runs_total` | Counter | `queue`, `outcome` | Job runs by outcome |
| `meridian_scheduler_leader` | Gauge | | 1 on the replica that holds the scheduler lease |
| `meridian_scheduler_task_success_age_seconds` | Gauge | `task` | On the leader: seconds since each scheduled task last succeeded |
| `meridian_scheduler_task_failures_total` | Counter | `task` | On the leader: each task's failures |
| `meridian_cache_entries`, `meridian_cache_hits_total`, `meridian_cache_misses_total` | Gauge, counters | | The in-process cache |
| `meridian_analytics_events_written_total`, `meridian_analytics_events_dropped_total` | Counter | | Analytics ingest; drops mean the ingest buffer was full |
| `meridian_search_queries_total` | Counter | `outcome` | Search queries by outcome |
| `meridian_search_breaker_open` | Gauge | | 1 while the search circuit breaker has stopped asking a failing backend |
| `meridian_mail_deliveries_total` | Counter | `outcome` (`sent`, `suppressed`, `rejected`, `provider_error`) | Transactional mail |
| `meridian_media_derivatives_generated_total`, `meridian_media_derivative_failures_total` | Counter | | Image derivative generation |
| `meridian_ai_requests_total` | Counter | `outcome` | AI provider calls, when AI is configured |

Series that read the database are collected at scrape time with a time limit, so a database that does not answer shows as `meridian_db_up 0` rather than a scrape that hangs.

### What to alert on [#what-to-alert-on]

| Alert | Expression (sketch) |
|---|---|
| Not ready | Readiness probe failing for more than 2 minutes |
| Database down | `meridian_db_up == 0` |
| Pool exhausted | `meridian_db_pool_acquired_connections / meridian_db_pool_max_connections > 0.9` for 10 minutes |
| Server errors | Rate of `meridian_http_requests_total{status=~"5.."}` above your baseline |
| Dead jobs | `meridian_jobs_dead > 0` |
| Queue stuck | `meridian_jobs_oldest_runnable_age_seconds > 900` |
| No scheduler | `sum(meridian_scheduler_leader) == 0` for 5 minutes |
| Analytics behind | `meridian_scheduler_task_success_age_seconds{task="analytics.rollup"} > 3600` |
| Search backend failing | `meridian_search_breaker_open == 1` |
| Mail failing | Rate of `meridian_mail_deliveries_total{outcome="provider_error"}` above zero |
| Disk | Free space on the storage, database and backup volumes (from your node exporter) |

## OpenTelemetry [#opentelemetry]

Traces and metrics can also be pushed over OTLP/HTTP (JSON encoding) to a collector:

```yaml
telemetry:
  otlp:
    endpoint: https://otel-collector.internal:4318   # /v1/traces and /v1/metrics are appended
    headers:
      Authorization: ${OTEL_AUTH_HEADER}
    timeout: 10s
  traces:
    enabled: true
    sample_ratio: 0.1
  metrics:
    export: true
    interval: 1m
  resource:
    service_name: meridian
    attributes:
      deployment.environment: production
```

Every header value is a secret (`${VAR}`). Traces sample 10% of new traces by default; an inbound `traceparent` decides only when `respect_parent_sampling: true`, so a visitor cannot make every request expensive. Each database statement is a span when tracing is on. The full key list is in [engine.yaml: telemetry](/reference/configuration/engine#telemetry).

## Error reporting [#error-reporting]

Errors and panics can be reported to Sentry (or any service that accepts the Sentry protocol):

```yaml
telemetry:
  errors:
    driver: sentry
    dsn: ${SENTRY_DSN}
    environment: production   # defaults to engine.environment
    sample_rate: 1.0          # errors only; a panic is always sent
```

Check the reporter and the OTLP endpoint from the deployment:

```bash
engine-dmo telemetry test --note "deploy 2026-11-02"
```

The engine also keeps its own grouped error log in the database, which `engine-dmo doctor --include-logs 20` prints and the admin's diagnostics screen shows. A configured secret quoted in an error is scrubbed before it is stored.

## Logs [#logs]

The engine writes one structured line per event to standard error: JSON by default, or logfmt-style text with `logging.format: text`.

```json
{"time":"2026-11-02T03:15:01.204Z","level":"INFO","msg":"request","request_id":"01JB...","event":"http.request","method":"GET","path":"/whats-on/","status":200,"bytes":48211,"duration_ms":12.4}
```

| Setting | Values | Default |
|---|---|---|
| `logging.level` | `debug`, `info`, `warn`, `error` | `info` |
| `logging.format` | `json`, `text` | `json` |

Each request is one `request` line with `method`, `path`, `status`, `bytes` and `duration_ms`, plus `request_id` and, when tracing, `trace_id`. A line written by a job or a provider call carries the `request_id` of the request that caused it. The request id is taken from an inbound `X-Request-ID` header when it comes from a trusted proxy, otherwise minted, and is sent on outbound calls. Single-use tokens in paths (enrolment, reset, magic and invitation links) are logged as `{token}`.

Boot logs the version, variant, bundle, modules, environment, the extensions loaded, the database server version, and each migration or schema change applied.

## Jobs and scheduled tasks [#jobs-and-scheduled-tasks]

Background work runs in every engine process: jobs from a queue in the database, and scheduled tasks on whichever replica holds the scheduler lease.

```bash
engine-dmo jobs list                    # jobs not yet complete, and dead ones, newest first
engine-dmo jobs list --failed           # dead jobs and jobs waiting to retry after an error
engine-dmo jobs retry --id <job id>     # run a dead job again with fresh attempts, once the cause is fixed
engine-dmo jobs retry --all-failed --queue <queue>

engine-dmo schedule list                # every scheduled task, its cadence, last success and the leader
engine-dmo schedule run analytics.rollup --now   # run one task once, in this process; audited
```

`schedule list` reads the last successes from the running engine's metrics listener, so run it where `telemetry.metrics.bind` is reachable.

With [`audit.hash_chain`](/deploying/data-protection#the-audit-chain) on, the daily `audit.anchor` task logs an `audit chain head` line per realm, with `realm`, `seq` and `hash`. Keep these lines: they are how a rebuilt chain is detected.

## The doctor bundle [#the-doctor-bundle]

`engine-dmo doctor` writes one pasteable text file describing the install: build, localisation data, configuration (non-secret), plugins, database (version, encoding, collation, ICU, pool, largest tables), storage, media pipeline, templates, mail, search (and whether the index matches what is published), jobs, permissions, timings, and recorded errors. It works without a database too, reporting the connection failure.

```bash
engine-dmo doctor --out doctor.txt
engine-dmo doctor --include-logs 20 --redact-level paranoid --out doctor.txt
engine-dmo doctor --mail-to you@example.org      # also send a live test message
engine-dmo doctor --telemetry-test               # also test the error reporter and OTLP endpoint
```

| Flag | Meaning |
|---|---|
| `--out` | Write the bundle to a file instead of the terminal |
| `--include-logs N` | Include the N most recent error groups the serving engine recorded |
| `--redact-level` | `standard` (default) redacts every secret by declaration and reports the database as host and name; `paranoid` also redacts host names, the database host and name, email addresses and IP addresses |
| `--mail-to` | Send a live test message through the configured mail driver |
| `--telemetry-test` | Send a test event to the error reporter and an empty export to the OTLP endpoint |

## Related [#related]

- [engine.yaml: telemetry and logging](/reference/configuration/engine#telemetry)
- [Scaling](/deploying/scaling): the scheduler lease across replicas.
- [Error codes](/reference/error-codes): every `MRD-nnnn` code a log line or refusal carries.


# Scaling (/deploying/scaling)

Running more than one engine replica behind a load balancer, covering what each replica does, the scheduler lease, shared storage, caches across replicas, background job workers, database connections and the page cache.

One engine process serves a typical destination site comfortably. Run more when you need to survive a machine failing, deploy without a gap, or serve more traffic than one process can. Replicas are identical engine processes against the same database, the same media store and the same search backend, behind a load balancer.

```yaml
server:
  replicas: 3
  trusted_proxies: ["10.0.0.0/16"]   # the load balancer's addresses
  security:
    signing_key: ${SIGNING_KEY}      # the same on every replica

storage:
  driver: s3
  s3:
    bucket: ${S3_BUCKET}
    region: ${S3_REGION}
    access_key_id: ${S3_ACCESS_KEY_ID}
    secret_access_key: ${S3_SECRET_ACCESS_KEY}
```

## What every replica does [#what-every-replica-does]

Every `engine-dmo serve` process does everything:

| Work | Across replicas |
|---|---|
| Public sites, admin, portal, APIs | Any replica answers any request. Sessions and rate-limit counters live in the database and CSRF tokens are signed with the shared key, so no sticky sessions are needed |
| Background jobs | Every replica takes jobs from the shared queue in the database. `jobs.workers` (default 4) caps how many run at once on each replica, across all queues; `jobs.queues.<queue>.workers` caps one queue |
| Scheduled tasks | Exactly one replica, the one holding the scheduler lease in the database, runs them. If it stops, another takes the lease within one heartbeat. `meridian_scheduler_leader` is 1 on the holder |
| Migrations | Never, unless `migrate.on_boot: apply`. Run `migrate up` once as a deploy step |

`engine-dmo serve --role` accepts `web`, `worker` or `all`, but in this release every value runs everything: there is no way yet to run a process that only serves or only works jobs. Size every replica for both.

## Requirements for more than one replica [#requirements-for-more-than-one-replica]

| Requirement | Why |
|---|---|
| Set `server.replicas` to the number you run | The configuration check uses it: filesystem storage on local disk is refused with more than one replica |
| Shared media storage: `storage.driver: s3`, or a filesystem every replica mounts with `storage.filesystem.shared: true` | An upload landing on one replica's disk would be missing on the others |
| The same `server.security.signing_key` (and `media.signing_key`, if set) on every replica | Forms, sessions and media addresses signed on one replica are checked on another |
| The same project files and engine version on every replica, outside a rollout | They must agree on the schema; a replica with different configuration refuses to start on drift |
| `server.trusted_proxies` naming the load balancer | So client addresses (`X-Forwarded-For`) and the scheme (`X-Forwarded-Proto`) are believed, for rate limits, analytics and absolute URLs |
| A shared search backend, if search is on | Every replica queries and indexes the same service |

## The load balancer [#the-load-balancer]

- Route to each replica's `server.listen` port; health-check with `GET /health?readiness`, which answers 503 while a replica starts, warms or shuts down.
- Terminate TLS at the load balancer and forward `X-Forwarded-For` and `X-Forwarded-Proto`.
- Give in-flight requests time to finish: a stopping replica reports not ready at once and finishes what it has for up to `server.shutdown_grace` (30 seconds). Set the load balancer's deregistration delay to at least that.
- Allow request bodies up to `media.max_upload_bytes` (50MB by default) for uploads.

## Caches across replicas [#caches-across-replicas]

| Cache | Behaviour |
|---|---|
| The in-process cache (resolved lists, blocks, navigation and other derived data) | Held separately by each replica, at most `cache.max_entries` entries for `cache.page_ttl`. A publish or other change writes an invalidation to the database, and every replica polls for them every `cache.invalidation_poll` (2 seconds by default), so a change shows on every replica within a few seconds |
| The page cache (`cache.pages.enabled: true`, off by default) | Whole public pages for anonymous visitors, held by each replica in memory up to `cache.pages.max_memory`, served stale while one render replaces them. Each replica renders `cache.pages.warm` (the paths listed, plus each site's most visited pages) before it reports ready, for at most `cache.pages.warm.deadline` |
| Media | Immutable addresses; put a CDN in front (see [Storage and media](/deploying/storage-and-media)) |

A page cache warmed on every replica at boot slows each replica's start by up to the warm deadline; the readiness check holds traffic back meanwhile. After a deploy, `engine-dmo warm --origin http://<replica>:8080` requests the warm list against one replica directly with each page's own host.

## Database connections [#database-connections]

Each replica opens up to `database.max_connections` (default 20). Keep the total, plus a few for one-off commands, under the server's limit:

```text
replicas × database.max_connections + headroom ≤ PostgreSQL max_connections
3 × 20 + 10 = 70 ≤ 100
```

Watch `meridian_db_pool_acquired_connections` against `meridian_db_pool_max_connections` and `meridian_db_pool_empty_acquire_wait_seconds_total`; raise `max_connections` (and the server's limit) when requests wait for connections. Use session pooling if a pooler sits between the engine and PostgreSQL.

## What does not scale out [#what-does-not-scale-out]

| Limit | Detail |
|---|---|
| Content MCP call limits | Calls a minute are counted per replica, so a client spread across replicas can make up to `replicas ×` the configured rate. Write limits are counted in the database and hold across replicas |
| Scheduled tasks | Run on one replica at a time, one task at a time. A slow task delays the next; `meridian_scheduler_task_success_age_seconds` shows it |
| Transactional mail | Each replica's mail queue has one worker, paced by `mail.rate_limit_per_minute` when set; the rate is per replica |

## Related [#related]

- [Upgrades](/deploying/upgrades): rolling upgrades across replicas.
- [Monitoring](/deploying/monitoring): the per-replica and leader metrics.
- [engine.yaml: server, cache, jobs](/reference/configuration/engine)


# Single-node deployment (/deploying/single-node)

A complete production deployment on one virtual machine with Docker Compose (Caddy for TLS, the engine, PostgreSQL and Meilisearch), with every file to copy, the first start, backups and the same setup under systemd without containers.

The single-node deployment runs everything on one virtual machine: Caddy terminating TLS with an automatic certificate, the engine, PostgreSQL and Meilisearch, under Docker Compose. It suits most destination and content sites, and every file it needs is on this page.

Only Caddy is reachable from outside; everything else talks on the Compose network:

```mermaid
flowchart LR
  people["Visitors and staff"] -->|"HTTPS 443"| caddy
  subgraph vm["One virtual machine"]
    caddy["caddy<br/>TLS, automatic certificate"] -->|"HTTP 8080"| engine["engine<br/>engine-dmo serve"]
    engine --> db[("db<br/>PostgreSQL 16")]
    engine --> search["search<br/>Meilisearch"]
    engine --> media[("storage volume<br/>uploaded media")]
    project["./project<br/>read only"] --> engine
  end
  engine -->|"SMTP 587"| relay["Your mail relay"]
  db -.->|"backup.sh, daily"| offsite["Backups off the machine"]
```

A machine with 2 vCPUs, 4 GB of memory and an SSD is a reasonable start. Size the disk for your media library, the database and its backups, and keep backups off the machine.

## The directory [#the-directory]

```text
meridian/
  compose.yaml
  Caddyfile
  .env              # secrets, never committed
  backup.sh
  restore.sh
  project/          # your project: config/, templates/, public/
    storage/        # empty; the media volume mounts here
```

<Steps>
<Step>
Put your project in `./project` and create its empty `storage` directory (`mkdir project/storage`), which the media volume mounts over.
</Step>
<Step>
Add the deployment settings below to `project/config/engine.yaml`.
</Step>
<Step>
Write `compose.yaml`, `Caddyfile` and `.env` from this page, and generate every secret with `openssl rand -base64 48`.
</Step>
<Step>
Point your domain's DNS at the machine and open ports 80 and 443.
</Step>
<Step>
Start it with `docker compose up -d`. Migrations and the schema are applied before the engine starts, and Caddy waits for the engine to report ready.
</Step>
</Steps>

## The project's engine.yaml [#the-projects-engineyaml]

The settings a single-node deployment relies on. The rest of your `engine.yaml` stays as it is.

```yaml
engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}

server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}
  # Caddy connects from the Compose network's fixed range.
  trusted_proxies: ["172.30.0.0/24"]
  security:
    signing_key: ${SIGNING_KEY}

database:
  url: ${DATABASE_URL}

logging:
  format: json

storage:
  driver: filesystem
  filesystem:
    root: ./storage

media:
  signing_key: ${MEDIA_SIGNING_KEY}

search:
  driver: meilisearch
  meilisearch:
    url: ${MEILISEARCH_URL}
    api_key: ${MEILISEARCH_API_KEY}

mail:
  driver: smtp
  from: "Visit Example <hello@example.org>"
  smtp:
    host: ${SMTP_HOST}
    port: 587
    username: ${SMTP_USERNAME}
    password: ${SMTP_PASSWORD}
    tls: starttls

telemetry:
  metrics:
    # Reachable on the Compose network for Prometheus; never publish this port.
    bind: 0.0.0.0:9090
```

Check it as production will read it before the first start:

```bash
ENVIRONMENT=production engine-dmo check --no-db --project project
```

## compose.yaml [#composeyaml]

```yaml
name: meridian

x-engine: &engine
  image: ${MERIDIAN_IMAGE}
  env_file: .env
  environment:
    ENVIRONMENT: production
    LISTEN_ADDR: 0.0.0.0:8080
    DATABASE_URL: postgres://meridian:${POSTGRES_PASSWORD}@db:5432/meridian?sslmode=disable
    MEILISEARCH_URL: http://search:7700
  read_only: true
  tmpfs: [/tmp]
  volumes:
    - ${PROJECT_DIR:-./project}:/srv/project:ro
    - storage:/srv/project/storage
  networks: [meridian]

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports: ["${HTTP_PORT:-80}:80", "${HTTPS_PORT:-443}:443"]
    environment:
      SITE_ADDRESS: ${SITE_ADDRESS}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      engine: { condition: service_healthy }
    networks: [meridian]

  # A new volume is owned by root; the engine runs as uid 65532.
  storage-init:
    image: busybox:1.37
    command: ["chown", "-R", "65532:65532", "/storage"]
    volumes: [storage:/storage]

  # Migrations and the schema are explicit steps before the engine starts.
  # Each runs once and exits; the image has no shell, so they are two.
  migrate:
    <<: *engine
    command: ["migrate", "up", "--project", "/srv/project"]
    restart: "no"
    depends_on:
      db: { condition: service_healthy }
      storage-init: { condition: service_completed_successfully }

  schema:
    <<: *engine
    command: ["schema", "apply", "--project", "/srv/project"]
    restart: "no"
    depends_on:
      migrate: { condition: service_completed_successfully }

  engine:
    <<: *engine
    command: ["serve", "--project", "/srv/project"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/app/engine-dmo", "health", "--project", "/srv/project", "--readiness"]
      interval: 5s
      timeout: 3s
      retries: 30
    depends_on:
      schema: { condition: service_completed_successfully }
      search: { condition: service_healthy }

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: meridian
      POSTGRES_USER: meridian
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_INITDB_ARGS: --encoding=UTF8 --locale=C.UTF-8
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U meridian"]
      interval: 2s
      timeout: 2s
      retries: 30
    networks: [meridian]

  search:
    image: getmeili/meilisearch:v1.15
    restart: unless-stopped
    environment:
      MEILI_MASTER_KEY: ${MEILISEARCH_API_KEY}
      MEILI_ENV: production
      MEILI_NO_ANALYTICS: "true"
    volumes: [meili:/meili_data]
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:7700/health"]
      interval: 2s
      timeout: 2s
      retries: 30
    networks: [meridian]

# A fixed subnet, so server.trusted_proxies can name Caddy's range.
networks:
  meridian:
    ipam:
      config: [{ subnet: 172.30.0.0/24 }]

volumes:
  pgdata: {}
  meili: {}
  storage: {}
  caddy-data: {}
  caddy-config: {}
```

What it does:

| Service | Role |
|---|---|
| `caddy` | Terminates TLS for `SITE_ADDRESS` with an automatic certificate and forwards everything to the engine. It starts once the engine is healthy |
| `storage-init` | Gives the media volume to the engine's user, then exits |
| `migrate` | `engine-dmo migrate up`, once, then exits |
| `schema` | `engine-dmo schema apply`, once, after `migrate`, then exits. A destructive plan stops here (see [Database and migrations](/deploying/database-and-migrations)) |
| `engine` | `engine-dmo serve`. Healthy once `health --readiness` passes |
| `db` | PostgreSQL 16, `UTF8`, with its data in the `pgdata` volume |
| `search` | Meilisearch, keyed with `MEILISEARCH_API_KEY`, its index in the `meili` volume |

Compose starts the services in this order on every `docker compose up -d`, and a step that fails stops everything after it:

```mermaid
flowchart LR
  init["storage-init<br/>chown, exits"] --> migrate
  dbok["db healthy"] --> migrate["migrate<br/>migrate up, exits 0"]
  migrate --> schema["schema<br/>schema apply, exits 0"]
  schema --> engine["engine<br/>serve"]
  searchok["search healthy"] --> engine
  engine -->|"health --readiness passes"| caddy["caddy<br/>takes traffic"]
```

Only Caddy publishes ports. The engine's port 8080, its metrics port 9090, PostgreSQL and Meilisearch are reachable on the Compose network alone.

## Caddyfile [#caddyfile]

```text
{$SITE_ADDRESS} {
	encode zstd gzip
	reverse_proxy engine:8080
}
```

Caddy sets `X-Forwarded-For` and `X-Forwarded-Proto`. The engine believes them only from `server.trusted_proxies`, which is why the network has a fixed subnet. To serve several sites from one install, list each domain: `www.example.org, www.example.com { ... }` with `SITE_ADDRESS` replaced by the list, and each domain in its site's `site.yaml`.

## .env [#env]

```bash
# Copy beside compose.yaml and fill in. Never commit this file.
# Generate each secret with: openssl rand -base64 48

# The address Caddy serves: a domain for an automatic certificate,
# or http://localhost:8088 to try it locally.
SITE_ADDRESS=www.example.org
# The public URL the engine builds links with.
BASE_URL=https://www.example.org
PROJECT_DIR=./project
MERIDIAN_IMAGE=ghcr.io/cherwell-studio/meridian:0.8.0-vips

POSTGRES_PASSWORD=
SIGNING_KEY=
MEDIA_SIGNING_KEY=
MEILISEARCH_API_KEY=

SMTP_HOST=
SMTP_USERNAME=
SMTP_PASSWORD=
```

`env_file: .env` passes every line to the engine containers; `POSTGRES_PASSWORD` and `MEILISEARCH_API_KEY` also configure the database and search containers through Compose interpolation.

## The first start [#the-first-start]

```bash
docker compose up -d
docker compose ps                          # migrate and schema exited 0; engine healthy
docker compose logs -f engine              # JSON log lines on standard error
```

Then create the first staff user. The command prints a single-use enrolment link to open in a browser:

```bash
docker compose exec engine /app/engine-dmo user create --project /srv/project \
  --email you@example.org --name "Your Name"
```

The first user joins the `administrators` group unless you name another with `--group`. If the database already holds content from another environment, restore it instead (see [Backups and restore](/deploying/backups-and-restore)) and rebuild the search index:

```bash
docker compose exec engine /app/engine-dmo search rebuild --project /srv/project
```

## Deploying a change [#deploying-a-change]

A change to the project (configuration, templates, public files) is a new copy of `./project` and a restart. A new engine version is a new `MERIDIAN_IMAGE`. Either way:

```bash
./backup.sh                               # before anything that migrates
docker compose up -d                      # migrate, schema apply, then the engine restarts
```

Compose re-runs `migrate` and `schema` because they exited; they do nothing when there is nothing to do. The engine is down between the old container stopping and the new one becoming healthy, usually a few seconds. For deploys without that gap, see [Scaling](/deploying/scaling).

## Backups [#backups]

`backup.sh` dumps the database in PostgreSQL's custom format and archives the media volume. Schedule it daily from cron and copy its output off the machine:

```bash
#!/usr/bin/env bash
# Back up the database and the storage volume into BACKUP_DIR, keeping
# KEEP_DAYS of them. Copy BACKUP_DIR off the host afterwards.
set -euo pipefail
cd "$(dirname "$0")"
backup_dir=${BACKUP_DIR:-./backups}
keep_days=${KEEP_DAYS:-30}
project=${COMPOSE_PROJECT_NAME:-meridian}
stamp=$(date -u +%Y%m%dT%H%M%SZ)
mkdir -p "$backup_dir"

docker compose exec -T db pg_dump --format=custom --no-owner -U meridian meridian >"$backup_dir/meridian-$stamp.dump"
docker run --rm -v "${project}_storage:/storage:ro" -v "$(cd "$backup_dir" && pwd):/backup" busybox:1.37 \
	tar -czf "/backup/storage-$stamp.tar.gz" -C /storage .
find "$backup_dir" -name 'meridian-*.dump' -mtime +"$keep_days" -delete
find "$backup_dir" -name 'storage-*.tar.gz' -mtime +"$keep_days" -delete
echo "backed up to $backup_dir/meridian-$stamp.dump and storage-$stamp.tar.gz"
```

```text
15 3 * * * cd /srv/meridian && ./backup.sh && rclone copy backups remote:meridian-backups
```

`restore.sh` and the restore procedure are in [Backups and restore](/deploying/backups-and-restore). The search index is not backed up; `engine-dmo search rebuild` recreates it from the database.

## Monitoring this machine [#monitoring-this-machine]

- Point an uptime check at `https://<your domain>/health?readiness`, which answers 200 when the engine is ready and 503 otherwise.
- Run Prometheus on the Compose network and scrape `engine:9090/_metrics`. [Monitoring](/deploying/monitoring) lists the series and what to alert on.
- Watch the disk: media, the database, Meilisearch and local backups all grow on it.

## Without containers: systemd [#without-containers-systemd]

The same topology runs with the binary under systemd and PostgreSQL, Meilisearch and Caddy (or nginx) installed on the machine. Install the binary as `/usr/local/bin/meridian-engine`, the project at `/srv/meridian` (with `storage/` owned by the `meridian` user), and the environment (`DATABASE_URL`, `SIGNING_KEY` and the rest of `.env`) at `/etc/meridian/engine.env`, readable by root only.

```ini
[Unit]
Description=Meridian content engine
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=meridian
Group=meridian
EnvironmentFile=/etc/meridian/engine.env
Environment=ENVIRONMENT=production LISTEN_ADDR=127.0.0.1:8080
ExecStart=/usr/local/bin/meridian-engine serve --project /srv/meridian
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
# The engine writes only its storage root.
ReadWritePaths=/srv/meridian/storage
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
NoNewPrivileges=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
RestrictNamespaces=true
LockPersonality=true
CapabilityBoundingSet=
AmbientCapabilities=
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
```

Migrations and the schema are a deploy step before each restart:

```bash
sudo -u meridian env $(cat /etc/meridian/engine.env) ENVIRONMENT=production \
  meridian-engine migrate up --project /srv/meridian
sudo -u meridian env $(cat /etc/meridian/engine.env) ENVIRONMENT=production \
  meridian-engine schema apply --project /srv/meridian
sudo systemctl restart meridian
```

With the reverse proxy on the same machine, set `server.trusted_proxies: ["127.0.0.1/32"]`. `TimeoutStopSec=30` matches the engine's default `server.shutdown_grace` of 30 seconds.


# Storage and media (/deploying/storage-and-media)

Where uploaded originals and generated image derivatives are stored (a local or shared filesystem, or an S3-compatible bucket), how media is served and cached, putting a CDN in front, upload limits, and keeping derivatives in check.

Every uploaded file and every image derivative the engine generates lives in one blob store, chosen by `storage.driver`. Everything else (the media library's records, alt text, rights, focal points) is in the database. A backup is therefore the database and the store together.

## Choose a driver [#choose-a-driver]

| Driver | Use when |
|---|---|
| `filesystem` (default) | One machine, or several replicas that mount the same network filesystem |
| `s3` | Several replicas without a shared filesystem, or when you want the provider's durability. Any S3-compatible service: Amazon S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi, DigitalOcean Spaces and others |

At boot the engine proves the store works before it serves: a filesystem root must be writable, and a bucket must accept a write, a read back and a delete within 30 seconds. A store that fails stops the boot with an error naming the store and the step that failed, not the first upload.

## Filesystem storage [#filesystem-storage]

```yaml
storage:
  driver: filesystem
  filesystem:
    root: ./storage
```

| Key | Default | Meaning |
|---|---|---|
| `storage.filesystem.root` | `./storage` | The directory, relative to the project directory or absolute |
| `storage.filesystem.shared` | `false` | Declares that `root` is one filesystem every replica mounts (NFS, Amazon EFS, a shared volume) |

The root must be writable by the engine's user (uid 65532 in the container images). The engine creates what it needs below it:

```text
storage/
  originals/ab/ab12...e9.jpg            # each upload, named by its SHA-256
  derivatives/<asset id>/<hash>/1200.webp
```

With `server.replicas` above 1, the filesystem driver is refused unless `storage.filesystem.shared: true` says every replica sees the same files: an upload that lands on one replica's local disk is missing on the others. `shared: true` with one replica is a warning.

## S3-compatible storage [#s3-compatible-storage]

```yaml
storage:
  driver: s3
  s3:
    endpoint: ${S3_ENDPOINT:-}
    region: ${S3_REGION:-eu-west-2}
    bucket: ${S3_BUCKET}
    access_key_id: ${S3_ACCESS_KEY_ID}
    secret_access_key: ${S3_SECRET_ACCESS_KEY}
```

| Key | Default | Meaning |
|---|---|---|
| `storage.s3.endpoint` | Empty | The service's base URL, `http` or `https` with no path, such as `https://<account>.r2.cloudflarestorage.com` or `http://minio:9000`. Empty for Amazon S3, which is addressed by region |
| `storage.s3.region` | `eu-west-2` | Required. `auto` for Cloudflare R2; MinIO uses `us-east-1` unless configured otherwise |
| `storage.s3.bucket` | Empty | Required. The bucket must exist |
| `storage.s3.access_key_id` | Empty | Required |
| `storage.s3.secret_access_key` | Empty | Required. A secret: always `${VAR}` |
| `storage.s3.path_style` | `false` | Address the bucket as `endpoint/bucket/key` rather than `bucket.endpoint/key`. MinIO and some other services need `true` |
| `storage.s3.public_base_url` | Empty | The `https` origin of a CDN in front of the engine's `/media/` path (below). Media addresses are written on it |

The credentials need to put, get, delete and list objects in the bucket. The bucket does not need to be public: the engine reads from it and serves media itself. A plain `http` endpoint is a warning in production unless it is on a private network the engine alone reaches.

## How media is served [#how-media-is-served]

The engine serves every media file from its own `/media/` path, on every site's host:

| Address | What it is | Caching |
|---|---|---|
| `/media/<asset>/<hash>/<slug>-<width>.<ext>` | A derivative: one image at one width and format, named by a signed hash of the asset, its version, its focal point and crop, and the transform | `public, max-age=31536000, immutable`. The address changes whenever any of those change |
| `/media/<asset>/o<version>/<name>` | The original as uploaded: documents, audio, video, SVG, and an image's own URL | `immutable`: a replaced file is a new version with a new address |

A derivative is generated on its first request and stored. While it cannot be generated, the request is answered with the original (which the browser scales), the failure is logged and counted, and the next request tries again. Byte ranges are answered from the store, so audio and video seek and a large PDF loads in parts. Originals are served so that they cannot run script on the site's origin.

The hash is signed with `media.signing_key`, or a key derived from `server.security.signing_key` when that is unset, so nobody can ask the engine to generate a crop or size your templates never use. Changing either key changes every derivative address. [Images](/templates/images) covers transforms, widths and formats.

### A CDN in front [#a-cdn-in-front]

Because every media address is immutable, any CDN can cache `/media/` for a year. Two ways to put one in front:

| Approach | How |
|---|---|
| The whole site behind the CDN | Point the CDN at the engine for every path. Media is cached by its `Cache-Control`; pages are not cached by a shared cache unless you configure it |
| A media host of its own | Create a CDN origin that forwards `/media/` to the engine, give it a host such as `media.example.org`, and set `storage.s3.public_base_url: https://media.example.org`. The engine then writes every media address on that origin. This works with the `s3` driver only |

## Upload limits [#upload-limits]

| Key | Default | Meaning |
|---|---|---|
| `media.max_upload_bytes` | `50MB` | The largest file an upload may carry. Sizes take `B`, `KB`, `MB`, `GB` (binary: 1MB is 1,048,576 bytes) |
| `media.max_pixels` | `50000000` | The largest image, in pixels (width times height), the pipeline decodes. At least 1,000,000 |
| `media.accept` | JPEG, PNG, WebP, AVIF, PDF, GPX | The media types an upload may have |
| `media.strip_exif_gps` | `true` | Remove GPS coordinates from an image's EXIF data on upload |
| `server.max_request_bytes` | `25MB` | Every other request body. A multipart upload may be up to `media.max_upload_bytes` plus 1MB |

A reverse proxy in front of the engine has its own body limit (nginx's `client_max_body_size` is 1MB by default); raise it to at least `media.max_upload_bytes`. Caddy has no limit by default. HEIC uploads need the `-vips` image or a build linked against libvips.

## Keeping derivatives in check [#keeping-derivatives-in-check]

Derivatives accumulate as templates and transforms change. A scheduled task, `media.prune_derivatives`, runs daily and removes:

- every derivative of a deleted asset;
- derivatives not served or warmed for `media.derivatives.keep_unused` (default `90d`);
- once unused for a day, derivatives of an old version of an asset, or of a transform definition nothing produces any more.

Run it by hand, and see the store's size:

```bash
engine-dmo media stats                    # the library's size, derivatives by transform and format, alt text coverage
engine-dmo media prune --dry-run          # what would go, and the bytes it would free
engine-dmo media prune --older-than 30d
```

After a deploy that changes transforms, generate the derivatives the published pages use before visitors ask for them:

```bash
engine-dmo media warm --dry-run           # count what is missing
engine-dmo media warm                     # render every published page in process and generate what they reference
engine-dmo media warm --shard 0/4         # one quarter of the pages; run 1/4, 2/4 and 3/4 elsewhere in parallel
```

## Moving between drivers [#moving-between-drivers]

There is no built-in copy between drivers. To move from `filesystem` to `s3`, copy the whole storage root into the bucket with its paths unchanged (for example with `aws s3 sync ./storage s3://<bucket>/` or `rclone copy`), switch `storage.driver`, and restart. Stop uploads (or the engine) while you copy, so nothing lands in the old store after the copy starts.

## Related [#related]

- [Backups and restore](/deploying/backups-and-restore): backing up the store with the database.
- [Scaling](/deploying/scaling): storage for several replicas.
- [Media](/features/media): the media library itself.


# Upgrades (/deploying/upgrades)

The production procedure for moving an install to a new engine version (check in CI, back up, migrate, apply the schema, roll out, verify), how a rolling upgrade behaves across replicas, and how to roll back.

An upgrade is a new binary or image against the same project and database. The project usually needs no change; the database needs the new version's migrations. [Upgrading the engine](/getting-started/upgrading-the-engine) explains what ties a project to an engine (`engine.version`, the template contract and the migrations). This page is the production procedure.

## Before the upgrade [#before-the-upgrade]

<Steps>
<Step>
**Read the release notes** for every version between yours and the target: what changed, the migrations each brings and any project change it needs.
</Step>
<Step>
**Check the project against the new engine in CI**, with the new image or binary and the production environment:

```bash
ENVIRONMENT=production engine-dmo check --no-db
engine-dmo check --no-db --contract-report
```

`check` exits 3 when anything is invalid. `--contract-report` lists template usage the next template contract removes, each with its replacement.
</Step>
<Step>
**Rehearse on staging**: restore last night's production backup into staging, run the new engine's `migrate up` against it, and note how long each migration took (`migrate up` prints each with its time and class). A `bounded` migration on a large table is the one to plan around.
</Step>
</Steps>

## The upgrade [#the-upgrade]

<Steps>
<Step>
**Back up the database** and note the backup's name. Migrations have no down step.
</Step>
<Step>
**See what will run**, with the new binary:

```bash
engine-dmo migrate status   # exits 2 when migrations are pending
```
</Step>
<Step>
**Apply the migrations and the schema**, with the new binary and the production environment:

```bash
engine-dmo migrate up
engine-dmo schema apply
```
</Step>
<Step>
**Roll out the new binary** to every replica (restart the service, or deploy the new image tag).
</Step>
<Step>
**Wait for readiness** on each replica: `engine-dmo health --readiness --wait 120s`, or your orchestrator's readiness probe on `/health?readiness`.
</Step>
<Step>
**Verify**: `engine-dmo version` reports the new version; `engine-dmo doctor` shows no errors; the admin's diagnostics screen and your error reporter are quiet.
</Step>
<Step>
**Warm**: `engine-dmo warm` repairs the search index, requests the pages the page cache warms and reports each page's status and time. Add `--media` to queue image derivative generation for every published page.
</Step>
</Steps>

## Rolling upgrades with several replicas [#rolling-upgrades-with-several-replicas]

Run `migrate up` and `schema apply` once, as a separate step (a Kubernetes Job, a pre-deploy task, a one-off container), before the new replicas start. Do not rely on `migrate.on_boot: apply` with several replicas: the first replica would migrate inside its own start-up, under the orchestrator's start timeout.

The migration step runs once, between the old replicas and the new ones:

```mermaid
sequenceDiagram
  participant O as Old replicas
  participant J as One-off step (new binary)
  participant DB as PostgreSQL
  participant N as New replicas
  O->>DB: keep serving
  J->>DB: migrate up, under the migration lock
  J->>DB: schema apply
  Note over O: readiness checks only the<br/>migrations they know
  N->>DB: start: every known migration applied?
  DB-->>N: yes
  N->>N: health --readiness passes
  Note over O,N: the load balancer moves traffic to the new replicas
  O->>O: stopped
```

What each process does during the rollout:

| Process | Behaviour |
|---|---|
| A second `migrate up` started at the same time | Waits on the migration lock, then finds nothing to do |
| An old replica still running | Keeps serving. Its readiness checks only the migrations it knows, which are all applied |
| An old replica that restarts | Starts: migrations newer than the binary are not treated as pending or drift. Whether its code is correct against the new tables is release-specific; the release notes say when old and new must not run together |
| A new replica | Starts once every migration it knows is applied; refuses (exit 2) if `migrate up` has not run |

## Rolling back [#rolling-back]

| Situation | Roll back by |
|---|---|
| The new version brought no migrations | Deploy the previous binary or image tag |
| Migrations ran, and the release notes say the previous version runs on them | Deploy the previous binary or image tag |
| Migrations ran, and the previous version cannot run on them | Stop the engine, restore the backup taken before the upgrade, deploy the previous version. Content written since the backup is lost |

Keep the previous image tag and the pre-upgrade backup until the new version has run in production for long enough to trust it.

## Related [#related]

- [Database and migrations](/deploying/database-and-migrations)
- [Backups and restore](/deploying/backups-and-restore)
- [Monitoring](/deploying/monitoring)


# Affiliates (/dmo/affiliates)

How a site earns as an affiliate publisher: programmes with networks or direct deals, tracked links under /go/, the disclosure templates print, importing conversions by CSV, network connectors or a signed postback, the postback's signature and body, and the affiliate commands.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The affiliates module makes the site an affiliate publisher. Staff set up **programmes** with merchants, through an affiliate network or as a direct deal with a business. A link to a merchant, in a link field or in rich text, then becomes a tracked first-party redirect under `/go/`, marked `rel="sponsored"`, which templates can tell apart to print a disclosure. The conversions a network reports are imported and matched to the clicks that led to them, so each programme's and each page's earnings are known.

Editors write ordinary links; nothing in the content changes. The tracking is added as the page renders.

## Networks [#networks]

The engine knows these networks. `engine-dmo affiliates networks` prints each one with the settings it needs and the export columns it reads.

| Key | Network | Site account settings | Programme settings | Tracks hosts | Reporting API |
|---|---|---|---|---|---|
| `awin` | Awin | `publisher_id` | `advertiser_id` | | yes |
| `booking` | Booking.com | `aid` | | `booking.com` | |
| `cj` | CJ | `website_id` | `ad_id`, `tracking_domain` (default `www.anrdoezrs.net`) | | |
| `direct` | A direct deal with one business | | `click_param` (default `ref`), or `template` with `{url}` and `{click}` | | |
| `getyourguide` | GetYourGuide | `partner_id` | | `getyourguide.com` and its country domains | |
| `impact` | Impact | `media_partner_id`, `account_sid` (for the API) | `tracking_domain`, `ad_id`, `campaign_id` | | yes |
| `partnerize` | Partnerize | | `camref` | | |
| `tiqets` | Tiqets | `partner` | | `tiqets.com` | yes |
| `tracked` | A link built in the network's own dashboard, sent on as it is; clicks are counted, conversions imported by hand and match no click | | | | |
| `viator` | Viator | `pid`, `mcid` | | `viator.com` | |

A site's account settings for a network are entered once on the admin's **Networks** screen (under Affiliates). Each network passes the click id the way it expects (as a label, campaign or parameter), which is how a reported conversion finds its click.

## Programmes and links [#programmes-and-links]

Staff with `affiliates.manage` set up programmes on the admin's **Programmes** screen. A programme has:

| Setting | Meaning |
|---|---|
| Network | One of the keys above |
| Name | As staff see it, and as `link.affiliate.programme` |
| Merchant | Optionally a CRM [organisation](/dmo/crm); a direct deal with a business always is one. Its name is `link.affiliate.merchant`. |
| Hosts | The merchant's hosts. Defaults to the network's own hosts. |
| Track links to these hosts | (`auto_link`, on by default) Any link to one of the hosts, or a subdomain, is tracked through the programme |
| Programme settings | The network's programme settings above |
| Status | `active`, `paused` or `ended` |
| Starts, ends | Optional dates bounding when it tracks |
| Terms | Free text: the commission agreed |

and its **managed links**, each a slug, a name and a destination. A managed link is written in content as `/go/<slug>` (or the site's full address of it), and a link whose destination is exactly a managed link's destination is treated as that managed link. Retire a managed link when it should stop being offered.

A link is tracked when it is a managed link, or when it goes to a host of an active programme with host tracking on; the most specific host wins. A programme that is paused, ended or outside its dates still sends visitors on, to the merchant, untracked.

## On the public site [#on-the-public-site]

Every link a page renders, from a `link` field or inside rich text, passes through the module. A tracked link:

- points at the site's own `/go/<slug>` (a managed link) or `/go/u/<token>` (a host-tracked link, signed so it cannot be forged or credited to another page);
- carries `rel="sponsored"`;
- has `isAffiliate` true and `affiliate` set.

| Link property | Meaning |
|---|---|
| `link.isAffiliate` | Whether the link goes through an affiliate programme |
| `link.affiliate.programme` | The programme's name |
| `link.affiliate.merchant` | The merchant: the organisation's name, or the programme's |
| `link.affiliate.network` | The network's name |

| Global | Meaning |
|---|---|
| `hasAffiliateLinks(value)` | Whether a value (an entry, with its relations) holds any affiliate link: use it to print the disclosure a page needs |

```jinja title="templates/_shared/listing/entry.html"
{% if hasAffiliateLinks(listing) %}<p class="affiliate-disclosure">{{ t("affiliate.disclosure") }}</p>{% endif %}
{% if listing.website %}
<p><a href="{{ listing.website.url|url }}"{% if listing.website.rel %} rel="{{ listing.website.rel }}"{% endif %}>{{ listing.website.text }}</a>
{% if listing.website.isAffiliate %}<span class="affiliate-badge">{{ t("affiliate.badge", "merchant", listing.website.affiliate.merchant) }}</span>{% endif %}</p>
{% endif %}
```

Print `rel` from the link, as above, so `sponsored` reaches the page.

When a visitor follows the link, the redirect builds the network's tracked link with a fresh click id, records the click against the programme and the page it was on, and sends the visitor on. One visitor's clicks on one programme are counted at most 20 times an hour; past that they are still sent on and nothing is counted. Clicks are kept for 400 days, long enough for a network to report a stay booked a year ahead.

From the click to the earnings it led to:

```mermaid
sequenceDiagram
  participant V as Visitor
  participant S as Your site
  participant M as Merchant (via network)
  participant N as Network
  V->>S: GET /go/<slug> or /go/u/<token>
  S->>S: record the click with a new click id
  S-->>V: redirect to the network's tracked link
  V->>M: books or buys
  M->>N: reports the sale with the click id
  N->>S: conversion by CSV import, API sync or signed postback
  S->>S: match the click id, credit the programme and page
```

## Conversions [#conversions]

A conversion is a sale a network reports: a transaction id, the click id it came from (when it came through a tracked link), a status, the commission, and optionally the sale amount, currency and when it happened. Importing the same transaction again updates it in place, so a later report that moves `pending` to `approved` never counts it twice.

| Status | Words the module reads as it (any case, spaces, underscores and hyphens ignored) |
|---|---|
| `pending` | pending, open, new, booked, confirmed |
| `approved` | approved, validated, locked, completed, cleared |
| `declined` | declined, rejected, reversed, cancelled, canceled, deleted, refunded |
| `paid` | paid |

Each network may add words of its own. A conversion whose click id matches a click is credited to that click's programme and page; one with no known click is unmatched, or credited to a fallback programme if the import names one. The admin's **Conversions** screen lists them, and the **Report** screen shows earnings by programme and by page.

Conversions arrive in three ways.

### 1. A CSV export [#1-a-csv-export]

Upload a network's transaction export on the Conversions screen, or:

```bash
engine-dmo affiliates import --network awin --file transactions.csv --site main --dry-run
engine-dmo affiliates import --network awin --file transactions.csv --site main
```

| Flag | Meaning |
|---|---|
| `--network` | The network the export is from; its column mapping is used |
| `--file` | The CSV file. Comma, semicolon or tab separated, detected from the first line. At most 100,000 rows. |
| `--site` | The site the conversions are for (default: the default site) |
| `--column field=Column` | Name a column by hand, repeatable: `--column id="Order Ref" --column occurred_at=Created`. The fields are `id`, `click`, `status`, `amount`, `commission`, `currency`, `occurred_at`. |
| `--date-layout` | A Go time layout for dates that are not ISO 8601, such as `02/01/2006` for day first. A date without a zone is UTC. Day-first and month-first dates are never guessed. |
| `--programme` | The programme id a conversion with no known click is credited to |
| `--dry-run` | Report what the export holds and write nothing |

The transaction id, the status and the commission are required in every row; a row that cannot be read is reported with its line and the rest are imported. Amounts may carry currency signs and grouping separators (`1,234.50` and `1.234,50` are both read as 1234.50).

A direct deal's business reports in the module's own format, which any network's export can also be reshaped into:

```csv title="brewery-october.csv"
id,click,status,amount,commission,currency,occurred_at
T-1042,8f3c2a91d0,approved,45.00,4.50,GBP,2026-10-03T14:20:00Z
T-1043,,pending,30.00,3.00,GBP,2026-10-05
```

### 2. A network's reporting API [#2-a-networks-reporting-api]

Awin, Impact and Tiqets can be connected, after which the engine reads their conversions every 6 hours, looking back 45 days. Store the site's secret for the network (Awin's token, Impact's auth token with the Account SID set on the Networks screen, or Tiqets' token):

```bash
AWIN_TOKEN=... engine-dmo affiliates connect --network awin --site main --secret-env AWIN_TOKEN
engine-dmo affiliates sync --network awin --site main --days 45
```

`connect` reads the secret from the named environment variable or from standard input, never from an argument, and stores it sealed with the install's key; it is never printed. The Networks screen can also connect and sync. Booking.com, GetYourGuide and Viator have no usable reporting API and stay on CSV.

### 3. The signed postback [#3-the-signed-postback]

A network or a business's own system can push conversions as they happen. Make a secret for the site and network:

```bash
engine-dmo affiliates postback-key --network direct --site main
```

The secret is printed once and stored sealed; running the command again replaces it, which is how a leaked secret is rotated. Until a site has a secret for a network, its postback address answers 404.

The sender posts JSON to `/affiliates/postback/<site>/<network>` on the site's host:

```http
POST /affiliates/postback/main/direct HTTP/1.1
Content-Type: application/json
Meridian-Signature: t=1793611200,v1=5d41402abc4b2a76b9719d911017c592...

{"conversions": [
  {"id": "T-1042", "click": "8f3c2a91d0", "status": "approved", "amount": "45.00",
   "commission": "4.50", "currency": "GBP", "occurred_at": "2026-10-03T14:20:00Z"}
]}
```

| Part | Rule |
|---|---|
| `Meridian-Signature` | `t=<unix seconds>,v1=<signature>`, where the signature is the lowercase hex HMAC-SHA256, keyed with the secret, of the time, a full stop and the raw body (`t + "." + body`). Several `v1=` values may be given. |
| Time | Within 5 minutes of the server's clock |
| Body | At most 1 MB; `conversions` holds 1 to 1000 objects with exactly the keys `id`, `click`, `status`, `amount`, `commission`, `currency`, `occurred_at` (strings). Unknown keys are refused. |
| Rate | At most 60 accepted postbacks a minute per site and network |
| Replay | A request with a signature already received is refused |

| Response | Meaning |
|---|---|
| `200` | `{"import": "...", "inserted": n, "updated": n, "unmatched": n, "problems": [...]}` |
| `400` | The body is not a postback |
| `401` | The signature is missing, malformed, stale or wrong |
| `404` | No such site or network, or no secret for it |
| `409` | This postback was already received |
| `413` | The body is larger than 1 MB |
| `429` | Too many postbacks, or too many failed signatures from the address; retry after a minute |

Signing in a shell, for a test:

```bash
body='{"conversions":[{"id":"T-1","click":"","status":"pending","amount":"","commission":"2.50","currency":"GBP","occurred_at":"2026-11-01T10:00:00Z"}]}'
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "https://www.example.org/affiliates/postback/main/direct" \
  -H "Content-Type: application/json" -H "Meridian-Signature: t=$t,v1=$sig" --data "$body"
```

## Seeding programmes [#seeding-programmes]

A seed set may hold programmes under `affiliates/<key>.yaml`, which `engine-dmo seed apply` creates (see [Seed data](/content-modelling/seeding-and-importing)):

```yaml title="seed/affiliates/booking.yaml"
network: booking
name: Booking.com
account: { aid: "1234567" }
terms: "4% of each stay's value, confirmed after checkout."
links:
  - { slug: wharf-hotel, name: The Wharf Hotel on Booking.com, destination: "https://www.booking.com/hotel/gb/the-wharf.html" }
```

| Key | Meaning |
|---|---|
| `network`, `name` | Required |
| `site` | The site; the default site when absent |
| `organisation` | A seed organisation's key: the merchant |
| `hosts`, `params`, `auto_link` | Hosts, programme settings, and host tracking (default `true`) |
| `account` | The site's account settings for the network |
| `status`, `starts`, `ends` | `active`, `paused` or `ended`; relative dates such as `-200d` |
| `terms` | Free text |
| `links` | Managed links: `slug`, `name`, `destination`, `retired` |
| `traffic` | Generated clicks and conversions for a demonstration site |

## Commands [#commands]

| Command | What it does |
|---|---|
| `engine-dmo affiliates networks` | Every network, its settings and the export columns it reads (no database) |
| `engine-dmo affiliates import ...` | Import a CSV export |
| `engine-dmo affiliates connect --network <n> [--site] [--secret-env <VAR>]` | Store a reporting API secret |
| `engine-dmo affiliates sync [--network] [--site] [--days 45]` | Read the connected networks' conversions now |
| `engine-dmo affiliates postback-key --network <n> [--site]` | Make or replace the postback secret, printed once |

## Permissions [#permissions]

| Permission | Allows | Built-in roles |
|---|---|---|
| `affiliates.view` | The programmes, conversions, report and networks screens | administrator, partnership-manager, analyst |
| `affiliates.manage` | Changing programmes, links and accounts, importing, connecting | administrator, partnership-manager |


# Claims (/dmo/claims)

How a business claims its organisation from the public site, how the claim is verified and scored from weighted signals, how staff review it, what approval does, every claims setting in engine.yaml and the claim commands.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A claim is how a business that has no portal account takes control of its entry. Someone fills in a short form ("Is this your business?"), proves their email address, and the engine gathers evidence for staff: whether their address matches the business's website or listed email, what the business's existing contacts say, and the result of a phone call or a posted code. Staff approve or reject; on approval the claimant becomes the organisation's `owner` and receives a portal invitation, and every existing contact is told, which is the control that catches a fraudulent claim after the fact.

A claim is always of an existing CRM [organisation](/dmo/crm). It does not create organisations.

## Linking to the claim form [#linking-to-the-claim-form]

The form is part of the portal, at `{portal path}/claim/{organisation id}` on the site's host. Link to it from a listing page that has an organisation:

```jinja title="templates/_shared/listing/entry.html"
{% if entry.organisation %}
<p><a href="/members/claim/{{ entry.organisation.id }}">{{ t("listing.claim") }}</a></p>
{% endif %}
```

A claim needs an organisation, so a listing a business could claim must have one: in a seed, an `organisations/<key>.yaml` with at least a `name`, and `organisation: <key>` on the listing. Use your site's portal path in place of `/members` (`server.portal_path`, or the `path` in the site's `portal.yaml`). There is no template helper that builds this address, so the path is written into the template. On a multisite install whose sites use different portal paths, put the link in each site's own template root (`templates/<site>/`) rather than in `_shared`, or the shared template links one site's visitors to another's path.

The form is open while `auth.member.registration` is `claim` (the default). With `invite_only` it answers not found, while links already sent for earlier claims keep working.

## How a claim proceeds [#how-a-claim-proceeds]

<Steps>
<Step>

**Submitted.** The claimant gives their name, email address, their role at the business and an optional message. No account is needed. The form asks the browser for a small proof of work (16 bits of `sha256` over its `_ts` value followed by a decimal number in `_pow`, and optional: a claim without one is only never approved automatically) and is rate limited; it answers the same way whether or not the business has contacts and whether or not the address can receive mail, so it cannot be used to find out who runs a business. The claim is `pending`.

</Step>
<Step>

**Verified.** The claimant follows the link mailed to them within `claims.verification_ttl`. To read that mail on a development install, see [Reading mail in development](/features/mail#reading-mail-in-development). The engine records the automatic signals, mails each current contact of the organisation a one-click "approve" or "object" check (when `contact_approval` is on), notifies the staff who review claims on the site, and the claim is `verified`. Claims never verified expire.

</Step>
<Step>

**Evidence gathered.** Contacts answer, staff record a phone call back, or staff send a letter with a code that the claimant types into their claim's status page. Each adds a weighted signal and the score is recomputed. An objection from a contact moves the claim to `held`.

</Step>
<Step>

**Decided.** Staff approve or reject from the queue. With `auto_approve` on, a verified claim whose score reaches the threshold and whose form passed the proof of work is approved by the engine.

</Step>
</Steps>

On **approval** the claimant is linked to the organisation as `owner` and sent a portal invitation (which expires after `portal.invitations.expiry`), and, with `notify_existing_contacts` on, every other current contact is told. On **rejection** the claimant is told, with the reason. A claimant can **withdraw** a claim.

```mermaid
stateDiagram-v2
  [*] --> pending : form submitted
  pending --> verified : email link followed<br/>within verification_ttl
  verified --> held : a contact objects
  verified --> approved : staff approve, or<br/>auto_approve at the threshold
  held --> approved : staff approve
  verified --> rejected : staff reject
  held --> rejected : staff reject
  pending --> withdrawn : withdrawn
  verified --> withdrawn : withdrawn
  held --> withdrawn : withdrawn
  approved --> [*]
  rejected --> [*]
  withdrawn --> [*]
```

A claim whose link is never followed stays `pending` after the link expires; the claimant can start a new one. A `held` claim is never approved automatically.

| Status | Meaning |
|---|---|
| `pending` | Submitted, email not yet verified |
| `verified` | Email verified, waiting for a decision |
| `held` | A current contact objected |
| `approved` | Approved; the claimant is an owner |
| `rejected` | Rejected with a reason |
| `withdrawn` | Withdrawn |

## Signals and the score [#signals-and-the-score]

The score is the sum of the signals' weights, kept between 0 and 100. It is evidence for a person, not a decision.

| Signal | When | Default weight |
|---|---|---|
| `email_domain_match` | The claimant's email domain is the registrable domain of the organisation's website (method `email_domain`) | 50 |
| `listed_email_match` | The claimant's address is the organisation's own email or a current contact's (method `listed_email`) | 60 |
| `contact_approval` | A current contact approved the claim (method `contact_approval`) | 70 |
| `contact_objection` | A current contact objected; the claim is held | -100 |
| `phone_callback` | Staff recorded a call back to the business (method `phone_callback`) | 60 |
| `post_code_returned` | The claimant entered the code from a posted letter (method `post`) | 60 |
| `free_provider_only` | The address is at a free mail provider and nothing else supports the claim; withdrawn once a positive signal arrives | -20 |
| `prior_rejection` | The same address had a claim on the organisation rejected in the last year | -30 |
| `manual` | Staff attested to the claimant themselves | 100 |

The admin shows a score of 80 or more as strong, 40 or more as moderate, and anything lower as weak.

## Reviewing claims [#reviewing-claims]

Staff with `crm.claim.review` on the site work the **Claims** queue (under Members), which shows verified and held claims first. On a claim they see the score, every signal with its detail, the contacts' answers and the letter, and can:

| Action | Effect |
|---|---|
| Approve | As above |
| Reject | With a reason the claimant reads |
| Record a call back | Adds `phone_callback`, with the outcome and a note |
| Attest | Adds `manual`, with a note |
| Ask the claimant | Mails the claimant a question |
| Send a letter | Generates a code and a printable letter to post to the business's address. The code is shown once. The claimant has `post.code_ttl` and `post.max_attempts` to enter it. |
| Withdraw | Withdraws the claim |

Inviting someone from an organisation's page in the admin records a claim approved by staff, with a `manual` signal.

## Configuration [#configuration]

```yaml title="config/engine.yaml"
claims:
  verification_ttl: 7d
  notify_existing_contacts: true
  free_provider_list: bundled
  methods:
    email_domain: { enabled: true }
    listed_email: { enabled: true }
    contact_approval: { enabled: true }
    phone_callback: { enabled: true }
    post: { enabled: true, code_ttl: 30d, max_attempts: 5 }
  signals:
    email_domain_match: 50
    free_provider_only: -20
  auto_approve:
    enabled: true
    threshold: 90
```

| Key | Default | Meaning |
|---|---|---|
| `claims.verification_ttl` | `7d` | How long the verification link works |
| `claims.notify_existing_contacts` | `true` | Tell every current contact when a claim is approved |
| `claims.free_provider_list` | `bundled` | The free mail providers for `free_provider_only`: `bundled` is the list shipped with the engine; anything else is a text file, relative to the project directory, of one domain per line with `#` comments |
| `claims.methods.email_domain.enabled` | `true` | Record `email_domain_match` |
| `claims.methods.listed_email.enabled` | `true` | Record `listed_email_match` |
| `claims.methods.contact_approval.enabled` | `true` | Send current contacts the approve or object check |
| `claims.methods.phone_callback.enabled` | `true` | Offer staff the call back |
| `claims.methods.post.enabled` | `true` | Offer staff the posted letter |
| `claims.methods.post.code_ttl` | `30d` | How long a posted code works |
| `claims.methods.post.max_attempts` | `5` | Wrong codes allowed |
| `claims.methods.phone_auto.enabled` | `false` | Reserved: must stay `false`, since no automated phone verification ships |
| `claims.signals.<signal>` | as in the table above | A signal's weight. Keys you leave out keep their defaults. |
| `claims.auto_approve.enabled` | `false` | Let the engine approve claims |
| `claims.auto_approve.threshold` | `80` | The score that approves |

`check` warns when `auto_approve` is on and the threshold is not above the largest automated signal weight (every signal but `manual` and `contact_approval`), since one signal alone could then approve a claim.

## Commands [#commands]

| Command | What it does |
|---|---|
| `engine-dmo crm claims list [--site <site>] [--status verified\|held\|pending\|decided]` | Claims on a site; verified and held by default |
| `engine-dmo crm claims show <id>` | One claim: the score, every signal, the contacts' answers and the letter |
| `engine-dmo crm claims rescore [--dry-run]` | Recompute open claims' scores under the current weights. It never approves. |

All three need the database. Run `rescore` after changing `claims.signals`.

## Templates [#templates]

The claim flow's screens are portal templates: `claim.html` (the form), `claim_sent.html`, `claim_status.html` (where the claimant follows the claim and enters a posted code), `claim_checked.html` (a contact's answer) and `claim_invalid.html`. `engine-dmo portal scaffold --site <site>` copies them for restyling with the rest of the portal; see [Restyling the portal](/dmo/portal-screens-and-actions#restyling-the-portal).


# CRM (/dmo/crm)

Organisations, people and the links between them; custom fields on both; the timeline, tags and smart lists of organisations and people; broadcasts to member contacts; the CSV and XLSX import, merging, duplicates, trash and erasure; and every CRM command.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The CRM holds the businesses and bodies a destination deals with (**organisations**) and the people it deals with (**people**). A person is linked to an organisation as one of its **contacts**, with a job title and a partner role. Everything partner-facing in `engine-dmo` is built on these records: memberships are an organisation's, portal accounts are a person's, listings belong to an organisation, and reports and broadcasts go to contacts.

CRM records are not documents: they are not localised, have no revisions and no publish state, and never appear on the public site. Staff work with them in the admin under **CRM**, and through the commands below.

## Organisations [#organisations]

| Field | Notes |
|---|---|
| `name` | Required |
| `legal_name` | Optional |
| `status` | `prospect`, `active` (the default), `lapsed` or `archived` |
| `email`, `website` | Optional |
| `address`, `phone` | Structured, as the `address` and `phone` field types store them |
| `social` | A list of social profiles |
| `hours` | Opening hours, as the `opening_hours` field type stores them |
| `lat`, `lon` | A point |
| `custom` | The custom fields you declare in `config/crm/organisation.yaml` |
| network | The [network](/dmo/multisite-networks) it belongs to; on creation, the default site's |

An organisation also carries its **memberships** (one per site, see [Partners and the portal](/dmo/partners-and-portal#tiers)), its contacts, its tags, its timeline and the documents it owns.

Create one from the command line, for example in a script that sets up a project:

```bash
engine-dmo crm organisation create '{"name": "Hook Norton Brewery", "status": "active", "email": "tours@hooknorton.example", "website": "https://www.hooknorton.example"}'
```

`--data -` reads the JSON object from standard input. Unknown keys are refused. The keys are `name`, `legal_name`, `status`, `email`, `website`, `address`, `phone`, `social`, `hours`, `custom`, `lat`, `lon` and `network` (a network key).

## People [#people]

| Field | Notes |
|---|---|
| given name, family name, display name | Display name is what lists and mail use |
| phonetic given name, phonetic family name | The reading of each part (furigana), which orders Japanese lists |
| email | Used for sign-in to the portal and for mail |
| phone | Structured |
| marketing consent | When it was given and its source; required for [broadcasts](#broadcasts) |
| `custom` | The custom fields you declare in `config/crm/person.yaml` |
| network | As for organisations |

## Contacts: linking people to organisations [#contacts-linking-people-to-organisations]

A contact is a person linked to an organisation. The link survives a change of job: when someone leaves, the link is ended rather than deleted. Each link has:

| Property | Meaning |
|---|---|
| Job title | Free text, such as "Landlady" |
| Partner role | What the person may do for the organisation in the portal: `owner`, `manager`, `contact`, `billing` or a role of your own. See [Partner roles](/dmo/partners-and-portal#partner-roles). A link with no role is `contact`. |
| Primary | The organisation's main contact |
| Digest opt-out | The person has stopped the monthly report digest |
| Started, ended | An ended link is history; only current links act |

Staff add and edit contacts on the organisation's page. A contact becomes a portal user by accepting an invitation, which staff send from the organisation's page or with `engine-dmo crm invite`, or by an approved [claim](/dmo/claims).

## Custom fields [#custom-fields]

Declare the extra fields of organisations and people in `config/crm/organisation.yaml` and `config/crm/person.yaml`, with the ordinary field grammar. The admin's record pages show them in their own group, smart lists filter on them, the import maps columns to them, and [portal actions](/dmo/portal-screens-and-actions#actions) can let members fill them in.

```yaml title="config/crm/organisation.yaml"
fields:
  - name: coachParking
    type: boolean
    label: { en-GB: Coach parking }
  - name: preferredContactTime
    type: select
    label: { en-GB: Preferred contact time }
    options:
      - { value: morning }
      - { value: afternoon }
```

```yaml title="config/crm/person.yaml"
fields:
  - name: dietaryNeeds
    type: text
    personal: true
    label: { en-GB: Dietary needs }
```

Run `engine-dmo check --fix` to write the ids, then `schema plan` and `schema apply`. `engine-dmo dev field add organisation coachParking --type boolean` does the same in one step.

Values are stored by field id (a select's by option id), so renaming a field or an option moves nothing.

| Rule | Detail |
|---|---|
| Types | `text`, `number`, `boolean`, `select`, `date`, `datetime`, `phone`, `money` |
| Not allowed | A core field's name, `translate:`, child `fields:`, `visible_when:`, `unique:`, a `use:` of a shared field group |
| `personal: true` | Person fields only. Marks personal data: included in a subject access export and cleared when the person is erased. |

`engine-dmo config schema --file crm` prints the file's JSON Schema.

## The timeline [#the-timeline]

Every organisation and person has a timeline in the admin: entries the engine records about the record (for example a message the business sent the team from the portal, or a report digest that could not be delivered because the contact's address is suppressed) and staff notes. A note has a body with mentions, can be pinned, and is either `internal` (staff only, the default) or `member_visible`, in which case the organisation's people see it in the portal and the member API's activity feed. Mentions notify the staff mentioned.

## Tags [#tags]

Organisations, people and documents share the install's tag vocabulary (`config/tags/vocabulary.yaml`, loaded once by `engine-dmo tags import` and then owned by the admin). Staff with `crm.tag.manage` tag records on their pages. See [engine-dmo tags](/reference/cli/tags) for the vocabulary, candidates and the `tags` commands.

## Smart lists of organisations and people [#smart-lists-of-organisations-and-people]

A smart list is a saved query that keeps itself up to date. Lists of documents are a core feature (see [smartList()](/templates/queries#smartlist) and [engine-dmo lists](/reference/cli/lists)); `engine-dmo` adds lists whose `subject` is `organisation` or `person`. They are used as working lists in the admin, as a [broadcast](#broadcasts)'s audience, and from the command line. They are never public: `public: true` is refused for them.

Seed lists live in `config/tags/smartlists.yaml`, which the seed and `engine-dmo tags import` load once; after that the admin owns them.

```yaml title="config/tags/smartlists.yaml"
smart_lists:
  - key: renewal-risk-90
    name: { en-GB: "Renewals due, low engagement" }
    subject: organisation
    query:
      membership: { status: [active], renews_within_days: 90 }
      analytics: { metric: portal_login, period: 180d, lt: 1 }
  - key: coach-friendly
    name: { en-GB: Coach friendly members }
    subject: organisation
    query:
      membership: { tier: [gold] }
      where:
        - { field: custom.coachParking, eq: true }
```

Query keys that apply to organisation and person lists:

| Key | Meaning |
|---|---|
| `tags` | Tag conditions, as for documents |
| `where`, `all`, `any`, `none` | Field clauses and groups, as for documents. A custom field is named by its handle or as `custom.<name>`. |
| `membership` | Organisations (or the people linked to them, or the documents they own) with a membership matching every key given; see below |
| `analytics` | Organisations by an analytics event counted over a period: `metric` (an event name), `period` (a number of days such as `180d`) and exactly one of `lt`, `lte`, `gt`, `gte`, `eq`. Not allowed on a person list. The count includes every event recorded against the organisation, such as `portal_login` or a click on one of its listings. |

`membership` keys:

| Key | Meaning |
|---|---|
| `site` | A site key, or `any`. Defaults to the list's own site, or the site it is run for. |
| `tier` | A list of tier keys. `none` is not allowed: an organisation with no membership has no membership to match. |
| `status` | A list of `pending`, `active`, `lapsed`, `cancelled` |
| `renews_within_days` | Renews between today and that many days from now |
| `renews_after_days` | Renews more than that many days from now |
| `lapsed_within_days` | Lapsed, and ended within that many days |
| `joined_before`, `joined_after` | A date or a relative date |

A list has at most 50 clauses. Organisations and people are always read within the networks the list's site and its reader can see.

| Command | What it does |
|---|---|
| `engine-dmo lists check [--key <key>]` | Validate every smart list, saved and seeded, against the schema and the vocabulary |
| `engine-dmo lists count --key <key> [--site <site>]` | How many rows the list matches now |
| `engine-dmo lists run --key <key> --out <file.csv>` | Write the full set of ids to a CSV file, recorded in the audit log as an export |

All three need the database. `engine-dmo check` does not read `config/tags/smartlists.yaml` at all, so a seeded list cannot be verified without one: after `engine-dmo seed apply` (or `tags import`), run `engine-dmo lists check` against the database to find a bad key, field or tier.

## Broadcasts [#broadcasts]

A broadcast is a message from staff to the contacts a smart list of organisations or people names, such as every member renewing this quarter. It is sent as marketing mail: a person receives it only with recorded marketing consent, and every message carries an unsubscribe link that cannot be removed.

Staff need `broadcast.draft` on the site to compose one and `broadcast.send` to schedule, send or cancel it. The admin's **Broadcasts** screen (under Members) shows, before anything is sent, how many people the list reaches and how many it leaves out and why.

### Who receives it [#who-receives-it]

The recipients are taken in one step when sending starts. A person the list names is left out, and counted against the reason, when they:

| Reason | Meaning |
|---|---|
| `no_consent` | No marketing consent is recorded |
| `unsubscribed` | They unsubscribed |
| `bounced` | Their address bounced |
| `complained` | They marked mail as spam |
| `suppressed` | Their address is on the install's suppression list |
| `no_email` | They have no address |
| `removed` | The record was trashed or erased |

An address shared by two recipients receives the message once.

### Writing one [#writing-one]

The body is Markdown (the public site's safe subset) or Portable Text. Merge fields are written `{{ person.given_name }}` and filled in as text, never as markup:

| Merge field | Value |
|---|---|
| `person.display_name` | The recipient's display name |
| `person.given_name` | The recipient's given name |
| `organisation.name` | The organisation the recipient is a contact of |
| `membership.tier` | That organisation's tier on the site |
| `membership.renews_on` | Its renewal date, in the site's default locale and timezone |

A merge field outside this list is refused. Links in the body go through the first-party redirect `/_b/c/`, so clicks are counted; the unsubscribe link is `/_b/u/`; and an open is recorded through `/_b/o/` only when `mail.broadcast.open_tracking` is on. The message is rendered with the `emails/broadcast.html` template, which a project can override in its template root (`engine-dmo mail templates` shows which file is used).

From the command line, a draft is a YAML or JSON file:

```yaml title="renewals.yaml"
subject: Your membership renews soon
preheader: Three things to check before it does
format: markdown
list: renewal-risk-90
body: |
  Hello {{ person.given_name }},

  {{ organisation.name }}'s {{ membership.tier }} membership renews on {{ membership.renews_on }}.
```

```bash
engine-dmo broadcast draft --file renewals.yaml --site main
engine-dmo broadcast show --id <id>
engine-dmo broadcast test-send --id <id> --to you@example.org
engine-dmo broadcast schedule --id <id> --at 2026-12-01T09:00 --confirm
```

`format` is `markdown` (the default) or `portabletext`, whose body is the blocks as a value or a JSON string. `list` names a smart list by key or id. `draft --id <id>` updates that draft.

| Command | What it does |
|---|---|
| `broadcast list --site <site> [--status <status>]` | The site's broadcasts, newest first |
| `broadcast show --id <id>` | The broadcast, its body and who its list reaches now, with who it leaves out and why |
| `broadcast draft --file <file> [--id <id>] [--site <site>]` | Write a new draft, or update one |
| `broadcast test-send --id <id> --to <address>` | Send a test with `[Test]` before the subject and placeholder merge fields |
| `broadcast schedule --id <id> --at <time> --confirm` | Schedule it: RFC 3339, or `2006-01-02T15:04` in the site's timezone |
| `broadcast send --id <id> --confirm` | Send it now; cannot be taken back |
| `broadcast cancel --id <id>` | Cancel a draft, a scheduled broadcast, or the rest of one being sent (messages already queued still go) |
| `broadcast report --id <id>` | Recipients by delivery state, who was left out, unsubscribes, clicks per link and opens |

A broadcast's statuses are `draft`, `scheduled`, `sending`, `sent` and `cancelled`.

### Sending settings [#sending-settings]

| Key in `engine.yaml` | Default | Meaning |
|---|---|---|
| `mail.broadcast.batch_size` | `50` | Messages queued at a time |
| `mail.broadcast.batch_pause` | `5s` | Wait between batches, on top of the mailer's own rate limit |
| `mail.broadcast.unsubscribe_footer` | on | Cannot be turned off; `false` is refused |
| `mail.broadcast.open_tracking` | `false` | Record opens |
| `mail.broadcast.per_recipient_tracking` | `false` | Record clicks and opens per recipient rather than per broadcast; the footer then says so |

Mail delivery itself (the driver, the sender, bounces and the suppression list) is configured under `mail:`; see [Mail](/features/mail).

## Importing organisations, people and memberships [#importing-organisations-people-and-memberships]

The import reads a CSV or XLSX file through a column mapping, matches each row against the records already held, plans every row as a dry run, and writes through the same rules as the admin. Staff with `crm.import` run it from the admin's **Imports** screen (under Members), which saves each source's mapping so the next file from it maps itself, or from the command line:

```bash
engine-dmo crm import --source chamber-2026 --name "Chamber of commerce list" --file members.csv --map mapping.yaml --dry-run
engine-dmo crm import --source chamber-2026 --file members.csv
```

```yaml title="mapping.yaml"
columns:
  Business: organisation.name
  "Trading email": organisation.email
  Postcode: organisation.address.postal_code
  Contact: person.display_name
  "Contact email": person.email
  "Opted in": person.marketing_consent
  Level: membership.tier
  "Renewal date": membership.renews_on
match: [external_id, email, name_postcode]
country: GB
date_order: dmy
site: main
currency: GBP
consent:
  basis: consent
  evidence: The opt-in box on the 2025 membership renewal form
```

| Mapping key | Meaning |
|---|---|
| `columns` | Column heading to target. A column not named, or named to `""`, is not imported. |
| `match` | Keys tried in order to find a record already held: `external_id`, `email`, `name_postcode`. Empty is all three. |
| `country` | ISO 3166-1 code for addresses and phone numbers whose row names none |
| `date_order` | `dmy` or `mdy`, to read dates written with slashes or dots. Empty accepts ISO 8601 only. |
| `site` | The site a membership is on when no column names one |
| `currency` | A membership amount's currency when no column names one |
| `consent.basis` | `consent` or `soft_opt_in`: the lawful source of a marketing consent column |
| `consent.evidence` | What the person agreed to, where and when; at least 12 characters. Without a documented basis, a consent column is recorded but never becomes marketing consent. |

Targets:

| Entity | Targets |
|---|---|
| Organisation | `organisation.external_id`, `name`, `legal_name`, `status`, `email`, `website`, `phone`, `address.line1`, `address.line2`, `address.locality`, `address.administrative_area`, `address.postal_code`, `address.country`, and `organisation.custom.<name>` |
| Person | `person.external_id`, `display_name`, `given_name`, `family_name`, `email`, `phone`, `job_title`, `primary`, `marketing_consent`, `marketing_consent_date`, and `person.custom.<name>` |
| Membership | `membership.site`, `tier`, `status`, `joined_on`, `renews_on`, `amount`, `currency`, `external_ref` |

`--source` names the source by key and creates it when new (`--name` and `--network` set a new source's name and network). `--map` is saved on the source for its next file. `--dry-run` prints what would be created, updated, skipped and rejected, and writes nothing.

## Duplicates, merging and the trash [#duplicates-merging-and-the-trash]

| Task | How |
|---|---|
| Find likely duplicates | `engine-dmo crm dedupe` scores candidate pairs of organisations and offers them for review in the admin. It uses the configured AI provider's embeddings, which are charged even with `--dry-run`. See [AI assistance](/features/ai-assistance). |
| Merge two records | In the admin (**Merge** under CRM), or `engine-dmo crm merge --subject organisation --keep <id> --merge <id> [--dry-run]`. Everything that pointed at the merged record moves to the kept one, its blank fields are filled from the merged one, and the merged record goes to the trash. |
| Trash and restore | On the record's page; the trash is under CRM. Trashed records disappear from lists, smart lists and `entry.organisation`. |
| Purge | Permanently delete from the trash; needs `crm.organisation.purge` or `crm.person.purge`. |
| Erase a person | `engine-dmo crm erase --person <id> --confirm`, irreversibly: their personal columns and `personal: true` fields are cleared, their sessions and links ended, their address suppressed, and every mention replaced by a tombstone. |
| Answer a subject access request | `engine-dmo sar --email <address> --out <file>` writes everything the install holds about the person to one archive, every custom field included. See [Data protection duties](/deploying/data-protection#subject-access-requests). |

## Commands [#commands]

| Command | What it does |
|---|---|
| `crm organisation create [json] [--data json]` | Create an organisation |
| `crm membership set <organisation-id> --tier <tier> [--site] [--status] [--reason]` | Give an organisation a tier on a site: changes its pending or active membership there, or starts one (`active` by default) |
| `crm invite --organisation <id> --email <address> --name <name> [--role <job title>] [--site]` | Link the contact as the organisation's owner and queue the portal invitation |
| `crm import ...` | See [Importing](#importing-organisations-people-and-memberships) |
| `crm merge ...`, `crm dedupe ...`, `crm erase ...` | See [Duplicates, merging and the trash](#duplicates-merging-and-the-trash) |
| `crm claims list`, `crm claims show <id>`, `crm claims rescore` | The claim queue; see [Claims](/dmo/claims#commands) |
| `lists check`, `lists count`, `lists run` | Smart lists |
| `broadcast ...` | Broadcasts |

Every one needs the database, and every one accepts `--json`. Run `engine-dmo crm <command> --help` for the details.

## Permissions [#permissions]

| Staff permission | Allows |
|---|---|
| `crm.organisation.view`, `.edit`, `.delete`, `.purge` | Organisations |
| `crm.person.view`, `.edit`, `.delete`, `.purge` | People |
| `crm.membership.view`, `.edit` | Memberships on a site |
| `crm.tag.manage` | Tagging records |
| `crm.smartlist.manage` | Saving and editing smart lists |
| `crm.claim.review` | The claim queue on a site |
| `crm.import` | The import |
| `broadcast.draft`, `broadcast.send` | Broadcasts on a site |

The built-in `partnership-manager` role holds the CRM permissions apart from delete and purge; `administrator` holds them apart from purge. See [What engine-dmo adds](/dmo#staff-permissions-the-modules-add).


# Directory (/dmo/directory)

The listing and area types engine-dmo adds, how to extend them, route and facet them, link a listing to the business behind it, and show places, maps, nearby results and enquiries in templates.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The directory module gives a project two core types: a **listing** is a place a visitor looks for (a pub, a museum, a walk's start, a hotel) and an **area** is a place that holds them (a town, a valley, a stretch of coast). They behave like the core `page` and `article` types: you extend them with your own fields, route them, give them templates and list them on index pages. What the module adds on top is the link from a listing to the business behind it, the place facets and [landing pages](/dmo/landing-pages) that cross a place with a category, and the figures that flow back to that business as its [member report](/dmo/member-reports).

## A minimal directory [#a-minimal-directory]

Extend the listing with the fields your sites need, extend the area, load the tag vocabulary, route both, and give each a template. The examples write the locale code `en-GB`: use your site's own codes in every label, or labels fail `check --strict` with `the label of field category has no translation for en`.

```yaml title="config/schema/listing.yaml"
extends: listing
label: { en-GB: Listing }
plural: { en-GB: Listings }
fields:
  - name: description
    type: portable_text
    label: { en-GB: Description }
  - name: heroImage
    type: asset
    label: { en-GB: Main photo }
  - name: address
    type: address
    index: true
    label: { en-GB: Address }
  - name: phone
    type: phone
    index: true
    label: { en-GB: Phone }
  - name: website
    type: link
    kinds: [{ of: url }]
    label: { en-GB: Website }
  - name: openingHours
    type: opening_hours
    holiday_calendar: uk-england-wales
    label: { en-GB: Opening hours }
  - name: area
    type: relation
    to: area
    index: true
    label: { en-GB: Area }
  - name: category
    type: select
    index: true
    label: { en-GB: Category }
    options:
      - { value: stay, label: { en-GB: Places to stay } }
      - { value: eat-drink, label: { en-GB: Eat and drink } }
```

```yaml title="config/schema/area.yaml"
extends: area
label: { en-GB: Place }
plural: { en-GB: Places to go }
fields:
  - name: parent
    type: relation
    to: area
    label: { en-GB: Part of }
```

```yaml title="config/tags/vocabulary.yaml"
tags:
  - key: stay
    kind: topic
    public: true
    label: { en-GB: Places to stay }
    children:
      - key: stay.hotel
        label: { en-GB: Hotels and inns }
  - key: eat-drink
    kind: topic
    public: true
    label: { en-GB: Eat and drink }
    children:
      - key: eat-drink.pub
        label: { en-GB: Pubs }
```

```yaml title="config/sites/main/routes.yaml"
routes:
  - type: page
    uri: "/{slug}"
    priority: 10
  - type: listing
    uri: "/places/{slug}"
    index: "/places"
    paginate: 24
    facets: [area, category]
  - type: area
    uri: "/{slug}"
    nest: true
    index: "/areas"

home: { type: page, slug: home }
```

Without the `priority:`, `check` refuses the two `/{slug}` routes: `routes "/{slug}" (page@en-GB) and "/{slug}" (area@en-GB) are ambiguous: same shape and priority; give one a priority`. The number settles that and hides nothing: a document's address is stored when it is published and looked up by that, so `/about` reaches the page and `/monmouth` the area whichever route has the higher number. One address holds one document, so a page and an area with the same slug cannot both be published. To rule that out, route areas under a word of their own (`/towns/{slug}`, with an index at `/towns`), which needs no priority.

Then write `templates/_shared/listing/entry.html`, `listing/index.html`, `area/entry.html` and `area/index.html` (an index route needs an index template), and run:

```bash
engine-dmo check --fix --project .
```

`check --fix` writes the stable id of every new field, option and route (`fld_`, `opt_`, `rte_`); you never write ids by hand. Then `engine-dmo schema plan` and `engine-dmo schema apply` against your database, as for any schema change (see [Schema changes](/content-modelling/schema-changes)).

## The listing type [#the-listing-type]

These fields are the core of every listing. A project's `extends: listing` file adds fields after them; it cannot remove or change them.

| Field | Type | Required | Notes |
|---|---|---|---|
| `title` | `text` | yes | Translated per locale, indexed |
| `slug` | `slug` | yes | Generated from `title`, per locale |
| `summary` | `text` | yes | Multiline, at most 280 characters, translated |
| `location` | `geo` | yes | The listing's point; not translated |
| `primaryTag` | `relation` to `tag` | yes | Labelled "Category" in the editor; a second-level topic tag from the vocabulary. See [The tag vocabulary](#the-tag-vocabulary) |

## The tag vocabulary [#the-tag-vocabulary]

A listing cannot be published without a `primaryTag`, and that must name a tag in `config/tags/vocabulary.yaml`, so every directory needs this file. `engine-dmo seed apply` loads it, and `engine-dmo tags import` loads it without seeding. Existing keys are left alone, and after that staff own the vocabulary in the admin.

| Key | Rule |
|---|---|
| A child's `key` | The full dotted key: `stay.hotel`, never `hotel`. A key not under its parent stops the import |
| `kind` | `topic`, `audience`, `operational` or `internal`. Default `topic` at the top level; a child takes its parent's |
| `public` | Whether the tag is listed to the public, in the content API's tag list. Default `true` at the top level; a child takes its parent's |
| Levels | Write two. The editor's picker for `primaryTag` offers only `topic` tags at the second level, so a flat vocabulary leaves editors nothing to choose. A seed file is not held to this: it is refused only for a key not in the vocabulary |

`primaryTag` and a `category` select are different things. The select is a short flat list in your schema, changed by a schema change: it is what a route's facet and a [landing page](/dmo/landing-pages) use, and a landing's category may not be a tag. `primaryTag` is what the listing is, as fine as "Pubs", changed by staff without a deployment: a [member report](/dmo/member-reports) compares a business with others sharing it. A seed file gives both: `category: eat-drink` and `primaryTag: { id: eat-drink.pub, type: tag }`.

## The area type [#the-area-type]

| Field | Type | Required | Notes |
|---|---|---|---|
| `title` | `text` | yes | Translated per locale |
| `slug` | `slug` | yes | Generated from `title` |
| `summary` | `text` | no | Multiline, at most 280 characters |
| `boundary` | `geo_shape` | yes | A GeoJSON Polygon or MultiPolygon in WGS 84 |
| `centre` | `geo` | no | When empty, templates read a centre the engine derives from the boundary (`centre.derived` is true). A derived centre has no `staticMap()`; see [Maps](#maps) |

An area is the place type a [landing page](/dmo/landing-pages) hangs from. To put one place inside another (a village inside a valley), give the area a `parent` relation to `area` and route it with `nest: true`, so `/wynd-valley/wyndcombe` sits under its parent's address. Nesting is the core routing feature; see [Routes](/concepts/sites-locales-and-routes).

Both types take every option a core type takes (`sites:`, `structured_data:`, `embed:`, field groups, per-site schema files). See [Content types](/content-modelling/types) and [Fields](/content-modelling/fields) for the field grammar, including `address`, `phone`, `opening_hours`, `geo` and `geo_shape`.

## Linking a listing to its business [#linking-a-listing-to-its-business]

A document of any type can be linked to one CRM [organisation](/dmo/crm), which is then the document's owner. Staff with `crm.organisation.view` see the **Organisation** panel of the document editor, which shows the organisation and its memberships; staff who may edit the document choose the organisation there. A seed document sets it with a top-level `organisation:` naming the seed organisation's file name (`organisation: pebble-porthwynd`); [Organisations and people](/content-modelling/seeding-and-importing#organisations-and-people) has that file's format.

The link is what the rest of the platform reads:

- the organisation's people can edit the listing in the [portal](/dmo/partners-and-portal), within the tier rules of `member_editable`;
- enquiries about the listing reach the organisation's contacts;
- impressions, views and clicks on the listing count towards the organisation's [member report](/dmo/member-reports);
- the listing can be [promoted](/dmo/promotions) by the organisation, and [claimed](/dmo/claims) by a business with no portal account yet.

The organisation must be in the same [network](/dmo/multisite-networks) as the document's owner site.

## Template surface [#template-surface]

The directory and CRM modules add these to every page's template context.

| Name | Kind | What it gives |
|---|---|---|
| `entry.organisation` | entry property (crm) | The organisation behind the entry: `id`, `name`, `legalName`, `website`, `email`, `phone`, `address`, `status`. Null when there is none or it is in the trash. Resolved for the page's own entry only, never for each item of a list. |
| `organisationId` | property of each list item | The id of the organisation that owns the item, on items of an index page and of `promoted()` |
| `entry.landings` | entry property (directory) | On a place: its live landing pages. On a listed document: the landing pages it appears on, the most specific place first. Each item has `title`, `uri`, `url`, `count`, `landing`, `category` (`value`, `label`, `slug`) and `place` (`id`, `title`, `uri`, `url`). Empty when the site declares no landings. |
| `memberTier(entry)` | global (memberships) | The key of the tier the entry's organisation holds on this site, or an empty string when it holds none or the document has no organisation |
| `nearby(entry, km, type)` | global (core) | Published documents of a type within `km` of the entry's point, nearest first, the entry left out. `type` defaults to the entry's own type, `km` to 10 |
| `value.distanceTo(other)` | `geo` helper (core) | The distance in kilometres to another point or place |
| `value.staticMap(...)` | `geo` helper (core) | A map image drawn by the server from your tile provider; see [Maps](#maps) |

A listing page using them, with its address, hours, phone and website. The layout must print `{{ jsonld() }}` beside `{{ head() }}`, or the type's `structured_data` is never printed ([SEO and structured data](/templates/seo-and-structured-data)):

```jinja title="templates/_shared/listing/entry.html"
{% extends "base.html" %}
{% block body %}
<h1>{{ listing.title }}</h1>
<p>{{ listing.summary }}</p>

{% if entry.address %}<address>{{ entry.address.oneLine }}</address>{% endif %}
{% if entry.phone %}<p><a href="{{ reveal(entry, 'phone', entry.phone)|url }}">{{ entry.phone.display }}</a></p>{% endif %}
{% if entry.website.url %}<p><a href="{{ track(entry, 'website', entry.website.url)|url }}" rel="noopener">{{ t("listing.website") }}</a></p>{% endif %}

{% set hours = entry.openingHours %}
{% if hours and not hours.isEmpty %}
<table>
  <caption>{{ t("listing.hours") }}</caption>
  <thead><tr><th scope="col">{{ t("listing.day") }}</th><th scope="col">{{ t("listing.times") }}</th></tr></thead>
  <tbody>
    {% for day in hours.week(now) %}
    <tr{% if day.isToday %} aria-current="date"{% endif %}><th scope="row">{{ day.label }}</th><td>{{ day.periodsLabel }}</td></tr>
    {% endfor %}
  </tbody>
</table>
{% endif %}

<section aria-labelledby="enquire-heading">
  <h2 id="enquire-heading">{{ t("listing.enquire") }}</h2>
  {{ enquiryForm('contact-listing', entry) }}
</section>

{% if entry.organisation %}
<p>{{ entry.organisation.name }}{% if memberTier(entry) == "gold" %} <span class="badge">{{ t("listing.gold") }}</span>{% endif %}</p>
{% endif %}

{% if entry.landings %}
<h2>{{ t("listing.more_like_this") }}</h2>
<ul>{% for l in entry.landings %}<li><a href="{{ l.uri|url }}">{{ l.title }}</a> ({{ l.count }})</li>{% endfor %}</ul>
{% endif %}

{% set close = nearby(entry, 2, "listing") %}
{% if close %}
<h2>{{ t("listing.nearby") }}</h2>
<ul>{% for n in close %}<li><a href="{{ n.url|url }}">{{ n.title }}</a></li>{% endfor %}</ul>
{% endif %}

{{ entry.location.staticMap(width=600, zoom=15) }}
{% endblock %}
```

Every `t()` key the template uses belongs in `config/strings/<locale>.yaml`; `check` warns about a key the catalogue does not have.

`memberTier()` exists so a page can treat a paying member differently, for example to leave other businesses' links off its page. It never varies a page by who is signed in: it reads the listing's organisation, not the visitor.

## Index pages and facets [#index-pages-and-facets]

A listing index is the core index page: `items`, `pagination` and, for each facet the route declares, `facets` (one per facet with `field`, `label`, `selected`, `clearUrl` and `values`). Draw the facets as lists of links in one navigation landmark, and take the `h1` from `t()`, since `page.title` is the type's plural label. See [An index page](/templates/context#an-index-page).

A facet on a single relation to a place type (one whose route nests, or which has a boundary, as `area` does) is a **place facet**. Choosing a place matches documents related to that place, documents related to any place within it, and documents with no place of their own whose point falls inside one of those places' boundaries. Place facets are core and also work in `engine-cms`; landing pages are what the directory adds to them.

When a route declares [landing pages](/dmo/landing-pages), a filter set that matches a live landing page is written as that page's clean path rather than a query string, so facet links lead to the real pages search engines index.

## Maps [#maps]

`staticMap()` on a `geo` value draws the map on the server from the tiles of the provider in `engine.yaml` and serves it from your own site, so a visitor's browser asks no mapping provider for anything. It is a core feature, also in `engine-cms`: the `maps:` keys are in the [engine.yaml content reference](/reference/configuration/engine-content#maps) and the field values in [Places](/content-modelling/fields/places). They are repeated here because a directory is where most maps are drawn.

```yaml title="config/engine.yaml"
maps:
  tiles: https://api.maptiler.com/maps/streets-v2/{z}/{x}/{y}.png?key={key}
  key: ${MAP_TILES_KEY}
  attribution: "© MapTiler © OpenStreetMap contributors"
  max_zoom: 18
```

| Key | Default | Meaning |
|---|---|---|
| `maps.tiles` | none | The tile URL template with `{z}`, `{x}`, `{y}`, and `{key}` where the provider takes the key in the address. Without it `staticMap()` prints nothing. |
| `maps.key` | none | The provider's key, always a `${VAR}` interpolation, written into `{key}` |
| `maps.attribution` | none | The credit the provider's licence requires, shown beneath every map |
| `maps.max_zoom` | `18` | The highest zoom a template may ask for |
| `maps.tile_size` | `256` | The provider's tile edge in pixels |
| `maps.timeout` | `10s` | How long fetching the tiles of one map may take |

`staticMap()` options:

| Option | Default | Meaning |
|---|---|---|
| `width` | `600` | Width in pixels, 64 to 1280 |
| `height` | two thirds of `width` | Height in pixels, 64 to 1280 |
| `zoom` | `15` | 1 to `maps.max_zoom` |
| `alt` | the `map.alt` string, "Map showing where `{name}` is" | The text alternative |
| `name` | the document's title | The place's name in the text alternative |
| `marker` | `true` | `false` leaves the point unmarked |

`staticMap()` works on a listing's `location`, on an address's `geo` and on a `geo_shape`'s `centroid`. It does **not** work on an area's derived centre: when `centre` is empty, `entry.centre.staticMap(...)` prints nothing, and neither `check` nor `render` reports it. Draw an area's map from whichever exists:

```jinja
{% if entry.centre and not entry.centre.derived %}{{ entry.centre.staticMap(width=480) }}{% elif entry.boundary %}{{ entry.boundary.centroid.staticMap(width=480, zoom=12, marker=false) }}{% endif %}
```

## Counting what visitors do [#counting-what-visitors-do]

The member report is built from events the public pages record. Use the core tracking helpers on listing pages and cards so a business's figures are complete:

| In the template | Records |
|---|---|
| `data-mrd-impression="{{ item.id }}"` on each card, and `{{ impressions() }}` once on the page | `listing_impression` for each card a visitor saw |
| Rendering the listing's own page | `listing_view` |
| `{{ track(entry, 'website', entry.website.url)\|url }}` as a link's `href` | `website_click` (also `booking`, `email`, `directions`, `social`). `check`'s warning about an untracked link suggests this without the `\|url`, which then fails with `a variable inside href must go through \|url` |
| `reveal(entry, 'phone', number)` | `phone_reveal` (`email` gives `email_click`) |
| An enquiry endpoint with an `analytics: { event: enquiry_submitted, subject: $listing }` step | `enquiry_submitted` |

See [Analytics](/features/analytics) for the helpers in full.

## Enquiries to the business [#enquiries-to-the-business]

A declared endpoint can send a visitor's message to the business behind a listing. `$listing.organisation.enquiryContacts` resolves to the organisation's current contacts whose partner role is `contact`; when there are none, its primary contact; when there is none, the organisation's own email address. `fallback_to` is used when that is empty too.

```yaml title="config/sites/main/endpoints.yaml"
endpoints:
  - key: contact-listing
    path: /enquire/{listing}
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    spam: { proof_of_work: true, honeypot: true, min_fill_time: 3s }
    input:
      listing: { type: relation, to: [listing], from: path, required: true }
      name:    { type: text, max: 120, required: true, label: { en-GB: Your name } }
      email:   { type: text, format: email, required: true, label: { en-GB: Your email address } }
      message: { type: text, multiline: true, max: 2000, label: { en-GB: Your message } }
    steps:
      - store: { as: enquiry, retention: 90d, subject: $listing, share_with_organisation: true }
      - mail:  { template: enquiry-to-member, to: $listing.organisation.enquiryContacts,
                 reply_to: $email, fallback_to: settings.enquiries_inbox }
      - analytics: { event: enquiry_submitted, subject: $listing }
    respond:
      fragment: partials/enquiry-sent.html
      on_error: partials/enquiry-form.html
```

Print the form on the listing's page with `{{ enquiryForm('contact-listing', entry) }}`. A form field cannot draw an endpoint that takes a value from its path. Keep `on_error`: without it a failed post answers with the success fragment. `partials/enquiry-form.html` holds `{{ enquiryForm(endpoint.key) }}`, which posts to the same listing again, and the root of `partials/enquiry-sent.html` has the id `form-{{ endpoint.key }}` ([Forms in templates](/templates/forms#rendering-the-answer)). A scripted test needs a challenge first ([Enquiry form](/agents/recipes/enquiry-form#a-form-about-a-listing)).

The `store` step with `subject: $listing` and `share_with_organisation: true` is what puts the enquiry in the organisation's inbox in the portal; without `share_with_organisation` the enquiry is stored for staff only and the business never sees it there, where its people can mark it read, replied or archived (see [Enquiries](/dmo/partners-and-portal#enquiries)). Endpoints themselves are covered in [Forms and submissions](/features/forms-and-submissions); `engine-dmo dev endpoint add <key> --subject listing` (the `recipe:enquiry` recipe) writes the start of one, with the input, the `store` step and a receipt to the visitor; add `share_with_organisation: true`, the `mail` step to the business and the `analytics` step yourself.

`reply_to: $email` reaches the template as `replyTo` but does not set the message's Reply-To header, which is always the site's `mail.reply_to`; print the visitor's address in `enquiry-to-member` so the business can answer (see [Forms and submissions](/features/forms-and-submissions#mail)).

## Widgets on another website [#widgets-on-another-website]

A directory can be shown on a customer's own website through the embed widgets, as HTML fragments inlined at build time or as a script. Widgets are a core feature, switched on per site with `embed.enabled` and the other `embed.*` keys; see [Site configuration](/reference/configuration/site). Their impressions count as `widget_impression` in the member report.

## Agents and the content MCP [#agents-and-the-content-mcp]

Listings and areas are ordinary documents to `engine-dmo content` and to the content MCP. The directory module adds landing page tools to the MCP; see [The content MCP](/integrating/content-mcp).


# What engine-dmo adds (/dmo)

The modules the DMO bundle compiles on top of the core content platform, what each one is for, how they depend on each other and which configuration files belong to them.

<Callout title="engine-dmo">This section is about the DMO bundle (engine-dmo). Everything in it is absent from engine-cms.</Callout>

The examples in this section write the locale code `en-GB`. Replace it with your own site's code in every label, slug and seed value. `engine-dmo init` writes `en`, and an example pasted under another code fails `check --strict` or, for a landing's slugs, only warns.

`engine-dmo` is the core content platform (everything `engine-cms` does) plus the modules a destination marketing organisation runs on: a directory of places, the businesses behind them, their memberships, a portal where those businesses keep their own listings, and the commercial features built on that relationship. The modules are compiled into the binary; there is nothing to install or switch on. A module's features appear as soon as you configure them, and most of them do nothing until you do.

Check which bundle and modules a binary carries with `version`:

```bash
engine-dmo version
```

```text
meridian v0.8.0 (pure-go) go1.27.3
  bundle dmo: modules ai directory forms crm affiliates memberships newsletter portal claims memberreport promotions paidlistings translation
```

`engine-cms version` lists `ai forms newsletter translation` only. The modules shared by both bundles (AI assistance, forms, the newsletter and translation) are documented under [Features](/features).

## The modules [#the-modules]

| Module | What it adds | Requires | Page |
|---|---|---|---|
| `directory` | The core `listing` and `area` types, landing pages (a place crossed with a category at a clean URL), `entry.landings` | nothing | [Directory](/dmo/directory), [Landing pages](/dmo/landing-pages) |
| `crm` | Organisations and people, their custom fields, partner roles, smart lists of organisations and people, broadcasts, the CRM import, merge and erasure | `forms` | [CRM](/dmo/crm) |
| `memberships` | Membership tiers, each organisation's membership on each site, renewals and reminders, `memberTier()` | `crm` | [Partners and the portal](/dmo/partners-and-portal) |
| `portal` | The member portal (sign in, screens, invitations), the member API, the `requireMember` tag | `crm`, `memberships` | [Partners and the portal](/dmo/partners-and-portal), [Portal screens and actions](/dmo/portal-screens-and-actions) |
| `claims` | A business claiming its entry: the public claim form, verification, scoring and the staff queue | `crm`, `memberships`, `portal` | [Claims](/dmo/claims) |
| `promotions` | Promotion slots, partners' requests from the portal, the staff queue, `promoted()` and `promotionLabel()` | `crm`, `memberships`, `portal` | [Promotions](/dmo/promotions) |
| `memberreport` | The member report (portal, member API, PDF, monthly digest) and scheduled organisation reports | `crm`, `memberships`, `portal` | [Member reports](/dmo/member-reports) |
| `affiliates` | Affiliate programmes, tracked links under `/go/`, conversion imports, the signed postback | `crm` | [Affiliates](/dmo/affiliates) |
| `paidlistings` | Prices for tiers and promotions, orders, Stripe Checkout or staff invoices, fulfilment | `crm`, `memberships`, `portal`, `promotions` | [Paid listings](/dmo/paid-listings) |

The arrows point from a module to the modules it requires; a requirement reached through another module is drawn once:

```mermaid
flowchart BT
  forms["forms (core)"]
  directory
  crm --> forms
  memberships --> crm
  portal --> crm
  portal --> memberships
  claims --> portal
  promotions --> portal
  memberreport --> portal
  affiliates --> crm
  paidlistings --> promotions
  paidlistings --> portal
```

## How they fit together [#how-they-fit-together]

The directory is content: listings and areas are documents like any other, edited in the admin, routed, rendered and searched by the core engine. The CRM is records: an **organisation** is a business or body, a **person** is someone you deal with, and a person is linked to an organisation in a **partner role**. The two meet at one point: a document can be linked to an organisation, which is then its owner. In the admin the link is the Organisation panel of the document editor; in templates it is `entry.organisation`.

This is the partner side's data model, in outline:

```mermaid
erDiagram
  NETWORK ||--|{ SITE : "groups"
  NETWORK ||--o{ ORGANISATION : "holds"
  NETWORK ||--o{ PERSON : "holds"
  PERSON ||--o{ CONTACT : "is"
  ORGANISATION ||--o{ CONTACT : "has"
  PARTNER_ROLE ||--o{ CONTACT : "grants"
  ORGANISATION ||--o{ MEMBERSHIP : "holds"
  SITE ||--o{ MEMBERSHIP : "sells"
  TIER ||--o{ MEMBERSHIP : "ranks"
  ORGANISATION |o--o{ DOCUMENT : "owns"
```

A **contact** is a person's link to an organisation in a partner role; a person may be linked to several organisations. A membership is one organisation's on one site at one tier. Documents are shared across the install; their organisation must be in the network of the document's owner site.

Everything else hangs off that link:

1. An organisation holds a **membership** on a site, at a **tier** (`config/memberships.yaml`). The tier decides what its people may change on its listings (`member_editable` on the type), which promotion slots and portal screens it may use, and which report digest it receives.
2. The organisation's people sign in to the **portal** and edit their listings within those rules. Their changes become revisions that wait for review or publish at once, as the tier says.
3. Visitors' interactions with the listing (impressions, views, website clicks, phone reveals, enquiries) are counted per organisation and returned to it as the **member report**.
4. A business with no portal account yet can **claim** its organisation from the public site.
5. Members can ask for **promotions** in the slots a site declares, and **paid listings** can take payment for tiers and promotions.
6. Sites in the same **network** share organisations, people and portal accounts; sites in different networks share none of them. See [Multisite and networks](/dmo/multisite-networks).

## Configuration files the modules read [#configuration-files-the-modules-read]

All of these are optional. A project that declares none of them still runs on `engine-dmo`; it simply has no tiers, no slots and the portal's defaults.

| File | Module | Page |
|---|---|---|
| `config/memberships.yaml` | memberships | [Partners and the portal](/dmo/partners-and-portal#tiers) |
| `config/networks.yaml` | core (used by the CRM and portal) | [Multisite and networks](/dmo/multisite-networks) |
| `config/crm/organisation.yaml`, `config/crm/person.yaml` | crm | [CRM](/dmo/crm#custom-fields) |
| `config/portal/portal.yaml` | portal | [Partners and the portal](/dmo/partners-and-portal#the-install-portal-file) |
| `config/portal/roles.yaml` | crm, portal | [Partners and the portal](/dmo/partners-and-portal#partner-roles) |
| `config/portal/enquiries.yaml` | portal | [Partners and the portal](/dmo/partners-and-portal#enquiries) |
| `config/sites/<site>/portal.yaml` | portal | [Portal screens and actions](/dmo/portal-screens-and-actions) |
| `config/sites/<site>/promotions.yaml` | promotions | [Promotions](/dmo/promotions) |
| `config/analytics/reports.yaml` | memberreport | [Member reports](/dmo/member-reports) |
| `config/paidlistings.yaml` | paidlistings | [Paid listings](/dmo/paid-listings) |
| `landings:` on a route in `routes.yaml` | directory | [Landing pages](/dmo/landing-pages) |
| `member_editable:` in a type's schema file | memberships, portal | [Partners and the portal](/dmo/partners-and-portal#what-members-may-edit) |
| `memberships.tiers` in `site.yaml` | memberships | [Partners and the portal](/dmo/partners-and-portal#tiers) |
| `claims:` and `membership:` in `engine.yaml` | claims, memberships | [Claims](/dmo/claims#configuration), [Partners and the portal](/dmo/partners-and-portal#renewal-reminders) |

`engine-dmo config schema --file <name>` prints the JSON Schema of any of them (`memberships`, `networks`, `crm`, `portal`, `site-portal`, `partner-roles`, `enquiries`, `promotions`, `reports`), and `engine-dmo check` validates every one, reporting each problem at its file, line and column.

## Staff permissions the modules add [#staff-permissions-the-modules-add]

The core staff permissions include the CRM's (`crm.organisation.*`, `crm.person.*`, `crm.membership.view`, `crm.membership.edit`, `crm.tag.manage`, `crm.smartlist.manage`, `crm.claim.review`). The modules register these as well:

| Permission | Module | Granted to built-in roles |
|---|---|---|
| `broadcast.draft`, `broadcast.send` | crm | administrator, partnership-manager |
| `crm.import` | crm | administrator, partnership-manager |
| `promotions.decide` | promotions | administrator, partnership-manager |
| `affiliates.view` | affiliates | administrator, partnership-manager, analyst |
| `affiliates.manage` | affiliates | administrator, partnership-manager |
| `paidlistings.manage` | paidlistings | administrator, partnership-manager |

The built-in `owner` role holds every permission. Grant the others through `config/access/roles.yaml` and `config/access/grants.yaml` as for any staff permission (see [Users, roles and permissions](/concepts/users-roles-and-permissions)).

Partners (the people signing in to the portal) never hold staff permissions. Their permissions come from partner roles, described in [Partners and the portal](/dmo/partners-and-portal#partner-roles).

## Commands the modules add [#commands-the-modules-add]

| Command | What it does | Page |
|---|---|---|
| `engine-dmo crm ...` | Organisations, memberships, invitations, import, merge, erase, duplicate candidates, claims | [CRM](/dmo/crm#commands) |
| `engine-dmo broadcast ...` | Draft, test, schedule, send and report broadcasts | [CRM](/dmo/crm#broadcasts) |
| `engine-dmo lists ...` | Check, count and run smart lists | [CRM](/dmo/crm#smart-lists-of-organisations-and-people) |
| `engine-dmo portal ...` | Check, scaffold and inspect the portal | [Portal screens and actions](/dmo/portal-screens-and-actions#restyling-the-portal) |
| `engine-dmo api member ...` | The member API's OpenAPI document, routes and form descriptions | [Portal screens and actions](/dmo/portal-screens-and-actions#the-member-api) |
| `engine-dmo affiliates ...` | Networks, imports, connections, postback keys | [Affiliates](/dmo/affiliates#commands) |
| `engine-dmo analytics report`, `digest`, `report-run` | Member reports and organisation reports | [Member reports](/dmo/member-reports#commands) |
| `engine-dmo dev tier`, `dev role`, `dev slot`, `dev portal`, `dev network` | Declare tiers, partner roles, slots, portal screens and actions, and networks, with their ids | the page for each |

Run `engine-dmo <command> --help` for every flag, or `engine-dmo help --json` for the whole command tree.

## Where to start [#where-to-start]

<Cards>
  <Card title="Directory" href="/dmo/directory" />
  <Card title="Partners and the portal" href="/dmo/partners-and-portal" />
  <Card title="Landing pages" href="/dmo/landing-pages" />
  <Card title="Promotions" href="/dmo/promotions" />
</Cards>

## Turning off what a site does not use [#turning-off-what-a-site-does-not-use]

Most modules do nothing until configured, but two answer from the start on every `engine-dmo` site: the member portal at `/members` (with the member API) and, through it, the claim form under `/members/claim/`. `engine-dmo describe project` shows the portal as `portal /members, both, ...` even on a site with no partners. To switch it off for the whole install:

```yaml title="config/portal/portal.yaml"
portal:
  mode: off
```

`/members` then answers 404, and `describe project` shows `portal /members, off`. A single site can do the same in `config/sites/<site>/portal.yaml` with `mode: off`. Setting `auth.member.registration: invite_only` in `engine.yaml` closes only the claim form.

A site with no listings simply declares no route for the `listing` and `area` types; their tables stay empty.

## Example projects [#example-projects]

The example projects (`dmo-minimal` with listings, tiers, affiliates and enquiries; `dmo-destination` with two sites, landing pages, promotions and custom portal screens and actions; `dmo-multisite` with two sites in two networks) live in the Meridian source repository, under `examples/`. They are not inside the binary or the container image, and `engine-dmo init` with no flag writes only the bare starter. `engine-dmo init <dir> --from <path>` copies a project directory you already have on disk, so it works only with a copy of the repository's `examples/` folder. Without one, build up from the starter with the pages of this section and the `dev` commands; see [Your first project](/getting-started/first-project).


# Landing pages (/dmo/landing-pages)

How to declare landing pages (a place crossed with a category, a category alone, or a calendar month) on a route, the threshold that makes one live, the generated and editor-written copy, the template and its landing context, and the redirects the engine keeps.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A landing page is a route's index filtered by fixed values, published at a clean URL of its own: "Places to stay in Wynd Valley" at `/wynd-valley/places-to-stay` rather than `/places?area=...&category=stay`. The engine counts the published results of every pairing, publishes each page with enough of them, gives it a generated title, description, breadcrumbs and structured data, and lists it in the sitemap. When a page falls below its threshold or its address changes, the engine leaves a redirect. Nothing about landing pages is on by default: a project has them only by declaring them.

There are three kinds:

| Kind | Declared with | Page per | Address |
|---|---|---|---|
| Place and category | `place:` and `category:` | each place with each category value | under the place's own address: `/wynd-valley/places-to-stay` |
| Category page | `category:` alone | each category value | under the route's index: `/places/places-to-stay` |
| Month page | `month:` alone, on a route whose type has a `recurrence` field | each calendar month with upcoming occurrences | under the route's index: `/whats-on/may` |

## A minimal landing [#a-minimal-landing]

This builds on the listing and area set up in [Directory](/dmo/directory): a listing with an `area` relation and a `category` select, both declared as facets of its route, and a routed `area` type. Keep the `page` route with its `priority:`. The examples write `en-GB` and `fr-FR`: use your site's locale codes in every map, since a slug under a locale the site does not enable only warns, and the raw option value is then used in the address.

```yaml title="config/sites/main/routes.yaml"
routes:
  - type: page
    uri: "/{slug}"
    priority: 10
  - type: listing
    uri: "/places/{slug}"
    index: "/places"
    paginate: 24
    facets: [area, category]
    landings:
      - key: by-place
        place: area
        category: category
        uri: "{place}/{category}"
        slugs:
          stay: { en-GB: places-to-stay, fr-FR: hebergement }
          eat-drink: { en-GB: food-and-drink, fr-FR: ou-manger }
        min_results: 3
        title: { en-GB: "{category} in {place}", fr-FR: "{category} à {place}" }
        description: { en-GB: "{count} {category_lower} in {place}, including {examples}." }
      - key: by-category
        category: category
        uri: "{category}"
  - type: area
    uri: "/{slug}"
    nest: true
    index: "/areas"

home: { type: page, slug: home }
```

Run `engine-dmo check --fix` to write each landing's id (`lnd_`), then `engine-dmo schema plan` and `schema apply`. The pages appear once the engine has counted them, which a running server does in the background (see [When a page is live](#when-a-page-is-live)): before that, `engine-dmo render` of a landing page's address answers 404.

## Landing keys [#landing-keys]

Each entry under a route's `landings:` takes these keys.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `key` | yes | | The landing's handle on the route: lowercase letters, digits and hyphens, unique on the route |
| `id` | written by `check --fix` | | The stable id (`lnd_` and ten characters). Everything stored about the landing's pages names it, so renaming `key` keeps them. |
| `place` | for a place and category landing | | A facet of the route that is a single relation to one document type (such as `area`). Not a relation to `tag`, not `multiple: true`. |
| `category` | for a place and category landing, and a category page | | A facet of the route that is a `select`, or a relation to one document type (not `tag`). Not the same facet as `place`. |
| `month` | for a month page | | The name of the type's `recurrence` field. A month page takes no `place` and no `category`. |
| `uri` | yes | | The page's path pattern, one string for every locale or one per locale. See [Addresses](#addresses). |
| `slugs` | no | the value itself (a select), the related document's slug (a relation), the month's name in the locale (a month page) | Each category value's path segment per locale. A month page's slugs are keyed `january` to `december`. |
| `min_results` | no | `3` | The fewest published results a page needs to be live. At least 1. |
| `content` | no | none | A project type an editor fills in for each page; see [Editors' copy](#editors-copy) |
| `title` | no | `{category}, {place}`; a category page `{category}`; a month page `{month}` | The generated title pattern, one string or one per locale |
| `description` | no | none | The generated description pattern, one string or one per locale |

### Placeholders in title and description [#placeholders-in-title-and-description]

| Placeholder | Replaced by |
|---|---|
| `{place}` | The place's title in the page's locale |
| `{category}` | The category value's label in the locale (for a month page, the month's name) |
| `{category_lower}` | The same label lower-cased by the locale's rules |
| `{month}` | The month's name in the locale (month pages) |
| `{count}` | The number of published results |
| `{examples}` | The titles of the first three results, separated by commas (description only; a listed page's own title in `entry.landings` and `landing.siblings` has none) |

### Addresses [#addresses]

| Kind | `uri` must hold | Result |
|---|---|---|
| Place and category | `{place}` and `{category}`, and nothing else in braces | `{place}` is replaced by the place's own path on the site (with its parents, for a nested place), so `"{place}/{category}"` gives `/wynd-valley/wyndcombe/places-to-stay` |
| Category page | `{category}` alone | The path under the route's index in the locale: `/places/places-to-stay` |
| Month page | `{month}` alone | The path under the route's index: `/whats-on/may` |

`uri` needs a value for every locale the site enables when it is given per locale. Each slug must be one path segment of letters, digits and hyphens, in any script. `check` warns when a select category has slugs for some values or locales and not others (the value itself is used where a slug is missing), and when a slug names a locale the site does not enable.

A category page's address has the same shape as the route's own documents (`/places/{slug}`). A document whose slug equals a category's slug wins and the page is not reachable, so choose slugs that no document uses. Two category pages of the same shape under one index may coexist only if no slug is shared between them; a relation category cannot share a shape, because its slugs are documents' slugs.

### Rules check enforces [#rules-check-enforces]

- The route must have an `index:`: a landing page is the index filtered.
- `place` and `category` must already be in the route's `facets:`.
- The place's type must be routed on the same site, since a landing page hangs under its place's page.
- A `select` category's `slugs` may only name values the field has; a month page's only `january` to `december`.
- A landing's `content` type must exist and must not be routed on any site: its address is the landing page's.

## When a page is live [#when-a-page-is-live]

The engine recomputes a site's landing pages as a background job:

- when anything published on the site changes;
- when routes move (a renamed slug, a moved place);
- at every start;
- every 24 hours on a site with a month page, since time alone moves a month's upcoming dates.

```mermaid
flowchart LR
  change["Publish, unpublish,<br/>route change or start"] --> job["Recompute job<br/>(queued per site)"]
  job --> count["Count each pairing's<br/>published results"]
  count --> enough{"at least<br/>min_results?"}
  enough -->|yes| live["Live: served,<br/>in the sitemap"]
  enough -->|no| gone["Not live: 301 to the place<br/>or the index, if it was live"]
```

The job runs inside `engine-dmo serve`, like every background job. A command that renders without a server (`engine-dmo render`, an agent's verification loop) sees only what the last run counted, so on a fresh database with freshly seeded content every landing page answers 404 until a server has run. Start `engine-dmo serve` against the database, give it a few seconds (`engine-dmo jobs list` shows the recompute while it is queued), stop it, and render again; the counts stay in the database. `seed apply` counts the pages itself only when it seeds a promotion that needs them.

Each place and category pairing (each value, for a category page) with at least `min_results` published results is live. A month page counts the events with an occurrence from the start of the month (or from today, when the month is under way) to its end, in the site's timezone; once a month has passed, its page stands for the same month next year.

The engine keeps a permanent (301) redirect wherever a page that was once live goes away, so links and search results keep working:

| What happened | The old address redirects to |
|---|---|
| The page's address changed (a slug, pattern or place moved) | The new address |
| The page fell below `min_results` | The place's own page; for a category or month page, the route's index |
| The landing was removed from `routes.yaml` | The place's own page; for a category or month page, the route's index |

When the page is live again at that address, the redirect is switched off. These redirects appear in the admin's redirect table with the origin `auto_route`.

Live pages are listed in the site's sitemap, in every locale the site enables.

## The template [#the-template]

A landing page renders with `<type>/landing.html` (`listing/landing.html`) when the site's template chain has it, and with the route's index template (`listing/index.html`) when it does not. It has everything an index page has (`items`, `pagination`, `facets`) and the `landing` context below. `page.landing` is true, and `page.title` is the generated title, so `head()` prints the title, description and canonical and the template writes only its body, with its one `h1`:

```jinja title="templates/_shared/listing/landing.html"
{% extends "base.html" %}
{% block body %}
<nav aria-label="{{ t('crumbs.label') }}">
  <ol>{% for c in landing.breadcrumbs %}<li>{% if c.current %}<span aria-current="page">{{ c.title }}</span>{% else %}<a href="{{ c.uri|url }}">{{ c.title }}</a>{% endif %}</li>{% endfor %}</ol>
</nav>
<h1>{{ landing.heading }}</h1>
{% if landing.description %}<p>{{ landing.description }}</p>{% endif %}
{% if landing.content %}{% blocks landing.content.body %}{% endif %}
<ul class="cards">
  {% for listing in items %}
  <li data-mrd-impression="{{ listing.id }}"><a href="{{ listing.uri|url }}">{{ listing.title }}</a></li>
  {% endfor %}
</ul>
{{ impressions() }}
{% if landing.faq %}
<h2>{{ t('landing.questions') }}</h2>
<dl>{% for qa in landing.faq %}<dt>{{ qa.question }}</dt><dd>{{ qa.answer }}</dd>{% endfor %}</dl>
{% endif %}
{% if landing.siblings %}
<h2>{{ t('landing.more') }}</h2>
<ul>{% for s in landing.siblings %}<li><a href="{{ s.uri|url }}">{{ s.title }}</a> ({{ s.count }})</li>{% endfor %}</ul>
{% endif %}
{% endblock %}
```

### The landing context [#the-landing-context]

| Property | What it holds |
|---|---|
| `landing.key` | The landing's key |
| `landing.pageKey` | The page's own key, which `promoted('slot', landing)` reads for a slot sold per landing page |
| `landing.place` | The place as an entry (title, uri, url and its fields); null on a category or month page |
| `landing.category` | `value`, `label` and `slug`; null on a month page |
| `landing.month` | On a month page: `number` (1 to 12), `name`, `slug`, `from`, `to`, `start` and `year`, in the site's timezone; otherwise null |
| `landing.title` | The page title: the generated one, the content document's title, or its SEO title (in that order of precedence, last wins) |
| `landing.heading` | The heading: the generated title, or the content document's title |
| `landing.description` | The generated description, or the content document's SEO description |
| `landing.content` | The content document as an entry, when an editor wrote one; otherwise null |
| `landing.faq` | The content document's questions as a list of `question` and `answer` (plain text); empty when there are none |
| `landing.count` | The number of published results |
| `landing.uri`, `landing.url` | The page's path, and its absolute address |
| `landing.siblings` | The place's other live landing pages (for a category page, the landing's other live pages). Each item: `title`, `uri`, `url`, `count`, `landing`, `category`, `place`, `month`. |
| `landing.parents` | The same category's live pages in the places above this one, root first |
| `landing.breadcrumbs` | Home, the place's ancestors, the place (or, on a category page, the index), then the page with `current: true`. Each crumb: `title`, `uri`, `url`. |
| `landing.jsonld` | The page's structured data: the page, its breadcrumbs, its results as an ItemList and, where the content type maps them, its questions as an FAQPage. The core head output uses it, so the template need not print it. |

A visitor who adds a facet beyond the page's own values sees the filtered results at a query string on the page's address; that filtered view is `noindex` and its canonical is the page itself.

Elsewhere, `entry.landings` lists a place's live pages and, on a listed document, the pages it is a result of (see [Directory](/dmo/directory#template-surface)).

## Editors' copy [#editors-copy]

Give a landing `content: <type>` to let editors write their own words for each page. The type is an ordinary project type with no route; the engine keys each document to its page by id and adds no field of its own.

```yaml title="config/schema/landing_page.yaml"
key: landing_page
label: { en-GB: Landing page }
plural: { en-GB: Landing pages }
fields:
  - name: title
    type: text
    max: 120
    label: { en-GB: Page title }
  - name: body
    type: blocks
    label: { en-GB: Content }
    blocks:
      - key: richText
        label: { en-GB: Text }
        fields:
          - { name: content, type: portable_text, label: { en-GB: Text } }
      - key: faq
        label: { en-GB: Questions and answers }
        fields:
          - name: items
            type: repeater
            max: 12
            label: { en-GB: Questions }
            fields:
              - { name: question, type: text, required: true, max: 200, label: { en-GB: Question } }
              - { name: answer, type: portable_text, label: { en-GB: Answer } }
  - { name: meta, type: seo, label: { en-GB: Search engines } }
structured_data:
  faq: { items: body.faq.items, question: question, answer: answer }
```

```yaml title="config/sites/main/routes.yaml (the landing)"
      - key: by-place
        place: area
        category: category
        uri: "{place}/{category}"
        content: landing_page
```

How the content document is used:

- its non-empty `title` replaces the generated title and heading;
- its first `seo` field's `title` and `description` replace the page title and description, and its social title and description become the page's;
- its questions, found through the type's `structured_data.faq` mapping, become `landing.faq` and the FAQPage in the structured data;
- everything else is yours to render from `landing.content` (`{% blocks landing.content.body %}` above).

Editors write the copy from the place's editor in the admin: the **Pages for** panel lists one row per category of each landing whose place type it is, with its result count, whether it is live and whether it has content, and a button that creates the content document (starting from the page's generated title) or opens the one that exists. Category and month pages have no place, so they have no such panel; their copy is written through the content MCP, whose `landing_content_get` and `landing_content_set` tools cover every kind of landing page (see [The content MCP](/integrating/content-mcp)).

## Selling a place on a landing page [#selling-a-place-on-a-landing-page]

A promotion slot with `scope: landing` sells one inventory per live landing page, priced per place and category. See [Promotions](/dmo/promotions#slots-sold-per-landing-page).

## Troubleshooting [#troubleshooting]

| Symptom | Cause |
|---|---|
| `type listing declares landings but has no index route` | Add `index:` to the route. |
| `place "area" is not a facet of the listing route` | Add the field to the route's `facets:`. |
| `place "area" must be a single relation to one document type, such as area` | The field is not a relation, relates to `tag`, has several targets, or is `multiple`. |
| `place area relates to area, which has no route on site main` | Route the place type on the same site. |
| `landing uri "..." needs both {place} and {category}` | A place and category landing's `uri` must contain both placeholders and nothing else in braces. |
| `landing by-place has no uri for locale fr-FR` | A per-locale `uri` needs every enabled locale. |
| `min_results must be at least 1` | A page with nothing in it is not allowed. |
| A page you expect is missing | It has fewer than `min_results` published results on that site, or a document with the same address shadows a category page. |


# Member reports (/dmo/member-reports)

What the member report tells a business about its listings, where members read it (portal, member API, PDF, monthly digest), how to configure the digest, the peer comparison and the improvement prompts, scheduled organisation reports for a board, and the report commands.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The member report shows one organisation its own numbers for a period: how often its listings were seen, what visitors did next, the enquiries it received, where its visitors came from, how it compares with similar businesses, what people searched for, and what it could do to its listing to do better. It is computed once and served in four places, so they never disagree:

| Where | How |
|---|---|
| The portal | The `report` screen, `/organisations/{org}/report`, for people whose role grants `report.view` |
| The member API | `GET /api/member/v1/organisations/{id}/report` |
| A PDF | `engine-dmo analytics report --format pdf` |
| The monthly digest | An email to the organisation's contacts, scheduled from `config/analytics/reports.yaml` |

The report needs analytics to be on (`analytics.enabled: true` in `engine.yaml`, see [Analytics](/features/analytics)) and listings [linked to their organisations](/dmo/directory#linking-a-listing-to-its-business).

## What is in it [#what-is-in-it]

| Section | Contents |
|---|---|
| Seen | `listing_impression` (appeared in lists), `widget_impression` (seen on a partner's page through a widget), `listing_view` (the listing's own page) |
| Referrals | `website_click`, `phone_reveal`, `directions_click`, `booking_click`, `email_click`, `social_click`, each with its total |
| Enquiries | `enquiry_submitted`: enquiry forms that reached the business. Shown on its own, never added to referrals. |
| Paid placements | `offer_impression` and `promotion_impression`, counted separately so they never inflate the listing's figures |
| Conversion | How many of the people who saw the listing went on to act, in percentage points, and referrals per day |
| Sources | Where visitors came from: search engines, direct, other websites, social media, within the site, campaigns, partner pages |
| Twelve months | A month by month series for the chart |
| Peer comparison | The organisation against the median of similar businesses on the site; see below |
| Search terms | Terms that brought people to the listing, and searches near it that found nothing |
| Improvement prompts | "Make your listing work harder": what to change, and the evidence for it |
| Sites | For an organisation listed on several sites, its figures on each and their total |
| Owner activity | What the organisation's own people did on its own listings while signed in, excluded from every figure above and shown so the exclusion is visible |
| Methodology | What is counted, what is excluded and why, how the comparison is protected, and the rule set the figures were rolled up under |

Each figure carries its change on the same period a year earlier and a direction (up, down or level). The events are recorded by the public pages; see [Counting what visitors do](/dmo/directory#counting-what-visitors-do).

## The monthly digest [#the-monthly-digest]

The digest is one email per organisation per site, sent to every current contact who may edit the listing and has not opted out (a link in the email stops it). It is declared as a `member` report:

```yaml title="config/analytics/reports.yaml"
reports:
  - key: member-monthly
    name: { en-GB: Your monthly performance }
    audience: member
    schedule: "0 8 2 * *"
    format: [email]
    range: previous_month
    compare: previous_year
    tiers: { min: bronze }
```

and switched on in the portal's file:

```yaml title="config/portal/portal.yaml"
portal:
  report:
    email_digest:
      enabled: true
      report: member-monthly
      skip_when_no_data: true
```

The digest uses the report's schedule, range and tiers, and needs `email` among its formats. It sends to each organisation with an active membership in the report's tiers. A period with no impressions and no interactions is skipped when `skip_when_no_data` is on. A run is recorded per site and per report, so a restart or a second scheduler tick never sends twice, and a contact whose address is suppressed leaves an entry on the organisation's timeline instead.

`engine-dmo analytics digest` queues the digest for the current period now, whatever the schedule says; `--run` also works through the mail queue in the command rather than leaving it to the server.

## Report definitions [#report-definitions]

`config/analytics/reports.yaml` holds every scheduled report. `engine-dmo config schema --file reports` prints its schema.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `key` | yes | | Unique handle |
| `id` | written by `check --fix` | | The stable id (`rep_`) |
| `name` | no | | The report's name per locale |
| `audience` | yes | | `member` (the digest) or `organisation` (a report for a board or funder) |
| `schedule` | yes | | A five-field cron expression, evaluated in UTC. The period it reports on is cut in the site's reporting timezone, but the send time is not: `0 8 2 * *` sends at 08:00 UTC, which is 09:00 in London during British Summer Time. Write the hour in UTC for the season that matters most. |
| `format` | organisation reports | | One or a list of `email`, `pdf`, `csv`, `json` |
| `range` | no | `previous_month`; `this_financial_year` for an organisation report with `metrics` | `previous_month`, `previous_quarter`, `previous_year`, `previous_financial_year`, `this_month`, `this_quarter`, `this_financial_year` |
| `compare` | no | `previous_year` | `previous_year`, `previous_period` or `none` |
| `tiers` | no | every tier | Member reports: the tiers whose organisations receive it. `none` is not allowed. |
| `to` | organisation reports | | The recipients, always a `${VAR}` interpolation of a comma separated list, never addresses written in the file |
| `dashboard` | organisation reports, or `metrics` | | A dashboard declared in `config/analytics/dashboards.yaml` |
| `metrics` | organisation reports, or `dashboard` | | KPI rows: `key` (a metric), optional `kind` (`measured` or `entered`), `label` per locale, `target` for the range (a percentage for a rate) |
| `sites` | no | every site | Organisation reports: the sites it runs for, one run each |

### Organisation reports [#organisation-reports]

An organisation report sends the destination's own figures against targets to the recipients the environment names, for a board or a funder:

```yaml title="config/analytics/reports.yaml"
  - key: board-quarterly
    name: { en-GB: Quarterly board report }
    audience: organisation
    schedule: "0 9 5 1,4,7,10 *"
    format: [email, pdf]
    range: previous_quarter
    compare: previous_year
    to: ${BOARD_REPORT_RECIPIENTS}
    metrics:
      - { key: visits, target: 120000 }
      - { key: member_referrals_total, target: 9000 }
```

```bash
BOARD_REPORT_RECIPIENTS="board@example.org,chair@example.org"
```

A metric is one of the engine's measured metrics (such as `visits`, `page_views`, `listing_views`, `enquiries`, `member_referrals_total`, `searches`, `members_active`) or a figure staff enter, declared in `config/analytics/dashboards.yaml`. The full list of metric keys is in [Analytics](/features/analytics#metrics); no command prints it. Staff see each run under the admin's **Reports** screen in Insight, and `engine-dmo analytics report-run --report board-quarterly [--site <site>] [--run]` queues one for its current period now.

## Report settings [#report-settings]

`config/portal/portal.yaml` holds the comparison and prompt rules, install-wide.

| Key | Default | Meaning |
|---|---|---|
| `portal.report.peer_comparison` | `true` | Compare the organisation with similar businesses |
| `portal.report.peer_min_cohort` | `5` | The smallest cohort compared. Below the banding threshold the comparison is shown as a band rather than a median, so no single business's figures can be recovered. |
| `portal.report.improvement_prompts.enabled` | `true` | Show prompts |
| `portal.report.improvement_prompts.max_shown` | `4` | The most prompts shown |
| `portal.report.improvement_prompts.min_impressions` | `100` | Impressions below which a prompt carries no claim |
| `portal.report.improvement_prompts.uplift_min_cohort` | `20` | The smallest group of listings an uplift is measured over |
| `portal.report.improvement_prompts.uplift_min_percent` | `10` | The smallest uplift worth claiming |
| `portal.report.improvement_prompts.filter_min_searches` | `50` | Searches needed before a filter's share is quoted |
| `portal.report.improvement_prompts.rules` | see below | The rules, merged over the defaults |
| `portal.report.email_digest.enabled` | `true` | The monthly digest |
| `portal.report.email_digest.report` | `member-monthly` | The `member` report in `reports.yaml` the digest sends |
| `portal.report.email_digest.skip_when_no_data` | `true` | Skip an organisation with nothing to report |

### Improvement prompts [#improvement-prompts]

Each rule looks at the organisation's listing and, where the site's own data supports it, says how much a change is worth. A prompt for a field the member's tier may not edit is not shown, and a rule with no field on the listing type is not shown.

| Rule | Default | Looks at |
|---|---|---|
| `photos` | `{ min: 4, target: 8 }` | Every image field of the listing, unless `field`/`fields` name them |
| `summary_words` | `{ min: 40 }` | The summary's length |
| `description_words` | `{ min: 150 }` | The first rich text field, unless named |
| `opening_hours` | `{ required: true, filter: open_now }` | The first opening hours field, unless named; evidence from how often searches filter by `open_now` |
| `accessibility` | `{ required: true }` | Only the fields you name (`fields: [accessibility, accessibilityNotes]`); `filter:` names a search filter for evidence |
| `website` | `{ required: true }` | Only the field you name (`field: website`) |
| `booking_link` | `{}` | Only the field you name; `tiers:` limits it to the tiers that may set a booking link (every tier but `none` when absent) |
| `stale_after` | `180d` | How long since the listing was last updated |
| `zero_result_terms` | `{ min_searches: 10, radius_km: 10 }` | Searches near the listing that found nothing |

```yaml title="config/portal/portal.yaml"
portal:
  report:
    improvement_prompts:
      enabled: true
      max_shown: 4
      rules:
        accessibility: { fields: [accessibility, accessibilityNotes] }
        website: { field: website }
        booking_link: { field: bookingUrl, tiers: { min: silver } }
```

The fields named here (`accessibility`, `accessibilityNotes`, `bookingUrl`) must be fields of your `listing` type: `check` reports a named field the type does not have, and a tier the tier list does not declare. A rule you leave out of `rules:` keeps its default.

## Commands [#commands]

| Command | What it does |
|---|---|
| `engine-dmo analytics report --organisation <id> [--site] [--from] [--to] [--format text\|html\|pdf] [--out <file>]` | One organisation's report. Dates default to the last year. Text and HTML print to the terminal; a PDF goes to `report.pdf` unless `--out` names a file (`-` is standard output). |
| `engine-dmo analytics digest [--run]` | Queue the member digest for the current period |
| `engine-dmo analytics report-run --report <key> [--site] [--run]` | Queue an organisation report for its current period |

All three need the database. The PDF is printed by a browser the engine drives (`analytics.pdf.renderer` in `engine.yaml`); `engine-dmo version --require pdf` exits 1 when this build cannot produce one.

## In the portal's templates [#in-the-portals-templates]

The report screen renders `report.html` in the portal's template directory, and a custom screen can read the report with a `report` data source (`figures: { report: { range: last_month } }`, see [Portal screens and actions](/dmo/portal-screens-and-actions#data-sources)). Copy `report.html` with `engine-dmo portal scaffold --site <site>` to restyle it.


# Multisite and networks (/dmo/multisite-networks)

How several sites in one install share or separate partners: networks of sites that share organisations, people and portal accounts, what stays per site (tiers, slots, portals, landing pages), how staff are scoped to a network, and moving a site out with site export and retire.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

One install can run several sites, each a property with its own domains, locales, routes and templates, sharing one body of content (see [Sites, locales and routes](/concepts/sites-locales-and-routes)). For the partner side of the platform there is one more decision to make: do two sites deal with the **same businesses**? A county guide and a town guide inside it may both list the same pub, but if the town's businesses deal with the town council and not the county, their records, their people and their portal accounts must not be the county's.

That boundary is a **network**: a set of sites that share organisations, people and partner accounts. Sites in different networks share none of them.

## Networks [#networks]

Every install has a network called `default`, which a site joins by leaving `network:` out. Declare others in `config/networks.yaml` and name one in a site's `site.yaml`:

```yaml title="config/networks.yaml"
networks:
  - key: llanwynd
    name: { en-GB: Llanwynd Town partners }
```

```yaml title="config/sites/town/site.yaml"
site:
  name: { en-GB: Llanwynd Town }
  network: llanwynd
  domains: [town.example.org]
```

| Key | Meaning |
|---|---|
| `networks[].key` | Lowercase letters, digits and hyphens. `default` is reserved: it is never declared. |
| `networks[].id` | The stable id (`net_`), written by `check --fix`. Records are stored against it, so renaming a network keeps them. |
| `networks[].name` | Its name per locale |
| `site.network` in `site.yaml` | The network the site belongs to; `default` when absent |

`engine-dmo dev network add <key> --name <name> --site <site>` declares a network and joins sites to it, and `engine-dmo dev site add <key> --network <key>` adds a site in a network (declaring the network when it is new). `check` refuses a site naming an undeclared network and warns about a network no site uses. `engine-dmo describe project` lists networks with their sites.

## What a network separates [#what-a-network-separates]

| Per network | Shared across the whole install |
|---|---|
| Organisations and people, and the contacts between them | Content (documents, revisions, publish state) |
| Portal accounts and member sessions | Tags and the vocabulary |
| Claims, imports (a source belongs to a network) | Media |
| Smart lists of organisations and people (read only within the list's networks) | Schema, templates, strings |
| Broadcasts' audiences | Staff accounts, roles and the admin |

So the same pub on both sites is **two organisations**, one in each network; the same owner's email address is **two people** with **two portal accounts**; and a portal session on one site is not signed in on a site of another network. A document's organisation must be in the network of the document's owner site.

Within one network, an organisation listed on several sites is one record with one portal account, and its [member report](/dmo/member-reports) shows its figures on each site and their total.

## What stays per site [#what-stays-per-site]

These belong to a site whichever network it is in:

| What | Where |
|---|---|
| The tiers it sells | `memberships.tiers` in `site.yaml` (every tier when absent) |
| Memberships | One per organisation per site |
| Who may edit what, per tier | `member_editable` in the type, or in the site's own schema file |
| Its portal path, mode, routes, hidden screens, screens and actions | `config/sites/<site>/portal.yaml` |
| Its promotion slots and label | `config/sites/<site>/promotions.yaml` |
| Its landing pages | `landings:` on its routes |
| Its prices | `sites.<site>` in `config/paidlistings.yaml` |
| Affiliate programmes | Set up per site in the admin |

```yaml title="config/sites/town/portal.yaml"
path: /partners
routes:
  organisation: "/businesses/{org}"
hide: [membership]
```

A town that handles memberships on paper hides the membership screen and moves its portal to `/partners`, while the county keeps the install's `/members`.

## Staff and networks [#staff-and-networks]

Staff accounts are install-wide, but what they reach of the CRM follows their grants: a staff user reaches the networks of the sites their grants are scoped to, and every network through a grant with no site scope. A town officer granted the `partnership-manager` role scoped to the town site sees only the town's businesses and people:

```yaml title="config/access/grants.yaml"
grants:
  - group: town-team
    role: partnership-manager
    scope: { site: [town] }
```

See [Users, roles and permissions](/concepts/users-roles-and-permissions) for grants and scopes.

## Templates shared between sites [#templates-shared-between-sites]

A template in a shared root is checked against every site whose chain includes it. Two things to watch in the DMO bundle:

- `promoted('<slot>')` must name a slot each such site declares, or `check` fails on the site that does not (see [Promotions](/dmo/promotions#templates-shared-between-sites));
- a link to the claim form or the portal written as a literal path must match each site's portal path. Read the path from a site setting, or override the template in the site's own root.

## A site leaving the install [#a-site-leaving-the-install]

When a site's organisation leaves, its site can be moved to an install of its own and then removed here.

```bash
engine-dmo site export --site town --out ./town-export --scratch-database-url "$SCRATCH_DATABASE_URL" --plan
engine-dmo site export --site town --out ./town-export --scratch-database-url "$SCRATCH_DATABASE_URL" --signing-key-env TOWN_SIGNING_KEY
engine-dmo site retire --site town --plan
engine-dmo site retire --site town --yes
```

| Command and flag | Meaning |
|---|---|
| `site export --site` | The site to export |
| `--out` | The directory to write, created with mode 0700; it must be empty or absent |
| `--scratch-database-url` | A PostgreSQL server on which the export may create two databases and drop them; the export is verified by restoring it there and serving its home page |
| `--signing-key-env` | An environment variable holding the receiving install's signing key, to reseal second factors; without it they are cleared |
| `--staff` | A staff user whose grants reach every site, by address, to copy as well; repeatable |
| `--plan` | Print what would be copied and stop |
| `site retire --site` | The site to remove: its rows, analytics and search indexes, and the people and organisations connected only to it, erased |
| `--plan` | Print what would be removed and erased, and stop |
| `--yes` | Retire without asking |

Both need the database. `site export` and `site retire` are core commands and also exist in `engine-cms`; in `engine-dmo` they carry the site's partners with it. Retiring cannot be undone: export first and check the export.


# Paid listings (/dmo/paid-listings)

How to sell membership tiers and promotions: prices in config/paidlistings.yaml, Stripe Checkout or staff invoices, the portal's billing screen, the Stripe webhook, orders and their statuses, and how a paid order grants, renews, refunds and lapses a membership or a promotion.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

Paid listings takes payment for what a site sells its partners: a membership **tier** for a period, and **promotions** in its priced slots. A partner pays in the portal through the provider's hosted checkout (Stripe Checkout is the one provider), or staff raise an invoice and record its payment. Either way the result is an **order**, and a paid order is **fulfilled**: a tier order makes the organisation's membership active at that tier until the end of the period it bought, and a promotion order approves the promotion. A refund takes it back, and a tier order's membership lapses when its period ends.

Without `config/paidlistings.yaml`, or with `provider: none`, nothing is sold in the portal; staff can still raise invoices for priced promotions.

## Configuration [#configuration]

```yaml title="config/paidlistings.yaml"
provider: stripe
stripe:
  secret_key: ${STRIPE_SECRET_KEY}
  webhook_secret: ${STRIPE_WEBHOOK_SECRET}
sites:
  main:
    promotions: checkout
    tiers:
      standard: { amount: "120.00", currency: GBP, months: 12 }
      gold: { amount: "300.00", months: 12 }
```

| Key | Default | Meaning |
|---|---|---|
| `provider` | `none` | `stripe` takes payment through Stripe Checkout; `none` keeps orders to staff invoices |
| `stripe.secret_key` | | Required for `stripe`. Must be a `${VAR}` interpolation; a literal key is refused. |
| `stripe.webhook_secret` | | Required for `stripe`. The webhook endpoint's signing secret, as a `${VAR}`. |
| `stripe.api_base` | `https://api.stripe.com` | Only for a test double: an `https` address, or `http` on a loopback address |
| `sites.<site>.tiers.<tier>.amount` | | The price, a quoted decimal such as `"120.00"` |
| `sites.<site>.tiers.<tier>.currency` | the site's `default_currency` | A three-letter code |
| `sites.<site>.tiers.<tier>.months` | `12` | The period bought, 1 to 36 months |
| `sites.<site>.promotions` | `invoice` | `checkout`: a priced promotion request is paid in the portal. `invoice`: staff invoice it. `checkout` needs a provider. |

A tier on sale must be declared in `config/memberships.yaml` and sold on the site (`memberships.tiers` in `site.yaml`). A promotion's price comes from its slot in `promotions.yaml` (see [Promotions](/dmo/promotions#slot-settings)), never from this file.

`engine-dmo check` validates the file without needing the secrets; the server reads the two variables at start and refuses to start when either is unset. A key beginning `sk_live_` or `rk_live_` is live mode; any other is test mode.

## Setting up Stripe [#setting-up-stripe]

<Steps>
<Step>

Create a restricted or secret API key in the Stripe dashboard and set it as `STRIPE_SECRET_KEY` in the engine's environment.

</Step>
<Step>

Add a webhook endpoint in Stripe at `https://<site host>/paidlistings/webhook/stripe`, listening for `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed`, `checkout.session.expired` and `charge.refunded`. Set its signing secret as `STRIPE_WEBHOOK_SECRET`.

</Step>
<Step>

Write `config/paidlistings.yaml`, run `engine-dmo check`, and restart the server.

</Step>
</Steps>

The engine creates one Checkout Session in payment mode per order, for one line at the order's amount, naming the order as the client reference and in the payment's metadata. It never sees card details.

### The webhook [#the-webhook]

`POST /paidlistings/webhook/stripe` checks the `Stripe-Signature` header and its age (at most 5 minutes) before reading the body, refuses an event it has already applied (event ids are kept 90 days), holds a payment's amount to the order's, and then fulfils the order. A delivery that fails its signature counts against its address's allowance and is answered 429 past it; one that verifies is never limited.

| Stripe event | Effect |
|---|---|
| `checkout.session.completed` with payment status `paid`, `checkout.session.async_payment_succeeded` | The order is paid and fulfilled |
| `checkout.session.expired`, `checkout.session.async_payment_failed` | The open order is cancelled |
| `charge.refunded` | When the charge is refunded in full, the order is refunded and what it granted is taken back. A partial refund changes nothing; record it from the Orders screen if it should. |

## The billing screen [#the-billing-screen]

The portal's billing screen, `{portal path}/billing/{org}`, is for people whose partner role grants `billing.pay` (the built-in `billing` and `owner` roles). It shows:

- the organisation's membership on the site;
- with a provider, each tier on sale with its price and period;
- on a site with `promotions: checkout`, its promotion requests waiting for payment, priced from their slot;
- its orders and their statuses.

Each offer is a plain form that posts to `{portal path}/billing/{org}/checkout`, which records the order at the price in configuration (the form only names the offer) and answers 303 to the provider's checkout page. It works without JavaScript. The screen renders the portal template `billing.html`, which `engine-dmo portal scaffold --site <site>` copies for restyling.

A promotion request on a `checkout` site is `requested` until the partner starts checkout, then `awaiting_payment` while its order is open; payment approves it, with the slot's capacity checked again. If the order is cancelled or abandoned, the promotion goes back to `requested`.

## Orders [#orders]

| Property | Meaning |
|---|---|
| Kind | `tier` or `promotion` |
| Method | `checkout` (paid through the provider) or `invoice` (raised and recorded by staff) |
| Amount, currency, description | Fixed when the order is made |
| Reference | The order's reference, written on the membership or promotion it fulfils |

| Status | Meaning | Moves to |
|---|---|---|
| `open` | Made, not yet paid | `paid`, `cancelled` |
| `cancelled` | Abandoned or cancelled | `paid` (a late payment) |
| `paid` | Payment received, not yet fulfilled | `fulfilled`, `failed`, `refunded` |
| `failed` | Fulfilment could not go ahead (for example the slot filled meanwhile); staff retry or refund | `fulfilled`, `refunded` |
| `fulfilled` | The tier or promotion was granted | `refunded`, `lapsed` |
| `lapsed` | A tier order's period ended | `refunded` |
| `refunded` | Refunded; what it granted was taken back | |

```mermaid
stateDiagram-v2
  [*] --> open : checkout started or invoice raised
  open --> paid : payment received
  open --> cancelled : abandoned or cancelled
  cancelled --> paid : a late payment
  paid --> fulfilled : tier or promotion granted
  paid --> failed : fulfilment could not go ahead
  paid --> refunded
  failed --> fulfilled : staff retry
  failed --> refunded
  fulfilled --> lapsed : a tier order's period ends
  fulfilled --> refunded
  lapsed --> refunded
  refunded --> [*]
```

### What fulfilment does [#what-fulfilment-does]

| Order | Fulfilled | Refunded | Period ends |
|---|---|---|---|
| Tier | The organisation's membership on the site becomes `active` at the tier, renewing on the period's end. With no current membership one is created, joined today. A renewal of an active membership at the same tier runs on from its current renewal date. The membership records the amount, currency and order reference. | The membership lapses, if it still carries this order's reference | The membership lapses, unless a later order or staff renewed it under another reference |
| Promotion | The promotion is approved (capacity checked again with the slot locked) | The promotion is cancelled with the reason the business reads | |

Paid orders whose fulfilment was interrupted are retried every minute; ended periods are lapsed every hour, by the site's timezone.

## Staff [#staff]

Staff with `paidlistings.manage` on the site (the built-in `administrator` and `partnership-manager` roles) use the **Orders** screen under Members to:

- raise an invoice for a tier on sale or for a promotion waiting for payment;
- record an invoice's payment, which fulfils it;
- cancel an open order;
- retry a failed fulfilment;
- record a refund made in Stripe or in the finance system.


## Troubleshooting [#troubleshooting]

| Message | Fix |
|---|---|
| `stripe.secret_key is a secret and must be an environment interpolation, not a literal` | Write `secret_key: ${STRIPE_SECRET_KEY}`. |
| `provider "..." is not one of stripe, none` | Use `stripe` or `none`. |
| `promotions: checkout needs a payment provider` | Set `provider: stripe`, or `promotions: invoice`. |
| `site <site> does not sell tier "<tier>"` | Add the tier to the site's `memberships.tiers`. |
| `a tier on sale needs the install's tier list` | Declare tiers in `config/memberships.yaml`. |
| `months <n> is not between 1 and 36` | Fix `months`. |
| The server will not start: `environment variable STRIPE_SECRET_KEY (stripe.secret_key) is not set` | Set both variables in the environment. |


# Partners and the portal (/dmo/partners-and-portal)

Membership tiers and memberships, what each tier may edit on a listing, partner roles and their permissions, the member portal's sign-in, invitations, reference screens and configuration, and the enquiry inbox businesses work from.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A **partner** is a business or body the destination works with, held as a CRM [organisation](/dmo/crm). It may hold a **membership** on a site at a **tier**; its people sign in to the **member portal** to keep their listings, photos and opening hours current, read their [report](/dmo/member-reports), answer enquiries and ask for [promotions](/dmo/promotions). What a person may do there depends on two things: their **partner role** in the organisation, and the organisation's **tier** on the site.

This page covers tiers, memberships, editing rules, roles, the portal itself and enquiries. Adding your own portal screens and forms, restyling the portal and the member API are in [Portal screens and actions](/dmo/portal-screens-and-actions).

## Tiers [#tiers]

The install's tiers are declared once, in rank order, lowest first:

```yaml title="config/memberships.yaml"
tiers:
  - key: bronze
    label: { en-GB: Bronze }
  - key: silver
    label: { en-GB: Silver }
  - key: gold
    label: { en-GB: Gold }
```

| Key | Meaning |
|---|---|
| `key` | Lowercase letters, digits and hyphens. Every rule that names a tier is checked against this list. |
| `id` | The stable id (`tier_`), written by `check --fix`. Memberships are stored against it, so renaming a tier keeps them. |
| `label` | The tier's name per locale |

`engine-dmo dev tier add <key> [--after <tier>] [--label <name>]` declares one with its id, and `engine-dmo dev tier rename <old> <new>` renames a tier everywhere it is named, keeping its id and memberships.

`none` is the tier of an organisation with no active membership on the site. It is reserved: you cannot declare it, but rules that apply to organisations (`member_editable`, slots, screens, actions) may name it.

A site sells every tier unless its `site.yaml` lists the ones it sells:

```yaml title="config/sites/town/site.yaml"
memberships:
  tiers: [silver, gold]
```

Rules that name a tier a site does not sell are warned about at that site, since no organisation there can hold it.

### Tier lists in rules [#tier-lists-in-rules]

Wherever a rule takes `tiers:` (portal screens and actions, promotion slots, report digests, the booking link prompt) it is either a list of keys or the lowest tier by rank:

```yaml
tiers: [silver, gold]   # exactly these
tiers: { min: silver }  # silver and every tier ranked above it
```

Omitted, a rule applies to every tier and to `none`. A list that names tiers excludes `none` unless it names it. `{ min: ... }` needs `config/memberships.yaml`.

## Memberships [#memberships]

A membership is one organisation's on one site. It has:

| Property | Meaning |
|---|---|
| Tier | One of the install's tiers that the site sells |
| Status | `pending`, `active`, `lapsed` or `cancelled` |
| Joined on, renews on, ended on | Dates. Lapsing or cancelling sets the end date. |
| Amount, currency, external reference, notes | What was charged and the invoice or order reference; for the record only |
| History | Every change, with its reason |

Only an `active` membership gives its tier. A pending one does not; an organisation with none, or only lapsed or cancelled ones, is at tier `none`.

Staff manage memberships on the organisation's page and on the site's **Memberships** screen (under Members), which counts active, pending and lapsed members and lists renewals due. A membership's status changes only when someone changes it (or a [paid order](/dmo/paid-listings) does); passing the renewal date does not lapse it.

```bash
engine-dmo crm membership set <organisation-id> --tier gold --site main --reason "Upgraded at the 2026 renewal"
```

`crm membership set` changes the organisation's pending or active membership on the site, or starts one (status `active` unless `--status` says otherwise).

### Renewal reminders [#renewal-reminders]

Each active membership whose renewal date comes within one of the configured intervals is sent the `renewal-notice` mail, once per interval per renewal date, in the site's timezone. It goes to the organisation's contacts with the `billing` role, else its primary contacts, else every current contact. A suppressed address is recorded on the organisation's timeline instead.

```yaml title="config/engine.yaml"
membership:
  renewal:
    reminders: [60d, 30d, 7d, 0d]
```

| Key | Default | Meaning |
|---|---|---|
| `membership.renewal.reminders` | `[60d, 30d, 7d, 0d]` | Days before `renews_on`, each a whole number of days from `0d` to `366d`. An empty list sends none. |

The reminder carries a link to the site's portal when the portal serves screens.

## What members may edit [#what-members-may-edit]

A type's `member_editable` rule says, per tier, which fields of a document the organisation's people may change from the portal and the member API, and whether their changes wait for staff. Without a rule, members cannot edit documents of the type.

```yaml title="config/schema/listing.yaml"
extends: listing
fields:
  # ...
member_editable:
  tiers:
    none:
      fields: [phone, website, openingHours]
      approval: required
    silver:
      fields: [summary, description, phone, website, openingHours, heroImage]
      approval: required
    gold:
      fields: "*"
      except: [slug, area, category]
      approval: auto
      review_window: 24h
      always_review: [primaryTag]
      links: { follow: false, max_per_field: 5 }
```

| Key | Meaning |
|---|---|
| `tiers.<tier>` | A tier key, or `none` |
| `fields` | The fields the tier may change, or `"*"` for every field on the site |
| `except` | Fields taken out of `"*"` |
| `approval` | `required`: every change waits for staff. `auto`: changes publish at once and staff review them afterwards. |
| `review_window` | With `auto`, how long staff have to review a change after it went live, such as `24h` |
| `always_review` | With `auto` only, fields whose changes still wait for staff |
| `links.follow` | `true` leaves links members write without `rel="nofollow ugc"`. Default `false`. |
| `links.max_per_field` | The most links in one rich text field. Default `3`; a negative number removes the cap. |

A tier the rule does not name may edit nothing. Fields are named by handle; `check` reports an unknown field, a field that is not on a site the rule applies to, a tier `config/memberships.yaml` does not declare, and `always_review` on a tier without `approval: auto`. A type's per-site schema file (`config/sites/<site>/schema/<type>.yaml`) may set its own `member_editable`, which replaces the shared one on that site.

A member's changes are revisions of the document. Those that wait appear in the admin's moderation queue for staff to approve or return, with the expected turnaround from `approvals.expected_turnaround` in `engine.yaml`; see [Documents, revisions and publishing](/concepts/documents-revisions-and-publishing).

`engine-dmo describe type listing` prints a type's member rules with its fields, and `engine-dmo api member form --listing <id> --person <id>` prints the form a given member would receive.

## Partner roles [#partner-roles]

A person's partner role in an organisation decides what they may do for it. Roles are install-wide. Four are built in:

| Role | Grants |
|---|---|
| `owner` | Everything (`*`), always. Its grants cannot be changed. An organisation always keeps at least one owner. |
| `manager` | `listing.*`, `photos.*`, `hours.*`, `organisation.update`, `event.submit`, `report.view`, `enquiries.view`, `enquiries.manage`, `promotion.request`, `screen.*` |
| `contact` | `report.view`, `enquiries.view` |
| `billing` | `membership.view`, `report.view`, `billing.pay` |

The permissions:

| Permission | Allows |
|---|---|
| `profile.update` | Changing one's own details. Everyone signed in holds it; it cannot be taken away. |
| `organisation.update` | Changing the organisation's contact details |
| `listing.update` | Editing the organisation's documents within the tier's `member_editable` rule |
| `photos.add`, `photos.remove` | Adding and removing photos on a listing |
| `hours.update` | Changing opening hours |
| `event.submit` | Submitting an event |
| `people.invite` | Inviting a colleague, in a role holding no permission the inviter lacks |
| `people.manage` | Changing colleagues' roles and removing them |
| `promotion.request` | Asking for a [promotion](/dmo/promotions) |
| `billing.pay` | Paying for a tier or a promotion ([paid listings](/dmo/paid-listings)) |
| `enquiries.view`, `enquiries.manage` | Reading the enquiry inbox, and changing an enquiry's status, note and fields |
| `report.view` | The member report |
| `membership.view` | The organisation's memberships |
| `pending.view` | Changes waiting for staff |
| `action.<key>`, `screen.<key>` | A portal action or screen a site declares (see [Portal screens and actions](/dmo/portal-screens-and-actions)) |

A grant may end in `.*` to cover a subject (`listing.*`, `screen.*`, `action.*`), and `*` covers everything.

Add roles, or change the grants of `manager`, `contact` and `billing`, in `config/portal/roles.yaml`:

```yaml title="config/portal/roles.yaml"
roles:
  - key: marketing
    label: { en-GB: Marketing }
    can: [listing.update, photos.*, report.view, enquiries.view]
  - key: contact
    can: [report.view, enquiries.view, enquiries.manage]
```

| Key | Meaning |
|---|---|
| `key` | The role's handle |
| `id` | The stable id (`role_`), written by `check --fix` for a role of your own. A built-in role keeps the engine's id; do not write one for it. |
| `label` | The role's name per locale |
| `can` | Permissions and patterns. `check` refuses an unknown permission, and an `action.<key>` or `screen.<key>` no site declares. Owner takes no `can`. |

`engine-dmo dev role add <key> --can <permissions> [--label <name>]` declares or restates a role. Without the file, the four built-in roles apply as shown.

Every permission is checked in the database against the person's current link to the organisation and the site's network, never in a template. A person with no current link to an organisation can do nothing for it.

## The portal [#the-portal]

The portal is served by the engine on each site's own host, under the portal path. It renders the engine's reference screens in a neutral style until you restyle it, and it works without JavaScript.

### Turning it on and off [#turning-it-on-and-off]

```yaml title="config/portal/portal.yaml"
portal:
  mode: both
  templated:
    enabled: true
    template_dir: portal
    routes:
      organisation: "/businesses/{org}"
  invitations:
    expiry: 30d
    reminder_after: 7d
```

| Key | Default | Meaning |
|---|---|---|
| `portal.mode` | `both` | `templated`: the engine renders the portal's screens. `api`: only the [member API](/dmo/portal-screens-and-actions#the-member-api) answers, for a portal you build elsewhere. `both`: screens and API. `off`: nothing is served under the portal path. |
| `portal.templated.enabled` | `true` | `false` stops the engine rendering screens in every mode |
| `portal.templated.template_dir` | `portal` | The directory, under each template root, that holds your portal templates |
| `portal.templated.routes.<screen>` | see [Reference screens](#reference-screens) | A reference screen's path under the portal path |
| `portal.invitations.expiry` | `30d` | How long an invitation link works |
| `portal.invitations.reminder_after` | `7d` | When an unaccepted invitation is sent a reminder |
| `portal.report.*` | see [Member reports](/dmo/member-reports#report-settings) | The member report's comparison, improvement prompts and digest |

The file is install-wide. A site can change its own mode, path, template directory, routes and hidden screens with `config/sites/<site>/portal.yaml` (see [Per-site portals](/dmo/portal-screens-and-actions#per-site-portals)); anything it leaves out keeps the install's value. `engine-dmo config schema --file portal` prints the file's schema.

The portal path is `server.portal_path` in `engine.yaml`, `/members` by default, and the member API is `server.api.member.enabled` (default `true`).

### Signing in [#signing-in]

Members sign in with a link sent to their email address, and may add a passkey from their account page. There are no member passwords.

| Key in `engine.yaml` | Default | Meaning |
|---|---|---|
| `auth.member.enabled` | `true` | The member realm |
| `auth.member.magic_link.enabled` | `true` | Sign-in links by email |
| `auth.member.magic_link.ttl` | `15m` | How long a sign-in link works |
| `auth.member.passkeys.enabled` | `true` | Passkeys |
| `auth.member.password.enabled` | `false` | Must stay `false`: member passwords are not built |
| `auth.member.session.absolute_lifetime` | `720h` | The longest a member session lasts |
| `auth.member.session.idle_timeout` | `336h` | How long an unused session lasts |
| `auth.member.registration` | `claim` | `claim`: staff invitations and the public [claim form](/dmo/claims). `invite_only`: invitations alone; the claim form answers not found. |

A member session belongs to the site's host and to its network: a session on one site is not signed in on a site of another network.

### Invitations [#invitations]

A person becomes a portal user by accepting an invitation; a seed file can invite one too ([Organisations and people](/content-modelling/seeding-and-importing#organisations-and-people)). Staff invite from the organisation's page in the admin or with:

```bash
engine-dmo crm invite --organisation <id> --email jo@example.org --name "Jo Bloggs" --role "General manager" --site main
```

The command links the person as the organisation's `owner` and queues the invitation mail; it prints no link. The mail links to the portal's sign-in page, `/members/login` on the site's first domain, and carries no token. There the person asks for a sign-in link, which is only valid in the browser that asked for it (a `__Host-mrd_link` cookie), so opening it elsewhere asks them to go back. To read these mails on a development install, see [Reading mail in development](/features/mail#reading-mail-in-development). Members with `people.invite` invite colleagues from the portal's people screen, in any role holding no permission they lack. An approved claim sends an invitation too.

### Reference screens [#reference-screens]

| Screen key | Default path under the portal path | Shows |
|---|---|---|
| `dashboard` | `/` | The organisations the person acts for |
| `organisation` | `/organisations/{org}` | An organisation: its listings, links to the other screens, the site's actions, a first-session checklist |
| `report` | `/organisations/{org}/report` | The [member report](/dmo/member-reports); needs `report.view` |
| `contact_details` | `/organisations/{org}/details` | The organisation's contact details; `organisation.update` to change them |
| `people` | `/organisations/{org}/people` | Colleagues, roles and invitations |
| `membership` | `/organisations/{org}/membership` | Memberships by site; needs `membership.view` |
| `contact_team` | `/organisations/{org}/contact` | A message to the destination's team, recorded on the organisation's timeline |
| `enquiries` | `/organisations/{org}/enquiries` | The [enquiry inbox](#enquiries); needs `enquiries.view` |
| `events` | `/organisations/{org}/events` | The organisation's events, and submitting one; needs `event.submit` |
| `promotions` | `/organisations/{org}/promotions` | [Promotion](/dmo/promotions) requests; needs `promotion.request` |
| `listing_edit` | `/listings/{id}` | Editing a document within the tier's rule; needs `listing.update` |
| `photos` | `/listings/{id}/photos` | A listing's photos |
| `hours` | `/listings/{id}/hours` | A listing's opening hours |

A route override must start with `/`, keep exactly one placeholder of the screen's kind (`{org}` or `{id}`) as a whole path segment, and not take another screen's path. The first path segments `login`, `auth`, `logout`, `account`, `passkeys`, `claim`, `digest`, `invitations` and `_assets` are the engine's own and cannot be used.

Beside these, the portal serves sign-in, the account page (details and passkeys), invitation acceptance, the digest opt-out, the [claim flow](/dmo/claims) under `/claim/`, the [billing screen](/dmo/paid-listings#the-billing-screen) at `/billing/{org}`, and any screens a site declares.

`engine-dmo portal check` prints each site's mode, path, template directory and every screen's route, and checks your portal templates against the portal context.

## Enquiries [#enquiries]

The enquiry inbox lists the enquiries an endpoint's `store` step saved about one of the organisation's documents and shared with it (`store: { as: enquiry, retention: 90d, subject: $listing, share_with_organisation: true }`, see [Directory](/dmo/directory#enquiries-to-the-business)), in full, newest first, with the listing each was about. A person whose role grants `enquiries.view` reads them; `enquiries.manage` changes them.

Each enquiry has a status, a private note and the install's enquiry fields.

| Status | Meaning |
|---|---|
| `new` | Not yet opened |
| `read` | Opened |
| `replied` | Marked as answered |
| `archived` | Out of the inbox |

The inbox's filters are `open` (everything not archived, the default), each status, and `all`.

A person with `enquiries.manage` moves an enquiry between the statuses like this:

```mermaid
stateDiagram-v2
  [*] --> new : the post is stored and shared
  new --> read : opened, or a note added
  read --> new : mark unread
  replied --> new : mark unread
  new --> replied : mark replied
  read --> replied : mark replied
  new --> archived : archive
  read --> archived : archive
  replied --> archived : archive
  archived --> read : unarchive (never replied)
  archived --> replied : unarchive (replied before)
  new --> [*] : retention passes
  read --> [*] : retention passes
  replied --> [*] : retention passes
  archived --> [*] : retention passes
```

Marking an enquiry replied, or writing a note or a field on it, extends its retention once to the store step's `while_open` period when it has one.

Declare the fields businesses keep against an enquiry in `config/portal/enquiries.yaml`, with the same grammar and the same eight types as [CRM custom fields](/dmo/crm#custom-fields) (`text`, `number`, `boolean`, `select`, `date`, `datetime`, `phone`, `money`). The names `intent`, `note`, `status` and `return` are reserved.

```yaml title="config/portal/enquiries.yaml"
fields:
  - { name: followUpOn, type: date, label: { en-GB: Follow up on } }
  - name: stage
    type: select
    label: { en-GB: Stage }
    options:
      - { value: quoted, label: { en-GB: Quoted } }
      - { value: booked, label: { en-GB: Booked } }
```

An enquiry is kept for the `retention` its `store` step set and then deleted.

## Configuration at a glance [#configuration-at-a-glance]

| File | Holds |
|---|---|
| `config/memberships.yaml` | The tiers |
| `config/sites/<site>/site.yaml` `memberships.tiers` | The tiers a site sells |
| `member_editable` in `config/schema/<type>.yaml` | What each tier may edit |
| `config/portal/roles.yaml` | Partner roles |
| `config/portal/portal.yaml` | The portal's mode, templates, routes, invitations and report settings |
| `config/sites/<site>/portal.yaml` | A site's own portal, screens and actions |
| `config/portal/enquiries.yaml` | Enquiry fields |
| `engine.yaml` `membership:`, `auth.member:`, `server.portal_path` | Renewal reminders, member sign-in, the portal path |

Every one is checked by `engine-dmo check` with the problem's file, line and column. After a change that adds ids or tiers, run `engine-dmo check --fix`, then `engine-dmo schema plan` and `schema apply`.


# Portal screens and actions (/dmo/portal-screens-and-actions)

How to give one site its own portal path, routes and hidden screens, declare portal screens with scoped data and portal actions that write documents or custom fields, restyle the reference portal's templates, and build a portal of your own on the member API.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The engine's [reference portal](/dmo/partners-and-portal#the-portal) covers the work every partner does. A site can go further without writing Go: it can move and trim its portal, add **screens** (pages with data the engine reads for the partner's own organisation) and **actions** (forms that write a document of the organisation or its custom fields), and restyle every template. Or it can switch the screens off and build its own portal on the **member API**.

All of this lives in one file per site, `config/sites/<site>/portal.yaml`, beside templates under the site's template chain.

## A screen and an action [#a-screen-and-an-action]

```yaml title="config/sites/main/portal.yaml"
path: /partners
hide: [events]
screens:
  - key: overview
    path: /organisations/{org}/overview
    template: overview.html
    title: { en-GB: Overview }
    nav: { group: business, order: 10 }
    can: listing.update
    data:
      listings: { documents: { type: listing, states: [draft, published], sort: -updatedAt, limit: 5 } }
      figures: { report: { range: last_month } }
      membership: { membership: {} }
      waiting: { pending: { limit: 5 } }
      nearby: { published: { type: listing, near: $org.listing, within: 2km, sort: distance, limit: 6 } }
actions:
  - key: preferences.update
    label: { en-GB: Update your preferences }
    can: organisation.update
    target:
      organisation: { fields: [custom.preferredContactTime, custom.coachParking] }
    rate_limit: 20/hour/person
    respond: { redirect: { screen: overview } }
```

```jinja title="templates/main/portal/overview.html"
{% extends "_layout.html" %}
{% block title %}{{ screen.title }}{% endblock %}
{% block main %}
<h1>{{ screen.title }}</h1>
<ul>
  {% for l in data.listings.items %}<li>{% if l.href %}<a href="{{ l.href|url }}">{{ l.title }}</a>{% else %}{{ l.title }}{% endif %}</li>{% endfor %}
</ul>
{% set f = portal_form('preferences.update') %}
<form {{ f.attrs }}>
  {{ f.hidden }}
  {% for field in f.fields %}{{ field_widget(field, f.errors) }}{% endfor %}
  <p><button class="p-button" type="submit">{{ f.label }}</button></p>
</form>
{% endblock %}
```

The action writes custom fields declared in `config/crm/organisation.yaml` (see [CRM](/dmo/crm#custom-fields)). The template extends `_layout.html`, the portal's layout, which `engine-dmo portal scaffold --site main` copies into `templates/main/portal/` (see [Restyling the portal](#restyling-the-portal)).

Then:

```bash
engine-dmo check --fix --project .
engine-dmo portal check --project .
```

`check --fix` writes the screen's `scr_` id and the action's `act_` id. `engine-dmo dev portal screen add` and `engine-dmo dev portal action add` write the same entries from flags, with `--scaffold` writing a starting template for a screen.

## Per-site portals [#per-site-portals]

`config/sites/<site>/portal.yaml` is laid over the install's `config/portal/portal.yaml`. Anything it leaves out keeps the install's value.

| Key | Meaning |
|---|---|
| `mode` | `templated`, `api`, `both` or `off`, for this site |
| `path` | Where the portal answers on this site's host, such as `/partners`. Defaults to `server.portal_path`. |
| `template_dir` | The directory under each of the site's template roots that holds its portal templates |
| `routes.<screen>` | A reference screen's path under the portal path, as in the install file |
| `hide` | Reference screens this site does not serve: any of `contact_details`, `contact_team`, `enquiries`, `events`, `hours`, `listing_edit`, `membership`, `people`, `photos`, `promotions`, `report` |
| `screens` | The site's own screens, and replacements of reference screens' templates |
| `actions` | The site's own actions |

The report rules and invitation timings stay install-wide. A link the engine builds to a hidden screen (in the portal, in mail, in the admin) is never made.

## Screens [#screens]

A screen is a page under the portal path, rendered from a template under the site's portal template directory, with declared data the engine reads for the person's active organisation. Templates never query; the data is a closed set of sources, each scoped in the database to the organisation, the person's role and the site's network.

| Key | Required | Meaning |
|---|---|---|
| `key` | yes | Lowercase letters, digits and underscores. Unique on the site. |
| `id` | written by `check --fix` | The stable id (`scr_`) |
| `path` | yes, for a new screen | The path under the portal path, with `{org}`, `{id}` or no placeholder. Must not match the same addresses as another screen. |
| `template` | yes | An `.html` file under the site's portal template directory, found along the site's template chain |
| `title` | no | The title per locale, which the navigation shows; the key humanised when absent |
| `nav` | no | `{ group: <lowercase word>, order: <number> }` puts the screen in the portal navigation. `group` defaults to `business`. A screen with `{id}` cannot be in the navigation. |
| `can` | no | The partner permission it needs: a built-in permission, another declared `action.<key>`, or `screen.<key>`. Defaults to `screen.<key>`, which a role must grant (the built-in `manager` holds `screen.*`). |
| `tiers` | no | The tiers whose organisations may open it, as a [tier list](/dmo/partners-and-portal#tier-lists-in-rules). Needs `{org}` or `{id}` in the path. |
| `data` | no | Named data sources, read in the order declared |

A screen keyed as a reference screen (`organisation`, `report`, `people` and so on) **replaces that screen's template** and nothing else: it takes only `key` and `template`, keeps the reference screen's path, permission and context, and cannot replace a hidden screen.

### Data sources [#data-sources]

Each entry under `data:` is `<name>: { <source>: { <parameters> } }`, and the template reads it as `data.<name>`. A list source gives `{ denied, items, count }`; when the person's role lacks a source's extra permission, `denied` is true and `items` is empty.

| Source | Parameters | Gives | Extra permission |
|---|---|---|---|
| `documents` | `type` (required), `states` (`draft`, `published` or both; default both), `sort` (`updatedAt`, `createdAt` or `title`, `-` for descending), `limit` (default 50, at most 100) | The organisation's documents of the type. Each item: `id`, `type`, `title`, `state`, `live`, `pending`, `site`, `created`, `updated`, `fields`, `href` | |
| `document` | `type` (required) | The document the path's `{id}` names, which must be the organisation's. Needs `{id}` in the path. | |
| `published` | `type` (required), `near` (`$org.listing`), `within` (a distance such as `5km` or `800m`, needs `near`), `from` (`today`, for events with an occurrence from today), `sort` (`name`, `recent` or `distance`; `distance` needs `near`), `limit` (default 10, at most 100) | Published documents of the type on the site. Each item: `id`, `type`, `title`, `summary`, `uri`, `url`, `tags`. With `near`, around the organisation's published listing. | |
| `report` | `range` (`last_12_months` or `last_month`) | The organisation's [member report](/dmo/member-reports) | `report.view` |
| `enquiries` | `since` (a period such as `30d`), `status` (`open`, `new`, `read`, `replied`, `archived`, `all`; default `open`), `limit` (default 50, at most 200) | Its enquiries | `enquiries.view` |
| `pending` | `limit` (default 50, at most 200) | Its changes waiting for staff. Each item: `id`, `document`, `type`, `title`, `status`, `submitted`, `fields`, `yours`, `href` | `pending.view` |
| `people` | none (`{}`) | Its people: `name`, `partner_role`, `is_primary`, `you` | |
| `membership` | none | Its memberships by site: `site`, `site_name`, `current`, `tier`, `status`, `joined_on` | `membership.view` |
| `organisation` | none | The organisation: `id`, `name`, `legal_name`, `email`, `website`, `phone`, `address`, `social`, `custom` | |
| `promotions` | `limit` (default 50, at most 200) | Its promotion requests | `promotion.request` |
| `first_session` | none | The first-session checklist: `steps` (each `label`, `href`, `done`), `remaining`, `total`, `complete` | |

Every source except `published` without `near` reads the active organisation, so the screen's path needs `{org}` or `{id}`; `check` says so at the line.

### The screen template's context [#the-screen-templates-context]

| Name | What it is |
|---|---|
| `screen` | `key`, `id`, `title`, `path` |
| `data.<name>` | Each declared source |
| `organisation` | The active organisation, with its links to the reference screens and what the person may do (`organisation.can.listing_update` and so on) |
| `member` | The signed-in person: `id`, `name`, `displayName`, `email`, `organisations`, `activeOrganisation` |
| `person` | The signed-in person's names and email |
| `portal` | `path`, `login`, `logout`, `account`, `assets`, `nav` (the site's own screens in the navigation), and `portal.route(screen, id)`, the path of any screen |
| `portal_form(key)` | A declared action's form; see below |
| `field_widget(field, errors)` | One accessible control for a field of a form |
| `component(name, ...)` | One of the shipped components: `asset`, `error_summary`, `field`, `link`, `opening_hours`, `place`, `portable_text`, `recurrence`, `status` |
| `site`, `locale`, `csrf`, `request`, `t()` | As on the public site, plus the public site's globals |

`t()` reads the site's string catalogue first and then the portal's own strings; `portal check` warns about a key in neither.

## Actions [#actions]

An action is a form the portal posts to `{portal path}/actions/<key>` (with `?id=` for a document it edits, `?org=` otherwise). It writes declared fields of one target, and it is refused unless the person's role grants its permission and the organisation's tier is one the action allows; both are decided in the database.

| Key | Required | Meaning |
|---|---|---|
| `key` | yes | `<subject>.<verb>`, lowercase, one dot. The verb is one of `create`, `update`, `remove`, `add`, `submit`, `request`, `invite`. A built-in action's key (`profile.update`, `organisation.update`, `listing.update`, `photos.add`, `photos.remove`, `hours.update`, `people.invite`, `people.role`, `event.submit`, `promotion.request`) cannot be reused. |
| `id` | written by `check --fix` | The stable id (`act_`) |
| `label` | no | Its name per locale where a screen lists it; the key when absent |
| `can` | no | The partner permission it needs. Defaults to `action.<key>`. |
| `tiers` | no | The tiers whose organisations may use it; every tier and `none` when absent |
| `target` | yes | One of `document`, `organisation`, `person`; see below |
| `fields` | for a document target | The document fields it writes |
| `approval` | no | Document targets only. `tier` (the default): the tier's `member_editable` rule decides whether the change waits. `required`: every change waits for staff. |
| `rate_limit` | no | `<count>/<window>/<key>`, keyed `person`, `organisation`, `session` or `ip`, such as `20/hour/person` |
| `respond` | no | `{ redirect: { screen: <screen> } }`, a reference screen or one of the site's own, answered with 303 after a good post. Absent, the post returns to the screen the form was on. |

Targets:

| Target | Writes |
|---|---|
| `document: { type: offer, create: true }` | A new document of the type, owned by the active organisation |
| `document: { type: offer, id: $id }` | The document named by `?id=`, which must be the organisation's |
| `organisation: { fields: [custom.<name>, ...] }` | The active organisation's custom fields, at once |
| `person: { fields: [custom.<name>, ...] }` | The signed-in person's custom fields, at once |

A document action's fields are also held to the tier's `member_editable` rule: a field no tier the action allows may edit is warned about at load, and a save keeps only what the tier's rule allows.

A document action from the reference example, which lets silver and gold businesses add offers:

```yaml
actions:
  - key: offer.create
    label: { en-GB: Add an offer }
    can: listing.update
    tiers: { min: silver }
    target:
      document: { type: offer, create: true }
    fields: [title, summary, validUntil, bookingEmail, heroImage]
    approval: tier
    rate_limit: 20/hour/person
    respond: { redirect: { screen: offers } }
```

### Rendering an action's form [#rendering-an-actions-form]

`portal_form('<key>')` (or `portal_form('<key>', id)` for a document it edits) returns the form for the active organisation. It is a template error when the site has no such action or the person may not use it, so a screen never shows a form that would be refused; wrap it in a check of the person's permission when a screen is open to people who cannot use the action.

| Property | Meaning |
|---|---|
| `attrs` | The form element's attributes: method, action, and the multipart encoding when a field uploads |
| `hidden` | The hidden inputs (CSRF token, return address) |
| `fields` | The form description's fields, each rendered with `field_widget(field, f.errors)` |
| `errors` | Field errors after a failed post, with `_summary` and `_count` for an error summary (`component('error_summary', f)`) |
| `label`, `key`, `id`, `action` | The action's label, key, id and post address |
| `approval` | `required` when changes will wait for staff |

The reference organisation screen lists every action the person's role and tier allow that needs no document (`actions` in its context).

## Restyling the portal [#restyling-the-portal]

The engine renders its own templates until a file of the same name exists in the site's portal template directory, `templates/<root>/<template_dir>/` along the site's template chain. Copy the reference portal there to start:

```bash
engine-dmo portal scaffold --site main
```

This writes about forty files (screens, the `_layout.html` they extend, the claim flow and `components/`) into the site's first template root, such as `templates/main/portal/`. Existing files are left alone unless you pass `--force`. **Always pass `--site`.** Without it the files go to `templates/portal/`, which is on no site's template chain unless one of your roots is named `portal`, so none of them is ever rendered; `check` then warns that nothing in the folder renders. If that happened, delete `templates/portal/` and run the command again with `--site`. To share one restyled portal between sites, pass `--out templates/_shared/portal`.

Then edit what you need and delete what you do not: a template you delete falls back to the engine's.

| Command | What it does |
|---|---|
| `engine-dmo portal scaffold [--site <site>] [--out <dir>] [--force]` | Copy the reference portal's templates into the project |
| `engine-dmo portal check` | Print each site's mode, path, template directory and screen routes, and check the portal templates against the portal context |
| `engine-dmo portal status` | What each site's portal is serving and which templates the project overrides (needs the database) |

The portal's strings are the engine's own catalogue; a project overrides one by adding the same key to `config/strings/<locale>.yaml`.

## The member API [#the-member-api]

The member API serves the same data and the same rules as the portal as JSON, for a portal built with another toolchain. It is on when `server.api.member.enabled` is true (the default) and the site's portal mode is `api` or `both`.

| | |
|---|---|
| Base path | `/api/member/v1` on the site's host |
| Authentication | The member session cookie (`__Host-mrd_member`) set by the portal's sign-in screens, same origin only |
| Unsafe requests | Carry the CSRF token from `GET /me` in `X-CSRF-Token` |
| Errors | RFC 9457 problem details; a 422 carries `field_errors` with structured paths |
| Rate limit | `endpoints.rate_limit.member` per session on every write, and four times that per address |
| Contract | `GET /api/member/v1/openapi.json`, or `engine-dmo api member openapi` |

| Operation | Method and path | Permission |
|---|---|---|
| `getMe` | `GET /me` | The person, their organisations and the CSRF token |
| `getOrganisation`, `patchOrganisation` | `GET`, `PATCH /organisations/{id}` | `organisation.update` for details, `hours.update` for opening hours |
| `listListings` | `GET /organisations/{id}/listings` | The organisation's documents |
| `getListing`, `patchListing` | `GET`, `PATCH /listings/{id}` | `listing.update`; fields the tier does not permit are discarded and recorded |
| `getListingForm` | `GET /listings/{id}/form` | The form description for this listing, person and tier |
| `getListingStatus` | `GET /listings/{id}/status` | What is live, pending or returned, and the expected turnaround |
| `listListingPhotos`, `arrangeListingPhotos` | `GET`, `POST /listings/{id}/photos` | Photos |
| `listOrganisationAssets` | `GET /organisations/{id}/assets` | The organisation's own uploads |
| `uploadAsset`, `patchAsset` | `POST /assets`, `PATCH /assets/{id}` | Uploads (multipart), alt text and caption |
| `getUploadTerms` | `GET /upload-terms` | The terms a member accepts with an upload |
| `listPeople`, `invitePerson`, `setPersonRole`, `removePerson` | `/organisations/{id}/people`, `/people/{link}` | `people.invite`, `people.manage` |
| `listInvitations` | `GET /organisations/{id}/invitations` | Open invitations |
| `getMembership` | `GET /organisations/{id}/membership` | Memberships by site |
| `getReport` | `GET /organisations/{id}/report` | The member report: the last twelve months by default, `range=last_month` or `month=2026-08` |
| `getActivity` | `GET /organisations/{id}/activity` | Member-visible timeline entries |
| `contactTeam` | `POST /organisations/{id}/contact` | A message to the team, recorded on the timeline |
| `listEvents` | `GET /events` | The organisations' event documents |

```bash
engine-dmo api member routes          # every operation and whether this project serves it
engine-dmo api member openapi         # the OpenAPI 3.1 document
engine-dmo api member form --listing <id> --person <id>   # the form a given member would receive
```

Declared screens and actions are portal features; the member API does not expose them, and event submission has no API operation yet.

## Troubleshooting [#troubleshooting]

| Message from `check` | Fix |
|---|---|
| `the <source> source reads the active organisation's data, and this screen's path has no {org} or {id}` | Add `{org}` to the path, such as `/organisations/{org}/<key>`. |
| `"<name>" is not a screen data source` | Use one of the sources in the table. |
| `screen <key> replaces the reference screen's template and takes no path` | A screen keyed as a reference screen takes `template` only; give a new screen its own key. |
| `unknown partner permission "<name>"` | Use a built-in permission, an `action.<key>` or a `screen.<key>`. |
| `action key "<key>" is <subject>.<verb>: lowercase, one dot` | Rename it, with one of the allowed verbs. |
| `an action with input and steps ... is not built yet` | Give the action a `target`; a form that only stores a message is a declared endpoint with `access: member`. |
| `tier "<tier>" is not sold on site <site>` (warning) | List the tier in the site's `memberships.tiers`, or drop it from the rule. |


# Promotions (/dmo/promotions)

How to declare promotion slots on a site (across the site or per landing page), how members request them and staff approve them, how promoted() and promotionLabel() render paid placements with the label the law requires, and every slot setting, status and check.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A promotion slot is a place on a site's pages where a business's document can be featured for a period: a home page feature, a featured listing at the top of an index, the first place on a landing page. A site declares its slots; members ask for one from the portal for one of their published documents and a window of dates; staff approve, reject, cancel or extend; and the public site shows each approved promotion while its window holds, always labelled as promoted.

Promotions record what was charged and an invoice reference. Taking payment in the portal is the [paid listings](/dmo/paid-listings) module's.

## A minimal slot [#a-minimal-slot]

```yaml title="config/sites/main/promotions.yaml"
label:
  en-GB: Promoted
slots:
  - key: home-feature
    name: { en-GB: Home page feature }
    types: [listing]
    capacity: 2
    days: { min: 7, max: 28 }
    lead_time: 3d
    tiers: { min: gold }
    price: { amount: "90.00", currency: GBP, per: week }
```

```jinja title="templates/_shared/partials/home-feature.html"
{% set items = promoted('home-feature') %}
{% if items %}
<section aria-labelledby="featured-heading">
  <h2 id="featured-heading">{{ t('home.featured') }}</h2>
  <ul>
    {% for item in items %}
    <li data-mrd-promotion="{{ item.promotion.id }}">
      <a href="{{ item.url|url }}">{{ promotionLabel(item) }} {{ item.title }}</a>
    </li>
    {% endfor %}
  </ul>
</section>
{{ impressions() }}
{% endif %}
```

Run `engine-dmo check --fix` to write the slot's id (`slot_`), then `engine-dmo schema plan` and `schema apply`, which records the slot in the database. `engine-dmo dev slot add home-feature --types listing --capacity 2 --min-days 7 --max-days 28 --lead-time 3d --min-tier gold --price 90.00 --per week` writes the same entry.

## The label [#the-label]

Paid placement must be identifiable. `promotionLabel(item)` prints the site's label as visible text:

```html
<span class="promotion-label" data-promotion-label id="promotion-<id>-label">Promoted</span>
```

Print it **inside each placement's link**, so it is part of the link's accessible name. Two checks hold templates to this:

- `engine-dmo check` refuses a template that calls `promoted()` and never calls `promotionLabel()` (`promoted-unlabelled`), and a `promoted('<slot>')` naming a slot the site does not declare (`unknown-slot`);
- the accessibility check of a rendered page reports a printed label that is hidden or is not in the accessible name of its placement's link.

`label:` in `promotions.yaml` sets the wording per locale. A locale it leaves out uses the engine's wording where it has one (`Promoted` in English, `Hyrwyddwyd` in Welsh), and `Promoted` in the site's default locale otherwise. A label written empty is an error; a label for a locale the site does not enable is warned about.

## Slot settings [#slot-settings]

`config/sites/<site>/promotions.yaml`:

| Key | Required | Default | Meaning |
|---|---|---|---|
| `label` | no | the engine's wording | The label per locale |
| `slots[].key` | yes | | Lowercase letters, digits and hyphens; unique on the site. What templates name. |
| `slots[].id` | written by `check --fix` | | The stable id (`slot_`). Promotions are stored against it, so renaming a slot keeps them. |
| `slots[].name` | no | | The slot's name per locale, as staff and partners see it |
| `slots[].types` | yes | | Document types it may promote. Each must be on the site and not a singleton. |
| `slots[].capacity` | no | `1` | How many promotions may be live at once (per page, for a landing slot). At least 1. |
| `slots[].days.min` | no | `1` | The shortest promotion in days |
| `slots[].days.max` | no | no limit | The longest promotion in days |
| `slots[].lead_time` | no | none | The earliest a member's request may start after it is made, such as `3d` |
| `slots[].tiers` | no | every tier and `none` | The tiers whose organisations may request it, as a [tier list](/dmo/partners-and-portal#tier-lists-in-rules) |
| `slots[].price.amount` | with `price` | | A quoted decimal with at most two places, such as `"90.00"`; a float is refused |
| `slots[].price.currency` | no | the site's `default_currency` | A three-letter ISO 4217 code |
| `slots[].price.per` | no | `placement` | `week`, `day` or `placement` |
| `slots[].scope` | no | `site` | `site`: one inventory across the site. `landing`: one inventory per live landing page. |
| `slots[].landings` | no | every landing with a place over one of the slot's types | `scope: landing` only: the landing keys whose pages it sells |
| `slots[].prices` | no | | `scope: landing` only: price overrides; see below |

The price is shown to the member when they ask and is what [paid listings](/dmo/paid-listings) charges; it is not a commitment the engine enforces otherwise. A price per week is charged for each week begun, per day for each day, per placement once.

`engine-dmo config schema --file promotions` prints the file's schema.

## Slots sold per landing page [#slots-sold-per-landing-page]

A slot with `scope: landing` sells each live [landing page](/dmo/landing-pages) separately: `capacity` counts per page, a member chooses the page when they ask, and the price can vary by place and category.

```yaml title="config/sites/main/promotions.yaml"
slots:
  - key: landing-top
    name: { en-GB: Top of a landing page }
    types: [listing]
    scope: landing
    landings: [by-place]
    capacity: 1
    days: { min: 28 }
    price: { amount: "25.00", per: week }
    prices:
      - { places: [banbury], categories: [stay], amount: "40.00" }
```

```jinja title="templates/_shared/listing/landing.html (excerpt)"
{% for item in promoted('landing-top') %}
<p class="featured" data-mrd-promotion="{{ item.promotion.id }}"><a href="{{ item.url|url }}">{{ promotionLabel(item) }} {{ item.title }}</a></p>
{% endfor %}
```

On a landing page, `promoted('landing-top')` reads the page it is on. Elsewhere, pass the page: `promoted('landing-top', landing)` where `landing` is a landing context (it reads `landing.pageKey`). Anywhere else a landing slot shows nothing.

Each entry of `prices` sets the amount for pages whose place is in `places` (the place's path on the site, or its last segment: `banbury` or `cotswolds/banbury`) and whose category is in `categories` (the category value). An empty list matches every place or category. The first match wins; a page no rule matches costs `price`. `prices` needs a `price`, whose currency and unit it uses.

Only landings with a place are sold this way: a slot naming none, or a site with no such landing over the slot's types, is an error. `scope: landing` needs the directory module, so `engine-cms` refuses it.

When a landing page stops being live while one of its promotions is running, the promotion is **paused**: it stops showing, the business reads why on its timeline, and staff see it on the admin's attention list to extend or credit. It resumes when the page is live again.

## How a promotion proceeds [#how-a-promotion-proceeds]

1. A member whose role grants `promotion.request`, at a tier the slot allows, asks from the portal's promotions screen (`/organisations/{org}/promotions`) for one of the organisation's documents that is published on the site and of a type the slot takes, with a start and an end. The form shows the dates already taken. The request must start at least `lead_time` from now, run between `days.min` and `days.max`, and fit the slot's capacity in that window; a window the approved promotions already fill is refused with the clash named. The promotion is `requested`.
2. Staff with `promotions.decide` on the site work the **Promotions** queue (under Members). Approving checks capacity again with the slot locked, so two approvals cannot both take its last place, and records the amount, currency and an invoice or order reference if given. Rejecting and cancelling need a reason the business reads.
3. Every minute the engine moves approved promotions to `live` when their window starts and to `ended` when it ends. A promoted document that is unpublished or trashed ends its promotions at once.

Staff can also create an approved promotion directly for a document of an organisation; the slot's types, length and capacity apply, but not the lead time or tiers. They can extend a booked or live promotion's end (within capacity, not the maximum length), and a member can withdraw their own request.

```mermaid
stateDiagram-v2
  [*] --> requested : a member asks
  [*] --> approved : staff create one
  requested --> awaiting_payment : checkout started
  awaiting_payment --> requested : order cancelled
  requested --> approved : staff approve
  awaiting_payment --> approved : paid
  requested --> rejected : staff reject
  awaiting_payment --> rejected : staff reject
  requested --> cancelled : withdrawn or cancelled
  awaiting_payment --> cancelled : withdrawn or cancelled
  approved --> live : window starts
  approved --> cancelled : staff cancel
  live --> cancelled : staff cancel
  live --> ended : window ends, or<br/>document unpublished
```

A paused promotion (its landing page stopped being live) keeps its status and simply stops showing until the page is live again.

| Status | Meaning |
|---|---|
| `requested` | Waiting for staff |
| `awaiting_payment` | On a site that sells the slot through [paid listings](/dmo/paid-listings) at checkout: the partner has started paying. Payment approves it; an abandoned or cancelled order returns it to `requested`. |
| `approved` | Booked; its window has not started |
| `live` | Showing now |
| `ended` | Its window ended, or its document was unpublished |
| `rejected` | Refused with a reason |
| `cancelled` | Withdrawn by the member, or cancelled by staff with a reason |

## In templates [#in-templates]

| Name | What it gives |
|---|---|
| `promoted('<slot>')` | The documents of the slot's live promotions, published in the request's locale and on the site, oldest start first, at most the slot's capacity |
| `promoted('<slot>', landing)` | The same for one landing page, for a slot sold per landing page |
| `item.promotion` | On each item: `id`, `slot`, `label`, `startsAt` and `endsAt` in the site's timezone |
| `item.organisationId` | The organisation that bought it |
| `promotionLabel(item)` | The label as a `span`, described above |

Each item is an ordinary entry, so `item.title`, `item.url` and the type's fields are there. A page is never varied by who is signed in: a promotion is the same for every visitor. The live set is cached until the next start or end in the slot, so a cached page shows a promotion from its start and not after its end without a purge.

Mark each placement with `data-mrd-promotion="{{ item.promotion.id }}"` and print `{{ impressions() }}` once on the page, and its views are counted as `promotion_impression`, a figure of its own in the business's [member report](/dmo/member-reports) that never inflates the listing's impressions.

### Templates shared between sites [#templates-shared-between-sites]

`check` holds every template on a site's chain to that site's slots. A template in a shared root that calls `promoted('home-feature')` is an error on any site sharing it that does not declare `home-feature`. Declare the slot on each such site (with the types the site has), or move the call into a template under the site's own root.

## Permissions [#permissions]

| Who | Permission |
|---|---|
| Members asking for a slot | `promotion.request` (partner role), and a tier the slot allows |
| Staff deciding | `promotions.decide` on the site (built-in `administrator` and `partnership-manager`) |

## Troubleshooting [#troubleshooting]

| Message | Fix |
|---|---|
| `slot <key> names no types: say what it may promote` | Add `types:`. |
| `type <type> is not on site <site>` | Use a type offered on the site (`sites:` in its schema file). |
| `write the amount as a quoted decimal such as "150.00", never a float` | Quote the amount. |
| `a price needs a currency, and site <site> has no default_currency` | Set `currency:` or the site's `default_currency`. |
| `landings name the pages a slot sells, which only a slot with scope: landing does` | Add `scope: landing` or remove `landings`. |
| `slot <key> is sold per landing page, but no landing with a place on site <site> lists ...` | Declare a place and category landing on the route of one of the slot's types. |
| `promoted() renders paid placements and this template never prints promotionLabel()` | Print `{{ promotionLabel(item) }}` inside each placement's link. |


# Extensions (/extending/extensions)

How to write a Meridian extension, a Go plugin built against github.com/wrux/meridian-extend that adds template globals and filters, HTTP routes, commands, an asset resolver and a dev server; every interface it offers, how to build it so the engine will load it, how to name it in engine.yaml, and every error the loader gives.

An extension is a Go plugin (a `.so` file) that the engine opens at boot when the project's `engine.yaml` names it. It adds template globals and filters, HTTP routes, commands, the asset helpers' resolver and a dev server to the project, without your needing the engine's source: you build it against one small module, `github.com/wrux/meridian-extend`, which uses the Go standard library only.

Use an extension when templates and configuration cannot express what you need. For logic behind a declared endpoint, a [project plugin](/extending/plugins) runs out of process and is easier to deploy; for wiring Vite, use the first-party [`vite` extension](/extending/first-party-extensions).

## A minimal extension [#a-minimal-extension]

```go
// shout.go
package main

import (
	"context"
	"strings"

	extend "github.com/wrux/meridian-extend"
)

type shout struct{}

func (shout) Manifest() extend.Manifest {
	return extend.Manifest{ID: "shout", Name: "Shout", Version: "1.0.0"}
}

// Register declares the filter, so engine-dmo check admits it in templates.
func (shout) Register(r extend.Registrar) error {
	return r.Filter("shout", "value|shout: the value in capitals")
}

// Init attaches the filter's function once the engine is running.
func (shout) Init(_ context.Context, h extend.Host) error {
	return h.Filter("shout", func(_ extend.Render, in, _ extend.Value) (any, error) {
		return strings.ToUpper(in.String()), nil
	})
}

// Extension is the symbol the engine looks up.
var Extension extend.Extension = shout{}

func main() {}
```

Build it for the engine it will load into (see [Building](#building) for the exact rules), put the file in the project and name it:

```bash
go build -trimpath -buildmode=plugin -o extensions/shout.so .
```

```yaml
# config/engine.yaml
extensions:
  - extensions/shout.so
```

```jinja
<h2>{{ entry.title|shout }}</h2>
```

`engine-dmo check --project .` now admits `|shout`, and `engine-dmo version --project .` lists `shout` among the modules.

## How the engine uses an extension [#how-the-engine-uses-an-extension]

This is the whole path from your source to a template calling your filter: one build on your side, then four stages in every engine process that names the file.

```mermaid
flowchart TD
  src["your extension<br/>(package main)"] -->|"go build -buildmode=plugin"| so["greet.so"]
  so --> yaml["engine.yaml<br/>extensions: [extensions/greet.so]"]
  yaml --> cgo{"engine built<br/>with cgo?"}
  cgo -->|no| refuse["refused: pure Go build"]
  cgo -->|yes| info{"build info matches<br/>the engine's?"}
  info -->|no| mismatch["refused, naming<br/>the difference"]
  info -->|yes| reg["Load and Register<br/>(every command, check included)"]
  reg -->|"serve only"| init["Init: attach functions,<br/>mount routes"]
  init -->|"a declared name<br/>not attached"| stop["boot stops"]
  init --> call["Call: each template use<br/>of a global or filter"]
```

<Steps>
<Step>
**Load.** When the engine reads `engine.yaml` (on `serve`, `check`, and every other command that loads the project), it opens each file under `extensions:`, after checking the file's build information against its own (see [Building](#building)). A file that does not match is refused by name, before it is opened.
</Step>
<Step>
**Register.** It calls `Manifest()` and `Register(r)`. `Register` declares names only: globals, filters, a dev server, commands. It must do no I/O and read no configuration, because `engine-dmo check` and every command run it.
</Step>
<Step>
**Init.** When the engine boots to serve, it calls `Init(ctx, h)` on an extension that implements `extend.Initer`, after the engine's services exist and before the server takes requests. `Init` attaches the function of every global and filter `Register` declared, mounts routes and sets the asset resolver. An error from `Init` stops the boot with the extension named. A declared global or filter that `Init` did not attach also stops the boot: `the template global cn is declared but Init did not attach it (Host.Global)`.
</Step>
<Step>
**Call.** Each time a template calls a global or applies a filter, the engine calls your function with the page's render context. A panic in any of your functions is recovered and becomes that render's error, naming the global or filter; it does not stop the process. A goroutine your extension starts itself is not protected.
</Step>
</Steps>

## The interfaces [#the-interfaces]

Your plugin's `main` package exports one variable, `Extension`, of type `extend.Extension`. You implement `Extension` and, optionally, `Initer`. Every other interface below is implemented by the engine; you call it and never implement it. The engine may add methods to those interfaces in a minor release of the module.

### Extension and Initer [#extension-and-initer]

```go
type Extension interface {
	Manifest() Manifest
	Register(r Registrar) error
}

type Initer interface {
	Init(ctx context.Context, h Host) error
}
```

### Manifest [#manifest]

| Field | Type | Meaning |
|---|---|---|
| `ID` | `string` | The extension's handle: lower case letters, digits and underscores, starting with a letter. It may not be `core`, `engine` or `meridian`, nor the id of a module the engine compiles (`engine-dmo version` lists them), nor another extension's. |
| `Name` | `string` | What the boot log and `engine-dmo check` show. |
| `Version` | `string` | Your extension's own version. |
| `Requires` | `[]string` | Ids of modules the engine must compile (`crm`, `portal`) or of other extensions the project loads. A missing one refuses the load: `module x requires module y, which neither bundle dmo nor the extensions have`. Extensions are registered after the bundle's modules and after the extensions they require. |

### Registrar [#registrar]

What `Register` receives.

| Method | What it declares |
|---|---|
| `Global(name, doc string, keywords ...string) error` | A template global: a function every page of the public site may call by name. `doc` is its one-line documentation for the generated template API and must not be empty. `keywords` are the keyword arguments it takes: none, their names, or `extend.AnyKeyword` (`"*"`) to admit any keyword. `engine-dmo check` admits a call to it, holds the call's keywords to this list, and refuses a call to a name nothing declares. A name core or a module already has is refused. |
| `Filter(name, doc string) error` | A template filter, used as `value|name` or `value|name:arg`. `doc` must not be empty. |
| `DevServer(fn DevServerFunc) error` | A dev server that `engine-dmo serve --dev` starts as a child before the engine boots and stops when it stops. Its origin is admitted by the development content security policy for scripts, styles, images, fonts and its socket. One per extension. |
| `Command(c Command) error` | A command on the engine's command line, present from the first run because extensions load before the command line is built. |

### Host [#host]

What `Init` receives.

| Method | Meaning |
|---|---|
| `ProjectDir() string` | The project's directory, under which an extension reads its own files. |
| `Production() bool` | Whether `engine.environment` is `production`, where an extension may cache what it reads. |
| `Log() *slog.Logger` | The engine's logger, with your extension's id on each line. |
| `Global(name string, fn GlobalFunc) error` | Attaches the function of a global declared in `Register`. An undeclared name is refused: `declare it in Register with Registrar.Global`. |
| `Filter(name string, fn FilterFunc) error` | Attaches the function of a declared filter. |
| `Route(pattern string, h http.Handler)` | Mounts a handler on the engine's top-level mux, ahead of the admin and the public site, for a Go `net/http` pattern such as `"GET /ui/health"`. The handler secures itself: no session, permission check, CSRF protection or rate limit of the engine's applies. |
| `Dev() bool` | Whether the engine runs under `serve --dev`. |
| `PublicDir() string` | The project's `public/` directory, which the engine serves and a frontend build writes under. |
| `Assets(fn AssetsFunc) error` | Sets the resolver of the asset helpers' bundles. The engine holds one at most; a second is refused. |

### Functions you write [#functions-you-write]

```go
// Called for every call a template makes.
type GlobalFunc func(r Render, args Args) (any, error)

// in is the value the filter is applied to; arg IsNil when the template wrote none.
type FilterFunc func(r Render, in, arg Value) (any, error)

// ok false leaves the bundle to the engine's own fallback.
type AssetsFunc func(r Render, req AssetRequest) (markup HTML, ok bool)

// Returns the zero DevServer, and no error, when there is nothing to serve.
type DevServerFunc func(ctx context.Context, d Dev) (DevServer, error)
```

A global or filter returns a `string`, a number, a `bool`, `[]any`, `[]string`, `map[string]any`, `extend.HTML`, an `extend.Value`, or `nil`. A string is escaped where the template prints it. `extend.HTML` is printed unescaped: return it only for markup you built from escaped parts. An error fails the render with the global or filter named (`greeting(): ...`, `|shout: ...`).

### Render [#render]

The page render a function runs in.

| Method | Meaning |
|---|---|
| `Site() Site` | The page's site. |
| `Locale() string` | The page's locale, a BCP 47 tag such as `en-GB`. |
| `Request() *http.Request` | The request the page renders for. Read it; do not change it. |
| `ProjectDir() string` | The project's directory. |
| `Once(key string) bool` | True the first time it is asked for `key` in this render, false after: for markup a page needs once, such as a client script. |

### Site [#site]

| Field | Meaning |
|---|---|
| `Key` | The site's key. |
| `TemplateChain` | The site's template roots in lookup order, its own first: directories under `templates/`. |
| `PathPrefix` | The path the site is served under on a shared host, `""` at its root. A link to a public file starts with it. |
| `Bundles` | `site.yaml`'s `assets.bundles`: an entry file relative to the project, by bundle name. A name not listed builds from `src/entries/<site>.js` (`main`) or `src/entries/<site>-<name>.js`. |
| `Manifest` | `site.yaml`'s `assets.manifest`, a build manifest relative to the project for a site built by its own toolchain; `""` for the project's build. |
| `Budgets` | `site.yaml`'s `assets.budgets`: a size by kind (`css`, `js`, `legacy_css`, `legacy_js`), as written (`120KB`). |

### Args and Value [#args-and-value]

`Args` are a call's arguments: positional ones, then keywords written `name=value`.

| Method | Meaning |
|---|---|
| `Len() int` | The number of positional arguments. |
| `At(i int) Value` | The positional argument at `i`; past the end it `IsNil`. |
| `Positional() []Value` | The positional arguments in order. |
| `Keywords() []string` | The keywords' names in call order. |
| `Keyword(name string) (Value, bool)` | A keyword's value and whether it was passed. |
| `Only(names ...string) error` | Refuses a keyword not among `names`. The engine already does this for the keywords you declared, unless you declared `AnyKeyword`. |

`Value` is a template value as your function receives it: `IsNil`, `IsString`, `IsNumber`, `IsInteger`, `IsBool`, `IsList`, `IsMap`, `IsTrue` (its truth as `{% if %}` reads it), `String()` (as a template prints it, `""` when nil), `Int()`, `Float()`, `Bool()` (false unless it is a boolean), `Len()` (of a string, list or map), `Index(i)` (a list's item, nil out of range) and `Interface()` (the Go value: strings, numbers, booleans, `[]any` and `map[string]any` are what they say; any other type is the engine's own and opaque to you).

### Assets [#assets]

The asset helpers (`assets.css('main')`, `assets.js('main')`, `assets.js('legacy', false)`, `preload()`) ask your resolver for each bundle:

| `AssetRequest` field | Meaning |
|---|---|
| `Bundle` | The bundle's name: `main`, `legacy`. |
| `Kind` | `css`, `js` or `preload`. |
| `Module` | For `js`: a module script rather than a classic deferred one. |

Return `ok` false to leave a bundle to the engine, which prints `css/<name>.css` or `js/<name>.js` under `public/` for `css` and `js`, and nothing for `preload`. [The frontend build](/templates/frontend-build) describes the helpers.

### Dev server [#dev-server]

| Type | Field | Meaning |
|---|---|---|
| `Dev` | `ProjectDir` | The project's directory. |
| | `Engine` | The running engine binary's path, for a toolchain that calls the engine back (`engine-dmo assets manifest`). |
| | `Log` | The engine's log, with your extension's id on each line. |
| `DevServer` | `Origin` | Its scheme, host and port: `http://127.0.0.1:5173`. |
| | `Stop` | Stops it; nil when there is nothing to stop. |
| | `Policy` | Further sources the development content security policy admits, by directive, beyond the origin: `"style-src": {"'unsafe-inline'"}` for a server that injects `<style>` elements. Development only: the production policy never sees them. |

### Commands [#commands]

| `Command` field | Meaning |
|---|---|
| `Path` | Where the command goes: `"ui"` for a top-level command, or a parent's path and a name (`"assets budget"`) beside the engine's own. |
| `Short` | Its one-line description for the help. |
| `Flags` | Declares its flags on a standard library `*flag.FlagSet`, which the engine parses with its own global flags. |
| `Run` | Runs it. An error exits with status 1, printed. A panic is recovered into an error. |

`Run` receives a `CommandContext`:

| Method | Meaning |
|---|---|
| `Args() []string` | The arguments after the command and its flags. |
| `Flags() *flag.FlagSet` | The flag set `Flags` declared, parsed. |
| `ProjectDir()`, `ConfigDir()` | The global `--project` and `--config`. |
| `JSON()`, `Quiet()` | The global `--json` and `--quiet`. |
| `Stdout()`, `Stderr()` | Where to write. |
| `Sites() ([]Site, error)` | The project's sites, from its configuration, loaded and checked as for any other command. |
| `TemplateDir() string` | The project's templates directory (`template.dir`, `templates` by default). |
| `PublicDir() string` | The project's `public/` directory. |

## A complete extension [#a-complete-extension]

This extension declares a global that takes a keyword and reads the page's locale, a filter with an optional argument, an asset resolver for one bundle, a dev server and a command.

```go
// greet.go
package main

import (
	"context"
	"flag"
	"fmt"
	"html"
	"net"
	"net/http"
	"strings"

	extend "github.com/wrux/meridian-extend"
)

type greet struct{}

var Extension extend.Extension = greet{}

func (greet) Manifest() extend.Manifest {
	return extend.Manifest{ID: "greet", Name: "Greetings", Version: "0.1.0"}
}

func (greet) Register(r extend.Registrar) error {
	if err := r.Global("greeting", "greeting(name, punct='.'): a greeting for name in the page's language, ending in punct", "punct"); err != nil {
		return err
	}
	if err := r.Filter("shout", "value|shout or value|shout:'!': the value in capitals, with the argument after it"); err != nil {
		return err
	}
	if err := r.DevServer(devServer); err != nil {
		return err
	}
	return r.Command(extend.Command{
		Path:  "greet hello",
		Short: "Print a greeting, to show an extension's command",
		Flags: func(fs *flag.FlagSet) { fs.String("name", "world", "who to greet") },
		Run: func(_ context.Context, c extend.CommandContext) error {
			_, err := fmt.Fprintf(c.Stdout(), "Hello, %s, from %s\n", c.Flags().Lookup("name").Value.String(), c.ProjectDir())
			return err
		},
	})
}

func (greet) Init(_ context.Context, h extend.Host) error {
	if err := h.Global("greeting", greeting); err != nil {
		return err
	}
	if err := h.Assets(assets); err != nil {
		return err
	}
	return h.Filter("shout", func(_ extend.Render, in, arg extend.Value) (any, error) {
		return strings.ToUpper(in.String()) + arg.String(), nil
	})
}

var hello = map[string]string{"en": "Hello", "ja": "こんにちは", "th": "สวัสดี"}

func greeting(r extend.Render, a extend.Args) (any, error) {
	word, ok := hello[strings.SplitN(r.Locale(), "-", 2)[0]]
	if !ok {
		word = hello["en"]
	}
	punct := "."
	if p, ok := a.Keyword("punct"); ok {
		punct = p.String()
	}
	return word + ", " + a.At(0).String() + punct, nil
}

// assets resolves the greet bundle and leaves every other one to the engine.
func assets(r extend.Render, req extend.AssetRequest) (extend.HTML, bool) {
	if req.Bundle != "greet" || req.Kind != "js" {
		return "", false
	}
	var b strings.Builder
	if r.Once("greet-client") {
		b.WriteString(`<script type="module" src="` + html.EscapeString(r.Site().PathPrefix+"/greet/client.js") + `"></script>`)
	}
	b.WriteString(`<script type="module" src="` + html.EscapeString(r.Site().PathPrefix+"/greet/"+r.Site().Key+".js") + `"></script>`)
	return extend.HTML(b.String()), true
}

// devServer serves a greeting on a free loopback port under serve --dev.
func devServer(_ context.Context, d extend.Dev) (extend.DevServer, error) {
	l, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		return extend.DevServer{}, err
	}
	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprintln(w, "hello from the greet dev server")
	})}
	go func() { _ = srv.Serve(l) }()
	d.Log.Info("greet dev server", "addr", l.Addr().String())
	return extend.DevServer{Origin: "http://" + l.Addr().String(), Stop: func() { _ = srv.Close() }}, nil
}

func main() {}
```

In a template:

```jinja
<p>{{ greeting("visitor", punct="!") }}</p>
<h2>{{ entry.title|shout:"!" }}</h2>
{{ assets.js('greet') }}
```

On an `en-GB` page the first line prints `Hello, visitor!`; on a `ja-JP` page, `こんにちは, visitor!`. From the shell:

```bash
engine-dmo greet hello --name Sian --project .
```

### Mounting a route [#mounting-a-route]

A route is mounted in `Init` and secures itself:

```go
func (greet) Init(_ context.Context, h extend.Host) error {
	h.Route("GET /greet/health", http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_, _ = w.Write([]byte(`{"ok":true}`))
	}))
	// attach globals and filters as above
	return nil
}
```

## Building [#building]

A Go plugin shares the Go runtime and every common package with the program that opens it, so it loads only into the exact build it was made for. The engine reads your plugin's build information before it opens it and refuses any difference, naming it and saying what to change. What your plugin must match:

| Must match | Where to read it |
|---|---|
| The Go toolchain, exactly (`go1.27.3`) | `engine-dmo version`, the `extensions:` line |
| Operating system and architecture (`linux/amd64`, `darwin/arm64`), and the architecture level when the engine records one (`GOARM64=v8.0`) | The same line |
| Built with cgo (`CGO_ENABLED=1`) | The same line says `cgo` |
| Built with `-trimpath` | The same line says `-trimpath` |
| `github.com/wrux/meridian-extend` at exactly the engine's version | The same line, `meridian-extend <version>` |
| Every module your plugin shares with the engine, at the engine's version | `engine-dmo version --json`, `extensions.modules` |
| Built outside a Go workspace (`GOWORK=off`) | |

```bash
engine-dmo version
```

```text
meridian v0.8.0 (vips) go1.27.3
  bundle dmo: modules ai directory forms crm ...
  extensions: built with go1.27.3 linux/amd64, cgo, -trimpath, meridian-extend v0.0.0-00010101000000-000000000000
```

The values above are an example; read your own engine's.

`engine-dmo version --json` gives the same under `extensions`: `supported`, `go_version`, `os`, `arch`, `level`, `cgo`, `trimpath`, `meridian_extend` and `modules` (every module the engine links, by path and version).

### The module file [#the-module-file]

```go
// go.mod
module example.com/greet

go 1.26.0

toolchain go1.27.3

require github.com/wrux/meridian-extend v0.0.0-00010101000000-000000000000

replace github.com/wrux/meridian-extend => ../meridian-extend
```

Require `meridian-extend` at exactly the version `engine-dmo version` prints. While the module is not published to a Go module proxy, that version is the zero pseudo-version shown above and your `go.mod` points a `replace` directive at your copy of the module's source.

<Callout type="warn" title="Getting the module's source">
A release does not carry `meridian-extend`: it is not on a Go module proxy, and neither the binary nor the container images contain its source. Today the only copy is in the Meridian source repository (`libs/extend`), so building an extension needs that source from Cherwell Studio, at the commit your engine was built from. With the binary alone, an extension cannot be built. Configuration, templates and declared endpoints need nothing beyond the binary.
</Callout>

Keep your extension's own dependencies to the standard library where you can: any module the engine also links must be required at the engine's version, or the plugin will not open.

### The build command [#the-build-command]

For the container image (`linux/amd64`), build with the official Go image of the engine's toolchain:

```bash
docker run --rm --platform linux/amd64 -v "$PWD":/src -w /src \
  -e GOWORK=off -e CGO_ENABLED=1 golang:1.27.3-trixie \
  go build -trimpath -buildmode=plugin -o greet.so .
```

For an engine binary on your own machine, with the same Go version installed:

```bash
GOWORK=off CGO_ENABLED=1 go build -trimpath -buildmode=plugin -o greet.so .
```

If your `replace` points outside the directory you mount into the container, mount that directory too.

### Which engines load extensions [#which-engines-load-extensions]

Extensions load only in an engine built with cgo, on Linux, macOS or FreeBSD. The `-vips` container image is one; an engine built without cgo refuses every extension (`this engine is a pure Go build, which cannot load extensions: run the -vips image, a cgo build`). Windows cannot load Go plugins. See [Container images](/deploying/container-images).

### Rebuild for every engine release [#rebuild-for-every-engine-release]

There is no compatibility window between releases: a plugin built for one engine build opens in that build only. A new engine release may change the Go toolchain, the `meridian-extend` version or a shared module. Rebuild every extension against each release before you deploy it, and run `engine-dmo check` with the new binary: it opens every extension and reports a mismatch at its line in `engine.yaml`.

## Naming extensions in engine.yaml [#naming-extensions-in-engineyaml]

```yaml
# config/engine.yaml
extensions:
  - vite                     # a first-party extension, by name
  - extensions/greet.so      # your own, by path relative to the project
```

| Entry | Resolves to |
|---|---|
| A bare name (no `/`, no `.so`, not starting with `.`) | A first-party extension shipped beside the engine binary: `extensions/<name>.so` next to the executable (`/app/extensions/<name>.so` in the image). |
| A path | The file at that path, relative to the project directory unless absolute. |

Each file loads once per process, in the order listed, then extensions are registered in the order their `Requires` allow. Every problem across the list is reported together, each at its line.

## Errors [#errors]

The loader's messages, each reported by `engine-dmo check` at the entry's line in `engine.yaml` with error code `MRD-1006`, and by `serve` before it boots:

| Message | Cause and fix |
|---|---|
| `no extension at <path>` | The file is not there. Paths are relative to the project directory. |
| `this engine has no extension named <name> (looked for ...)` | A bare name that is not a first-party extension of this engine. Write a path for your own. |
| `this engine is a pure Go build, which cannot load extensions` | Run the `-vips` image or another cgo build. |
| `extensions load on Linux, macOS and FreeBSD, not <os>` | Go plugins do not exist on that system. |
| `this engine was built in a Go workspace, which no extension can match` | An engine you built yourself in a workspace. Use a release binary or image. |
| `<path> is not a Go plugin with build information` | Not a Go plugin, or built without module information. |
| `<path> does not match this engine (...)` followed by each difference | One or more of: `it is not a Go plugin (built with -buildmode=...)`; `it was built with go1.x and the engine with go1.y: build it with go1.y (the golang:1.y-trixie image)`; `it was built for os/arch and the engine runs on os/arch`; a different architecture level; `it was built against meridian-extend x and the engine links y: require github.com/wrux/meridian-extend y`; `build it with -trimpath, as the engine was`; `it requires <module> x and the engine links y`. |
| `<path> shares the package <pkg> with the engine at another version` | A shared package differs although the versions above match: build with `-trimpath`, against the engine's `meridian-extend`, outside a workspace, with the engine's version of every module it also links. |
| `<path> exports no Extension: declare var Extension extend.Extension = ...` | The symbol is missing. |
| `<path> exports Extension as <type>, not an extend.Extension` | Declare it with the interface type: `var Extension extend.Extension = greet{}`. |
| `module id "X" is not lower case letters, digits and underscores starting with a letter`, `module id "core" is reserved`, `module x is in the bundle already` | Change `Manifest().ID`. |
| `the template global x has no documentation` | Pass a non-empty `doc` to `Global` or `Filter`. |
| `the template global x is not declared: declare it in Register with Registrar.Global` | `Init` attached a name `Register` did not declare. |
| `the command "x" has no Run` | Give the command a `Run` function. |

## Security [#security]

An extension runs inside the engine process with the engine's privileges, its memory and its environment, secrets included. It is trusted code, like the engine itself: review it as you would the engine, build it yourself from source you control, and never load a `.so` you did not build. A route it mounts has no authentication unless the handler adds it.


# First-party extensions (/extending/first-party-extensions)

The extensions that ship beside the engine binary and load by name from engine.yaml (today the vite extension): what each adds, where its file lives in a release and in the container image, and how to turn it on.

A first-party extension is an [extension](/extending/extensions) built and released with the engine, against the same `meridian-extend` module your own extensions use. It ships as a `.so` file beside the engine binary and is never compiled into it, so a project that does not name it does not load it. You name one in `engine.yaml` by its name alone:

```yaml
# config/engine.yaml
extensions:
  - vite
```

| Where the engine looks | When |
|---|---|
| `extensions/<name>.so` in the directory of the running engine binary | Always, for a bare name |
| `/app/extensions/vite.so` | In the `-vips` container image, where the engine is `/app/engine-dmo` |

The same rules apply as to your own extensions: they load only in an engine built with cgo (the `-vips` image), on Linux, macOS or FreeBSD. A name the engine does not ship is refused at its line: `this engine has no extension named <name> (looked for .../extensions/<name>.so); a path names a project's own, extensions/<name>.so`.

`engine-dmo version --project .` lists a loaded first-party extension among the bundle's modules.

<Callout type="warn" title="Where you can get one today">
A release publishes container images only, so the one place a first-party extension ships is the `-vips` image (`/app/extensions/vite.so`, `linux/amd64`). The pure Go image, including every `arm64` host, cannot load it, and a project that names `vite` is refused there at boot and by `check`. Run `check` and `serve` on the same image you deploy. A project that does not name `vite` serves its assets from `public/` on either image.
</Callout>

## vite [#vite]

Connects a [Vite](https://vite.dev) build to the template asset helpers and the development loop. A project that builds no frontend, or builds it with another tool, leaves it out and is served from the files in `public/`.

| It adds | What it does |
|---|---|
| The asset resolver | `assets.css('main')`, `assets.js('main')`, `assets.js('legacy', false)` and `preload()` print the content-hashed files a Vite build wrote, read from the build manifest at `public/build/.vite/manifest.json` (or the site's `assets.manifest`), with each bundle's CSS and the chunks it imports. A bundle the manifest does not hold falls back to `public/css/<name>.css` and `public/js/<name>.js`. |
| A dev server under `engine-dmo serve --dev` | When the project has a `vite.config.js` (or `.mjs`, `.ts`, `.mts`, `.cjs`, `.cts`) and Vite installed at `node_modules/.bin/vite`, the engine starts Vite on a free loopback port (`--port <n> --strictPort --host 127.0.0.1`) before it boots, points the helpers at it with hot reloading, admits its origin and inline styles in the development content security policy, and stops it on exit. Vite runs with `MERIDIAN_VITE_ORIGIN`, `MERIDIAN_PROJECT` and `MERIDIAN_ENGINE` in its environment. With a config and no installed Vite, the engine says so and serves `public/` as it is. |
| `engine-dmo assets budget [--site key] [--strict]` | Each site's built CSS and JavaScript, plain and gzipped, with a bundle named `legacy` counted apart, against `site.yaml`'s `assets.budgets` and the previous build (recorded in `.meridian/assets-sizes.json`). `--strict` exits 1 when a budget is exceeded. |
| `engine-dmo assets unused --site key [--bundle name]` | The CSS selectors in a site's bundles that match nothing in that site's templates. A report; it changes nothing. |

`assets.url()`, the plain `public/` fallback and `engine-dmo assets manifest` (each site's resolved components, blocks, template globs and bundle entries, for a bundler) are the engine's own and work without the extension.

The whole workflow, from `vite.config.js` to the production build, is in [The frontend build](/templates/frontend-build).

```bash
engine-dmo check --project .                 # loads the extension; refuses the project if it cannot
engine-dmo serve --dev --project .           # starts Vite beside the engine when the project has a config
engine-dmo build --project .                 # the project's frontend build, then check
engine-dmo assets budget --strict --project . # in CI, after the build
```

`engine-cms` behaves the same.


# Extending (/extending)

The ways to add behaviour to a Meridian site without changing the engine: configuration and declared endpoints, templates and components, Go extensions loaded from engine.yaml, and experimental out-of-process plugins, with how to choose between them.

You are given the engine as a binary (`engine-dmo` or `engine-cms`) and never its source. Everything a site needs beyond what the binary does is added from the project directory, in one of four ways. Start with the first that can express what you need: each later one costs more to build, test and keep in step with engine releases.

| Way | What it adds | Written in | Runs | Where it is described |
|---|---|---|---|---|
| Configuration | Content types and fields, routes, sites and locales, declared endpoints (forms, JSON projections, calls to upstream APIs), outbound webhooks, scheduled feed imports, roles | YAML under `config/` | Inside the engine | [Content modelling](/content-modelling), [Forms and submissions](/features/forms-and-submissions), [Integrating](/integrating) |
| Templates | Every page's markup, components, blocks, partials, the portal's look | Pongo2 templates under `templates/` | Inside the engine | [Templates](/templates) |
| Extensions | Template globals and filters, HTTP routes, commands, the asset helpers' resolver, a dev server under `serve --dev` | Go, as a plugin (`.so`) built against `github.com/wrux/meridian-extend` | Inside the engine process | [Extensions](/extending/extensions) |
| Project plugins (experimental) | Logic a declared endpoint calls when YAML cannot express it: branching rules, a calculation, a partner SDK | Any language that speaks the protocol; Go with `github.com/wrux/meridian-plugin` | A separate process the engine supervises | [Project plugins](/extending/plugins) |

## Choosing [#choosing]

- **A new field, type, page or form.** Configuration and templates. The engine validates both with `engine-dmo check`, renders them through the real pipeline with `engine-dmo render`, and reports every mistake at its file, line and column.
- **Reading another service's JSON on a page or from an endpoint.** A source in `sources.yaml` and the `source()` template function or a `source` step. See [Sources and importers](/integrating/sources-and-importers).
- **Telling another system that content changed.** An outbound webhook in `webhooks.yaml`. See [Webhooks](/integrating/webhooks).
- **A template function or filter the engine does not have** (a class-name merger, a formatter for a house style, a lookup in a file the project ships). An extension.
- **An HTTP route that is not a page, a form or a JSON projection**, or a command of your own beside the engine's. An extension.
- **Wiring a frontend toolchain into the asset helpers and the dev loop.** The first-party [`vite` extension](/extending/first-party-extensions), or an extension of your own built the same way.
- **An endpoint whose answer needs control flow** (a market that runs every Thursday except over Christmas, a price that depends on three inputs). A project plugin, marked experimental: its protocol may change in any release.

## What none of them can do [#what-none-of-them-can-do]

- Change how content is stored, validated, versioned or published, or add a field type. Field types are the engine's.
- Reach the database. Extensions and plugins see what the interfaces below hand them, and nothing else.
- Change the admin's screens. The admin's look is themed with `admin.theme` in `engine.yaml`; its screens are the engine's.
- Bypass permissions. An extension's route secures itself; it is given no session or permission check of the engine's.

## The checks that hold it together [#the-checks-that-hold-it-together]

Whichever way you choose, the same loop applies:

```bash
engine-dmo check --project .        # configuration, schema, templates and extensions, every problem at once
engine-dmo render / --project .     # a page through the real pipeline, in process
engine-dmo template api --project . # the template surface, including what your extensions declare
```

`engine-dmo check` loads every extension the project names and runs its `Register`, so a template that calls a global no extension declares, or passes a keyword the global does not take, fails the check rather than the page.

`engine-cms` behaves the same for everything on these pages: extensions and project plugins are core features of both bundles.


# Project plugins (experimental) (/extending/plugins)

How to give a declared endpoint logic YAML cannot express with a project plugin: an ordinary program the engine starts, supervises and calls over a Unix socket; plugins.yaml with every option, default and limit, the plugin step, writing one in Go with github.com/wrux/meridian-plugin, protocol version 0 on the wire, building, pinning and failure behaviour.

<Callout type="warn" title="Experimental">Project plugins speak plugin protocol version 0, which is experimental and may change in any engine release. The engine refuses a plugin built against a protocol version it does not speak, at `engine-dmo check` and at start. `engine-dmo version` prints the protocol it speaks (`plugin protocol 0 (experimental)`).</Callout>

A project plugin is an ordinary program, usually Go, that the engine starts, supervises and calls when a [declared endpoint](/features/forms-and-submissions) reaches a `plugin` step. It is for the logic an endpoint's YAML cannot express: a rule with branches, a calculation, a partner's API that needs an SDK. The endpoint keeps everything else: its access rule, input validation, CSRF, rate limits, audit, caching and response shape. The plugin receives the endpoint's validated input and returns data; it never sees the request.

A plugin is not an [extension](/extending/extensions). It runs out of process, so it needs no matching Go toolchain, and a crash costs the endpoints that use it rather than the site. It cannot add template functions or routes.

## A minimal plugin [#a-minimal-plugin]

A market calendar whose rules have branches in them: every Thursday except over Christmas, plus the last Saturday of every month but December.

```go
// plugin/main.go
package main

import (
	"fmt"
	"time"

	plugin "github.com/wrux/meridian-plugin"
)

func main() {
	plugin.Serve(plugin.Handlers{
		Endpoints: map[string]plugin.EndpointFunc{"market-days": marketDays},
	})
}

type Day struct {
	Date string `json:"date"`
	Kind string `json:"kind"`
}

func marketDays(ctx plugin.Context, r plugin.Request) (plugin.Response, error) {
	from := time.Now().UTC().Truncate(24 * time.Hour)
	if s := r.Input.String("from"); s != "" {
		d, err := time.Parse(time.DateOnly, s)
		if err != nil {
			return plugin.Response{}, fmt.Errorf("from is a date such as 2026-10-08, got %q", s)
		}
		from = d
	}
	count := 4
	if f, ok := r.Input.Float("count"); ok {
		count = min(max(int(f), 1), 12)
	}
	var out []Day
	for d := from; len(out) < count; d = d.AddDate(0, 0, 1) {
		christmas := (d.Month() == time.December && d.Day() >= 24) || (d.Month() == time.January && d.Day() == 1)
		switch {
		case d.Weekday() == time.Thursday && !christmas:
			out = append(out, Day{d.Format(time.DateOnly), "market"})
		case d.Weekday() == time.Saturday && d.Month() != time.December && d.AddDate(0, 0, 7).Month() != d.Month():
			out = append(out, Day{d.Format(time.DateOnly), "farmers-market"})
		}
	}
	ctx.Log.Info("market days", "from", from.Format(time.DateOnly), "count", len(out))
	return plugin.Data(out), nil
}
```

Declare it for the site, with the handlers an endpoint may call:

```yaml
# config/sites/<site>/plugins.yaml
plugins:
  markets:
    command: bin/markets          # the binary, relative to the project
    build: plugin                 # the Go program engine-dmo plugin build compiles to it
    endpoints: [market-days]      # the handlers a plugin step may call
    timeout: 2s
    concurrency: 4
    memory: 256MB
    circuit_breaker: { failures: 5, window: 1m, cooldown: 30s }
```

Call it from an endpoint:

```yaml
# config/sites/<site>/endpoints.yaml
endpoints:
  - key: market-days
    path: /api/market-days.json
    methods: [get]
    access: public
    input:
      from:  { type: date, from: query }
      count: { type: number, from: query, min: 1, max: 12 }
    steps:
      - plugin: { name: markets, handler: market-days, with: { from: $from, count: $count }, as: days }
    respond:
      json: { from: days, fields: [date, kind] }
    cache: 1h
```

Build it, then check:

```bash
engine-dmo plugin build --project .
engine-dmo check --fix --project .    # writes the endpoint's id, then checks everything
```

`GET /api/market-days.json?count=3` answers the projection of what the handler returned, with only `date` and `kind` exposed.

## plugins.yaml [#pluginsyaml]

One file per site, `config/sites/<site>/plugins.yaml`, with a map of plugins by key. A key is lowercase letters, digits and hyphens, at most 63 characters.

| Key | Default | Limits | Meaning |
|---|---|---|---|
| `command` | (required) | A path inside the project, or absolute; never looked up on `PATH`, never interpolated (no `$`) | The binary the engine starts. |
| `args` | none | | Arguments passed to the binary. |
| `build` | none | A directory inside the project | The Go program `engine-dmo plugin build` compiles to `command`. Leave it out when you build the binary some other way. |
| `sha256` | none | 64 lowercase hex digits | Pins the binary: the engine refuses to start one whose digest differs. `engine-dmo plugin build` prints the digest. |
| `env` | none | Names are uppercase letters, digits and underscores; not `MERIDIAN_PLUGIN_*` | Environment variables the plugin gets beyond the minimal base. A name containing `auth`, `key`, `token`, `secret`, `password` or `cookie` must be a `${VAR}` interpolation, never a literal. |
| `endpoints` | (required) | Handler names: lowercase letters, digits and hyphens, at most 63, no repeats | The handlers a `plugin` step may call. The plugin's handshake must serve every one. |
| `timeout` | `5s` | At most `1m` | How long one call may take. |
| `concurrency` | `8` | 1 to 256 | Calls in flight at once. A call that finds every slot busy until its deadline fails. |
| `memory` | `512MB` | 32MB to 64GB | The process's memory limit where the platform allows, and its `GOMEMLIMIT`. |
| `circuit_breaker.failures` | `5` | 1 to 100 | Failed calls inside `window` that open the breaker. |
| `circuit_breaker.window` | `1m` | At most `1h` | |
| `circuit_breaker.cooldown` | `30s` | At most `1h` | How long the breaker stays open; meanwhile the plugin's steps fail at once without calling it. |

## The plugin step [#the-plugin-step]

```yaml
- plugin: { name: markets, handler: market-days, with: { from: $from, count: $count }, as: days }
```

| Key | Meaning |
|---|---|
| `name` | A plugin declared in this site's `plugins.yaml`. |
| `handler` | One of the plugin's `endpoints`. May be left out when the plugin is granted exactly one. |
| `with` | A mapping of names to references (`$from`, `$listing.title`) or literals, sent as the call's input. Without it, every input of the endpoint is sent. |
| `as` | The name later steps and `respond` read the result by. Defaults to the handler's name. |

The step takes only these four keys. `engine-dmo check` refuses a plugin that is not declared, a handler the plugin is not granted, and anything else, each with a suggestion where one is close. `respond: json:` projects the result as for a `query` or `source` step, exposing only the `fields` it lists.

Any failure of the call (the binary missing, the process down, the breaker open, every slot busy, a timeout, or the handler's own error) fails the endpoint with HTTP 502 and the message "This information is not available just now. Try again in a moment.", as a failing upstream source does. The handler's error and any panic stack go to the engine's log, never to the visitor.

## Writing a plugin in Go [#writing-a-plugin-in-go]

Require `github.com/wrux/meridian-plugin` in the plugin's own `go.mod`. It uses the standard library only, and the plugin may use any Go version, since the contract is messages, not shared code.

```go
// go.mod
module example.com/markets-plugin

go 1.26.0

require github.com/wrux/meridian-plugin v0.0.0-00010101000000-000000000000

replace github.com/wrux/meridian-plugin => ../meridian-plugin
```

While the module is not published to a Go module proxy, point a `replace` directive at your copy of its source. A release does not carry that source (it is in the Meridian source repository, `libs/plugin`), so a Go plugin needs it from Cherwell Studio. A plugin in another language needs only the protocol, which this page describes.

| Name | What it is |
|---|---|
| `plugin.Serve(h Handlers)` | Runs the plugin until the engine stops it, then exits the process. Your `main` calls it. |
| `plugin.Run(ctx, h) error` | `Serve` without the exit, for a program that does more. |
| `plugin.Handler(h) http.Handler` | The protocol as an `http.Handler`, for serving it another way or testing a plugin over the wire with `net/http/httptest`. |
| `Handlers.Name` | The name in the handshake. Empty takes the key the engine started it under. |
| `Handlers.Endpoints` | Handler name to `EndpointFunc`. |
| `EndpointFunc` | `func(ctx Context, r Request) (Response, error)`. An error fails the step. |
| `Context` | A `context.Context` that ends when the engine stops waiting, with `Site`, `Locale`, `Endpoint`, `RequestID`, and `Log`, a `*slog.Logger` whose records the engine writes to its own log. |
| `Request.Input` | The endpoint's validated input as JSON values: a string, a `float64`, a bool, nil, `[]any` or `map[string]any`. A relation input arrives as the document's id. Helpers: `Value(name)`, `String(name)`, `Float(name) (float64, bool)`, `Bool(name)`. |
| `plugin.Data(v)` | A `Response` carrying `v`, which must marshal to JSON. |

A panic in a handler is recovered and returned with its stack; the engine logs it and the plugin keeps running. Handlers are plain functions, so you test them with `go test` and nothing else running.

## Building, pinning and deploying [#building-pinning-and-deploying]

```bash
engine-dmo plugin build [key...] [--site key] --project .
```

For each plugin with a `build:` directory, this runs `go build -trimpath -o <command> .` in that directory (Go must be on `PATH`) and prints the binary's sha256. When `plugins.yaml` pins a different digest, it says so and prints the one to set. `engine-dmo check` warns when a declared binary is not built (`the binary bin/markets is not built, so its steps would fail with 502`).

The binary runs on the machine the engine runs on, so build it for that operating system and architecture: in a container image, build it in the image build and copy it to the path `command` names. Pin `sha256` in production so a changed binary is refused rather than run.

## How the engine runs a plugin [#how-the-engine-runs-a-plugin]

- **Started on first use**, per site and plugin, and replaced when its declaration (command, arguments, pin, environment or memory) changes.
- **Environment**: `PATH`, `HOME`, `TMPDIR`, `USER`, `LANG`, `LC_ALL`, `SSL_CERT_FILE` and `SSL_CERT_DIR` from the engine's environment if set, the `env:` you declared, and `MERIDIAN_PLUGIN_SOCKET`, `MERIDIAN_PLUGIN_PROTOCOL`, `MERIDIAN_PLUGIN_NAME` and `MERIDIAN_PLUGIN_LIFELINE`. Nothing else of the engine's environment, its secrets included, is passed.
- **Working directory**: the project directory.
- **Start**: it must answer the handshake within 10 seconds, naming protocol 0 and serving every handler `endpoints:` grants.
- **Health**: checked every 10 seconds; a process that fails twice is killed and restarted.
- **Restarts**: a process that exits is restarted with a backoff from 100ms doubling to 30s; one that ran for a minute resets it.
- **Lifeline**: with `MERIDIAN_PLUGIN_LIFELINE=stdin` the engine holds the plugin's standard input open; when it closes, the engine has gone and the plugin exits (`plugin.Serve` does this for you).
- **Logs**: the plugin writes JSON records to standard error, which the engine reads into its own log.

## The protocol, version 0 [#the-protocol-version-0]

For a plugin in another language. JSON over HTTP/1.1 on the Unix socket at the path in `MERIDIAN_PLUGIN_SOCKET`:

| Request | Answer |
|---|---|
| `GET /v0/handshake` | `{"protocol": 0, "name": "...", "build": "...", "go": "...", "endpoints": ["market-days"]}`, at most 64 KiB. `name` and each endpoint are lowercase letters, digits and hyphens, none repeated. |
| `GET /v0/health` | `200` while the plugin can take calls. |
| `POST /v0/endpoint/<handler>` | Body `{"site", "locale", "endpoint", "request_id", "input"}`, at most 1 MiB, with the `Meridian-Deadline` header holding the deadline in Unix milliseconds. Answer `200 {"data": ...}`, or any other status with `{"error": {"message": "...", "panic": false, "stack": "..."}}`, at most 4 MiB. A body over its bound is refused whole. |

## Security [#security]

A plugin is not a sandbox. It runs as a normal process with the engine user's privileges and can read what that user can read. The engine contains it (a timeout per call, bounded concurrency, restarts, a circuit breaker, a memory limit where the platform allows, no inherited secrets) but does not isolate it. Treat plugin code as trusted, like your templates: review it, build it yourself, and pin it.

`engine-cms` behaves the same.


# Accessibility (/features/accessibility)

What the engine does for accessibility on public pages and what a template author must still do, the accessibility checks in engine-dmo check and engine-dmo a11y audit, the alt text policy, and the accessibility statement, issues register and conformance report the engine generates.

The engine takes care of the parts of accessibility that are mechanical and easy to get wrong in every project: alt text that cannot be skipped, accessible forms with no CAPTCHA, the language of fallback text, third-party embeds that load nothing until asked, and checks that catch the common template mistakes before they ship. It cannot make a page accessible on its own: the markup, the design and the words are yours. This page lists both halves, then the tools for evidence and the statement.

## What the engine does [#what-the-engine-does]

### Images [#images]

- **Alt text is required.** With `media.require_alt_text` (the default), an image needs alt text in the source locale at upload and in the page's locale at publish, unless a person marks it decorative. A missing value is an error, not a warning. See [Media library](/features/media).
- **Decorative is explicit.** A decorative image renders `alt=""`, and the library counts decorative images apart so the marking cannot hide a backlog.
- **Bad alt text is refused**: over 200 characters, or opening with "image of", "photo of" and the like.
- **Language of fallback text.** When an image's alt text or caption comes from a fallback locale, `img()`, `picture()` and `figure()` write `lang` on the element (WCAG 3.1.2), and each site sets per locale whether that is allowed, warned or blocked at publish (`accessibility.alt_fallback`).
- **Credits.** `figure()` writes the licence credit in the caption; `check` warns when a template renders an image another way without printing it.

### Forms [#forms]

The form an endpoint draws (`render()` on a `form` field, `enquiryForm()`, `subscribeForm()`) writes a visible label for every input, its help text, `autocomplete` tokens you declare, an error summary with `role="alert"` that focus moves to after a failed post, each error tied to its field with `aria-invalid` and `aria-describedby`, and what the visitor typed kept. It works without JavaScript. Spam is stopped with a honeypot, a minimum fill time and a proof of work: never a CAPTCHA. See [Forms and submissions](/features/forms-and-submissions).

### Embeds and third parties [#embeds-and-third-parties]

`embed(url, title=)` renders a YouTube, Vimeo, Google Maps, OpenStreetMap, Instagram or Spotify embed as a facade: a notice naming the provider, a real `<button>` that loads it, and a plain link to it. Nothing loads from the third party until the visitor acts. Give `title` so the button and the frame have a name. Any other address is printed as a plain link.

### No cookie banner [#no-cookie-banner]

Analytics sets no cookie and stores no personal data, and a public page sets no cookie for an anonymous visitor, so the site needs no consent banner ([Analytics](/features/analytics)).

### Pages the engine renders itself [#pages-the-engine-renders-itself]

The newsletter's confirmation, preference centre and unsubscribe pages, when you do not supply your own templates, are plain pages with no script and no tracking. The transactional email layout sets the language and is a single readable column with a dark-mode palette.

### Fragments and live updates [#fragments-and-live-updates]

When part of a page is replaced after a form post or a filter, the `{% focus %}` tag moves focus to a selector and `{% announce %}` tells screen readers what changed, so an in-place update is not silent.

## What a template author must do [#what-a-template-author-must-do]

The engine cannot check these for you, or can only warn:

- Set the page language and direction: `<html lang="{{ locale.code }}" dir="{{ locale.direction }}">`.
- Give every page a title (`head()` writes it) and exactly one `h1`, with headings in order.
- Provide a skip link to `<main>`, and use landmarks: `header`, `nav` with an `aria-label` when there is more than one, `main`, `footer`.
- Mark the current page in navigation with `aria-current="page"` (`item.isCurrent`).
- Write link text that makes sense out of context. "Read more" needs the item's name.
- Meet colour contrast (4.5:1 for text, 3:1 for large text and controls), show a visible focus indicator, and do not convey meaning by colour alone.
- Let the page zoom and reflow: never `maximum-scale` or `user-scalable=no` in the viewport.
- Respect `prefers-reduced-motion` for animation.
- Use a real `<button>` for actions and a real `<a href>` for navigation. Never a positive `tabindex`.
- When you write your own form markup instead of `render()`, keep a visible `<label>` for each control, an error summary, and `aria-invalid` and `aria-describedby` on fields with errors. A placeholder is not a label.
- Give every `embed()` a `title`, every `iframe` a `title`, and transcripts or captions for audio and video.
- Print an image's credit when you render it with `img()` or `picture()`.

## Checks [#checks]

### In engine-dmo check [#in-engine-dmo-check]

`engine-dmo check` lints every template, reported at the line and column:

| Code | Severity | Finds |
|---|---|---|
| `positive-tabindex` | error | A `tabindex` above 0, which takes the element out of the visual order. |
| `placeholder-label` | warning | An `input` or `textarea` named only by its placeholder: no `label for` its id, no enclosing `label`, no `aria-label` or `aria-labelledby`. |
| `one-h1` | warning | A template that can render more than one `h1` on a page. Alternative branches of an `if` count as one. |
| `image-credit` | warning | An image rendered with `img()` or `picture()` whose credit is printed nowhere in the file. |
| `img-no-sizes` | warning | An `<img>` with a width-descriptor `srcset` and no `sizes`. |

`--strict` makes the warnings errors, for a CI gate.

### On rendered pages [#on-rendered-pages]

`engine-dmo a11y audit` renders pages through the real pipeline and runs the automated checks on the HTML, exiting 1 on a failure:

```bash
engine-dmo a11y audit --site main                    # a sample of 20 pages across the site's routes
engine-dmo a11y audit --site main --all
engine-dmo a11y audit --site main --path / --path /visit
```

| Rule | WCAG | Severity | Checks |
|---|---|---|---|
| `html-lang` | 3.1.1 | fail | The page declares its language. |
| `page-title` | 2.4.2 | fail | The page has a title. |
| `image-alt` | 1.1.1 | fail | Every image has a text alternative, empty for decoration. |
| `control-name` | 4.1.2 | fail | Every link, button and form control has an accessible name. |
| `frame-title` | 4.1.2 | fail | Every frame has a title. |
| `label-in-name` | 2.5.3 | fail | A control's accessible name contains its visible text. |
| `placeholder-name` | 3.3.2 | fail | No control is named only by its placeholder. |
| `missing-reference` | 1.3.1 | fail | Every id a label or ARIA reference names is on the page. |
| `positive-tabindex` | 2.4.3 | fail | No positive `tabindex`. |
| `viewport-zoom` | 1.4.4 | fail | The viewport does not stop zooming. |
| `duplicate-id` | 4.1.2 | warn | No id is used twice. |
| `one-h1` | 2.4.6 | warn | Exactly one `h1`. |
| `heading-order` | 1.3.1 | warn | Heading levels do not skip. |

`engine-dmo render <path> --json` includes the same findings for one page. Both need the database. These checks are evidence, not a verdict: a page that passes every rule can still fail WCAG, so test with a keyboard and a screen reader as well.

## The accessibility statement [#the-accessibility-statement]

Set the statement's facts per site:

```yaml
# config/sites/<site>/site.yaml
accessibility:
  statement_path: /accessibility
  conformance: "WCAG 2.2 AA"
  contact_email: access@example.org
  last_reviewed: "2026-10-01"
```

| Key | Meaning |
|---|---|
| `statement_path` | Where the site publishes its statement. |
| `conformance` | The standard you claim against. |
| `contact_email` | Where people report a problem or ask for another format. |
| `last_reviewed` | When the statement was last reviewed. |
| `alt_fallback`, `alt_fallback_locales` | The alt text fallback policy ([Media library](/features/media)). |

Record the problems you know about in the issues register:

```yaml
# config/accessibility.yaml
issues:
  - key: map-keyboard
    summary: The venue map cannot be panned with the keyboard
    severity: major
    clause: "2.1.1"
    surface: site
    owner: web team
    target: "2026-12-31"
    found: "2026-10-01"
```

| Key | Meaning |
|---|---|
| `key` | A short id. |
| `summary` | The problem in plain words, as the statement will print it. |
| `severity` | `blocker`, `major`, `minor` or `note`. |
| `clause` | The WCAG success criterion or EN 301 549 clause, where one applies. |
| `surface` | `site`, `admin`, `portal` or `pdf`. |
| `owner` | Who will fix it. |
| `target` | The date it will be fixed by, or empty with a `reason`. |
| `reason` | Why it is not fixed yet. |
| `found` | When it was found. |

Then generate the documents:

```bash
engine-dmo a11y issues                                  # the register, with owners and target dates
engine-dmo a11y statement --site main --format md --out statement.md
engine-dmo a11y report --site main --format vpat --out acr.html
engine-dmo a11y report --site main --no-audit           # from the register alone, no database
```

| Command | Produces |
|---|---|
| `a11y issues` | The register as a table. |
| `a11y statement` | A statement scaffold in the structure the UK public sector accessibility regulations and the EU Web Accessibility Directive expect, from `site.yaml` and the register, with bracketed gaps for what only you can say. `--format html` (default) or `md`. |
| `a11y report` | An Accessibility Conformance Report scaffold, EN 301 549 clause by clause, from the automated checks and the register. `--format md` (default), `json` or `vpat` (the VPAT 2.5 table as HTML). `--sample` and `--all` choose the pages audited; `--no-audit` leaves the automated checks out. Every clause is marked as needing a person's review. |

The statement's enforcement procedure is always the UK one (the Equality and Human Rights Commission, the 2018 public sector bodies regulations and the Equality Advisory and Support Service), whatever the site's `country`. A site outside the UK, or one not covered by those regulations, must replace that section with its own body and law before publishing.

`a11y issues` and `a11y statement` read configuration only. Publish the statement as a page at `statement_path` and keep the register current: the statement is regenerated from it, not typed once and left.


# AI assistance (/features/ai-assistance)

How to connect your own AI provider (Azure OpenAI, OpenAI, Anthropic, Mistral or any OpenAI-compatible endpoint), which authoring tasks AI drafts and where, the review queue, budgets and the data boundary, prompt overrides, public disclosure and the ai commands.

Meridian can draft some of the tedious parts of authoring: alt text and captions, structured opening hours from a pasted sentence, tags from your vocabulary, SEO titles and descriptions, summaries, and translations. It runs against a provider **you** configure, with your credentials; nothing is proxied and nothing is sent anywhere by default.

Three rules hold whatever you configure:

- **No provider, no AI.** With `ai.enabled` false or no provider, every AI control is absent from the admin and the portal, not disabled.
- **A person decides.** AI only proposes. Every suggestion waits for a person to accept, edit or reject it, and accepting writes through the same validation as a person's own edit. Nothing is published by AI.
- **Authoring only.** AI runs in the admin and, in the DMO bundle, the member portal. The public site never calls a provider: there is no chatbot and no AI on visitor pages.

## Connect a provider [#connect-a-provider]

```yaml
# config/engine.yaml
ai:
  enabled: ${AI_ENABLED:-false}
  provider: ${AI_PROVIDER:-none}
  openai_compatible:
    base_url: ${AI_BASE_URL:-http://localhost:11434/v1}
    api_key: ${AI_API_KEY}
    model_text: ${AI_TEXT_MODEL:-llama3.1}
    model_vision: ${AI_VISION_MODEL:-}
  budget:
    monthly_cost_cap: "20"
    per_user_daily_requests: 100
  pricing:
    input_per_million: "0.15"
    output_per_million: "0.60"
```

Then confirm it, and give your editors the permission:

```bash
engine-dmo check                        # provider keys, models, and which features stay unavailable
engine-dmo ai test                      # one round trip with no content
engine-dmo ai status                    # provider, models, health and this month's spend
```

```yaml
# config/access/roles.yaml: a role holding the AI permissions
roles:
  - key: ai-drafter
    name: { en: AI drafting }
    permissions: [ai.use, ai.bulk]
```

```yaml
# config/access/grants.yaml: give it to the editors group beside its editor role
grants:
  - { group: administrators, role: owner }
  - { group: editors, role: editor }
  - { group: editors, role: ai-drafter }
```

Run `engine-dmo check --fix` to write the role's id. No built-in role holds the AI permissions except Owner; grant them in `roles.yaml`.

### Providers [#providers]

Write only the block for the provider you use. API keys are secrets: a bare `${VAR}` with no default.

| `provider` | Block keys | Required | Notes |
|---|---|---|---|
| `openai_compatible` | `base_url` (up to and including `/v1`), `api_key`, `model_text`, `model_vision`, `model_embedding` | `base_url`, `model_text` | Ollama, vLLM, a sovereign or air-gapped endpoint. A local endpoint may need no key (set the variable empty). |
| `openai` | as above; `base_url` defaults to `https://api.openai.com/v1` | `model_text` | |
| `mistral` | as above; `base_url` defaults to `https://api.mistral.ai/v1` | `model_text` | |
| `anthropic` | `api_key`, `base_url` (default `https://api.anthropic.com`), `model_text`, `model_vision` | `model_text` | No embeddings, so duplicate detection is unavailable. |
| `azure_openai` | `endpoint`, `api_key`, `deployment_text`, `deployment_vision`, `deployment_embedding`, `api_version` (default `2024-10-21`) | `endpoint`, `deployment_text` | |
| `none` | | | The default. |

Alt text drafting uses the vision model, else the text model (which may not accept images; `check` warns). Duplicate detection needs an embedding model (`check` warns while there is none). `ai.models` overrides the model for one feature: `models: { alt_text: gpt-4o-mini }` (for Azure, a deployment name).

## What AI does, and where [#what-ai-does-and-where]

Each feature has its own switch under `ai.features`, and each needs `ai.use` on the site.

| Feature | Key (default) | Where | What it does |
|---|---|---|---|
| Alt text and captions | `alt_text` (on) | An asset's page; the alt text queue's "Draft these with AI"; `engine-dmo ai bulk alt-text` | Drafts alt text or a caption per locale, for the default or one site's own wording. Held to 125 characters and never "image of". |
| Opening hours extraction | `hours_extraction` (on) | A document's assistance page, for an `opening_hours` field; the member portal (DMO) | Turns what a business wrote ("12 til 3, closed Mondays") into structured hours, shown beside the source text. |
| Tag suggestion | `tag_suggestion` (on) | A document's assistance page | Suggests tags from your configured vocabulary only; the reviewer ticks which to add. |
| SEO drafting | `seo_drafting` (on) | A document's assistance page, for an `seo` field | Drafts a title and a description within the field's limits, from the document's own text. |
| Summarisation | `summarisation` (off) | A document's assistance page, for a `text` field that declares `summary_of: <field>` | Drafts a summary of the source field, held to the field's `max` (280 when it has none). |
| Translation drafting | `translation` (off) | The side-by-side translation editor | Drafts the field being translated, with the glossary and translation memory as context. |
| Zero-result content briefs | `zero_result_briefs` (off) | Insight, search (`analytics.view` too) | Turns the site's commonest searches that found nothing into up to five briefs (a listing, an article, a synonym or a redirect to consider). Writes nothing. |
| Duplicate detection | `duplicate_detection` (on) | CRM organisations (DMO) | Finds likely duplicate organisations by embedding. |
| Member listing improvement | `member_improvement` (off) | The member portal (DMO) | Suggests clearer wording for a member's own listing text. |

A field that summarises another:

```yaml
fields:
  - name: body
    type: text
    multiline: true
  - name: summary
    type: text
    max: 280
    summary_of: body
```

`ai.features.image_generation: true` is refused: there is no image generation. `quality_review` and `ai.translation.quality_signals` are accepted and do nothing. There is no Amazon Bedrock adapter; reach a model hosted there through an OpenAI-compatible gateway.

The editor's SEO advice panel (a title that duplicates another page, internal link suggestions) is computed, not generated, and is shown with or without a provider.

## How a suggestion is made and reviewed [#how-a-suggestion-is-made-and-reviewed]

<Steps>
<Step>A person asks for a draft. Nothing runs in the background on content.</Step>
<Step>The data boundary is applied (below), the budget is checked and reserved, and the request is built from a versioned prompt with your content sent as delimited data, never as instructions.</Step>
<Step>The answer is validated by the same rules that validate a person's input: the field's type and limits, the select's options, the vocabulary. An invalid answer is retried once with the problems, then abandoned with a clear message.</Step>
<Step>The valid answer waits as a suggestion, beside the current value.</Step>
<Step>A person accepts, edits or rejects it. Accepting saves a normal revision under that person's name, with an assistance record of how the text was made.</Step>
</Steps>

The admin's AI queue lists every suggestion waiting for review; `engine-dmo ai queue` does the same. Bulk runs (`ai.bulk`) print an estimate of the cost before they queue anything, and each draft still waits in the queue. Suggestions that have been decided are kept for `retention.ai_suggestions` (thirteen months).

```bash
engine-dmo ai bulk alt-text --locale cy --dry-run     # count and estimate only
engine-dmo ai bulk alt-text --locale cy --site main   # queue drafts of the site's own wording
```

## Cost control [#cost-control]

| Key | Default | Meaning |
|---|---|---|
| `budget.monthly_cost_cap` | `50` | A hard stop in the site currency; at the cap every AI feature is unavailable. `0` is no cap. |
| `budget.monthly_tokens` | `5000000` | A token cap per month. |
| `budget.per_user_daily_requests` | `200` | Requests per person per day. |
| `budget.per_feature_monthly_requests` | `{}` | Caps per feature: `{ alt_text: 2000 }`. |
| `budget.sites` | `{}` | A site's own monthly cost cap: `{ main: "10" }`. |
| `budget.estimate_before_bulk` | `true` | Accepted and not read: a bulk run always prints its estimate first. |
| `budget.estimated_tokens_per_call` | `{}` | Override the engine's estimate per feature. |
| `pricing.input_per_million`, `pricing.output_per_million` | | Your provider's prices in the site currency, for the cap and the estimate. The engine never bills. |
| `cache.enabled`, `cache.ttl` | `true`, `720h` | The same question about unchanged content is not sent twice. |
| `circuit_breaker.failures`, `window`, `cooldown` | `3`, `1m`, `2m` | After repeated failures every feature pauses, sending nothing, until the cool-down ends. |
| `timeout` | `30s` | Per request. |

```bash
engine-dmo ai budget --period 2026-10     # spend by feature and by user against the caps
engine-dmo ai log --from 2026-10-01       # every request: feature, user, model, tokens, cost, outcome, data sent
```

## The data boundary [#the-data-boundary]

| Key | Default | Meaning |
|---|---|---|
| `data_boundary.allow_content` | `true` | The content being assisted may be sent. |
| `data_boundary.allow_personal_data` | `false` | CRM personal fields and phone and email values are stripped. `true` is a warning in `check`. |
| `data_boundary.redact_before_send` | `true` | Email addresses and phone numbers inside free text are replaced before sending. |
| `data_boundary.allow_analytics` | `aggregate_only` | `aggregate_only` or `none`. Raw events are never sent; `none` turns off zero-result briefs. |
| `data_boundary.exclude_fields` | `[]` | Fields never sent: `listing.internalNotes`, `*.bookingNote`. |

Credentials, session tokens, audit entries and membership records are never sent. `engine-dmo ai data-flow-statement` writes a data protection annex from your configuration: the provider and where requests go, each feature and what it sends, the boundary, the budget and what is recorded. It needs no database:

```bash
engine-dmo ai data-flow-statement --out ai-data-flow.md
```

## Telling visitors [#telling-visitors]

Accepting a suggestion records how the text was made: drafted (accepted as written), edited, extracted, translated, suggested. On public pages, `entry.aiAssisted` is true when the published text carries a record the disclosure policy covers, and `aiDisclosure(entry)` prints the disclosure sentence, or nothing:

```jinja
{{ aiDisclosure(entry) }}
```

The sentence is the `ai.disclosure` string in your string catalogue, in the page's locale, else "Parts of this page were drafted with the help of AI and reviewed by a person before publication." Reading the records calls no provider.

| `ai.disclosure.public` | Discloses |
|---|---|
| `never` | Nothing. |
| `drafted_only` (default) | Text accepted as drafted without material change, and text written by an agent through the content MCP. |
| `all` | Any assisted text, edited and extracted included. Tag suggestions are never counted. |

`ai.disclosure.admin` is `always` and cannot be changed: the admin always shows provenance.

## Prompt overrides [#prompt-overrides]

Each feature's prompt can be replaced with your own wording, one file per prompt in `ai.prompts_dir` (`config/ai/prompts`):

```yaml
# config/ai/prompts/alt-text.yaml
key: alt-text
version: 2
system: |
  You write alt text for an image on a public website about an arts centre.
  ...
  Answer with a JSON object: {"alt": "<the alt text>"}.
```

The keys are `alt-text`, `caption`, `hours-extraction`, `tag-suggestion`, `seo-drafting`, `summarisation`, `translation`, `zero-result-briefs`, `member-improvement` and `duplicate-detection`. `version` (1 or more) is recorded on every suggestion the prompt produces; raise it when you change the text. `check` refuses an unknown key, a missing version and empty text. Keep the answer format the engine's prompt asks for: the answer is validated against it.

## Commands [#commands]

| Command | What it does |
|---|---|
| `ai status` | Provider, models, capabilities, health and spend this month. |
| `ai test` | One round trip with no content: confirms the endpoint, the key and the model. |
| `ai queue` | Suggestions waiting for review. |
| `ai bulk alt-text` | Queue alt text drafts for every image missing alt text in a locale (`--locale`, `--site`, `--dry-run`). |
| `ai budget` | Spend by feature and user against the caps (`--period`). |
| `ai log` | The activity log (`--from`, `--limit`). |
| `ai data-flow-statement` | The data protection annex (`--out`). |

All but `data-flow-statement` need the database.

## Permissions [#permissions]

| Permission | Allows |
|---|---|
| `ai.use` | Asking for a draft on a site. Accepting also needs the permission the write itself needs, such as `media.edit` for alt text or `content.edit` for a field. |
| `ai.bulk` | Bulk runs and the duplicate scan. |
| `ai.configure` | The admin's AI usage screen: spend by feature and user against the caps. |

Only Owner holds them by default.

## Configuration reference [#configuration-reference]

The `ai:` section of `config/engine.yaml`, beyond the provider blocks and the tables above:

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `false` | Must read `true` or `false` after interpolation. |
| `provider` | `none` | `azure_openai`, `anthropic`, `openai`, `mistral`, `openai_compatible` or `none`. |
| `models` | `{}` | A model per feature. Not `duplicate_detection`. |
| `features.*` | see the features table | One switch per feature. |
| `duplicates.threshold` | `0.9` | Similarity, 0.5 to 1, at or above which two organisations are offered as duplicates. |
| `translation.memory_examples` | `8` | Prior translations sent per request, 0 to 50. |
| `translation.length_ratio_bands` | `{}` | Per language pair, the expected length ratio: `{ "en:de": [0.9, 1.5] }`. |
| `disclosure.public` | `drafted_only` | `never`, `drafted_only` or `all`. |
| `prompts_dir` | `config/ai/prompts` | Where prompt overrides live. |


# Analytics (/features/analytics)

What the built-in, cookieless analytics collects and how (server-side views, the beacon, tracked links, impressions), why it needs no consent banner, the template helpers, dashboards in analytics/dashboards.yaml, exports, retention and every analytics setting.

Meridian measures its own sites. Page views are recorded on the server as each page renders; outbound clicks, phone reveals and card impressions are recorded through first-party links and a small script the engine serves. Everything is stored in your own database, aggregated into hourly, daily and monthly rollups, and read on the admin's Insight screens, in exports and in reports.

This is how an event travels from a visitor to a figure:

```mermaid
flowchart LR
  subgraph collect["Collection"]
    render["Page render<br/>(server)"]
    beacon["/_e beacon<br/>(analytics script)"]
    tracked["/r/v1 tracked link"]
    api["Content API events<br/>(headless)"]
  end
  collect --> filter{"bots, exclude_ips,<br/>DNT"}
  filter --> raw[("Raw events<br/>monthly partitions")]
  raw --> rollup["Hourly, daily and<br/>monthly rollups"]
  rollup --> insight["Insight dashboards"]
  rollup --> export["Exports"]
  rollup --> reports["Member and<br/>organisation reports"]
```

The design is privacy first: no cookies, no IP address stored, no user id, no fingerprint. Because no personal data is processed and no cookie is set, the analytics needs no consent banner.

## What you get with no work [#what-you-get-with-no-work]

Analytics is on by default (`analytics.enabled: true`). With nothing in your templates, every page render records a `page_view`, every search records its query, and index pages and search filters record what was filtered. Staff with `analytics.view` see the Insight overview for the site.

To record interactions as well, print the client in your layout:

```jinja
  {{ analytics() }}
</body>
```

It writes one deferred script tag (`/_e.js`) and nothing in a preview. The script records card impressions and marked interactions, batched into one request to `/_e`. Without JavaScript nothing it measures is recorded; server-side views and tracked links still work.

## What is collected [#what-is-collected]

| Event | Recorded when | How |
|---|---|---|
| `page_view` | A page or index page renders | Server, as the page renders |
| `listing_view`, `event_view` | A page of type `listing` or `event` renders | Server, beside `page_view` |
| `newsletter_click` | A visitor lands on a document from a link with `utm_medium=email` or `newsletter` | Server |
| `search`, `search_zero`, `search_click` | A search, a search with no results, a result chosen (with its position) | Server, through the search route |
| `filter_apply` | A search or index page is filtered (the filter keys, never typed text) | Server, or the client for an element marked `data-mrd-filter` |
| `website_click`, `booking_click`, `phone_reveal`, `email_click`, `directions_click`, `social_click`, `event_click`, `download`, `share` | A tracked link is followed | A first-party redirect from `track()` or `reveal()`; the client for marked elements |
| `listing_impression` | A card marked `data-mrd-impression` is half in view for half a second | The client |
| `offer_impression`, `promotion_impression`, `widget_impression`, `enquiry_submitted`, `affiliate_click`, `portal_login`, `claim_submitted` | DMO bundle features | See [the DMO bundle](/dmo) |

Every event carries: the time, the site, the locale, the source channel (organic, social, referral, campaign, internal or direct), the medium (the referring host or the campaign), the campaign (`utm_campaign`, normalised), the device class, the country when a trusted proxy supplies it, and two keys. The keys are an HMAC of the address, user agent and site under a salt that changes every UTC day; the previous day's salt is deleted when the next is made, so nothing links across days and nothing can be reversed. A visit is one visitor key's day. Each event of a visit is attributed to the source of the visit's first event, so no cookie is needed to carry it.

Not collected: the IP address, any cookie, any user or member id, any free text a visitor typed (search queries are kept in the separate search log, without identity), cross-day identity. So there is no returning-visitor metric, no multi-session funnel and no cohort retention.

### Filtering [#filtering]

- **Bots.** `bot_filtering: standard` drops requests whose user agent is on the built-in crawler list; `strict` (the default) also drops requests claiming to be a browser without an `Accept` header; `off` keeps everything.
- **Your own office.** `exclude_ips` lists addresses and CIDR ranges that record nothing. They are compared in memory and never stored.
- **Do Not Track.** With `respect_dnt: true`, a request with `DNT: 1` or `Sec-GPC: 1` records nothing.
- **Repeat views.** Repeat views of the same subject by the same visitor key within `dedupe_window` (30 minutes) count once when events are rolled up.
- **Previews and tooling.** Previews, `engine-dmo render` and the warm job record nothing.

## Template helpers [#template-helpers]

### Tracked outbound links [#tracked-outbound-links]

`track(entry, kind, url)` returns a first-party, signed `/r/v1/` address that records the click and redirects to the target. It works without JavaScript, cannot be spoofed and cannot be used as an open redirect. An empty target returns an empty string, so a template can pass a field that may be absent. Like every address in an `href`, print it through the `url` filter; `engine-dmo check` refuses one that is not. The target may be a string or a link value (its `url`).

```jinja
{% if entry.website %}<a href="{{ track(entry, 'website', entry.website)|url }}">Visit the website</a>{% endif %}
{% if entry.bookingUrl.url %}<a href="{{ track(entry, 'booking', entry.bookingUrl.url)|url }}">Book</a>{% endif %}
```

| `kind` | Records |
|---|---|
| `website` (default) | `website_click` |
| `booking` | `booking_click` |
| `directions` | `directions_click` |
| `social` | `social_click` |
| `event` | `event_click` |
| `download` | `download` |
| `share` | `share` |

`reveal(entry, kind, value)` does the same for a telephone number (`kind` `phone`, making a `tel:` link) or an email address (`email`, a `mailto:` link):

```jinja
{% if entry.phone %}<a href="{{ reveal(entry, 'phone', entry.phone)|url }}">Call {{ entry.phone }}</a>{% endif %}
```

The target must be an ordinary web, mail or telephone address. The entry's organisation is stamped on the event (DMO bundle), so a business's figures survive a listing moving between organisations.

### Marked elements [#marked-elements]

With `{{ analytics() }}` on the page:

| Markup | Records |
|---|---|
| `data-mrd-impression="<document id>"` on a card | `listing_impression` once per page when half of it has been in view for 500ms |
| `<a>` or `<button>` with `data-mrd-event="<event>"` and `data-mrd-subject="<id>"` (and `data-mrd-subject-type` when the subject is not a listing) | That event when clicked, for an interaction that does not leave the page |
| `data-mrd-filter="<key>"` on a filter control | `filter_apply` when it is turned on; the key is yours, never what was typed |

The beacon accepts only interaction events (impressions, clicks, reveals, shares, downloads, filters and search events); page views cannot be reported through it. Cards patched into the page later are watched too.

## Insight and dashboards [#insight-and-dashboards]

The admin's Insight screen shows a site's dashboard over a date range with a comparison. Without a dashboards file, the overview shows visits, page views, listing views, member referrals, page views over time, the top listings and the top zero-result searches.

Declare your own dashboards, and the figures staff enter by hand, in `config/analytics/dashboards.yaml`:

```yaml
# config/analytics/dashboards.yaml
metrics:
  - { key: box_office_visits, kind: entered, label: { en: Box office visitors }, period: month, unit: people }

dashboards:
  - key: default
    name: { en: Overview }
    default_range: 30d
    compare: previous_year
    widgets:
      - { type: metric, metric: visits, size: 1 }
      - { type: metric, metric: page_views, size: 1 }
      - { type: metric, metric: box_office_visits, size: 1 }
      - { type: timeseries, metric: page_views, breakdown: source, interval: day, size: 4 }
      - { type: table, metric: page_views, dimension: page, limit: 10, size: 2 }
      - { type: table, metric: search_zero, dimension: query, limit: 10, size: 2, highlight: true }
      - { type: funnel, steps: [page_views, downloads], size: 2 }
```

Run `engine-dmo check --fix` to write the entered metric's `id`.

### Dashboard keys [#dashboard-keys]

| Key | Meaning |
|---|---|
| `key` | Required, unique. `default` replaces the overview. |
| `name` | Per locale. |
| `default_range` | `today`, `7d`, `30d`, `90d`, `12m`, `this_month`, `previous_month`, `this_quarter`, `previous_quarter`, `this_financial_year`, `previous_financial_year`, `previous_year`. |
| `compare` | `previous_year`, `previous_period` or `none`. |
| `widgets` | At least one. |

### Widget keys [#widget-keys]

| Key | Meaning |
|---|---|
| `type` | `metric` (one figure), `table` (a metric broken down by a dimension), `timeseries` (over time), `funnel` (two or more counted steps), `list`. |
| `metric` | A metric key. Not on a funnel. |
| `dimension` | A table's breakdown: one the metric allows. |
| `breakdown` | A timeseries split by `source` or `device`. |
| `interval` | A timeseries' `day` or `month`. |
| `steps` | A funnel's metrics, in order, at least two counted events. |
| `limit` | Rows, 1 to 100. |
| `order` | `top` or `bottom`. |
| `size` | Columns, 1 to 4. |
| `highlight` | Draw attention to the widget. |
| `label` | Per locale, in place of the metric's name. |

### Metrics [#metrics]

| Metric | Dimensions |
|---|---|
| `visits` | source, device, locale |
| `page_views` | page, source, device, locale, campaign |
| `listing_impressions` | listing, source |
| `listing_views` | listing, source, device, campaign |
| `event_views` | event, source |
| `event_clicks` | event |
| `downloads` | |
| `shares` | page |
| `widget_impressions` | listing |
| `newsletter_clicks` | listing, campaign |
| `website_clicks` | listing, source, campaign |
| `phone_reveals`, `email_clicks`, `directions_clicks`, `booking_clicks`, `social_clicks` | listing, source |
| `enquiries` | listing, source, campaign |
| `member_referrals_total` | listing, referral_type, source, campaign |
| `searches`, `search_zero` | query |
| `search_unclicked` | query |
| `search_clicks`, `search_ctr`, `search_position` | |

The DMO bundle's memberships module adds these:

| Metric | Value | Dimensions |
|---|---|---|
| `members_active` | members at the end of the range | tier |
| `members_new`, `members_lapsed` | count | |
| `renewal_rate` | a share, shown as a percentage | |
| `renewals_due` | due at the end of the range | |
| `referrals_per_member` | an average | |
| `members_zero_referrals` | a list of members with no referrals, for a `list` widget | |

That is the whole catalogue: these keys are what a dashboard widget, an organisation report's KPI and a funnel step may name, besides your entered metrics. A funnel's steps must be counted events: the metrics from `page_views` to `enquiries` in the first table. No command prints the catalogue; this table is it for this version. A widget naming a metric the bundle does not compile is refused. `engine-dmo check` reports every mistake at its line: an unknown metric (with a suggestion), a dimension the metric does not have, a funnel with one step, a size or limit out of range.

### Entered metrics [#entered-metrics]

A figure no website measures, such as visitor numbers from a survey, is declared under `metrics:` with `kind: entered`:

| Key | Meaning |
|---|---|
| `key` | Its own key; not one the engine measures. |
| `label` | Required, per locale. |
| `period` | `month`, `quarter`, `year` or `financial_year`. |
| `unit` | Shown with the figure. |
| `description` | Per locale. |

Staff with `analytics.enter` record a value per period on the Insight screen's entered figures page. An entered figure is always shown as entered, never as measured.

## Exports [#exports]

The Insight screen exports the dashboard on screen as CSV or JSON (`analytics.export`). The command line does the same:

```bash
engine-dmo analytics export --site main --range 30d --format csv --out overview.csv
engine-dmo analytics export --site main --metric page_views --from 2026-09-01 --to 2026-09-30 --format json
engine-dmo analytics export --dashboard board --range this_financial_year --compare previous_year --as analyst@example.org
```

| Flag | Meaning |
|---|---|
| `--site` | Site key (default: the default site). |
| `--dashboard` | A dashboard key (default: the overview). |
| `--metric` | One metric instead, as a single tile. |
| `--range` | A preset, as `default_range`. |
| `--from`, `--to` | A custom range, `YYYY-MM-DD`, inclusive, in the site's time zone. |
| `--compare` | `previous_year`, `previous_period` or `none`. |
| `--format` | `csv` (default) or `json`. |
| `--out` | A file; standard output when empty or `-`. |
| `--as` | Export as this staff account, which needs `analytics.export` on the site. |

Every export is audited.

## Retention and rollups [#retention-and-rollups]

Raw events are kept for `raw_retention_days` (90) in monthly partitions, dropped a whole month at a time once every row in it is past the window. Hourly rollups and the search log are kept for 400 days. Daily and monthly rollups are aggregated, identify nobody and are kept. Rollups and retention run on the engine's scheduler; the commands run them by hand:

| Command | What it does |
|---|---|
| `analytics rollup --from --to` | Roll raw events into the hourly, daily and monthly tables for a range. |
| `analytics recompute --from --to` | Rebuild every rollup level from raw events for a range, under the rules in force now. Idempotent. |
| `analytics prune [--dry-run]` | Apply retention. |
| `analytics partitions [--drop-expired]` | List the monthly raw partitions, create them ahead, drop expired ones. |
| `analytics collection --site --days` | The events a site received by collection path (rendered, beacon, api) over the last 1 to 90 days, and a headless site's collection health. |

The DMO bundle adds member reports, the monthly digest and scheduled organisation reports ([Member reports](/dmo/member-reports)).

## Headless sites [#headless-sites]

A headless frontend has no server-rendered views, so the content API hands it a signed view token with each document it resolves. The frontend reports the view through the beacon (proxied under its own domain) or from its server through the content API's events operation, and the engine records exactly the events a rendered page would. See the [content API](/integrating/content-api).

## Permissions [#permissions]

| Permission | Allows | Built-in roles |
|---|---|---|
| `analytics.view` | The Insight screens | Administrator, Editor, Analyst, Auditor (and Partnership manager in the DMO bundle) |
| `analytics.export` | Exports | Administrator, Analyst (and Partnership manager) |
| `analytics.enter` | Recording entered figures | Administrator, Analyst |

## Configuration reference [#configuration-reference]

Every key is under `analytics:` in `config/engine.yaml`.

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `true` | Record anything at all. Off, `analytics()` prints nothing. |
| `ingest_buffer` | `10000` | Events held in memory before writing; a full buffer drops events and counts the drops, never slowing a page. |
| `salt_rotation` | `daily` | The only value. |
| `raw_retention_days` | `90` | 30 to 400. |
| `hourly_retention_days` | `400` | At least 30. |
| `search_log_retention_days` | `400` | At least 30. |
| `reporting_timezone` | UTC | The zone for a site whose `site.yaml` sets no `timezone`. |
| `financial_year_start` | from the default site's country | The month, 1 to 12, the financial year starts in. |
| `bot_filtering` | `strict` | `off`, `standard` or `strict`. |
| `dedupe_window` | `30m` | |
| `respect_dnt` | `false` | Honour `DNT: 1` and `Sec-GPC: 1`. |
| `exclude_ips` | | Addresses and CIDR ranges, separated by commas or spaces. |
| `country_header` | | The header a trusted proxy or CDN writes the visitor's country into, such as `CF-IPCountry`. Read only from `server.trusted_proxies`, and refused without them. Empty records no country. |
| `statement_timeout` | `10s` | Bounds report and tile queries; must be below `database.statement_timeout`. |
| `pdf.renderer` | `auto` | `auto`, `browser` or `builtin`: how a report becomes a PDF (DMO bundle reports). |
| `pdf.browser_binary` | | A Chromium binary; empty searches the path. |
| `pdf.timeout` | `1m` | |


# Forms and submissions (/features/forms-and-submissions)

How to build a contact or enquiry form with no code: declaring an endpoint in endpoints.yaml, its inputs, validation, spam protection and rate limits, the store and mail steps, retention, the drawn form, the response templates and the submissions inbox.

A form on a Meridian site is a **declared endpoint**: an entry in the site's `endpoints.yaml` that names the inputs a post carries, the checks they pass, the steps that run (store the submission, send mail, subscribe to the newsletter, and more) and the template that answers. You write no server code. The engine validates the input in the visitor's language, applies CSRF protection, rate limits and spam controls, keeps the stored copy for the retention you declare, and draws an accessible form for you if you want it.

## A contact form [#a-contact-form]

<Steps>
<Step>
Declare the endpoint:

```yaml
# config/sites/<site>/endpoints.yaml
endpoints:
  - key: contact
    path: /contact/send
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    spam: { proof_of_work: true, honeypot: true, min_fill_time: 3s }
    input:
      name:    { type: text, max: 120, required: true, autocomplete: name, label: { en: Your name } }
      email:   { type: text, format: email, required: true, autocomplete: email, label: { en: Your email address } }
      message: { type: text, multiline: true, max: 2000, required: true, label: { en: Your message } }
      consent: { type: boolean, required_value: true, label: { en: I agree to you keeping this message for 90 days } }
    steps:
      - store: { as: contact, retention: 90d }
      - mail:  { template: contact-to-staff, to: settings.contact_inbox }
      - mail:  { template: contact-receipt, to: $email }
    respond:
      fragment: partials/contact-sent.html
```

and the inbox address it mails, in `site.yaml`:

```yaml
# config/sites/<site>/site.yaml
settings:
  contact_inbox: hello@example.org
```
</Step>
<Step>
Write the response and the two emails:

```jinja
{# templates/_shared/partials/contact-sent.html #}
<div id="form-contact" role="status"><h2>Thank you</h2><p>We have your message.</p></div>
```

```jinja
{# templates/_shared/emails/contact-to-staff.html #}
{% extends "emails/_layout.html" %}
{% block subject %}A message from {{ name }}{% endblock %}
{% block preheader %}Sent through the contact form.{% endblock %}
{% block body %}
<h1>A message from {{ name }}</h1>
<p>{{ name }} ({{ email }}) wrote:</p>
<blockquote>{{ message }}</blockquote>
{% endblock %}
```

Email templates are covered in [Transactional mail](/features/mail). They have no `t()`: see [Forms in more than one language](#forms-in-more-than-one-language).
</Step>
<Step>
Add the interface strings the drawn form prints, in `config/strings/<locale>.yaml` for every locale the site enables:

```yaml
# config/strings/en.yaml
strings:
  form.leave.blank: Leave this field blank
  form.submit: Send
```

`form.leave.blank` labels the hidden honeypot field, which screen readers can still meet; without it the label prints as the key itself. `form.<key>.submit` (here `form.contact.submit`), then `form.submit`, is the button's text; without either the button reads as the endpoint's key with a capital letter ("Contact").
</Step>
<Step>
Put the form on a page. Either let editors choose it with a `form` field on the content type:

```yaml
# config/schema/page.yaml
extends: page
fields:
  - name: contactForm
    type: form
    endpoints: [contact]
    label: { en: Form }
```

```jinja
{% if entry.contactForm %}
<section aria-labelledby="contact-heading">
  <h2 id="contact-heading">Send us a message</h2>
  {{ entry.contactForm.render(submit="Send my message") }}
</section>
{% endif %}
```

or print it in a template by its key with `{{ enquiryForm("contact") }}`. Printed that way the form is drawn as a plain post, without the in-place post a form field's `render()` adds. `enquiryForm()` has no `render()`: `engine-dmo check` accepts `enquiryForm("contact").render()`, but it prints nothing.
</Step>
<Step>
Run `engine-dmo check --fix` to write the endpoint's `id`, then `engine-dmo check`. Every mistake in the declaration, a step or a template is reported at its line.
</Step>
</Steps>

The form posts in place when JavaScript is available and as an ordinary post without it. A failed post draws the form again with what the visitor typed, an error summary and each field's error; a successful post answers with `partials/contact-sent.html`.

`engine-dmo dev endpoint add <key>` writes the start of an enquiry endpoint like this one (`--from recipe:newsletter` for a subscription). It writes `endpoints.yaml` and exits 0, but it writes no templates: `engine-dmo check` then fails until you write the response fragment, the `on_error` form and each mail template it names. Its labels are in the source locale only.

### What happens to a post [#what-happens-to-a-post]

A post passes the endpoint's gates in this order, and only a post that passes all of them runs its steps:

```mermaid
flowchart TD
  post["POST /contact"] --> access{"CSRF token<br/>and access"}
  access -->|refused| deny["refused<br/>(401 member, 404 staff)"]
  access --> rate{"rate limits"}
  rate -->|over| r429["429, form drawn again"]
  rate --> spam{"honeypot, fill time,<br/>proof of work"}
  spam -->|refused| fake["fragment with empty values<br/>(looks like success)"]
  spam --> valid{"inputs and validation"}
  valid -->|invalid| again["form drawn again<br/>with errors"]
  valid --> steps["steps in order:<br/>store, mail, subscribe, ..."]
  steps --> respond["respond: fragment,<br/>location, json or stream"]
  steps --> kept[("stored submission")]
  kept -->|"retention passes"| purge["hard deleted with<br/>its uploads"]
```

## The endpoint [#the-endpoint]

Each entry of `endpoints:` in `config/sites/<site>/endpoints.yaml`:

| Key | Default | Meaning |
|---|---|---|
| `key` | required | Lowercase letters, digits and hyphens. Unique on the site; templates name the endpoint by it. |
| `id` | written by `check --fix` | The stable id a `form` field stores. Never delete or change it: an endpoint whose id is removed gets a new one from `check --fix`, and `schema apply` then fails with a duplicate key error for the endpoint's key until the old id is put back from version control (`schema plan` shows the endpoint removed and added again). |
| `path` | required | Starts with `/`. A segment is literal or one `{parameter}`, which needs an input `from: path`. Two endpoints may not claim the same method and path shape. |
| `methods` | `[post]` | `get`, `post` or both. |
| `access` | `public` | `public`, `member` (a signed-in member of the portal, DMO bundle; needs an `organisation` input) or `staff`. |
| `permission` | | With `access: staff`, the permission the staff user needs. |
| `csrf` | `true` for a post | `false` only on a `public` endpoint, for a post from another origin. |
| `rate_limit` | the install default | One limit or a list, each `<count>/<window>/<key>`. See [Rate limits](#rate-limits). |
| `spam` | the install default | The abuse controls on a public post. See [Spam protection](#spam-protection). |
| `input` | | The inputs, in form order. See [Inputs](#inputs). |
| `validation` | | Rules across inputs. See [Validation](#validation). |
| `steps` | | What a valid post does, in order. See [Steps](#steps). |
| `respond` | required | Exactly one of `fragment`, `location`, `json`, `stream`, plus `on_error`. See [Responses](#responses). |
| `cache` | | A duration such as `60s` for a public `get` endpoint whose steps have no effect. A post, a member or staff endpoint, or one with a `mail`, `store`, `subscribe`, `audit`, `analytics`, `job` or `webhook` step cannot be cached. |

## Inputs [#inputs]

Each key under `input:` is an input name, and its value is a field declaration with the same grammar as a content type's fields ([Field types](/content-modelling/fields)): `text`, `select`, `boolean`, `number`, `date`, `relation` and the rest. `blocks`, `repeater` and `portable_text` have no place in a visitor form. The order you write them is the order of the drawn form and of the error summary.

| Key | Meaning |
|---|---|
| `type` | A field type, or `file` for an upload. |
| `label`, `help` | Per locale. The drawn form uses them; error messages name the input by its label. |
| `required` | The input must have a value. |
| `required_value` | On a `boolean`: it must be ticked. This is how consent is declared. |
| `autocomplete` | The HTML `autocomplete` token the drawn form writes (`name`, `email`, `tel`). |
| `from` | `body` (the default), `path` or `query`. |
| `visible_when`, `required_when` | A condition on other inputs, such as `"topic == 'bookings'"`. |
| anything else | The field type's own parameters: `max`, `min`, `format: email`, `multiline`, `options`, `to` for a relation, and so on. |

A `relation` input names a published document by id, and a step can then reach that document's fields (`$listing.organisation`). A relation's `to` must name types that exist.

### File uploads [#file-uploads]

```yaml
input:
  cv: { type: file, accept: [pdf], max_bytes: 10MB, label: { en: Your CV } }
```

A `file` input needs a `post` endpoint, is read from the body, accepts `image` (JPEG, PNG, WebP, AVIF), `pdf` and `csv`, and is at most `max_bytes` (default `media.max_upload_bytes`, at most 50MB). The file is sniffed from its bytes and stored as a private library asset that only the submissions inbox can open. A file input needs a `store` step, whose retention deletes the file with the submission.

## Validation [#validation]

Each input is validated by its field type. `validation:` adds rules across inputs:

```yaml
validation:
  - rule: "message != empty"
    message: { en: Tell us what you would like to know. }
    fields: [message]
```

| Key | Meaning |
|---|---|
| `rule` | A condition that must hold, in the schema's condition syntax. |
| `message` | Per locale, shown when the rule fails. |
| `fields` | The inputs the message is attached to. Each must be declared. |
| `severity` | `error` (the default). |

An invalid post runs no steps.

## Steps [#steps]

Steps run in order after the input is valid and the abuse checks pass. Each step is one keyed entry.

| Step | What it does |
|---|---|
| `store` | Keeps the submission for the inbox, for a declared retention. |
| `mail` | Sends a transactional email from a template. |
| `subscribe` | Adds the address to the newsletter with double opt-in ([Newsletters](/features/newsletters)). |
| `audit` | Writes an audit log row: `{ action: area.verb, resource: $input }`. |
| `analytics` | Records an analytics event: `{ event: enquiry_submitted, subject: $listing }`. |
| `signal` | Sets named values for a streamed response: `{ set: { ... } }`. |
| `query` | Reads published documents of one type, filtered by indexed fields, at most 100, for a `json` response. |
| `source`, `job`, `webhook`, `plugin` | Read a configured upstream, queue a job, send an outbound webhook, or call a project plugin. See [Integrating](/integrating) and [Extending](/extending). |

A value in a step is a literal, `$input` (an input's value), `$input.field` (a field of the document a relation input names) or `settings.key` (a value from the site's `settings:` in `site.yaml`).

### store [#store]

```yaml
- store: { as: contact, retention: 90d }
```

| Key | Meaning |
|---|---|
| `as` | The name the stored submission is bound to. |
| `retention` | Required. A period (`30d`, `13m`, `2y`), at most `forms.max_retention` (`2y` by default). Or `{ default: 90d, while_open: 180d }` (see below). |
| `subject` | A relation input the submission is about, such as `$listing`. |
| `share_with_organisation` | DMO bundle: `true` lets the partners of the subject's organisation read the submission in the member portal. Needs `subject`. |

`while_open` keeps a shared submission longer once the organisation's partners reply to it or write a note on it; it must be longer than `default` and needs `share_with_organisation: true`.

A store step with no retention is refused: a form that keeps data must say for how long.

### mail [#mail]

```yaml
- mail: { template: contact-to-staff, to: settings.contact_inbox }
- mail: { template: contact-receipt, to: $email }
```

| Key | Meaning |
|---|---|
| `template` | Required. The name of a template in an `emails/` directory of one of the site's template roots (`templates/<site>/emails/` or `templates/_shared/emails/`), without the extension. `check`'s error for a missing one says "not under templates/emails/" and means any root's `emails/`. |
| `to` | Required. `$input` (an email input), `settings.key`, a literal address, or `$relation.field` for an address or a list of addresses on a related document. |
| `fallback_to` | Used when `to` resolves to no address. |
| `reply_to` | Resolved like `to`, and passed to the template as `replyTo`. The message's Reply-To header is the site's `mail.reply_to`, not this value, so a staff member who presses Reply answers the site's address, not the visitor: print `replyTo` in the message for them to copy. |

A `subject` key is accepted and ignored: the subject always comes from the template's `subject` block.

The template receives every input by name, `submission` (the stored submission, when a `store` step ran first), `replyTo`, and the common mail context. Every message a post sends, the staff notice included, is rendered in the locale the visitor posted in. A send that cannot be queued (a suppressed address, a template that fails) is recorded against the submission and does not fail the post. When neither `to` nor `fallback_to` resolves, the submission stays `received`.

## Responses [#responses]

`respond:` names exactly one shape:

| Key | Answers with |
|---|---|
| `fragment` | A template rendered with the result. The usual answer to a form. |
| `location` | A redirect to a path. |
| `json` | A projection of a `query`, `source` or `plugin` step's result: `{ from: results, fields: [title, url], shape: list }` or `shape: geojson` with `geometry: <geo field>`. Nothing is exposed that is not listed. |
| `stream` | A template patched with a `job` step's progress (`stream: true` on the step). |
| `on_error` | With `fragment`: the template a failed post renders. |

Without `on_error`, an endpoint drawn as a form answers a failed post with the form drawn again; any other endpoint renders its `fragment` with the errors.

The response template receives:

| Name | Meaning |
|---|---|
| `values` | What the post carried, by input name. |
| `errors` | After a failure: messages by input name, plus `_summary` (a list of `path` and `message`, in form order) and `_count`. Form-wide problems are under `_form`. |
| `submission` | The stored submission. |
| `endpoint` | The endpoint's `key` and `path`. |
| `form` | The form the post came from. |
| `subscriber` | After a `subscribe` step: the subscriber. |

A refusal for spam reasons looks like success to the sender: the `fragment` renders with empty `values`.

## Drawing the form [#drawing-the-form]

| Template | Draws |
|---|---|
| `entry.<formField>.render(submit=, enhance=)` | The form a `form` field names. |
| `{{ enquiryForm("key") }}` | Any endpoint on the site, printed as a plain post form. It has no `render()`. |
| `{{ subscribeForm("key") }}` | The same, for a subscription endpoint. |

`engine-dmo check` does not check the key you pass to `enquiryForm()` or `subscribeForm()`: a misspelt key passes and prints nothing, so render the page once to see the form.

A printed form and `render()` write the CSRF and abuse-control fields, the error summary after a failed post (focus moves to it), and each input with its label, help, error message and `aria-invalid` and `aria-describedby` wiring, then the submit button. `submit` sets the button's text (by default the string `form.<key>.submit`, then `form.submit`). `enhance=false` leaves out the in-place post, so the form is a plain post with or without JavaScript. Any other keyword becomes an attribute of the `<form>` element; `id`, `action`, `method`, `enctype` and `data-on:submit` are the engine's. The drawn form's id is `form-<key>`, its error summary `form-<key>-errors` and its button `form-<key>-submit`.

To write your own markup, use the description's keys:

| Key | Meaning |
|---|---|
| `action`, `method` | Where and how to post, with the site's path prefix and locale. |
| `inputs` | The inputs in order: `name`, `type`, `label`, `help`, `required`, `autocomplete`, `multiline`, `max`, `format`, `options`. |
| `hidden` | Hidden fields the abuse controls need, name to value. |
| `honeypot`, `honeypotName` | Whether the endpoint has a honeypot, and its field name. |
| `challenge` | The challenge token, for a `data-mrd-challenge` attribute on the form. |
| `challengeScript` | The script that fetches a challenge and computes the proof of work. Print it after the form. |

```jinja
{% with form = enquiryForm("contact") %}
<form method="post" action="{{ form.action|url }}" id="form-contact"{% if form.challenge %} data-mrd-challenge="{{ form.challenge }}"{% endif %}>
  {{ csrfInput() }}
  {% for k, v in form.hidden %}<input type="hidden" name="{{ k }}" value="{{ v }}">{% endfor %}
  {% if form.honeypot %}<p hidden><label for="hp">Leave this blank</label><input id="hp" name="{{ form.honeypotName }}" tabindex="-1" autocomplete="off"></p>{% endif %}
  {% for fld in form.inputs %}
  <p><label for="c-{{ fld.name }}">{{ fld.label }}</label>
     <input id="c-{{ fld.name }}" name="{{ fld.name }}" value="{{ values[fld.name] }}"{% if errors[fld.name] %} aria-invalid="true"{% endif %}></p>
  {% endfor %}
  <button type="submit">Send</button>
</form>{{ form.challengeScript }}
{% endwith %}
```

Your own markup must keep what the drawn form does for accessibility: a visible label for every control, an error summary, and the errors tied to their fields ([Accessibility](/features/accessibility)).

The drawn form draws text, email, URL and telephone inputs, textareas and checkboxes. It does not draw a `select` input's options or radio buttons: a `select` input is drawn as a text box. For a choice, write your own markup from `form.inputs` (each input carries its `options`).

## Forms in more than one language [#forms-in-more-than-one-language]

- **One path for every locale.** An endpoint has one `path`. The drawn form's `action` adds the locale's prefix, so on a site with `cy` the Welsh form posts to `/cy/contact` while the English one posts to `/contact`. Write the `action` from `form.action` in your own markup, never by hand.
- **An endpoint and a page may share a path.** Endpoints answer only their declared methods, so a `post`-only endpoint at `/contact` and a page whose address is `/contact` live side by side: `GET` shows the page, `POST` runs the endpoint. The Welsh page can have its own slug (`/cy/cysylltu`); its form still posts to `/cy/contact`.
- **Give every `label`, `help` and validation `message` a value in every locale.** `engine-dmo check` does not warn when an endpoint label lacks a locale (it does for schema labels), and a missing one falls back to the source locale's text without notice.
- **Email templates have no `t()`.** The interface strings are not available in email templates: `t()` prints nothing there, and `check` does not flag it. Branch on the recipient's locale instead:

```jinja
{% block subject %}{% if locale == "cy" %}Mae eich neges gyda ni{% else %}We have your message{% endif %}{% endblock %}
```

## Spam protection [#spam-protection]

There is never a CAPTCHA. A public post is protected by three controls, each checked against the fields the drawn form carries:

| Control | What it does |
|---|---|
| `honeypot` | A hidden field a person leaves empty. A post that fills it is refused. |
| `min_fill_time` | A signed challenge dates when the form was drawn; a post sooner than this is refused with "That was quicker than a form can be filled in. Try again." |
| `proof_of_work` | A browser with JavaScript computes a small proof of work (about 256 hashes) over the challenge. A wrong proof is refused; a missing one is not, since a browser without JavaScript cannot compute one. |

Each challenge can be posted once: the same drawn form posted twice stores once. A page's form fetches its challenge with `challengeScript` after the page loads; a browser without JavaScript posts without one, gets the form back with a challenge in it and what was typed kept, and its second post goes through. Refusals for the honeypot, a bad or replayed challenge or a bad proof answer as if they succeeded, so a bot learns nothing.

The install defaults in `engine.yaml` apply to every public post endpoint. An endpoint may add a control or lengthen `min_fill_time`, and may not remove a control the default sets. Spam controls need the forms module, which both bundles compile.

## Rate limits [#rate-limits]

A limit is `<count>/<window>/<key>`: `window` is `second`, `minute`, `hour` or `day`, and `key` is what is counted:

| Key | Counts per |
|---|---|
| `ip` | client address |
| `session` | signed-in session |
| `person` | signed-in person |
| `organisation` | the organisation a post is about (needs a step with a `subject`) |
| `endpoint` | the endpoint as a whole |

Each endpoint starts with the install default for its class (public post `10/hour/ip`, public get `60/minute/ip`, member `60/hour/session`, staff `600/minute/session`); a limit it declares replaces the default with the same key, and other keys are added. A public endpoint with a `mail` step also carries the install's mail cap (`500/day/endpoint`). A post over a limit answers 429 with the form drawn again, what was typed kept, and "Too many attempts. Try again in …".

## The submissions inbox [#the-submissions-inbox]

The admin's Submissions screen lists what visitors sent through the site's endpoints that have a `store` step, newest first, filtered by endpoint and status (`received`, `failed`, `forwarded`, `delivered`, `opened`, `replied`, `spam`). A submission's page shows its values labelled from the declaration, its uploads (downloaded as attachments, never displayed inline), what became of each mail it sent, and when it will be deleted.

Reading needs `submissions.view` on the site, which the built-in Administrator role holds; grant it to others in `config/access/roles.yaml`. Every read and download is audited.

## Retention [#retention]

A scheduled task, at `forms.purge_schedule`, hard deletes every submission past its declared retention, with its uploads, and every submission of an endpoint that has left the configuration once `forms.orphan_retention` has passed.

## When check reports a problem [#when-check-reports-a-problem]

`engine-dmo check` reports every endpoint problem together. An endpoint's diagnostic carries the line of the endpoint's `- key:` entry (or of the step) and column 0, not the column of the offending key, so read the message for which key it means.

## Configuration reference [#configuration-reference]

In `config/engine.yaml`:

| Key | Default | Meaning |
|---|---|---|
| `forms.max_retention` | `2y` | The longest retention a `store` step may declare. |
| `forms.orphan_retention` | `30d` | How long submissions outlive their endpoint leaving the configuration. |
| `forms.purge_schedule` | `0 2 * * *` | When the purge runs: five-field cron, UTC. |
| `endpoints.defaults.rate_limit.public_post` | `10/hour/ip` | |
| `endpoints.defaults.rate_limit.public_get` | `60/minute/ip` | |
| `endpoints.defaults.rate_limit.public_mail` | `500/day/endpoint` | Added to a public endpoint with a `mail` step. |
| `endpoints.defaults.rate_limit.member` | `60/hour/session` | |
| `endpoints.defaults.rate_limit.staff` | `600/minute/session` | |
| `endpoints.defaults.spam.honeypot` | `true` | |
| `endpoints.defaults.spam.min_fill_time` | `2s` | |
| `endpoints.defaults.spam.proof_of_work` | `true` | |
| `endpoints.max_input_bytes` | `256KB` | The largest post body other than file uploads. |

## Headless sites [#headless-sites]

On a headless site, a post endpoint is submitted through the content API's forms operation, which answers JSON and hands out the challenge; a `respond` on such an endpoint is unused and `engine-dmo check` warns. See the [content API](/integrating/content-api).


# Features (/features)

What the engine does for a website beyond content and templates, in both bundles, and which page explains each feature.

These pages cover the parts of Meridian a website uses beyond its content model and its templates: the media library, search, menus, forms, mail, newsletters, redirects, analytics, AI assistance and accessibility. Every feature here is in both bundles. `engine-cms` and `engine-dmo` behave the same for all of them, and the commands on these pages are written as `engine-dmo`; swap in `engine-cms` on a plain CMS install.

A feature is switched on in configuration, and `engine-dmo check` validates that configuration before the server starts. Most features also need a database (they store something) and some need an external service you bring: a search backend, a mail provider, an AI provider. Nothing on these pages needs a third-party service to boot: without a search backend the search page serves browse mode, without a mail provider development mail goes to the log, and without an AI provider the AI features do not appear.

<Cards>
  <Card title="Media library" href="/features/media" />
  <Card title="Search" href="/features/search" />
  <Card title="Navigation" href="/features/navigation" />
  <Card title="Forms and submissions" href="/features/forms-and-submissions" />
  <Card title="Transactional mail" href="/features/mail" />
  <Card title="Newsletters" href="/features/newsletters" />
  <Card title="Redirects and URLs" href="/features/redirects-and-urls" />
  <Card title="Analytics" href="/features/analytics" />
  <Card title="AI assistance" href="/features/ai-assistance" />
  <Card title="Accessibility" href="/features/accessibility" />
</Cards>

## Where each feature is configured [#where-each-feature-is-configured]

| Feature | Configuration | Admin screen | Command |
|---|---|---|---|
| Media library | `media:` and `storage:` in `engine.yaml`; `images.yaml` | Media | `engine-dmo media` |
| Search | `search:` in `engine.yaml`; `special.search` in `routes.yaml`; `search/synonyms.yaml` | Search index, Search synonyms, Insight search | `engine-dmo search` |
| Navigation | `nav:` in `site.yaml`; `seed/navigation/` | Navigation | |
| Forms | `endpoints.yaml` per site; `forms:` and `endpoints:` in `engine.yaml` | Submissions | |
| Transactional mail | `mail:` in `engine.yaml`; `mail:` in `site.yaml`; `templates/emails/` | | `engine-dmo mail` |
| Newsletters | `newsletter:` in `engine.yaml`; a `subscribe` step in `endpoints.yaml` | Newsletter | `engine-dmo newsletter` |
| Redirects | `redirects:` in `routes.yaml`; the redirect table | | `engine-dmo redirects` |
| Analytics | `analytics:` in `engine.yaml`; `analytics/dashboards.yaml` | Insight | `engine-dmo analytics` |
| AI assistance | `ai:` in `engine.yaml`; `ai/prompts/` | AI queue and the editor | `engine-dmo ai` |
| Accessibility | `accessibility:` in `site.yaml`; `accessibility.yaml` | | `engine-dmo a11y` |

Every key of every file is listed in the [configuration reference](/reference/configuration), and `engine-dmo config schema --file <kind>` prints a file's JSON Schema from the binary you are running. `<kind>` is the kind of file without `.yaml` (`engine`, `site`, `routes`, `endpoints`, `dashboards`, ...) or a real path such as `config/sites/main/site.yaml`; a bare `site.yaml` is refused.

## Common rules [#common-rules]

- **Secrets are environment variables.** A provider key, token or password in `engine.yaml` is a bare `${VAR}` interpolation. A literal secret is refused (`MRD-1004`), and so is a secret with a default value.
- **Ids are written by the tooling.** Endpoints, navigation slots, entered metrics and other configuration elements carry a stable `id`. Leave it out when you write the element and run `engine-dmo check --fix`, which writes one. See [stable ids](/concepts/stable-ids).
- **Every problem at once.** `engine-dmo check` reports every configuration problem with its file, line and column, together, and exits 3 when any is an error. Template warnings (a layout without `head()`, a missing `t()` key) are printed above the summary but not counted in it, so `0 errors, 0 warnings` can follow printed warnings: read every line, not only the last.
- **Permissions.** Each admin screen needs a permission. The built-in roles hold the common ones; a project grants the rest in `config/access/roles.yaml`. Each page lists the permissions its feature uses.


# Transactional mail (/features/mail)

How to configure the mail driver (Postmark, Amazon SES, Resend, SMTP or the development log), per-site senders, the email templates the engine and your forms send, bounce and complaint webhooks, the suppression list and the mail commands.

The engine sends transactional mail itself: staff invitations and password resets, notifications, form receipts and notices, newsletter confirmations, and in the DMO bundle the member portal's sign-in links, claims and reports. It never runs mail infrastructure. You bring a provider account or an SMTP relay; in development the `log` driver writes each message to the log instead of sending it.

## Configure a driver [#configure-a-driver]

```yaml
# config/engine.yaml
mail:
  driver: ${MAIL_DRIVER:-log}
  from: "Riverside Arts <hello@example.org>"
  reply_to: ${MAIL_REPLY_TO:-}
  postmark:
    server_token: ${POSTMARK_SERVER_TOKEN}
    message_stream: outbound
    webhook_token: ${POSTMARK_WEBHOOK_TOKEN}
```

Then check it end to end:

```bash
engine-dmo mail status                     # driver, sender, webhook path, queue, bounces and complaints
engine-dmo mail test --to you@example.org  # a real send of the magic-link template with sample data
engine-dmo mail test --to you@example.org --template contact-receipt --site main
```

`mail test` prints the provider's response. Both commands need the database.

### Reading mail in development [#reading-mail-in-development]

At the default log level the `log` driver writes `to`, `subject` and `tag`, with no body, so a sign-in, invitation or claim link cannot be read from it. Either turn the log level up:

```yaml
# config/engine.yaml
logging:
  level: debug
```

which adds a `mail body` line with the text and its links, or send to a local catcher such as Mailpit, which listens for SMTP on port 1025 and has an inbox at `http://localhost:8025`:

```yaml
# config/engine.yaml
mail:
  driver: smtp
  from: hello@example.org
  smtp:
    host: localhost
    port: 1025
    tls: none
```

A mail's links use one of two origins. A member's sign-in and claim links use the address the request came in on. An invitation or a membership notice comes from a job with no request, and uses the site's first domain with no port, so on a development install it reads `http://localhost/members/login`: open that path on your server's own address.

### Drivers [#drivers]

| `driver` | Keys | Notes |
|---|---|---|
| `log` (also empty) | none | Development only: each message is written to the log, its address, subject and tag at the `info` level and its body at `debug`. Refused in production. |
| `postmark` | `server_token` (secret), `message_stream`, `broadcast_stream`, `webhook_token` (secret) | `broadcast_stream` (default `broadcast`) carries newsletters and broadcasts so their reputation stays apart from transactional mail. `webhook_token` is required in production. |
| `ses` | `region`, `access_key_id`, `secret_access_key` (secret), `configuration_set`, `notification_topic_arn` | Amazon SES through its v2 API. Bounces and complaints arrive through the SNS topic named by `notification_topic_arn`. |
| `resend` | `api_key` (secret), `webhook_secret` (secret) | `webhook_secret` is the endpoint's `whsec_` signing secret from the Resend dashboard. Both are required in production. Resend has no separate streams; send the newsletter from a subdomain if you want its reputation apart. |
| `smtp` | `host`, `port` (default 587), `username`, `password` (secret), `tls` | `tls: starttls` requires STARTTLS; `tls: tls` connects with TLS (port 465); `tls: none` sends in clear. Left empty, STARTTLS is used when the relay offers it. TLS 1.2 is the minimum. |

Secrets are bare `${VAR}` interpolations. A failed send is retried when the failure is temporary (a timeout, an SMTP 4xx) and recorded as failed when it is final.

### Production rules [#production-rules]

`engine-dmo check` refuses, when `engine.environment` is `production`:

- `driver: log` or no driver;
- an empty `mail.from`;
- `driver: postmark` without `webhook_token`, since anyone could otherwise fill the suppression list;
- `driver: resend` without `api_key` or `webhook_secret`, or a `webhook_secret` that is not a `whsec_` secret.

These rules run in `engine-dmo check` only, not when the server starts: an engine started in production on the `log` driver boots and writes every message to its log instead of sending it. Run `ENVIRONMENT=production engine-dmo check` (with your production variables) in the deploy pipeline before the new version starts.

In every environment, `from` and `reply_to` must be an address (`hello@example.org`) or a name and an address (`Riverside Arts <hello@example.org>`).

## Senders per site [#senders-per-site]

A message sent for a site goes out from the site's own address when its `site.yaml` sets one:

```yaml
# config/sites/<site>/site.yaml
mail:
  from: "Riverside Arts <hello@example.org>"
  reply_to: box-office@example.org
  newsletter:
    from_address: news@example.org
    from_name: Riverside Arts
```

`from` and `reply_to` replace `mail.from` and `mail.reply_to` for that site's transactional mail. When `from` has no name, the site's name is used. The `newsletter` block replaces the newsletter's sender for the site's campaigns ([Newsletters](/features/newsletters)). A site that sets nothing sends as the install does.

## Templates [#templates]

Every message is a template in an `emails/` directory, resolved along the site's template chain like a page: `templates/<site>/emails/` first, then `templates/_shared/emails/`, then the engine's own default. A project template with the same name as a default replaces it. Where a message or the CLI says "templates/emails/", it means the `emails/` directory of any of these roots.

A template extends `emails/_layout.html` and fills its blocks. The engine renders it three times, with `part` set to `subject`, `preheader` and `html`, so one file yields every part:

```jinja
{% extends "emails/_layout.html" %}
{% block subject %}We have your message{% endblock %}
{% block preheader %}A copy of what you sent.{% endblock %}
{% block body %}
<h1>Thank you, {{ name }}</h1>
<p>We will reply to {{ email }} within two working days.</p>
{% endblock %}
```

| Block of `_layout.html` | Holds |
|---|---|
| `subject` | The subject line. Whitespace is collapsed. Default: the site's name. |
| `preheader` | The preview text a mail client shows after the subject. |
| `subject_title` | The HTML `<title>`. |
| `preheader_html` | The hidden preview text in the body. |
| `body` | The message. |
| `footer` | The line under the card. Default: "Sent by" the site's name and address. |

The default layout is a single-column card that sets `lang`, a dark-mode palette and `role="article"`. To restyle every message, write your own `templates/_shared/emails/_layout.html` that switches on `part` the same way.

**Plain text.** A message's text alternative is `emails/<name>.txt` when it exists, else generated from the HTML. With `mail.templates.plain_text: require`, a template without a `.txt` is an error.

**Context.** Every template receives:

| Name | Meaning |
|---|---|
| `site.name`, `site.url` | The site's name in the recipient's locale, and its base address. |
| `recipient.displayName`, `recipient.email`, `recipient.locale` | Who it is for. |
| `locale` | The recipient's locale. Dates and numbers are formatted in it, in the site's time zone. |
| `now` | The time of rendering. |

plus what the sender adds: a form's inputs and `submission` for a `mail` step ([Forms](/features/forms-and-submissions)), and named values for each engine template.

**Locale.** A form's mail, the staff notice included, is rendered in the locale the visitor posted in. A message sent with no locale is formatted in the site's default locale.

**No page functions.** Email templates have the template language and its filters, but not the functions a page has: `t()`, `query()`, `head()` and the rest are not defined there. Calling one prints nothing, and `check` does not report it. Write text for each locale by branching on `locale`:

```jinja
{% block subject %}{% if locale == "cy" %}Diolch am eich neges{% else %}Thank you for your message{% endif %}{% endblock %}
```

**Checked.** `engine-dmo check` compiles every engine template, and every template a `mail` step names, against sample data, so a broken email fails the check rather than a send. `engine-dmo mail templates` lists every template, the root that resolved it and whether a `.txt` exists.

Transactional mail carries no unsubscribe footer. Newsletters and broadcasts do, and cannot be sent without one.

### The engine's templates [#the-engines-templates]

| Template | Sent when | Bundle |
|---|---|---|
| `staff-invitation` | A staff user is invited | both |
| `staff-password-reset` | A staff user asks to reset a password | both |
| `mention` | A staff user is mentioned in a note | both |
| `notification-digest` | The daily digest of a user's notifications | both |
| `newsletter-confirm` | A visitor subscribes: the double opt-in link | both |
| `newsletter` | A newsletter campaign is sent | both |
| `magic-link` | A member signs in to the portal | DMO |
| `portal-invitation` | A person is invited to an organisation's portal | DMO |
| `claim-verification`, `claim-contact-check`, `claim-question`, `claim-approved-notice`, `claim-rejected` | A listing claim moves | DMO |
| `moderation-outcome` | A member's change is approved or returned | DMO |
| `renewal-notice` | A membership is due to renew | DMO |
| `member-digest` | The monthly member report | DMO |
| `organisation-report` | A scheduled organisation report | DMO |
| `broadcast` | A CRM broadcast | DMO |

Override one by writing a template of the same name. `engine-dmo mail test --template <name>` renders and sends it with the sample data `check` uses.

## Bounces, complaints and suppression [#bounces-complaints-and-suppression]

Every send checks the **suppression list** first. A suppressed address is never sent to: no job is queued and the delivery record says why.

Addresses are suppressed install-wide, on every channel, by:

| Reason | How |
|---|---|
| `hard_bounce` | The provider reports a hard bounce. |
| `complaint` | The recipient marks a message as spam. |
| soft bounces | `mail.suppression.soft_bounce_threshold` soft bounces (3) within `soft_bounce_window` (30 days) suppress as a hard bounce. |
| `manual`, `unsubscribe_all` | Added by hand: `engine-dmo mail suppression add --reason`, or `engine-dmo newsletter suppress`. |
| `erasure` | The person's data was erased. Cannot be removed. |

Providers report bounces, complaints and deliveries to a webhook on the engine. Point your provider at the path for your driver:

| Driver | Webhook | Authenticated by |
|---|---|---|
| `postmark` | `POST /_mail/webhooks/postmark` | An `Authorization: Bearer <webhook_token>` header: add it as a custom header on the Postmark webhook. |
| `ses` | `POST /_mail/webhooks/ses` | The SNS message signature and `notification_topic_arn`. The subscription confirmation is followed automatically. |
| `resend` | `POST /_mail/webhooks/resend` | The Svix signature, with `webhook_secret`. |

`mail.webhooks.path` changes the prefix. Only the configured driver's path answers. With `notify_on_suppress`, staff are notified when a hard bounce suppresses the address of a CRM contact (DMO bundle).

```bash
engine-dmo mail suppression check --email someone@example.org
engine-dmo mail suppression list --reason hard_bounce --since 30d
engine-dmo mail suppression add --email someone@example.org --reason manual
engine-dmo mail suppression remove --email someone@example.org --reason "asked to be re-added" --confirm
```

`list` shows addresses as hashes. `remove` is audited; an `erasure` row cannot be removed.

## Delivery records [#delivery-records]

Every message has a delivery record: the template, the recipient, the provider's message id and what the provider reported (sent, delivered, bounced, complained, failed, suppressed). Records are kept for `mail.delivery_record_retention`, thirteen months by default. A form's submission shows the records of the mail it sent.

Queued messages that carry single-use links (invitations, resets, sign-in links) are encrypted in the job queue.

## Commands [#commands]

| Command | What it does |
|---|---|
| `mail status` | The driver, the from address, the webhook path and whether it has received anything, the queue depth, and bounce and complaint figures. |
| `mail test` | A real send through the driver with sample context: `--to`, `--template` (default `magic-link`), `--site`, `--locale`. |
| `mail templates` | Every transactional template for a site (`--site`), the root that resolved it, and whether a `.txt` exists. |
| `mail suppression add`, `check`, `list`, `remove` | The suppression list. |

## Configuration reference [#configuration-reference]

Every key is under `mail:` in `config/engine.yaml`.

| Key | Default | Meaning |
|---|---|---|
| `driver` | log | `postmark`, `ses`, `resend`, `smtp` or `log`. |
| `from` | | The sender. Required in production. |
| `reply_to` | | The Reply-To of every message. |
| `postmark.*`, `ses.*`, `resend.*`, `smtp.*` | | The driver's keys, above. `ses.region` has no default here. |
| `webhooks.path` | `/_mail/webhooks` | The prefix of the provider webhooks. |
| `templates.dir` | `emails` | The directory under each template root. |
| `templates.plain_text` | `generate` | `generate` or `require`. |
| `suppression.soft_bounce_threshold` | `3` | |
| `suppression.soft_bounce_window` | `30d` | |
| `suppression.notify_on_suppress` | `true` | |
| `delivery_record_retention` | `13m` | How long delivery records are kept (`13m` is thirteen months). |
| `rate_limit_per_minute` | `0` | Space sends to at most this many a minute per process; `0` is no limit. |
| `broadcast.*` | | The DMO bundle's CRM broadcasts: `batch_size` (50, 1 to 1000), `batch_pause` (`5s`, up to `1h`), `open_tracking` (false), `per_recipient_tracking` (false). `unsubscribe_footer` cannot be false. |

`retention.mail_events` (thirteen months) is how long provider events are kept, and must be at least `suppression.soft_bounce_window`.


# Media library (/features/media)

How uploads, alt text and captions per locale and per site, licence and rights records, duplicates, orphans and image derivatives work, with every media setting in engine.yaml.

The media library holds every image, document, audio and video file a site uses. An asset is uploaded once, install-wide, and chosen in documents through an `asset` field. The library keeps the words about each asset (alt text and caption) per locale with a per-site override, records the licence it is used under, and generates the image sizes your templates ask for.

## A minimal setup [#a-minimal-setup]

A new project already has a working library: originals and derivatives are stored on the local disk under `storage.filesystem.root`.

```yaml
# config/engine.yaml
storage:
  driver: filesystem
  filesystem:
    root: ./storage

media:
  max_upload_bytes: 30MB        # default 50MB
  require_alt_text: true        # the default: an image needs alt text unless it is decorative
```

A content type offers the library through an `asset` field, and a template renders the image through a named transform from `images.yaml`:

```yaml
# config/schema/article.yaml
fields:
  - name: hero
    type: asset
    alt: required          # never empty unless the image is marked decorative
    caption: true          # offer a per-use caption
```

```jinja
{% if entry.hero %}{{ entry.hero.figure("hero", priority=true) }}{% endif %}
```

`figure()` writes the picture, the caption and the licence credit. How to render images, the transforms in `images.yaml` and the responsive sizes are covered in [Images](/templates/images).

## Uploading [#uploading]

Staff upload in the admin's Media screen, or from an `asset` field that declares `upload: true`. Members upload through the portal (DMO bundle), agents through the content MCP, and a migration through `engine-dmo media import`. Every path goes through the same pipeline:

<Steps>
<Step>The size is checked against `media.max_upload_bytes`, and the file's type is sniffed from its bytes and checked against `media.accept`. The file name and the declared type are never trusted.</Step>
<Step>An image is decoded and checked against `media.max_pixels`.</Step>
<Step>A JPEG or PNG is re-encoded to strip its metadata, GPS location included, while `media.strip_exif_gps` is true. A photo whose metadata cannot be removed is refused rather than stored with its location. WebP originals are kept as uploaded; every derivative is re-encoded.</Step>
<Step>With `media.require_alt_text` on, an image uploaded in the admin needs alt text in the source locale unless it is marked decorative. Other locales are required when a document using the image is published in them.</Step>
<Step>The asset is recorded with its checksum and a perceptual hash, the original is stored, and possible duplicates are listed on the asset's page.</Step>
</Steps>

A refused upload says why: "this file type is not accepted", "the file is larger than the upload limit", or "alt text is required for every enabled locale unless the image is decorative".

The admin's upload form needs `media.upload`. Editing an asset afterwards needs `media.edit`.

## Alt text and captions [#alt-text-and-captions]

Alt text describes the image for someone who cannot see it. A caption is editorial text shown to everyone. The library keeps both:

- **Per locale.** Each enabled locale has its own alt text and caption.
- **Per site.** The text written on the asset is the default for every site. A site may override the alt text, the caption, or both, in any locale, so the same photograph can be described differently on two sites. The asset page shows, for each locale, what every site will display.
- **Per use.** An `asset` field may carry its own alt text and caption for one document (`alt: inherit`, the default, lets the editor override; `caption: true` offers a caption). A per-use value wins over the library's.
- **Decorative.** An image marked decorative renders `alt=""` everywhere and is never overridden per site. The library counts decorative images separately, so marking cannot hide a backlog.

The admin refuses alt text over 200 characters, shows a count against an advised 125, and refuses alt text that opens with "image of", "photo of" and similar.

### How a page finds its alt text [#how-a-page-finds-its-alt-text]

For a page on site S in locale L, alt text and caption are each taken from the first of:

1. the per-use value on the field;
2. S's override in L;
3. the default in L;
4. for each locale in L's fallback chain, then the install's default locale: S's override, then the default.

Language comes before site: a reader gets text in their own language before a site-specific text in another language. When the text comes from a fallback locale, the image value's `altLang` (and `captionLang`) names that locale, and `img()`, `picture()` and `figure()` write a `lang` attribute so a screen reader pronounces it correctly.

### Missing translations at publish [#missing-translations-at-publish]

Each site decides what happens when an image's alt text exists only in a fallback locale, in `site.yaml`:

```yaml
# config/sites/<site>/site.yaml
accessibility:
  alt_fallback: warn            # allow | warn (the default) | block
  alt_fallback_locales:
    cy-GB: block                # Welsh pages must carry Welsh alt text
```

| Policy | At publish |
|---|---|
| `allow` | Publishes with the fallback and says nothing. |
| `warn` | Publishes, and lists the image in the publish warnings (`alt_fallback`). |
| `block` | Refuses the publish (`alt_fallback_blocked`) until the locale has its own alt text. |

An image with no alt text in any locale of the chain is always an error at publish (`alt_needed` for an `alt: required` field, otherwise `alt` while `media.require_alt_text` is on). Saving a draft is never refused for alt text. The policy used is the owning site's, also for a document shared to other sites.

### Working through a backlog [#working-through-a-backlog]

The admin's Alt text queue lists images missing alt text (or captions) in one locale, for the default or for one site, most used first, with a field per row saved from the keyboard. With an AI provider configured, "Draft these with AI" fills the queue with drafts a person reviews ([AI assistance](/features/ai-assistance)).

`engine-dmo media stats` reports the library's size and, per site and locale, how many images have alt text of their own, how many show a fallback, and how many have none:

```bash
engine-dmo media stats
engine-dmo media stats --site main --json
```

Editing the default text needs `media.edit` with no site restriction; a site's override needs `media.edit` on that site; a grant scoped to locales covers those locales only.

## Rights and licences [#rights-and-licences]

Every asset can carry a rights record: the licence term, the holder, the uses it covers, the territory, the start and end dates, the credit line, the source, and an evidence file (a model release or licence PDF, itself an asset). The record is edited on the asset's Rights panel and needs the `media.rights` permission, which no built-in role except Owner holds; grant it in `config/access/roles.yaml`. Every change is audited.

### Licence terms [#licence-terms]

`media.rights.terms` is the vocabulary editors choose from. Applying a term fills the uses and territory when they are empty, and the end date from the start date (today when none is given) plus the term's duration. A term with `credit_required` refuses a record without a credit line.

```yaml
# config/engine.yaml
media:
  rights:
    on_expiry: placeholder
    expiry_warnings: [90d, 30d, 0d]
    terms:
      commissioned:
        label: { en: "Commissioned, perpetual" }
        uses: [website, social, newsletter, print]
        territory: [WORLD]
      stock-web-1y:
        label: { en: "Stock, web only, one year" }
        uses: [website]
        territory: [WORLD]
        duration: 1y
        credit_required: true
      member-supplied:
        label: { en: "Supplied by member" }
        uses: [website, social, newsletter]
        territory: [WORLD]
        credit_required: true
```

Setting `terms` replaces the engine's four defaults: `commissioned-perpetual`, `stock-2yr-web`, `member-supplied` and `press-only`. Keep a `member-supplied` term if members upload photos through the portal (DMO bundle): without it, member uploads are unavailable.

| Term key | Type | Meaning |
|---|---|---|
| `label` | map of locale to text | What the Rights panel shows. |
| `uses` | list | Any of `website`, `social`, `newsletter`, `print`, `editorial`, `press`, `partner`, `handover`. |
| `territory` | list | `WORLD` or country codes. |
| `duration` | period | `90d`, `18m`, `2y`; empty is perpetual. |
| `credit_required` | boolean | The record must have a credit line, and templates must show it. |

### Expiry [#expiry]

- **At publish**, an image whose licence ended before today refuses the publish (`rights_expired`) while `block_publish_when_expired` is true, the default, and is a warning when it is false. An image whose licence ends while the page stays live is a warning (`rights_expiring`) while `warn_publish_when_expiring` is true. Saving is never refused for rights.
- **Every day**, a scheduled sweep finds licences ending within the largest of `expiry_warnings` and notifies every user holding `media.rights`, once per threshold crossed.
- **Once a licence has ended**, `on_expiry: warn` (the default) changes nothing on the live site. `on_expiry: placeholder` renders the image as absent on public pages, exactly as a deleted asset, so a template's `{% if entry.hero %}` falls through to its own fallback. Nothing is ever deleted automatically.

### Credits [#credits]

An image's `credit` is the credit line its licence requires, and `creditRequired` is true when there is one. `figure()` always writes it in the `<figcaption>`. `img()` and `picture()` write no caption, so a template that uses them must print the credit itself:

```jinja
{{ entry.hero.picture("hero") }}
{% if entry.hero.credit %}<small>{{ entry.hero.credit }}</small>{% endif %}
```

`engine-dmo check` warns (`image-credit`) at every `X.img(...)` or `X.picture(...)` in a template that neither prints `X.credit` nor calls `X.figure(...)` anywhere in the same file.

### Member-supplied photos [#member-supplied-photos]

A photo whose licence is `member-supplied`, or that a member uploaded and accepted the upload terms for, is given to a third party only when its rights record names that use: `partner` for a partner site's widget or embed and for `engine-dmo export embeds`, `handover` for `engine-dmo site export`. Without it the photo is left out. The site's own pages, feeds and APIs always show it.

## Duplicates, orphans and bulk editing [#duplicates-orphans-and-bulk-editing]

- **Duplicates.** Each image gets a 64-bit perceptual hash at upload. Images whose hashes differ by at most `media.duplicates.threshold` bits (10 by default), and files with the same checksum, are listed on the asset page under "Possible duplicates" and in the library's "Possible duplicates" filter. It is a suggestion: nothing is merged or refused. "Not a duplicate" dismisses a pair for good.
- **Orphans.** A scheduled scan, at `media.orphans.scan_schedule` (03:00 UTC by default), marks every asset as in use, used only in old revisions, or unreferenced. The library's Usage filter reads it, and "Scan now" runs it on demand. An asset used as rights evidence or in a collection counts as in use.
- **Bulk editing.** The library's list view selects assets (up to 2,000 matching a filter) and applies one operation: add or remove a tag, apply a licence term or credit line (`media.rights`), add to a collection, set or clear decorative, regenerate derivatives, soft delete or restore (`media.delete`). A preview says what will change before it runs; the run is one audited job. Deleted assets are listed under "Deleted", where they can be restored.
- **Collections** are named, install-wide, manual groups of assets, used as a filter.

Not in this version: merging two duplicate assets into one, a hard purge of a deleted asset's file (a deleted asset stays restorable; `media prune` removes only derivatives), collections that fill themselves from a rule, and press packs.

## Derivatives [#derivatives]

Image sizes are generated on demand from the transforms in `config/images.yaml` (and a site's own `config/sites/<site>/images.yaml`). A derivative's address carries a keyed hash, so nobody can request a size the site never rendered. Derivatives are stored and reused; the pure Go build serves JPEG, and the `-vips` image also serves WebP and AVIF.

```bash
engine-dmo media transforms                  # every transform and its width ladder
engine-dmo media transforms --site main --source-width 1600
engine-dmo media warm --dry-run              # count derivatives the published pages need
engine-dmo media warm --site main            # generate them, JPEG before WebP before AVIF
engine-dmo media prune --dry-run             # what pruning would remove, and the bytes freed
```

| Command | What it does |
|---|---|
| `media transforms` | Lists every transform a template can name, resolved over `images.yaml` defaults and, with `--site`, the site's own file; `--source-width` and `--source-height` show the ladder for a given source. |
| `media warm` | Renders published pages in process and generates the derivatives their markup references. `--site`, `--type`, `--document` narrow it; `--shard i/n` splits the work across runs; `--dry-run` only counts. |
| `media prune` | Removes the derivatives of deleted assets, those not served or warmed for `--older-than` (default `media.derivatives.keep_unused`), and, once unused for a day, those of old asset versions or retired transforms. `--dry-run` removes nothing. |
| `media stats` | Asset count and bytes, alt text and caption coverage by site and locale, derivatives by transform and format. |
| `media import` | Uploads the files a `meridian.media.v1` manifest lists through the pipeline, under the manifest's ids, with alt text, captions and rights. Running it again skips ids already in the library. See [Migrating content](/integrating/migration). |

All media commands need the database.

## Configuration reference [#configuration-reference]

Every key is under `media:` in `config/engine.yaml`.

| Key | Default | Meaning |
|---|---|---|
| `max_upload_bytes` | `50MB` | The largest upload. A size such as `30MB`. |
| `max_pixels` | `50000000` | The largest image, in pixels, that is decoded. At least 1,000,000. |
| `accept` | `image/jpeg`, `image/png`, `image/webp`, `image/avif`, `application/pdf`, `application/gpx+xml` | The media types an upload may be, sniffed from the bytes. |
| `strip_exif_gps` | `true` | Re-encode JPEG and PNG uploads to remove metadata, GPS included. |
| `require_alt_text` | `true` | Alt text at upload (source locale) and at publish (the page's locale), unless decorative. |
| `signing_key` | derived | The key derivative addresses are signed with. A secret (`${VAR}`); when empty it is derived from `server.security.signing_key`. Changing it changes every derivative address. |
| `derivatives.keep_unused` | `90d` | How long a derivative nothing serves or warms is kept before the nightly prune. At least a day. |
| `rights.terms` | four built-in terms | The licence vocabulary; setting it replaces the defaults. |
| `rights.expiry_warnings` | `[180d, 90d, 30d, 0d]` | Periods before a licence ends at which `media.rights` holders are notified. |
| `rights.block_publish_when_expired` | `true` | An ended licence refuses a publish; `false` makes it a warning. |
| `rights.warn_publish_when_expiring` | `true` | Warn at publish when a licence ends while the page stays live. |
| `rights.on_expiry` | `warn` | `warn` or `placeholder` (render the image as absent once its licence has ended). |
| `orphans.scan_schedule` | `0 3 * * *` | The reference scan's schedule, a five-field cron expression in UTC. |
| `duplicates.threshold` | `10` | How many of the perceptual hash's 64 bits may differ for two images to be offered as near duplicates. |

The files themselves live where `storage:` says:

| Key | Default | Meaning |
|---|---|---|
| `storage.driver` | `filesystem` | `filesystem` or `s3`. |
| `storage.filesystem.root` | | The directory, relative to the project. |
| `storage.filesystem.shared` | `false` | Declare that every replica mounts the same filesystem. Required for filesystem storage with `server.replicas` above 1. |
| `storage.s3.endpoint`, `region` (`eu-west-2`), `bucket`, `access_key_id`, `secret_access_key`, `path_style`, `public_base_url` | | An S3-compatible bucket. `secret_access_key` is a secret. |

## Permissions [#permissions]

| Permission | Allows | Built-in roles |
|---|---|---|
| `media.view` | Reading the library, the asset pages and the queue | Administrator, Editor, Author, Translator |
| `media.upload` | Uploading | Administrator, Editor, Author |
| `media.edit` | Alt text, captions, focal point, tags, collections, decorative, duplicates, the orphan scan | Administrator, Editor |
| `media.rights` | The rights record, licence terms and credit lines, alone and in bulk | Owner only |
| `media.delete` | Soft delete and restore | Owner only |

Owner holds every permission. A built-in role is changed by declaring a role with the same key in `config/access/roles.yaml`.


# Navigation (/features/navigation)

How menus work: navigation slots declared in site.yaml, navigation sets edited in the admin or seeded from files, the nav global and the nav tag in templates, and breadcrumbs, child pages and language switchers.

A site's menus are **navigation sets** filling **slots**. A slot is a place on the site's pages that the project declares in `site.yaml`, such as the header or the footer. A set is a tree of items that staff edit in the admin's Navigation screen and assign to a slot. Templates read the assigned set as `nav.<slot>`.

Items point at documents, files, a type's index page or an address. A document item links to the document's live address in the visitor's locale and drops out of the menu by itself when the document is unpublished, so a menu never links to a page that is gone.

## Add a menu [#add-a-menu]

<Steps>
<Step>
Declare the slot in `site.yaml`:

```yaml
# config/sites/<site>/site.yaml
nav:
  main: { label: { en: Header }, depth: 2 }
  footer: { label: { en: Footer }, depth: 1 }
```

Run `engine-dmo check --fix`, which writes each slot's `id`. The id is what the stored sets are keyed by, so renaming a slot keeps its sets.
</Step>
<Step>
Render it in the layout:

```jinja
<nav aria-label="Main">
  <ul>{% nav item in nav.main %}<li><a href="{{ item.url|url }}"{% if item.isCurrent %} aria-current="page"{% endif %}>{{ item.label }}</a>{% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}</li>{% endnav %}</ul>
</nav>
```
</Step>
<Step>
Create the set. Either in the admin (Navigation, choose the site and slot, add items, assign), or as a seed file that `engine-dmo seed apply` loads:

```yaml
# seed/navigation/main.yaml
site: main
slot: main
name: Header
assigned: true
items:
  - label: { en: Visit }
    document: page/visit
  - label: { en: Search }
    url: /search
  - label: { en: Find us }
    children:
      - label: { en: Getting here }
        document: page/visit
        suffix: "#getting-here"
      - label: { en: Box office }
        url: "https://tickets.example.org/"
```

`engine-dmo seed verify` checks the file against the site's slots and the seed's documents, and names the file in each problem (`seed/navigation/main.yaml: document page/visit is not in the seed`). Its summary line counts documents, assets and users only, never navigation sets, so a clean run that says nothing about navigation means every navigation file passed. To see the menu itself, `engine-dmo seed apply` against a database and `engine-dmo render /`.

On a site with more than one locale, give every item's `label` a value in each locale (`{ en: Visit, cy: Ymweld }`). A missing one falls back along the locale chain to the source locale's label without a warning.
</Step>
</Steps>

A slot with no assigned set renders as an empty list, so a template can always loop over it.

## Slots [#slots]

Each key under `nav:` is a slot. The key is how templates name it (`nav.main`), so it is letters, digits and underscores, starting with a letter.

| Key | Default | Meaning |
|---|---|---|
| `id` | written by `check --fix` | The slot's stable id. |
| `label` | the key | The slot's name in the admin, per locale. |
| `depth` | `1` | The deepest an item may sit, 1 to 5. `1` is a flat list; `2` allows one level of children. Items deeper than the depth are not rendered. |

A slot takes no other keys. Older projects that listed items directly under `nav.<slot>` are refused with a hint to move the items into a set.

## Items [#items]

Every item has a label per locale and at most one target:

| Seed key | Admin kind | Links to | Drops out when |
|---|---|---|---|
| `document` | Document | The document's live address in the visitor's locale. In a seed, a `type/key` reference to a seeded document. | The document is not published on the site in the locale chain. |
| `asset` | File | A library file's address. | The asset is deleted. |
| `index` | Index page | A type's index page, from its route's `index`. The label defaults to the type's plural name. | The type has no index route on the site. |
| `url` | Address | A path on the site (`/search`, prefixed with the locale as `path()` does) or an absolute `http` or `https` address with a host. | The address is not a valid link. |
| none | Heading | Nothing: a heading that groups its children, such as a footer column. | It has no children left to show. |

`suffix` adds a fixed ending to the resolved address: an anchor (`#getting-here`) or a query string (`?category=stay`).

`label` is read along the visitor's locale chain. An item with no label in the chain takes its target's title (a document's title, a type's plural name, an external host name); an item with no label at all is not rendered.

## In templates [#in-templates]

`nav` holds every slot of the site, each a list of items:

| Key | Meaning |
|---|---|
| `label` | The label in the visitor's locale. |
| `url` | The address. Print it through the `url` filter. |
| `kind` | `document`, `asset`, `index`, `url` or `heading`. |
| `isExternal` | True for an address on another host. |
| `isCurrent` | True when the item's address is the page being served (the same path, trailing slash ignored, and the same values for any query parameters the item names). |
| `isActive` | True when the item or any item beneath it is current: the active trail. |
| `depth` | 1 for the top level. |
| `children` | The items beneath it. |
| `id`, `type` | A document item's document id and type key. |

The `{% nav %}` tag renders a tree: its body runs once per item with the item bound to the name you give, `{% ifchildren %}` renders only when the item has children, and `{% children %}` renders the same body for them one level deeper. It works over any list of maps with `children`, not only `nav`. A flat list needs only a `for` loop:

```jinja
<ul>{% for item in nav.footer %}<li><a href="{{ item.url|url }}">{{ item.label }}</a></li>{% endfor %}</ul>
```

A heading item has an empty `url`; render it as text:

```jinja
{% nav item in nav.footer %}
  {% if item.kind == "heading" %}<h2>{{ item.label }}</h2>{% else %}<a href="{{ item.url|url }}">{{ item.label }}</a>{% endif %}
  {% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}
{% endnav %}
```

Navigation is resolved once per site and locale and cached; publishing a document a menu names, or editing a set, refreshes it. A `{% cache %}` block that names `nav` is invalidated with it.

## Other navigation [#other-navigation]

| Need | Use |
|---|---|
| Breadcrumbs on a nested page | `entry.ancestors`, or `ancestors(doc)`: the published ancestors on the site, root first. |
| A page's sub-pages | `entry.children`, or `children(doc)`: the published children, in title order. |
| A table of contents for rich text | The `toc` filter on a Portable Text value: a nav of its headings, linking to their ids. |
| A language switcher | `localeSwitcher()`: a nav of the locales the page exists in, the current one marked. `localeUrl(code)` is the current page in another locale, empty when it has no translation. |
| Links to another site of the install | `siteUrl(path, site="other")`; `sites` lists every site when there is more than one. |
| Pagination on index and search pages | `pagination` ([Search](/features/search)). |

```jinja
{% if entry.ancestors %}
<nav aria-label="Breadcrumb"><ol>
  {% for a in entry.ancestors %}<li><a href="{{ a.uri|url }}">{{ a.title }}</a></li>{% endfor %}
  <li aria-current="page">{{ entry.title }}</li>
</ol></nav>
{% endif %}
```

Breadcrumbs and children apply to types whose routes nest; see [Routes](/concepts/sites-locales-and-routes).

## The admin [#the-admin]

The Navigation screen lists the slots a site declares, the sets that fill them and which set is assigned. A set's items are edited with plain forms: add an item of a kind, set its labels per locale, move it up, down, in (under the item above) or out, remove it. Sets can be renamed, deleted and assigned to their slot. Every change works from the keyboard and without JavaScript. Sets are kept per slot, so a new menu can be prepared and assigned when it is ready.

Every route of the screen needs `nav.manage` on the site, which the built-in Administrator and Editor roles hold.


# Newsletters (/features/newsletters)

How the built-in newsletter works: capturing subscribers with double opt-in through a declared endpoint, topics and consent records, the confirmation and preference centre pages, composing and sending campaigns from live content, tracking, deliverability checks and the newsletter commands.

The newsletter is built in, in both bundles. Visitors subscribe through a form you declare; each subscription is confirmed by the subscriber (double opt-in) and recorded with the exact wording they agreed to. Staff compose campaigns in the admin from text and live content blocks, send them to a segment of a site's subscribers through your mail provider, and read a report of deliveries, clicks and the referrals they produced. Subscribers manage their topics, frequency and pauses in a preference centre behind a signed link.

Campaigns go out through the configured mail driver ([Transactional mail](/features/mail)), on the provider's marketing stream where it has one.

## Capture subscribers [#capture-subscribers]

<Steps>
<Step>
Declare a subscription endpoint with a `subscribe` step:

```yaml
# config/sites/<site>/endpoints.yaml
endpoints:
  - key: newsletter
    path: /newsletter
    methods: [post]
    input:
      email:   { type: text, format: email, required: true, autocomplete: email, label: { en: Your email address } }
      topic:   { type: select, options: [exhibitions, family], label: { en: What interests you? } }
      consent: { type: boolean, required_value: true, label: { en: Yes, send me the monthly programme } }
    steps:
      - subscribe: { form: newsletter, email: $email, tags: [$topic] }
    respond:
      fragment: partials/subscribed.html
      on_error: partials/subscribe-form.html
```
</Step>
<Step>
List the topics subscribers may choose, in `engine.yaml`:

```yaml
# config/engine.yaml
newsletter:
  from_address: news@example.org
  from_name: Riverside Arts
  topics: [exhibitions, family]
```
</Step>
<Step>
Draw the form, for example in the footer of every page, and write the two partials:

```jinja
{# templates/_shared/partials/subscribe-form.html #}
{{ subscribeForm("newsletter").render(submit="Sign up") }}
```

```jinja
{# templates/_shared/partials/subscribed.html #}
<div id="form-newsletter" role="status"><h2>Check your email</h2><p>Open the link we sent to confirm.</p></div>
```
</Step>
<Step>
Run `engine-dmo check --fix`, then `engine-dmo check`.
</Step>
</Steps>

The endpoint takes every other endpoint key, rate limits and spam controls included ([Forms](/features/forms-and-submissions)).

### The subscribe step [#the-subscribe-step]

| Key | Meaning |
|---|---|
| `email` | Required. The input holding the address, `$email`. |
| `name` | The input holding the subscriber's name. |
| `form` | A name for where the subscription came from, recorded with the consent. |
| `tags` | The topics subscribed to: literal topic keys, or `$input` references to an input whose posted value (a string or a list) is matched against `newsletter.topics`. Anything not in `topics` is dropped silently, so a visitor's free text never becomes a tag. |

The consent recorded is the label of the endpoint's `required_value` boolean, in the visitor's locale, so word that checkbox as the promise you are making. The source recorded is the page the form was on (the referring path on the site's own host, else the endpoint's path), never a foreign address or a query string.

### Double opt-in [#double-opt-in]

A post creates a **pending** subscriber and mails the `newsletter-confirm` template with a signed link to `/newsletter/confirm/<token>` on the site. The link works for seven days. A second post for the same pending address within a day sends nothing more, and answers exactly as the first did, so the form cannot be used to flood an inbox.

The link opens a page with one button; the button's post confirms. A mail scanner that follows the link confirms nothing. Unconfirmed subscribers are deleted after `newsletter.pending_expiry` (14 days), with their consent records.

`newsletter.double_opt_in` cannot be set to false.

## The subscriber's pages [#the-subscribers-pages]

Each page renders your template when the site has one, along its template chain, and a plain built-in page otherwise. All of them answer `Cache-Control: no-store` and `X-Robots-Tag: noindex`.

### Confirmation [#confirmation]

`newsletter/confirm.html` is the page with the button. It receives `subscriber` (`email`, `status: pending`, `confirmed: false`) and `confirm` (`action`, the path to post to, and `csrf`, the token for the `_csrf` field):

```jinja
{# templates/_shared/newsletter/confirm.html #}
{% extends "base.html" %}
{% block body %}
<h1>Confirm your subscription</h1>
<p>Confirm that {{ subscriber.email }} should receive our newsletter.</p>
<form method="post" action="{{ confirm.action|url }}">
  <input type="hidden" name="_csrf" value="{{ confirm.csrf }}">
  <button type="submit">Confirm</button>
</form>
{% endblock %}
```

`newsletter/confirmed.html` is the outcome. `subscriber.status` is `active` with `confirmed: true` when this post confirmed it, `active` with `confirmed: false` when the address was already confirmed, and `expired` (with no email) when the link does not verify, has run out or names an address that has left.

### The preference centre [#the-preference-centre]

At `newsletter.preference_centre_path` (`/newsletter/preferences`) with the subscriber's signed token, linked from every campaign's footer. It offers "Unsubscribe from everything", the topics of `newsletter.topics` (labelled from the tag vocabulary, else the key), the frequency (`every`, `weekly`, `monthly`) and a pause of one, three or six months.

`newsletter/preferences.html` receives `preferences`:

| Key | Meaning |
|---|---|
| `status` | `unknown` (a link that opens nothing), `active`, `pending`, `unsubscribed`, `bounced`, `complained` or `suppressed`. |
| `subscribed` | Active or pending. |
| `email` | The address. |
| `topics` | Each with `key`, `label` and `chosen`. |
| `frequency`, `frequencies` | The chosen frequency and the choices. |
| `pausedUntil`, `pauses` | The pause end date (empty when not paused) and `[1, 3, 6]`. |
| `notice` | What the last post did: `saved`, `refused` (with `error`), `unsubscribed`, or empty. |
| `action`, `csrf` | Where the form posts (the path carries the token) and a CSRF token. |

The form posts `action=save` with `topic` (repeated), `frequency` and `pause` (`0` sends again or resumes, `1`, `3` or `6` pauses, `-1` leaves a pause as it is), or `action=unsubscribe`. An unknown token renders the same template with `status: unknown` and nothing else, so addresses cannot be probed. The token does not expire and names one subscriber.

### Unsubscribe [#unsubscribe]

Every campaign carries an unsubscribe link at `/_n/u/<token>` and the `List-Unsubscribe` headers for one-click unsubscribe. A GET shows a page with one button (mail scanners must not unsubscribe anyone); the button's post, or the mail client's one-click post, unsubscribes. Unsubscribing records a withdrawal of consent with how it was made.

## Campaigns [#campaigns]

Not in this version: an image block, A/B tests, sending at each recipient's own local time, and automated sequences (a welcome series, a drip). The preference centre has no language choice and offers no download or deletion of the subscriber's data: staff answer those requests by hand (`engine-dmo newsletter export` for a copy, `engine-dmo newsletter suppress` to stop all mail).

Campaigns are composed in the admin under Newsletter, Campaigns. A campaign belongs to one site and has a subject, a preheader, a key (the `utm_campaign` its links carry) and a list of blocks:

| Block | Holds |
|---|---|
| Text | Markdown, through the site's safe subset. |
| Button | A label and an address. |
| Latest documents | The newest published documents of a type (three by default, at most twenty). |
| Smart list | A public document smart list, as the site shows it. |
| Events coming up | Documents with a published, uncancelled occurrence in the next N days (seven by default). |
| One document | A document chosen by search. |

Live blocks read published content at the moment of the preview, the test or the send, through the public site's own reads, so a draft or a page the site does not show never reaches a campaign. A test send goes to the composer with "[Test]" before the subject.

### The template [#the-template]

A campaign renders as `emails/newsletter.html` along the site's template chain; the engine ships a default. It receives `campaign` and `subscriber.name` with the common mail context:

| `campaign` key | Meaning |
|---|---|
| `subject`, `preheader`, `key` | As composed. |
| `blocks` | In order, each with `kind` (`text`, `button`, `latest`, `list`, `events`, `document`), `title`, `html` for text, `label` and `url` for a button, and `entries` (each `title`, `summary`, `url`) for the live ones. Links are already tracked and carry the campaign's parameters. |
| `unsubscribeUrl` | Required: a message that does not link it is refused before anything is queued, and `engine-dmo check` refuses a template without it. |
| `preferencesUrl` | The preference centre. |
| `tracked` | True when links are counted, so the footer can say so. |

```jinja
{# templates/_shared/emails/newsletter.html #}
{% extends "emails/_layout.html" %}
{% block subject %}{{ campaign.subject }}{% endblock %}
{% block preheader %}{{ campaign.preheader }}{% endblock %}
{% block body %}
<h1>{{ campaign.subject }}</h1>
{% for b in campaign.blocks %}
  {% if b.title %}<h2>{{ b.title }}</h2>{% endif %}
  {% if b.kind == "text" %}{{ b.html }}
  {% elif b.kind == "button" %}<p><a class="button" href="{{ b.url|url }}">{{ b.label }}</a></p>
  {% else %}{% for e in b.entries %}<h3><a href="{{ e.url|url }}">{{ e.title }}</a></h3>{% if e.summary %}<p>{{ e.summary }}</p>{% endif %}{% endfor %}{% endif %}
{% endfor %}
{% endblock %}
{% block footer %}<a href="{{ campaign.preferencesUrl|url }}">Manage your preferences</a> or <a href="{{ campaign.unsubscribeUrl|url }}">unsubscribe</a>.{% endblock %}
```

### Audience [#audience]

A campaign's segment is its site's subscribers with any of its topics (or every one, with match all) whose frequency is one the campaign is for; no topics or frequencies is everyone. Frequency is a filter, not a timer: a monthly roundup is a campaign for `every`, `weekly` and `monthly`.

From the segment, pending, unsubscribed, withdrawn-consent, paused, bounced, complained and suppressed subscribers are left out when the recipients are taken. The composer counts the recipients and each reason. Each address receives a campaign once.

### Sending [#sending]

Sending needs `newsletter.send`, a ticked confirmation of the count and, while `newsletter.require_domain_verification` is true (the default), a sending domain the deliverability check has verified. A campaign can be sent now or scheduled (in the site's time zone), returned to draft, or cancelled. Recipients are queued at `newsletter.send_rate_per_minute`; a retry or a second server never sends anyone twice. A subscriber who unsubscribes after the send starts is skipped.

```bash
engine-dmo newsletter campaigns --site main --status draft
engine-dmo newsletter send --campaign <id> --confirm
```

### Tracking and the report [#tracking-and-the-report]

Every link to the site carries `utm_source=newsletter`, `utm_medium=email` and `utm_campaign=<key>`. With `click_tracking` (the default), links first pass through a first-party redirect at `/_n/c/<token>`, which counts the click and redirects to the address stored with the campaign, never one taken from the request. Opens are not tracked unless `open_tracking` is true, which adds a pixel at `/_n/o/<token>.gif`.

The report shows recipients, delivered, awaiting delivery, bounced, complaints, not sent, unsubscribed, clicks and clickers, clicks per link, who the audience left out, and, in the DMO bundle, the referrals the campaign sent to member businesses.

## Deliverability [#deliverability]

The admin's Newsletter, Deliverability screen and `engine-dmo newsletter deliverability` check each site's sending domain (the domain of the site's newsletter sender, else `newsletter.from_address`, else `mail.from`) and show what was found and the exact record to add:

| Check | Passes when |
|---|---|
| Sender | A sender is configured and the driver sends. |
| SPF | One `v=spf1` record carrying the provider's include (`spf.mtasv.net` for Postmark, `amazonses.com` for SES and Resend; Resend's on `send.<domain>`). |
| DKIM | A published key at `<selector>._domainkey.<domain>` for each of `dkim_selectors` (Resend's own `resend` selector when the list is empty and the driver is `resend`). |
| DMARC | A `v=DMARC1` record at `_dmarc.<domain>`. `p=none` passes with a warning. |

Passing every check verifies the domain; a later failure clears it, which blocks the next campaign. The screen also shows the newsletter's 30-day complaint rate and warns from 0.08 percent.

## Subscribers from the command line [#subscribers-from-the-command-line]

```bash
engine-dmo newsletter subscribers --site main --status active
engine-dmo newsletter subscribers --site main --dormant 12m
engine-dmo newsletter import --site main --file list.csv --basis consent --dry-run
engine-dmo newsletter export --site main --topics family --out family.csv
engine-dmo newsletter hygiene --site main --report
engine-dmo newsletter suppress --email someone@example.org --reason manual
```

| Command | What it does |
|---|---|
| `subscribers` | Lists a site's subscribers, by `--status` (`pending`, `active`, `unsubscribed`, `bounced`, `complained`, `suppressed`); `--dormant 12m` lists active ones with no click in that period. |
| `import` | Imports a CSV with an `email` column and optionally `name`, `locale`, `topics` and `consented_at`, under a declared `--basis` (`consent`, `legitimate_interest` or `contract`) recorded on every row. Never adds a suppressed address and leaves an existing one as it is. `--dry-run` counts each outcome. |
| `export` | Exports a site's subscribers, or with `--topics` a segment, as CSV. Audited with the row count. |
| `hygiene` | Active, dormant, never confirmed, unsubscribed and bounced counts. |
| `campaigns` | A site's campaigns, by `--status` (`draft`, `scheduled`, `sending`, `sent`, `cancelled`). |
| `send` | Sends a draft campaign now; needs `--confirm`. |
| `deliverability` | Runs the domain checks and records the results. |
| `suppress` | Suppresses an address on every channel, as `mail suppression add`. |

All need the database.

## Permissions [#permissions]

| Permission | Allows | Built-in roles |
|---|---|---|
| `newsletter.view` | Campaigns, reports, subscribers, deliverability | Administrator, Editor, Analyst |
| `newsletter.draft` | Create, compose, preview and test-send | Administrator, Editor |
| `newsletter.send` | Schedule, send and cancel | Administrator |
| `newsletter.manage` | Import, re-check the domain, preferences | Administrator |
| `newsletter.export` | Export, audited | Administrator |

## Configuration reference [#configuration-reference]

Every key is under `newsletter:` in `config/engine.yaml`.

| Key | Default | Meaning |
|---|---|---|
| `from_address` | `mail.from` | A bare address. Its domain is the one the deliverability check verifies. |
| `from_name` | the site's name | One line of plain text. |
| `reply_to` | `mail.reply_to` | A bare address. |
| `double_opt_in` | `true` | Cannot be false. |
| `pending_expiry` | `14d` | Unconfirmed subscribers are deleted after this; `1d` to `90d`. |
| `preference_centre_path` | `/newsletter/preferences` | Starts with `/`, not `/_`, no trailing slash. |
| `click_tracking` | `true` | Count clicks through the first-party redirect. |
| `open_tracking` | `false` | Add an open pixel. |
| `send_rate_per_minute` | `600` | 1 to 100000. |
| `dormant_after` | `12m` | An active subscriber with no click for this long is dormant; at least `30d`. |
| `require_domain_verification` | `true` | A campaign is refused until its sending domain passes the checks. |
| `topics` | `[]` | The topic keys subscribers may choose; lowercase keys, each once. |
| `dkim_selectors` | `[]` | The DKIM selectors your provider gave you. |

A site's `mail.newsletter` block in `site.yaml` (`from_address`, `from_name`, `reply_to`, `dkim_selectors`) replaces these for that site's campaigns, and its `mail.from` is used before the install's `from_address`.


# Redirects and URLs (/features/redirects-and-urls)

How addresses stay stable: slugs, the automatic redirects on a slug change, trash or move, redirect and 410 rules in routes.yaml, importing a CSV of redirects from an old site, the order rules are matched in, and how missing pages are recorded.

A page's address comes from its route's pattern and its fields, usually a `slug`. When an address changes, the engine keeps the old one working with a redirect it creates itself. For a site migration you import the old site's addresses from a CSV, and for structural rules you write redirects in `routes.yaml`. Every path that finds nothing is counted, per site and locale.

| Redirects come from | How you add them |
|---|---|
| The engine, when an address changes | Automatically; see below |
| `redirects:` in `routes.yaml` | By hand, under version control |
| A CSV import | `engine-dmo redirects import` |

There is no admin screen or command to add a single redirect by hand (the `managed` origin below is reserved for one), and no screen or command reads the missing-page counts yet. Put a one-off redirect in `routes.yaml`, or import a one-row CSV.

## Slugs [#slugs]

A `slug` field is a URL segment per locale, generated from another field and transliterated to ASCII:

```yaml
fields:
  - name: title
    type: text
    required: true
  - name: slug
    type: slug
    source: title       # the field the slug is generated from
    max: 80
```

A route's `uri` pattern uses it: `uri: "/whats-on/{slug}"`. Routes, nesting and locale prefixes are covered in [Sites, locales and routes](/concepts/sites-locales-and-routes); the field in [Field types](/content-modelling/fields).

## Automatic redirects [#automatic-redirects]

| When | What the engine does | Origin |
|---|---|---|
| A published locale's address changes (a new slug, a new parent) | A permanent redirect (301) from the old path to the document, per locale. It follows the document, so a later rename does not break it. A rule from the new path left by an earlier rename is disabled. | `auto_slug` |
| A page moves in a hierarchy, or a route's `parent` or pattern changes | A 301 from each descendant's old path. | `auto_route` |
| A live document is trashed | A redirect from each released path to the choice made when trashing: the type's index page (`parent`), a path, or `none` with a reason. It is a 302 while the document can still be restored, upgraded to 301 when it is purged. | `auto_trash` |
| A live locale is unpublished with a destination | A 302 to the destination; publishing the locale again disables it. | `auto_unpublish` |
| A path with capital letters finds nothing, and its lower-case form is a page or a rule | A 301 to the lower-case path, keeping the query string. | `auto_case` |
| A path finds nothing but has live pages beneath it | A 301 to the nearest ancestor path that is a page, keeping the query string. | `auto_segment` |

The last two are decided at request time and never stored as rules.

Declining a slug redirect needs a reason, which is audited:

```bash
engine-dmo content publish --id <document-id> --locale en --no-redirect "the old address was never public"
engine-dmo content trash --id <document-id> --redirect parent
engine-dmo content trash --id <document-id> --redirect /whats-on
engine-dmo content trash --id <document-id> --redirect none
```

`content trash` requires `--redirect` when any locale of the document is live. The admin's trash action asks for the same choice.

Unpublishing with a destination (`auto_unpublish`) is offered only by the content MCP's unpublish tool ([content MCP](/integrating/content-mcp)). The admin's unpublish asks for no destination and there is no `content unpublish` command, so an unpublished page otherwise answers 404 at its old address. To send its visitors somewhere, add a rule for the old path in `routes.yaml`.

A rule that points at a document resolves the document's current address when it is matched, and is skipped while the document has none. When the document is purged, the rule becomes a 410 for its path.

## Rules in routes.yaml [#rules-in-routesyaml]

Structural rules that belong to the project go in the site's `routes.yaml`, under version control:

```yaml
# config/sites/<site>/routes.yaml
redirects:
  - { from: /visit-us, to: /visit }                              # exact, 301
  - { from: /whats-on/, to: "/events/{1}" }                       # prefix: the rest of the path is {1}
  - { from: "/news/*/amp", to: "/news/{1}", status: 308 }         # wildcard: each * is {1}, {2}, ...
  - { from: /old-shop, to: "https://shop.example.org/", status: 302 }
  - { from: "/cgi-bin/*", status: 410 }                           # gone: no target
  - { from: /welcome-old, to: /welcome, locale: en }             # only for this locale
```

| Key | Meaning |
|---|---|
| `from` | The path. Containing `*`: a wildcard, each `*` matching any run of characters. Ending in `/`: a prefix, matching the path and everything beneath it. Otherwise exact. |
| `to` | The target: a path on the site, an absolute URL, or a template with `{1}`, `{2}` for the captures. Quote a value containing braces. Required unless `status` is 410. |
| `status` | `301` (default), `302`, `307`, `308` or `410`. A 410 has no `to`. |
| `locale` | Apply only to paths in this locale. Without it, every locale. |

`engine-dmo check` reports, at the rule's line:

- a rule with no `from`, or no `to` when it is not a 410;
- a 410 with a `to`;
- a status outside the five;
- a **loop** (an error): `redirect loop: /a -> /b -> /a`;
- a **chain** of more than one hop (a warning): `redirect chain: /c -> /visit-us -> /visit`, with the hint to point the first rule at the last target;
- an internal target no route, index, special page, home page, endpoint or other rule of the site answers, in a locale the rule applies to: `redirect target /nowhere resolves to nothing on site main in en`. A target built from captures and an external address are not checked.

## Matching [#matching]

Redirects are consulted only when a path finds nothing else: a published document, a type's index page, a module's page, a public file. A real page at a path always wins over a rule for it. This is the order for a `GET`:

```mermaid
flowchart TD
  req["GET /path"] --> ep{"endpoint, feed or<br/>module path?"}
  ep -->|yes| engine["The engine answers"]
  ep -->|no| doc{"document, index or<br/>landing page?"}
  doc -->|yes| page["Render the page"]
  doc -->|no| file{"file in public/?"}
  file -->|yes| static["Serve the file"]
  file -->|no| rule{"redirect or 410 rule,<br/>or a case or segment fix?"}
  rule -->|yes| redirect["301, 302, 307, 308 or 410"]
  rule -->|no| miss["Count the miss"]
  miss --> notfound["404 with errors/404.html"]
```

Paths are matched with their trailing slash removed. Exact rules are matched first, a locale-specific rule before an all-locale one. Then prefix and wildcard rules, the longest literal prefix first. (Regular-expression rules cannot be written in `routes.yaml` or imported.) Between rules for the same path, the origin decides:

1. `config` (from `routes.yaml`)
2. `managed`
3. `imported`
4. `auto_slug`
5. `auto_route`
6. `auto_trash` and `auto_unpublish`

The visitor's query string is carried over to the target. A 410 answers with status 410. A matched rule's hit count and last hit time are recorded.

## Importing redirects from an old site [#importing-redirects-from-an-old-site]

On migration day, import the old site's addresses as exact rules from a CSV:

```csv
source,target,status,locale,note
/attractions/broughton-castle,/places/broughton-castle,301,,old CMS
/whats-on/2025,/whats-on,301,,
/accommodation,document:0b8f3c2e-5a61-4c39-9d1e-2f7a1b9c4d10,301,en,follows the page
/wp-content/uploads/map.pdf,,410,,never coming back
```

```bash
engine-dmo redirects import --site main --file redirects.csv --dry-run
engine-dmo redirects import --site main --file redirects.csv
engine-dmo redirects list --site main --origin imported
engine-dmo redirects rollback --site main --batch <batch-id>
```

The header row names `source` and `target`, and optionally `status`, `locale` and `note`; other columns are ignored. A target is a path on the site, an absolute URL, `document:<uuid>` (the rule follows the document if its address changes), or empty with status 410.

Every row is checked: the source and status, the locale, a duplicate in the file or in the table, the target (a document that exists, a path the site answers) and loops and chains through every rule the site has. Any error refuses the whole import unless `--skip-invalid`, which imports the valid rows. The import is one transaction and prints a batch id; `redirects rollback --batch` disables every rule that import wrote, audited.

| Command | Flags |
|---|---|
| `redirects import` | `--file`, `--site`, `--dry-run` (check every row, write nothing), `--skip-invalid` |
| `redirects list` | `--site`, `--origin` (`config`, `managed`, `imported`, `auto_slug`, `auto_route`, `auto_trash`, `auto_unpublish`): the table's rules, newest first |
| `redirects rollback` | `--batch`, `--site` |

All need the database.

## Missing pages [#missing-pages]

Every request that ends in a 404 is counted per site, path and locale: first seen, last seen, hits, and hits from known bots counted apart. Paths that look like probes (`/.env`, `/wp-admin`, `.php` and the like) are marked as scanners; paths longer than 512 bytes are not recorded. No visitor identity is stored. A headless site's misses are recorded through the content API's resolve operation in the same way. `engine-dmo render` does not count its misses.

The counts are kept for a report, but no admin screen or command reads them in this version. Until one does, use your web server's or CDN's logs to find the old addresses that need a rule.

## Headless sites [#headless-sites]

The content API serves a site's complete, ordered rule list for a frontend or an edge function to apply, and resolves a path to a page, a redirect, a 410 or a miss. See the [content API](/integrating/content-api).


# Search (/features/search)

How to give a site a search page, connect Meilisearch, Elasticsearch or OpenSearch, what is indexed, the search.html template and search() function, browse mode without a backend, synonyms and the zero-result report.

Meridian's search is two halves. The engine owns the query, the locale, what a visitor may see, the query log, zero-result detection, click tracking and the results a template reads. Retrieval is always an external service you run: Meilisearch, Elasticsearch or OpenSearch. With no service configured, the same search page answers in **browse mode**: results filtered from the published content in the database, not ranked by relevance.

## Add a search page [#add-a-search-page]

<Steps>
<Step>
Declare the search route in the site's `routes.yaml`:

```yaml
# config/sites/<site>/routes.yaml
special:
  search: "/search"
```

The path may differ per locale: `search: { en: /search, cy: /chwilio }`.
</Step>
<Step>
Write `search.html` in one of the site's template roots (`templates/<site>/` or `templates/_shared/`). `engine-dmo check` refuses a site that routes search without one.

```jinja
{% extends "base.html" %}
{% block body %}
<h1>Search</h1>
<form method="get" action="{{ request.path|url }}" role="search">
  <label for="q">What are you looking for?</label>
  <input id="q" type="search" name="q" value="{{ results.query }}">
  <button type="submit">Search</button>
</form>
{% if results.degraded %}<p role="status">Search is in browse mode: results are filtered, not ranked.</p>{% endif %}
{% if results.facets.type %}
<nav aria-label="Filter by type"><ul>
  {% for f in results.facets.type %}<li><a href="{{ request.path|url }}?q={{ results.query|urlencode }}&amp;type={{ f.value|urlencode }}">{{ f.label|default:f.value }} ({{ f.count }})</a></li>{% endfor %}
</ul></nav>
{% endif %}
{% if results.items %}
<p>{{ results.total }} results</p>
<ol>
  {% for item in results.items %}
  <li>
    <h2><a href="{{ item.clickUrl|default:item.uri|url }}">{{ item.title|default:item.uri }}</a></h2>
    {% if item.image %}{{ item.image.img("thumb") }}{% if item.image.credit %}<small>{{ item.image.credit }}</small>{% endif %}{% endif %}
    {% if item.highlight %}<p>{{ item.highlight }}</p>{% elif item.summary %}<p>{{ item.summary }}</p>{% endif %}
  </li>
  {% endfor %}
</ol>
{% if results.pagination.next %}<a rel="next" href="{{ results.pagination.next|url }}">Next page</a>{% endif %}
{% elif results.query %}
<p>Nothing matched that. Try a shorter phrase.</p>
{% endif %}
{% endblock %}
```
</Step>
<Step>
Put a search box on every page with `searchForm()`, which prints a GET form to the site's search route (and nothing when the site routes no search):

```jinja
<header>{{ searchForm() }}</header>
```
</Step>
<Step>
Run `engine-dmo check`. Without a backend it warns that the route serves browse mode only. That is a working search page; add a backend when ranking matters.
</Step>
</Steps>

The page is a plain GET form, so it works without JavaScript and every result page has a shareable address. Search pages are never cached, because each search is logged.

## Connect a backend [#connect-a-backend]

```yaml
# config/engine.yaml
search:
  driver: meilisearch
  meilisearch:
    url: ${MEILISEARCH_URL}
    api_key: ${MEILISEARCH_API_KEY}     # a secret; set it empty for a server with no key
    index_prefix: riverside
```

```yaml
# Elasticsearch, or OpenSearch with driver: opensearch and an opensearch: block
search:
  driver: elasticsearch
  elasticsearch:
    addresses: ["${ES_ADDRESS}"]        # only the first entry is used
    username: ${ES_USERNAME:-}
    password: ${ES_PASSWORD}
    index_prefix: riverside
```

Elasticsearch and OpenSearch authenticate with a username and password (HTTP basic authentication); an API key is not used by these drivers. `addresses` is a list, but the drivers send every request to its first entry only: point that entry at a load balancer or a coordinating node when the cluster has several.

Then build the index:

```bash
engine-dmo search status          # the backend, its health, what is indexed
engine-dmo search rebuild         # index everything published
engine-dmo search test "harbour walk" --site main
```

The engine creates one index per site and locale, named from `index_prefix`, with analysis for the locale's language. Meilisearch needs `url`; Elasticsearch and OpenSearch need at least one entry in `addresses`. `engine-dmo search capabilities` lists what the configured backend supports.

## What is indexed [#what-is-indexed]

Every document that is published on a site in a locale and has an address there is indexed in that site and locale's index. A type that is not on a site never reaches its index. There is no per-type switch: a type's `searchable` key is accepted and has no effect, so to keep a type out of search, give it no route on that site. Each entry holds:

| Part | Source |
|---|---|
| Title | The document's `title` field (a site's override applied), read from the indexed projection. A type without a `title` field, such as a singleton declared without one, gives an empty title. |
| Summary | The document's `summary` field, read from the indexed projection: a `summary` your project declares is empty here unless it has `index: true` (the core types' `summary` is indexed). |
| Body | The searchable text of every field, as each field type defines it, walked into repeaters and blocks, up to 20,000 characters. A link's address, an image's asset, a relation's id and container keys are never indexed. |
| Address | The document's path on the site. |
| Type and tags | For filters and facets. |
| Location | The point in the `geo` field keyed `location` (the DMO listing's field), with `index: true`, for distance search. A point in a field with another key is not used. |
| Organisation | The organisation the document belongs to (DMO bundle). |
| Card fields | Fields declared `index: true` holding a short string (up to 200 characters), a number, a boolean or a list of up to 20 short strings, returned as `item.fields`. |
| Image | The field the type's structured data maps as `image`, else its first `asset` field, returned as `item.image`. |

Indexing never holds up a publish. Publishing, unpublishing, trashing, restoring, sharing and unsharing each queue an index job for the document, and the index catches up within seconds. Hits that are no longer published are dropped from results even if the index has not caught up yet. A nightly sweep compares each index with what is published, by id and content digest, and repairs any drift; `engine-dmo search verify` runs the same comparison on demand.

## The search route [#the-search-route]

The search route reads these query parameters:

| Parameter | Meaning |
|---|---|
| `q` | The words searched for. |
| `type` | A type key to filter by; repeat for several. |
| `tag` | A tag key to filter by; repeat for several. |
| `sort` | `relevance` (the default with words), `name`, `distance` or `recent`. |
| `page` | The page, from 1. Twenty results a page. |
| `lat`, `lon` | A point to search near. |
| `km` | The radius around `lat` and `lon`, default 10. |

A query shorter than `search.min_query_length` (2 by default, counted in characters as a reader sees them) is not sent to the backend and not logged: the page lists published documents in browse mode, which is what a search page with no `q` shows.

### `results` [#results]

`search.html` receives `results`:

| Key | Meaning |
|---|---|
| `query` | The words searched for. |
| `items` | The hits on this page. |
| `total` | How many hits in all. |
| `facets` | Counts by `type` and by `tags`, each a list of `value`, `count` and `label`. `label` is empty for search facets, so print `value` or map it to your own words. |
| `degraded` | True when the answer came from browse mode because the backend is not configured or not answering. Say so on the page. |
| `backend` | `meilisearch`, `elasticsearch`, `opensearch`, or `none`. |
| `sort` | The sort asked for. |
| `page`, `pages`, `hasMore` | Where this page is. |
| `pagination` | `page`, `pages`, `total`, `per`, `next` and `prev` (addresses, empty at the ends) and `range` (the page numbers). Also available as `pagination`. |
| `didYouMean` | Always empty: no backend offers a correction yet. |

Each item in `results.items`:

| Key | Meaning |
|---|---|
| `id`, `type` | The document's id and type key. |
| `title`, `summary` | As indexed. |
| `uri`, `url` | The path on the site, and the absolute address. |
| `clickUrl` | A first-party address that records which result position was chosen and then redirects to the result. Link to it when present to feed the click report; it is absent in browse mode. |
| `highlight` | The matched passage with the words marked, when the backend highlights. Safe HTML. |
| `tags` | Tag keys. |
| `fields` | The card fields described above. |
| `image` | The result's main image as an image value: `item.image.img("thumb")`. |
| `distance` | Kilometres from the point searched near, when there was one. |
| `position` | The result's position across all pages, from 1. |

### `search()` in any template [#search-in-any-template]

The `search()` function runs the same service from any page: a "nearby" panel, a type's own search, a results block on a landing page. It is a chain, run by `.paginate(n)` (reads the page from the request's `page` parameter) or `.limit(n)` (the first n):

```jinja
{% set found = search(request.query.q).types(["event", "article"]).facets(["type"]).paginate(12) %}
{% if found.degraded %}<p role="status">Showing filtered results.</p>{% endif %}
{% for item in found.items %}<a href="{{ item.uri|url }}">{{ item.title }}</a>{% endfor %}
```

| Method | Meaning |
|---|---|
| `search(q)` | Start a search for the words `q` (may be empty: browse). |
| `.types(list)` | Only these type keys. |
| `.tags(list)` | Only documents with these tags. |
| `.near(point, km)` | Within `km` (default 10) of anything with `lat` and `lon`, such as a `geo` field. With no words, nearest first. |
| `.sort(order)` | `relevance`, `name`, `distance` or `recent`. |
| `.facets(list)` | Only these facets in `facets`. |
| `.paginate(n)` | Run it, `n` a page (default 20, at most 100). |
| `.limit(n)` | Run it, the first `n` (default 20, at most 100). |

It returns the same object as `results`.

## Browse mode [#browse-mode]

Browse mode answers a search from the published projection in the database, through the same filter machinery as a type's index page: type, tags and distance filters work, facet counts are computed, and results are ordered by the requested sort rather than by relevance.

It is used when:

- `search.driver` is `none` (the default);
- the query is shorter than `min_query_length`;
- the backend fails, or has failed `circuit_breaker.failures` times within `circuit_breaker.window` and is resting for `circuit_breaker.cooldown`, while `degraded_mode` is `browse`.

This is the path one request takes:

```mermaid
flowchart TD
  q["GET /search?q=..."] --> short{"q shorter than<br/>min_query_length?"}
  short -->|yes| browse0["Browse mode<br/>not logged, degraded false"]
  short -->|no| log["Log the query"]
  log --> backend{"Backend configured<br/>and breaker closed?"}
  backend -->|yes| ask["Ask the backend"]
  ask -->|answers| live["Drop hits no longer published"]
  live --> ranked["Ranked results<br/>degraded false"]
  ask -->|fails| mode{"degraded_mode"}
  backend -->|no| mode
  mode -->|browse| browse1["Browse mode<br/>degraded true"]
  mode -->|error| err["The site's error page"]
```

`results.degraded` is true whenever words were searched and no backend answered, including with `driver: none`; a short or empty query is browse mode with `degraded` false, because nothing was asked. With `degraded_mode: error`, a failed backend answers the page with the site's error page instead.

### What browse mode does not do [#what-browse-mode-does-not-do]

Browse mode is a filter, not a search. Write `search.html` for it as well as for a backend, because a site without one serves it for every query:

- **The words are not matched.** `q` is logged and echoed in `results.query`, but every published document that passes the type, tag and distance filters is listed, in the requested sort (by title when none is given). Say so on the page when `results.degraded` is true.
- **No `highlight` and no `clickUrl`.** Link to `item.clickUrl|default:item.uri`.
- **Empty titles and summaries show.** As with a backend (see [What is indexed](#what-is-indexed)), an unindexed `summary` and a type with no `title` give empty values, and browse mode lists such documents even though no words matched them. Print `item.title|default:item.uri` so every link has a name.
- **Facet labels are empty**, as they are with a backend: print `f.label|default:f.value`, or map the value to your own interface string.

Distance filters read the same `location` field in both modes, and result images and card fields (`item.image`, `item.fields`) are filled the same way.

## Synonyms [#synonyms]

Synonyms are rules held in the database and pushed to each index's settings; changing them reindexes nothing. A rule without `from` makes every term find every other; with `from`, a search for `from` also finds each term and not the reverse.

```yaml
# config/search/synonyms.yaml: a seed, loaded once
synonyms:
  - { locale: en, terms: [gig, concert, performance] }
  - { locale: en, from: kids, terms: [family, children] }
  - { locale: en, sites: [main], terms: [beach, seafront, shore] }
```

`engine-dmo seed apply` and `engine-dmo search synonyms import` load the file; rules already held are left alone. After that, the admin's Search synonyms screen owns them (`search.synonyms`). `engine-dmo search synonyms list` prints what the database holds. A rule without `sites` applies on every site that enables its locale. `engine-dmo check` warns when the file exists and no backend is configured.

## The query log and zero results [#the-query-log-and-zero-results]

Every search of at least `min_query_length` is logged before the backend is asked: the words as typed, a folded form for grouping (so "Café", "CAFE" and "cafe" are one row), the backend, the result count and whether it was degraded. No visitor identity is stored. Searches made by `engine-dmo render` and the warm job are not logged.

```bash
engine-dmo search zero-results --site main --since 30d --limit 50
```

The admin's Insight search screen (`analytics.view`) shows the commonest searches, the zero-result searches, and the click-through and average position from `clickUrl`. Degraded searches are left out of the zero-result report. The log is kept for `analytics.search_log_retention_days` (400 by default). `search.log_queries` cannot be false in production.

## Running the index [#running-the-index]

| Command | What it does |
|---|---|
| `search status` | The backend, its health and what each index holds. |
| `search capabilities` | What the configured backend supports. |
| `search rebuild` | Reindexes what is published, then deletes what is indexed and no longer published. Resumable: a rebuild that stopped resumes unless `--fresh`. `--site` limits it to one site. Recorded where the admin's Search index screen shows it. |
| `search verify` (alias `check`) | Compares each index with what is published and reports drift. |
| `search test <query>` | Runs a query (`--site`, `--locale`) and shows what came back. |
| `search synonyms import`, `list` | The synonym seed and the rules held. |
| `search zero-results` | What visitors searched for and did not find (`--site`, `--since`, `--limit`). |

`engine-dmo content reindex` queues an index job for every published document, or one type's. `engine-dmo warm` repairs the index after a deploy. All of these need the database.

The admin's Search index screen (`search.view`) shows each index's count against what is published, the last rebuild and check, and offers rebuild (`search.rebuild`) and purge (`search.purge`).

## Configuration reference [#configuration-reference]

Every key is under `search:` in `config/engine.yaml`.

| Key | Default | Meaning |
|---|---|---|
| `driver` | `none` | `meilisearch`, `elasticsearch`, `opensearch` or `none`. |
| `log_queries` | `true` | Log every search. Cannot be false in production. |
| `min_query_length` | `2` | Shorter queries are browse, not retrieval, and are not logged. |
| `degraded_mode` | `browse` | `browse` or `error`: what a failed backend does to the page. |
| `circuit_breaker.failures` | `5` | Failures within the window that open the breaker. |
| `circuit_breaker.window` | `30s` | |
| `circuit_breaker.cooldown` | `1m` | How long the breaker stays open, answering in browse mode without asking the backend. |
| `runs_kept` | `20` | Finished rebuild, purge and check runs kept per site and kind, 1 to 1000. |
| `meilisearch.url` | | Required with `driver: meilisearch`. |
| `meilisearch.api_key` | | A secret. |
| `meilisearch.index_prefix` | `meridian` | Prefix of every index name. |
| `meilisearch.timeout` | `2s` | Per request. |
| `elasticsearch.addresses` | | Required with `driver: elasticsearch`. Only the first URL is used. |
| `elasticsearch.username`, `password` | | HTTP basic authentication. `password` is a secret. |
| `elasticsearch.index_prefix` | `meridian` | |
| `elasticsearch.timeout` | `3s` | |
| `opensearch.*` | as `elasticsearch` | Used with `driver: opensearch`. When `opensearch.addresses` is empty, the `elasticsearch` block is used instead. |

Each backend block also accepts `url`, `addresses`, `api_key`, `username` and `password`, but each driver reads only the keys above: Meilisearch reads `url`, `api_key`, `index_prefix` and `timeout`; Elasticsearch and OpenSearch read `addresses`, `username`, `password`, `index_prefix` and `timeout`, and authenticate with basic authentication only.

## Headless sites [#headless-sites]

A headless frontend searches through the [content API](/integrating/content-api), which answers from the same service, log and browse fallback.


# The development loop (/getting-started/development-loop)

The commands for day-to-day work on a Meridian project (dev up, serve --dev, the dev authoring verbs, check, schema plan and apply, migrate, seed, describe, render, template tests, guide and docs serve), what each needs and what it exits with.

Working on a project is a short loop: change a file, let the engine check and apply it, look at the page, repeat. This page lists the commands in that loop, what each needs, and how to read what it prints.

## Run the site while you work [#run-the-site-while-you-work]

<Tabs items={["dev up (recommended)", "serve --dev"]}>
<Tab value="dev up (recommended)">

```bash
engine-dmo dev up
```

`dev up` runs the server in development mode and watches `config/`. On every change it:

1. writes an id for every element that has none (as `engine-dmo check --fix` does);
2. loads and checks the whole project;
3. computes the schema plan against the database;
4. applies the plan if it is not destructive;
5. reloads the engine in the same process.

```mermaid
flowchart TD
  save["You save a file in config/"] --> ids["Write missing ids"]
  ids --> check{"Project checks?"}
  check -- no --> keep["Keep serving the last good configuration<br/>and print the errors"]
  check -- yes --> plan{"Schema plan destructive?"}
  plan -- yes --> hold["Keep serving; print the plan<br/>for you to approve and apply"]
  plan -- no --> apply["Apply the plan"]
  apply --> reload["Reload the engine"]
```

A failed check or a destructive plan leaves the engine running on the last good configuration and prints why. A destructive change (removing a field that holds values, for example) is yours to apply by hand with `engine-dmo schema apply`; see [Destructive changes](#destructive-changes).

`engine-dmo dev status` prints what `dev up` last found: the check, the plan, live field aliases, the address it serves on, and images the sizing check found oversized. `--json` gives the same as JSON, which is how an agent reads it. It reads `.meridian/dev-status.json`, and says so when `dev up` has not run in the project.

| Flag | Effect |
|---|---|
| `--listen <addr>` | Serve on this address instead of `server.listen` |

</Tab>
<Tab value="serve --dev">

```bash
engine-dmo serve --dev
```

The server in development mode, without the automatic plan and apply. It refuses to start while migrations are pending or the configuration differs from the database (unless `schema.on_drift` says otherwise), so run `engine-dmo schema apply` after each configuration change.

</Tab>
</Tabs>

Development mode, in both:

- reparses a template on every request, so a template change shows on reload;
- shows the development error page, with the template, line and context of a failure;
- starts each extension's development server as a child process (the `vite` extension runs Vite);
- watches the configuration;
- serves Go's profiler at `/_debug/pprof/`.

The admin is at `/studio`, the public sites at their configured domains (`localhost` answers for the default site).

## Change configuration with the dev verbs [#change-configuration-with-the-dev-verbs]

You can edit the YAML by hand, but the `engine-dmo dev` verbs are safer: each edits the files keeping their comments, writes the new element's id, and checks the configuration it changed. A change that would make the configuration invalid (an unknown field type, an unknown option) is refused with `nothing was written` and exit 3. With `dev up` running, the change is applied as soon as the verb writes it.

A verb does not count templates, so it can exit 0 and leave `check` failing:

- `dev route add` writes the route even though the type has no `entry.html` (or no `index.html` for `--index`) yet.
- `dev endpoint add` writes the endpoint; the recipe's partials and mail templates are yours to write, and it says so.

Run `engine-dmo check --no-db` after every verb.

```bash
engine-dmo dev type add walk --label Walk --plural Walks
engine-dmo dev field add walk distance --type number --label Distance
engine-dmo dev route add walk "/walks/{slug}" --index /walks --scaffold
engine-dmo new template walk/index.html
engine-dmo dev field rename walk distance lengthKm
```

`--scaffold` writes the type's `entry.html` from its fields. It does not write `index.html`: a route with an index also needs `<type>/index.html`, which `engine-dmo new template walk/index.html` starts for you, and `check` refuses the route until it exists. The scaffolded index is an empty `body` block with no heading, so fill it in before you check a page's accessibility.

<Callout type="warn" title="--scaffold needs the configuration to load">
`--scaffold` and `new template` load the whole configuration, so every `${VAR}` without a default must be set (a placeholder `DATABASE_URL` is enough). When one is not, `dev route add --scaffold` has already written `routes.yaml` before it fails with exit 3, and running it again prints `nothing to change` without writing the template. Set the variable and run `engine-dmo new template <type>/entry.html` to finish.
</Callout>

Every verb takes `--dry-run`, which prints the diff of every file it would change and writes nothing, and `--apply`, which applies the schema plan afterwards when it is not destructive (use it when `dev up` is not running).

| Verb | Does |
|---|---|
| `dev type add <key>` | Add a custom type with a title, a slug and a summary (`--label`, `--plural`, `--site` for one site's own type, `--sites` to limit a shared type) |
| `dev field add <type> <name>` | Add a field (`--type`, `--label`, `--required`, `--index`, `--translate`, `--options`, `--param key=value`, `--group`, `--after`, `--site`) |
| `dev field set <type> <name>` | Change a field's label, help text or a parameter |
| `dev field rename <type> <old> <new>` | Rename a field: the id and every stored value stay, and the old handle keeps answering as an alias (`--no-alias` to drop it) |
| `dev field remove <type> <name>` | Remove a field; its values stay stored under its id |
| `dev group add <type> <key>` | Add a group to a type's editor layout |
| `dev option add <type> <field> <value>` | Add an option to a select field, or a style to a link field |
| `dev route add <type> <uri>` | Route a type on a site (`--index`, `--site`, `--scaffold` to write its template) |
| `dev site add <key>` | Add a site with its `site.yaml` and `routes.yaml` (`--name`, `--domain`, `--locales`, `--network`) |
| `dev site rename <old> <new>` | Rename a site: its directory moves, its id and data stay |
| `dev locale add <code>` | Declare a locale and enable it on a site |
| `dev config set <file> <path> <value>` | Set one value in a configuration file, such as `dev config set engine.yaml search.driver meilisearch` |
| `dev config unset <file> <path>` | Remove one key |
| `dev endpoint add <key>` | Add a declared endpoint from a recipe (`recipe:enquiry`, `recipe:newsletter`) |
| `dev network add <key>` | Declare a network of sites |
| `dev source rename`, `dev importer rename`, `dev webhook rename` | Rename an outbound declaration, keeping what is stored under its id |

`engine-dmo` adds `dev tier`, `dev role`, `dev portal` and `dev slot` for the DMO modules. `engine-dmo help --json` lists every verb with its arguments and flags. When a project has `AGENTS.md` or the agent skills, the verbs regenerate them after each change.

## Check the project [#check-the-project]

```bash
engine-dmo check
```

`check` is the gate to run before every commit and in CI. It validates every configuration file, the schema, every template and the deployment settings, and prints every problem at once (`seed verify` checks the seed):

```text
config/sites/main/routes.yaml:2:11: route "page" has no id
    2 |   - type: page
      |           ^^^^
      = run engine-dmo check --fix to write one; ids are written by the tooling, never by hand
      = error code MRD-1006

1 error, 0 warnings. Configuration is not valid.
```

`check` prints template findings first, one line each (`_shared/base.html:3:1: warning: ...`), then every diagnostic in full with its source line. An error can therefore appear twice, once in each form.

<Callout type="warn" title="Read every line, not the summary">
The summary counts configuration errors and warnings only. Template warnings, such as a layout with no `head()` or a `t()` key missing from the string catalogue, are printed above it and not counted: a project with template warnings still ends `0 errors, 0 warnings` and exits 0, even with `--strict`.
</Callout>

| Flag | Effect |
|---|---|
| `--no-db` | Skip the checks that need a database. Secrets need not be set, so a CI job or an image build can run it; a secret that is set is still checked (a `SIGNING_KEY` shorter than 32 characters fails) |
| `--fix` | Write an id for every element without one, keeping comments, then check |
| `--strict` | Treat the counted warnings as errors. Template warnings are not counted and do not fail it |
| `--contract-report` | List template usage the next template contract version removes, with the replacement for each |

| Exit code | Meaning |
|---|---|
| `0` | Valid; warnings may have been printed |
| `3` | The configuration is not valid |
| `1` | The check could not run (for example, the database could not be reached), or the command line was wrong: an unknown command or flag exits 1, although `help --json` lists exit 3 for a bad invocation |

Every error carries an error code (`MRD-1006` above); [Error codes](/reference/error-codes) explains each.

`engine-dmo config validate` checks only the configuration files, and `engine-dmo config render` prints the configuration as the engine resolved it, every default filled in and secrets redacted.

## Plan and apply schema changes [#plan-and-apply-schema-changes]

The database holds a copy of your schema: types, fields, locales, sites, routes, roles and grants, each by its id. `schema plan` compares the files with it; `schema apply` makes the database match.

```bash
engine-dmo schema plan
engine-dmo schema apply
```

`schema plan` is read-only and exits 2 when changes are pending, 0 when there are none. Each line is one change:

| Mark | Change |
|---|---|
| `+` | Add |
| `~` | Change |
| `-` | Remove |
| `>` | Rename: same id, new handle. Every stored value is kept |
| `=` | Bind: a stored element made before ids takes the id its file gives it |
| `!` | Replace: the file gives an existing handle a new id, usually a copied block |

A change marked `[DESTRUCTIVE: ...]` loses data or access: a removed field that documents hold values in, or a grant whose removal takes a permission from active users. `schema apply` runs the whole plan in one transaction and refuses a destructive plan unless it is approved.

### Destructive changes [#destructive-changes]

Approve a destructive plan in one of two ways:

- **An approval file.** The plan prints its digest; write it to `config/schema/.destructive-approved` (or the path `schema.destructive_approval` names) and run `engine-dmo schema apply`. A different plan has a different digest, so the approval covers exactly the plan you reviewed.
- **Interactively.** `engine-dmo schema apply --allow-destructive` shows the plan and asks you to confirm; add `--yes` where no terminal can ask.

A removed field's values are not deleted: they stay in each document's revisions, kept under `_orphaned` with the field's id, and nothing is dropped silently.

### Replacements [#replacements]

A `!` line means an element in the files has a new id but an old handle. That is almost always a copied block whose id came with it. Put the stored id back in the file to keep the stored element, or, when you really mean a new element, apply with `--replace <type>.<field>` for each one named.

### Refusals [#refusals]

`schema apply` refuses a plan that would leave nobody able to manage users or holding the `owner` role, even with `--allow-destructive`. A plan line under `NOT YET` is a change this engine version cannot apply; undo it in the files to apply the rest.

## Migrations [#migrations]

```bash
engine-dmo migrate status   # exits 2 if any are pending
engine-dmo migrate up
```

Migrations create and change the engine's own tables. They only move forward, and they are separate from your schema: a new engine version brings migrations, your configuration brings schema changes. The server refuses to start while a migration is pending. See [Upgrading the engine](/getting-started/upgrading-the-engine).

## Seed and reset content [#seed-and-reset-content]

| Command | Does | Needs |
|---|---|---|
| `seed verify` | Check the seed loads and matches the schema: known types, fields and locales | Configuration |
| `seed list` | List the seed sets and what each contains | Nothing |
| `seed apply` | Load the seed through the same validation and history as an editor | An applied schema and an empty database |
| `seed reset --confirm` | Remove all content, media and analytics; keep users and configuration. Never runs in production | A database |
| `seed generate --type <key> --count 20` | Create documents whose values pass every field's validation, from word lists and placeholder images (`--publish`, `--locale`, `--site`, `--near lat,lng`, `--seed`) | A database |
| `seed write` | Write the seed's generated records from `seed/generate.yaml`; `--check` reports how the files differ | Configuration |

`seed verify` does not validate values: a select value that is not an option, or a number below its `min`, passes it and fails only in `seed apply`. Its errors name the file but not the line, and a problem in a field is reported once per locale.

`seed apply` refuses a database that already holds documents or media, since seeding would duplicate them: run `seed reset --confirm` first. Its flags are `--set <dir>` (another seed set under `seed/`), `--profile <name>` (a profile from `seed.yaml`; the help text's mention of `make check` refers to the engine's own test suite, not your project), `--scale small|medium|large` (the volume of generated analytics) and `--timeout`. In production it refuses unless the database is empty and you pass `--i-know-what-i-am-doing`, and it never creates seed users there.

You can also write content from the command line: `engine-dmo content create`, `content update`, `content publish` and `content get` take and print JSON. [The CLI reference](/reference/cli) lists them.

## Look at what the engine sees [#look-at-what-the-engine-sees]

| Command | Shows | Needs |
|---|---|---|
| `describe project` | Networks, sites, locales, types, routes, endpoints, reports, tiers and roles, with ids | The project files |
| `describe type <key>` | A type's fields at every depth, with ids, types, parameters and aliases | The project files |
| `describe fieldtypes` | Every field type, what it stores and its parameters | Nothing |
| `describe template <name>` | Which file a template resolves to on a site's chain, what it extends and includes, and the contract it is checked against | Configuration |
| `describe route <path>` | Which route answers a path, the template it resolved, and the whole template context with real values | A database |
| `template api` | Every global, function, filter and type a site's templates can use (`--site`, `--json`) | The project files |
| `render <path>` | Render a public page through the real pipeline, in process. `--json` adds errors, queries, assets, accessibility findings and the image report (`--site`, `--locale`, `--host`, `--fragment`) | A database |
| `template test` | Render every page `tests/templates/*.test.yaml` names and check each (`--filter`, `--snapshots`, `--update`) | A seeded database |

Every command takes `--json`. "The project files" means the files are read and no variable need be set; "Configuration" means the whole configuration must load, which needs every `${VAR}` without a default to be set (a placeholder value is enough); "a database" means one that is migrated and has the schema applied. `describe project` and `describe type` show the core fields of a core type (`page` has only `title` and `slug`) and the fields you added.

`render` and `describe route` write the engine's start-up log lines to standard error before their result, and before failing when the database cannot be reached; with `--json`, standard output holds only the JSON. A path the site does not answer renders with status 404: the home page answers `/`, and its slug path (`/home`) is not found.

The usual way to write a template: `describe route <path> --json` for the context it receives, write it, then `render <path> --json` to see the result and any errors.

## Scaffold files [#scaffold-files]

`engine-dmo new` writes starting files you then edit:

| Command | Writes |
|---|---|
| `new type <key>` | A schema file for a custom type, and its template |
| `new template <name>` | A starter template, such as `walk/entry.html` or `walk/index.html`; `--from-shared` copies the shared template into a site's own root and records where it came from, so `check` reports when the original changes |
| `new component` | A component: its contract, markup and co-located CSS |
| `new block` | A block template and the schema stub that declares the block |

`--site <key>` writes into that site's template root; `--force` overwrites.

## Editor support [#editor-support]

- **Configuration:** `init` maps each configuration file to its JSON Schema for VS Code and Zed. `engine-dmo config schema --write` rewrites them after an engine upgrade, and `engine-dmo config schema --file site` prints one kind of file's schema. `--file` takes a kind (`engine`, `locales`, `site`, `routes`, `schema`, `endpoints` and the rest) or a real path such as `config/sites/main/site.yaml`; a bare file name such as `site.yaml` is refused with the list of kinds.
- **Templates:** `engine-dmo lsp` is a language server on standard input and output. It gives `check`'s diagnostics as you type, completion, hover and go to definition. Configure your editor to start it in the project directory. It refuses a production project.

## Read the guide and the handbook [#read-the-guide-and-the-handbook]

```bash
engine-dmo guide                        # this project: rules, sites, types, fields, template roots and filters
engine-dmo guide --out AGENTS.md        # the same, to a file
engine-dmo docs serve                   # this project's template API at http://127.0.0.1:6061
```

`guide` is generated from the project's schema, routes and the engine's template contract, so it is always current; regenerate it after any change rather than editing it. `--skill` writes it with skill front matter. `docs serve` takes `--listen` and `--site` (one site's template API only).

## Build the frontend [#build-the-frontend]

```bash
engine-dmo build
```

Runs the project's `package.json` `build` script (or `--command`), then `engine-dmo check` (`--no-check` to skip it, `--no-db` and `--strict` passed to `check`).

## A typical session [#a-typical-session]

<Steps>
<Step>
Start `engine-dmo dev up` in one terminal.
</Step>
<Step>
Change the model with the `dev` verbs, or edit YAML and save. Watch `dev up`'s output, or run `engine-dmo dev status --json`.
</Step>
<Step>
Generate content to work against: `engine-dmo seed generate --type walk --count 20 --publish`.
</Step>
<Step>
Write the template against `engine-dmo describe route /walks/some-walk --json`, and check it with `engine-dmo render /walks/some-walk --json`.
</Step>
<Step>
Finish with `engine-dmo check`, then commit.
</Step>
</Steps>


# Your first project (/getting-started/first-project)

Create a Meridian project with init or init --from, migrate and apply it to a database, seed it, serve it and sign in to the admin as the first staff user.

A Meridian project is a directory: configuration under `config/`, templates under `templates/`, seed content under `seed/` and static files under `public/`. This page creates one, puts it in a database and signs you in to the admin.

Each step needs the one before it:

```mermaid
flowchart LR
  init["init<br/>writes the files"] --> check["check --no-db<br/>no database"]
  check --> migrate["migrate up<br/>engine tables"]
  migrate --> apply["schema apply<br/>your types and sites"]
  apply --> seed["seed apply<br/>the home page"]
  seed --> dev["dev up<br/>serves the site"]
  migrate --> user["user create<br/>admin sign-in"]
```

You need the binary and a PostgreSQL database ([Install](/getting-started/install)).

## Create the project [#create-the-project]

<Tabs items={["The starter", "A copy of a project"]}>
<Tab value="The starter">

```bash
engine-dmo init my-site
```

```text
created a project in /home/you/my-site from the starter (...)

guidance for coding agents: AGENTS.md, .claude/skills/meridian-project/SKILL.md, .claude/skills/meridian/SKILL.md

editor support: config schemas in .meridian/schema, mapped for zed and vscode

next:
  export DATABASE_URL=postgres://...
  engine-dmo migrate up --project /home/you/my-site
  engine-dmo schema apply --project /home/you/my-site
  engine-dmo seed apply --project /home/you/my-site
  engine-dmo serve --dev --project /home/you/my-site
```

The starter is the smallest project that passes `engine-dmo check` and serves a page: one locale, one site, the core `page` type routed at `/{slug}`, a home page in the seed, and four templates (the layout `base.html`, `page/entry.html`, and the error pages `errors/404.html` and `errors/500.html`).

</Tab>
<Tab value="A copy of a project">

```bash
engine-dmo init my-site --from ../agency-starter
```

`--from` copies an existing project directory instead of writing the starter. It takes a directory you already have: the binary carries no example projects, and the examples the Meridian team maintains live in the Meridian source repository, not in a release. It leaves out `node_modules/`, the frontend build output (`public/build/`), local media storage (`storage/`), `.git/`, `.meridian/` and every `.env` file except `.env.example`. It then gives every configuration element in the copy a new id, so the copy and the original are separate projects that can never be confused in a database (see [Stable ids](/concepts/stable-ids)).

When the copied seed imports photographs from a media library directory outside the project, `init` says where it expected them.

</Tab>
</Tabs>

`init` takes the directory as its argument (the current directory when omitted) and refuses a directory that already holds `config/engine.yaml`.

| Flag | Default | Effect |
|---|---|---|
| `--from <dir>` | none | Copy this project directory instead of writing the starter |
| `--editors <list>` | `zed,vscode` | Map the configuration files to their JSON Schemas in these editors' project settings (`.zed/settings.json`, `.vscode/settings.json`), so the editor completes and validates keys. Pass `--editors ""` for none |
| `--agents` | `true` | Write guidance for coding agents: `AGENTS.md` and the `meridian-project` skill (both generated by `engine-dmo guide` from this project), and the `meridian` skill (the handbook's [For agents](/agents) page). Each is written only when the file is not already there. `--agents=false` writes none |

## What the starter contains [#what-the-starter-contains]

<Files>
  <Folder name="my-site" defaultOpen>
    <File name=".gitignore" />
    <File name="AGENTS.md" />
    <File name="README.md" />
    <Folder name=".claude">
      <Folder name="skills">
        <Folder name="meridian">
          <File name="SKILL.md" />
        </Folder>
        <Folder name="meridian-project">
          <File name="SKILL.md" />
        </Folder>
      </Folder>
    </Folder>
    <Folder name=".meridian" >
      <Folder name="schema" />
    </Folder>
    <Folder name=".vscode">
      <File name="settings.json" />
      <File name="extensions.json" />
    </Folder>
    <Folder name=".zed">
      <File name="settings.json" />
    </Folder>
    <Folder name="config" defaultOpen>
      <File name="engine.yaml" />
      <File name="locales.yaml" />
      <Folder name="access" defaultOpen>
        <File name="grants.yaml" />
      </Folder>
      <Folder name="sites" defaultOpen>
        <Folder name="main" defaultOpen>
          <File name="site.yaml" />
          <File name="routes.yaml" />
        </Folder>
      </Folder>
    </Folder>
    <Folder name="public">
      <File name=".keep" />
    </Folder>
    <Folder name="seed" defaultOpen>
      <File name="seed.yaml" />
      <Folder name="documents" defaultOpen>
        <Folder name="page" defaultOpen>
          <File name="home.yaml" />
        </Folder>
      </Folder>
    </Folder>
    <Folder name="templates" defaultOpen>
      <Folder name="_shared" defaultOpen>
        <File name="base.html" />
        <Folder name="page" defaultOpen>
          <File name="entry.html" />
        </Folder>
        <Folder name="errors" defaultOpen>
          <File name="404.html" />
          <File name="500.html" />
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

`config/engine.yaml` reads everything that differs between machines from the environment:

```yaml
engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}

server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}

database:
  url: ${DATABASE_URL}

logging:
  format: ${LOG_FORMAT:-text}

storage:
  driver: filesystem
  filesystem:
    root: ./storage
```

`config/locales.yaml` declares one locale, `en`. Set its `timezone` and `currency` to your own before you add content; the starter uses `Etc/UTC` and `EUR`:

```yaml
locales:
  available:
    - code: en
      id: loc_3990wq8rss
      label: English
      source: true
      default: true
      timezone: Etc/UTC
      currency: EUR
```

`config/sites/main/site.yaml` declares the one site, answering on `localhost` and `localhost:8080`, and `routes.yaml` routes pages and names the home page:

```yaml
routes:
  - type: page
    id: rte_8397jasp17
    uri: "/{slug}"

home: { type: page, slug: home }
```

The `id:` values are written by `init` and are different in every project; never copy them between projects. [Stable ids](/concepts/stable-ids) explains why.

`config/access/grants.yaml` gives the `administrators` group the built-in `owner` role, so the first staff user you create can do everything ([Users, roles and permissions](/concepts/users-roles-and-permissions)):

```yaml
grants:
  - { group: administrators, role: owner }
```

`seed/seed.yaml` names the seed and lists `locales: [en]`. That list limits only the analytics a seed can generate; document values load in every locale a seed file gives, so a new locale needs its values in the documents, not in this list.

`templates/_shared/page/entry.html` renders a page:

```jinja
{% extends "base.html" %}
{% block body %}
<h1>{{ entry.title }}</h1>
{% endblock %}
```

The core `page` type has only two fields, `title` and `slug`. To give pages a body or a summary, extend the type in `config/schema/` ([Types](/content-modelling/types#extending-a-core-type)); `engine-dmo describe type page` lists the fields a type has.

### Replace the starter layout [#replace-the-starter-layout]

`templates/_shared/base.html` is a placeholder that writes its own `<title>` and canonical link, so `check` warns that it has no `head()`. Replace its head with `head()`, which writes the title, description, canonical link, hreflang links, robots and social tags from the page and the site's SEO settings:

```jinja
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
</head>
<body>
  <main id="main">{% block body %}{% endblock %}</main>
</body>
</html>
```

[SEO and structured data](/templates/seo-and-structured-data) covers what `head()` prints.

## Put it in a database [#put-it-in-a-database]

<Steps>
<Step>
### Point the engine at the database [#point-the-engine-at-the-database]

```bash
cd my-site
export DATABASE_URL='postgres://meridian:meridian@localhost:5432/meridian?sslmode=disable'
```

Every command reads the project in the current directory, or the one `--project` names.
</Step>
<Step>
### Check the project [#check-the-project]

```bash
engine-dmo check --no-db
```

`check` validates every configuration file, the schema and every template, and prints each problem with its file, line and column. It exits 0 when the project is valid and 3 when it is not. `--no-db` skips the checks that need a database and does not need secrets to be set.

The unchanged starter passes and prints one warning, that `base.html` has no `head()` ([Replace the starter layout](#replace-the-starter-layout)). The summary line still says `0 errors, 0 warnings`: template warnings are printed above it but not counted, and `--strict` does not fail on them. Read every line `check` prints, not only the summary.
</Step>
<Step>
### Run the migrations [#run-the-migrations]

```bash
engine-dmo migrate up
```

Migrations create the engine's own tables: core's and those of every module the binary compiles. They only ever move forward.
</Step>
<Step>
### Apply the schema [#apply-the-schema]

```bash
engine-dmo schema apply
```

This reconciles the database with your configuration: locales, sites, types, fields, routes, roles and grants. `engine-dmo schema plan` shows the same changes without applying them.
</Step>
<Step>
### Seed it [#seed-it]

```bash
engine-dmo seed apply
```

The starter's seed creates and publishes the home page. Seeding goes through the same validation and revision history as an editor's save, and refuses a database that already holds documents or media; `engine-dmo seed reset --confirm` empties content, media and analytics first (never in production).
</Step>
<Step>
### Serve it [#serve-it]

```bash
engine-dmo dev up
```

`http://localhost:8080` now serves the home page. The page `home: { type: page, slug: home }` names in `routes.yaml` answers `/`, not `/home`, which is not found. `dev up` serves the site in development mode and watches `config/`: each time you save a file it writes any missing ids, checks the project, plans the schema change and applies it when it is not destructive. Stop it with Ctrl+C. [The development loop](/getting-started/development-loop) covers it and `engine-dmo serve --dev`.
</Step>
</Steps>

## Sign in to the admin [#sign-in-to-the-admin]

The admin is at `/studio` on any of the project's sites. Staff users are created from the command line:

```bash
engine-dmo user create --email you@example.org --name "Your Name"
```

```text
first user: added to the administrators group
created you@example.org (...) in groups administrators
enrolment link, valid 24 hours, single use:
  http://localhost:8080/studio/enrol/...
```

The first user created goes into `administrators`, which the starter's `grants.yaml` gives the `owner` role. Later users name their groups with `--group` (repeatable). The link is built from `server.base_url`.

Open the link, choose a password of at least 12 characters, scan the code into an authenticator app and enter a code from it. The admin then shows your recovery codes once. Staff accounts require a second factor by default.

`user create` needs the migrations applied. It does not send mail: it prints the link.

### Development shortcuts [#development-shortcuts]

Two settings make signing in quicker on your own machine. Neither is allowed in production.

<Tabs items={["A seeded user", "No second factor"]}>
<Tab value="A seeded user">
A file in `seed/users/` creates a staff user when the seed is applied, with a password and an authenticator secret, so you can sign in straight away after every reseed:

```yaml
# seed/users/admin.yaml. Development only: seed apply skips users in production.
email: admin@example.test
name: Dev Admin
groups: [administrators]
password: correct horse battery staple
totp_secret: JBSWY3DPEHPK3PXP
```

`totp_secret` is a base32 secret you add to your authenticator app. The value above is a well-known example; use your own. Leave it out and the user cannot sign in while a second factor is required.
</Tab>
<Tab value="No second factor">
```yaml
# config/engine.yaml
auth:
  staff:
    local:
      require_mfa: false
```

`engine-dmo check` refuses `require_mfa: false` when `engine.environment` is `production`.
</Tab>
</Tabs>

## What to do next [#what-to-do-next]

- Add a type, a field or a route with the `engine-dmo dev` verbs while `dev up` runs: [The development loop](/getting-started/development-loop).
- Learn what each file is for: [Project layout](/getting-started/project-layout).
- Model your content: [Content modelling](/content-modelling).
- Write templates: [Templates](/templates).
- Point your coding agent at `AGENTS.md` and the two skills `init` wrote; the `engine-dmo dev` verbs regenerate them whenever they change the configuration.


# Getting started (/getting-started)

The path from nothing to a running Meridian site on your machine, and which page answers each step.

This section takes you from an empty machine to a site you can edit, preview and check, and explains the files you are working with.

<Steps>
<Step>
### Install [#install]

Get the engine for your bundle, a PostgreSQL 14 or later database, and decide whether you want a search service and a real mail service in development. Releases publish Linux container images of `engine-dmo` only, with no standalone binary download; [Getting the engine](/getting-started/install#getting-the-engine) says how to run it on your machine. [Install](/getting-started/install).
</Step>
<Step>
### Create a project [#create-a-project]

`engine-dmo init` writes a starter project; `engine-dmo init --from <dir>` copies an existing one you already have (the binary carries no example projects). Migrate the database, apply the schema, seed it, serve it and create the first staff user. [Your first project](/getting-started/first-project).
</Step>
<Step>
### Learn the layout [#learn-the-layout]

Every directory and file a project can hold, which ones you write and which the tooling writes. [Project layout](/getting-started/project-layout).
</Step>
<Step>
### Work in the loop [#work-in-the-loop]

`engine-dmo dev up` keeps the site running and applies safe configuration changes as you save; `check`, `schema plan`, `render` and `guide` do the rest. [The development loop](/getting-started/development-loop).
</Step>
<Step>
### Upgrade the engine [#upgrade-the-engine]

How a new engine version reaches a project: the template contract, the project's `engine.version`, and migrations as an explicit deploy step. [Upgrading the engine](/getting-started/upgrading-the-engine).
</Step>
</Steps>

## The shortest path [#the-shortest-path]

With PostgreSQL running and the binary on your `PATH`:

```bash
engine-dmo init my-site
cd my-site
export DATABASE_URL='postgres://meridian:meridian@localhost:5432/meridian?sslmode=disable'
engine-dmo migrate up
engine-dmo schema apply
engine-dmo seed apply
engine-dmo user create --email you@example.org --name "Your Name"
engine-dmo dev up
```

Open `http://localhost:8080` for the site and the enrolment link `user create` printed for the admin at `/studio`.

Two things surprise people on the first run: `check` warns that the starter's `base.html` has no `head()` and still ends `0 errors, 0 warnings`, because template warnings are not counted ([Replace the starter layout](/getting-started/first-project#replace-the-starter-layout)); and once your `engine.yaml` names a secret such as `${SIGNING_KEY}`, it must be set on your machine too ([Variables you must set](/getting-started/install#variables-you-must-set-even-in-development)).

<Callout title="engine-cms or engine-dmo">
Every command in this section is the same on both binaries. Use `engine-cms` in place of `engine-dmo` if you run the CMS bundle.
</Callout>

Once the site runs, read [Concepts](/concepts) before you model content: sites, locales and stable ids shape every file you will write.


# Install (/getting-started/install)

What Meridian needs to run (the engine binary or container image, PostgreSQL 14 or later, and optional search and mail services) and how to check an installation.

Meridian is one binary. It needs a PostgreSQL database and nothing else to serve a site; a search service and a mail service are optional and add site search and real email.

## What you need [#what-you-need]

| Component | Required | Notes |
|---|---|---|
| The engine binary, `engine-dmo` or `engine-cms` | Yes | One self-contained executable. No runtime, interpreter or system library is needed for the pure Go build |
| PostgreSQL | Yes | Version 14 or later; 15 or later is recommended. The database must be created with `UTF8` encoding |
| A search service | No | Meilisearch, Elasticsearch or OpenSearch. Without one, the search route serves browse mode only |
| A mail service | No | SMTP, Postmark, Amazon SES or Resend. Without one, messages are written to the log |
| Node.js | Only for a frontend build | The engine never needs Node at runtime. A project with its own CSS and JavaScript build uses it to run that build |

Nothing else runs beside the engine: there is no separate worker process, cache server or queue. Every `engine-dmo serve` process serves requests and runs the background jobs. `serve` accepts `--role web|worker|all`, but this version ignores it: a process given `--role web` still runs jobs, so you cannot split web and worker processes.

## Getting the engine [#getting-the-engine]

What a release publishes today:

| Available | Not available |
|---|---|
| Two Linux container images of `engine-dmo` (below), for `linux/amd64` and, for the pure Go image, `linux/arm64` | A standalone download of either binary |
| | An `engine-cms` image |
| | A macOS or Windows build |
| | The example projects: they are in the Meridian source repository, not in the binary or the images |

So on your own machine you have three ways to run the engine:

- **A binary you have been given.** Put it on your `PATH`. Everything in this handbook assumes this.
- **The image, as a command.** Every command works through the image with the project mounted as the working directory. A shell alias makes it read like a local binary:

  ```bash
  alias engine-dmo='docker run --rm -i -v "$PWD":/srv/project -w /srv/project \
    -e DATABASE_URL -e SIGNING_KEY ghcr.io/cherwell-studio/meridian:0.8.0'
  engine-dmo check --no-db
  ```

  To serve this way, add `-p 8080:8080 -e LISTEN_ADDR=0.0.0.0:8080` to the `docker run` for `serve` or `dev up`. Inside the container `localhost` is the container itself: point `DATABASE_URL` at `host.docker.internal` (Docker Desktop) or run with `--network host` (Linux) to reach a database on your machine.
- **The binary copied out of the image**, on Linux only, since the image holds a Linux executable:

  ```bash
  id=$(docker create ghcr.io/cherwell-studio/meridian:0.8.0)
  docker cp "$id":/app/engine-dmo ./engine-dmo
  docker rm "$id"
  ```

## The binary [#the-binary]

Put the binary for your bundle on your `PATH` and check it:

```bash
engine-dmo version
```

```text
meridian v0.8.0 (pure-go) go1.27.3
  bundle dmo: modules ai directory forms crm affiliates memberships newsletter portal claims memberreport promotions paidlistings translation
  ...
  image pipeline Go image, golang.org/x/image: encodes jpeg png; heic false, icc false
  template contract 1
```

The lines that matter:

| Line | Tells you |
|---|---|
| `meridian v0.8.0 (pure-go)` | The engine version and the build variant: `pure-go`, or `vips` for a build linked against libvips |
| `bundle dmo: modules ...` | The bundle and every module compiled in |
| `image pipeline ...` | The image formats this build can encode, and whether it reads HEIC and ICC colour profiles |
| `template contract 1` | The template contract version this engine implements (see [Upgrading the engine](/getting-started/upgrading-the-engine)) |

`engine-dmo version --json` prints the same as JSON. `engine-dmo version --require webp,avif` exits 1 unless the build has every capability named, which makes a quick smoke test after an install. The capabilities are `webp`, `avif`, `heic`, `icc`, `pdf` (a browser that prints a tagged PDF) and `extension:<name>` (a first-party extension that opens).

`engine-cms` and `engine-dmo` take the same commands. A project written for `engine-cms` also runs on `engine-dmo`, since every module of the CMS bundle is in the DMO bundle too.

## The container images [#the-container-images]

Each release is published as two Linux container images of `engine-dmo`:

| Image | Platforms | Contents |
|---|---|---|
| `ghcr.io/cherwell-studio/meridian:<version>` | `linux/amd64`, `linux/arm64` | The pure Go build on a distroless static base. Encodes JPEG and PNG |
| `ghcr.io/cherwell-studio/meridian:<version>-vips` | `linux/amd64` | Linked against libvips: encodes JPEG, PNG, WebP and AVIF, reads HEIC and ICC profiles, prints the member report as a tagged PDF through a bundled headless Chromium, and carries the first-party extensions in `/app/extensions/`. The recommended image for production |

Tags: every release is tagged with its full version (`0.8.0`) and its minor version (`0.8`), each with the `-vips` suffix for the libvips image. `latest` points at the newest pure Go release that is not a release candidate; there is no `latest-vips`, so the floating libvips tag is the minor one (`0.8-vips`). On an `arm64` host the `-vips` image does not run natively, so an `arm64` server gets the pure Go image: JPEG and PNG only, no member report PDF and no extensions.

Both images run as a non-root user with no shell, have the binary at `/app/engine-dmo` as their entrypoint, run `serve` by default, work in `/app`, and expose port `8080`. Mount your project into the container and name it with `--project`:

```bash
docker run --rm \
  -v "$PWD":/srv/project:ro \
  -e DATABASE_URL='postgres://meridian:secret@db:5432/meridian?sslmode=disable' \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  ghcr.io/cherwell-studio/meridian:0.8.0-vips \
  check --no-db --project /srv/project
```

Run the image with a read-only root filesystem, a writable `/tmp`, and the project's storage directory on a volume of its own. [The container images](/deploying/container-images) and [Single-node deployment](/deploying/single-node) cover production use.

<Callout type="info" title="engine-cms in a container">
The published images contain `engine-dmo`. Because a CMS project runs on `engine-dmo` unchanged, you can run an `engine-cms` project in them.
</Callout>

## PostgreSQL [#postgresql]

Any PostgreSQL 14 or later server works, managed or self-hosted. The engine refuses to start against an older server and names the version it found, and `engine-dmo migrate up` refuses a database whose encoding is not `UTF8`.

For development, a container is the quickest route:

```bash
docker run -d --name meridian-db \
  -e POSTGRES_USER=meridian -e POSTGRES_PASSWORD=meridian -e POSTGRES_DB=meridian \
  -e POSTGRES_INITDB_ARGS="--encoding=UTF8 --locale=C.UTF-8" \
  -p 5432:5432 postgres:16
```

The engine reads the connection string from `database.url` in `config/engine.yaml`, which a new project sets to `${DATABASE_URL}`:

```bash
export DATABASE_URL='postgres://meridian:meridian@localhost:5432/meridian?sslmode=disable'
```

The engine does not read `.env` files, although the starter's `.gitignore` lists `.env`: that is for a file your shell, `direnv`, Docker Compose or your process manager loads. Export variables in your shell, or have your process manager or container runtime set them.

Sorting text in a locale's own order uses the server's ICU collations. On a server built without ICU the engine still runs and logs a warning; text then sorts in code point order. Run `engine-dmo doctor` against a database to see its version, encoding, collation and whether ICU is present.

Use one database per project. Projects with different schemas must not share a database.

## Variables you must set, even in development [#variables-you-must-set-even-in-development]

A `${VAR}` without a default must be set for any command that loads the whole configuration, which includes `check` (without `--no-db`), `config validate`, `seed verify`, `new template`, `dev route add --scaffold`, `describe template`, `render`, `migrate` and `serve`. A placeholder is enough for the commands that never connect. `check --no-db`, `describe project`, `describe type`, `template api`, `guide` and the `dev` verbs other than `--scaffold` run without them.

The new project uses only `${DATABASE_URL}`. When you add secrets for production, such as `signing_key: ${SIGNING_KEY}`, they must be set on your machine too, and a secret cannot take a default (`${SIGNING_KEY:-}` is refused). Keep development values in a file you load into your shell:

```bash
# .env, loaded with: set -a; . ./.env; set +a
DATABASE_URL='postgres://meridian:meridian@localhost:5432/meridian?sslmode=disable'
SIGNING_KEY='development-only-0123456789abcdef'   # at least 32 characters, even here (meridian:allow-secret, a local placeholder)
```

`server.security.signing_key` is checked for length whenever it is set, by `check --no-db` too. Left out of `engine.yaml` altogether, the engine derives a development key from the database URL and logs a warning; `check` refuses a missing key when `engine.environment` is `production`.

## Search (optional) [#search-optional]

Without a search backend, `search.driver` is `none` and a site's search route serves browse mode. To search, run Meilisearch (or Elasticsearch or OpenSearch) and point `engine.yaml` at it:

```yaml
search:
  driver: meilisearch
  meilisearch:
    url: ${MEILISEARCH_URL:-http://localhost:7700}
    api_key: ${MEILISEARCH_API_KEY}
```

```bash
docker run -d --name meridian-search \
  -e MEILI_MASTER_KEY=dev-key -e MEILI_ENV=development \
  -p 7700:7700 getmeili/meilisearch:v1.15
export MEILISEARCH_API_KEY=dev-key
```

`api_key` is a secret, so it must be a bare `${VAR}` and the variable must be set, even to an empty value for a server with no key. [Search](/features/search) covers the backends and their options.

## Mail (optional) [#mail-optional]

`mail.driver` defaults to `log`: every message, including staff enrolment and password reset mail, is written to the engine's log instead of being sent. That is enough for development. To catch real messages locally, run an SMTP catcher such as Mailpit and use the `smtp` driver:

```yaml
mail:
  driver: smtp
  from: "Visit Wyndmouth <hello@wyndmouth.example>"
  smtp:
    host: ${SMTP_HOST:-localhost}
    port: 1025
```

The drivers are `log`, `smtp`, `postmark`, `ses` and `resend`. Each provider's keys are secrets and come from environment variables. `engine-dmo mail status` and `engine-dmo mail test` check a configuration against a running database.

## Ports [#ports]

| Port | Used for | Set with |
|---|---|---|
| `8080` | The public sites, the admin at `/studio`, the APIs | `server.listen`; a new project reads `${LISTEN_ADDR:-127.0.0.1:8080}` |
| `9090` on `127.0.0.1` | Prometheus metrics at `/_metrics` | `telemetry.metrics.bind` |
| `6061` on `127.0.0.1` | `engine-dmo docs serve` | `--listen` |

`engine-dmo serve --listen` and `engine-dmo dev up --listen` override `server.listen` for one run.

## Checking an installation [#checking-an-installation]

<Steps>
<Step>
`engine-dmo version` prints the version, bundle and modules.
</Step>
<Step>
`engine-dmo check --no-db --project <dir>` validates a project's configuration and templates with no database and no secrets set (a secret that is set is still checked, so a short `SIGNING_KEY` fails).
</Step>
<Step>
`engine-dmo migrate status` lists applied and pending migrations against the database `DATABASE_URL` names, and exits 2 if any are pending.
</Step>
<Step>
`engine-dmo doctor` writes a support bundle in one text file: the build, whether the configuration is valid, the database server and more, with every secret redacted.
</Step>
</Steps>

Next: [Your first project](/getting-started/first-project).


# Project layout (/getting-started/project-layout)

Every directory and file a Meridian project can hold, what each is for, which bundle reads it, and which files you write and which the tooling writes.

A project is one directory. The engine reads it from the current directory, or from the directory `--project` names; `--config` changes the configuration directory's name from `config`. Everything in it is text you commit to version control, except the few local directories listed under [What not to commit](#what-not-to-commit).

## The whole tree [#the-whole-tree]

<Files>
  <Folder name="my-site" defaultOpen>
    <Folder name="config" defaultOpen>
      <File name="engine.yaml" />
      <File name="locales.yaml" />
      <File name="images.yaml" />
      <File name="accessibility.yaml" />
      <File name="networks.yaml" />
      <File name="memberships.yaml" />
      <File name="paidlistings.yaml" />
      <Folder name="schema" />
      <Folder name="blocks" />
      <Folder name="strings" />
      <Folder name="sites" defaultOpen>
        <Folder name="main" />
      </Folder>
      <Folder name="access" />
      <Folder name="analytics" />
      <Folder name="crm" />
      <Folder name="portal" />
      <Folder name="tags" />
      <Folder name="search" />
      <Folder name="ai" />
      <Folder name="guidance" />
    </Folder>
    <Folder name="templates" defaultOpen>
      <Folder name="_shared" />
      <Folder name="main" />
    </Folder>
    <Folder name="public" />
    <Folder name="seed" />
    <Folder name="src" />
    <Folder name="tests" />
    <Folder name="storage" />
    <Folder name=".meridian" />
    <File name="package.json" />
    <File name="vite.config.js" />
    <File name="AGENTS.md" />
    <File name="README.md" />
    <File name=".gitignore" />
  </Folder>
</Files>

Only `config/engine.yaml`, `config/locales.yaml`, one site directory and the templates its routes need are required. Every other file is optional: leave it out and the engine uses its defaults.

## What reads what [#what-reads-what]

The engine reads `config/` and `templates/` at start and on every check; `schema apply` copies the schema into the database, `seed apply` loads `seed/` into it once, and from then on content lives in the database:

```mermaid
flowchart LR
  subgraph project["The project directory"]
    config["config/<br/>engine, locales, sites, schema, access"]
    templates["templates/"]
    public["public/"]
    seed["seed/"]
  end
  config -->|schema apply| db[("PostgreSQL<br/>schema copy and content")]
  seed -->|seed apply, once| db
  config --> engine["The engine<br/>serve, dev up, check"]
  templates --> engine
  public -->|served as is| engine
  db --> engine
  engine --> site["Public sites, admin, APIs"]
  config -->|guide| agents["AGENTS.md and skills"]
```


## Who writes what [#who-writes-what]

You write every file in the project. The tooling writes into your files in three cases only, each one a command you run on purpose, never the running engine:

- `engine-dmo check --fix`, the `engine-dmo dev` verbs and `engine-dmo dev up` write the `id:` of each configuration element that has none, and the verbs make the edit you asked for. They keep your comments and layout. See [Stable ids](/concepts/stable-ids).
- `engine-dmo init` and `engine-dmo new` write new files.
- `engine-dmo config schema --write` and `init` write the editor schemas under `.meridian/schema/` and the editor settings that map them.

Content (documents, media, organisations, users) lives in the database, not in the project. The project's `seed/` holds content to load into a database, which is a one-way copy.

## config/ [#config]

Configuration is YAML. Every file is validated as a whole by `engine-dmo check`, which reports every problem at once with its file, line and column. Secrets never appear as values: a secret key must be a bare `${VAR}` reference to an environment variable. [Configuration reference](/reference/configuration) lists every key of every file.

### Install-wide files [#install-wide-files]

| Path | Holds | Bundle |
|---|---|---|
| `engine.yaml` | The install: server, database, storage, mail, search, authentication, media, cache, logging, jobs, analytics and each module's own section. Required | Both |
| `locales.yaml` | Every locale the install knows, its formatting and its fallback chain; exactly one is the source locale. Required | Both |
| `images.yaml` | Image breakpoints, defaults and named transforms | Both |
| `accessibility.yaml` | The register of known accessibility issues the accessibility statement lists | Both |
| `networks.yaml` | Networks of sites that share organisations, people and partner accounts. Without it every site is in one network | Both, used by the DMO modules |
| `memberships.yaml` | The membership tiers, in rank order | `engine-dmo` (Memberships) |
| `paidlistings.yaml` | Prices and payment for paid listings | `engine-dmo` (Paid listings) |
| `schema/` | Content types. Any `.yaml` file at any depth is read; `schema/_shared.yaml` holds field groups other files include with `use:`; other files whose names start with `_` are not read as types | Both |
| `blocks/_index.yaml` | Blocks shared by every `blocks` field | Both |
| `strings/<locale>.yaml` | The interface strings templates print with `t()`, one file per locale | Both |
| `access/roles.yaml` | Staff roles: your own, and replacements for the built-in ones | Both |
| `access/grants.yaml` | Which staff group holds which role, under which scope. The starter's gives the `administrators` group the built-in `owner` role, and `user create` puts the first user in `administrators`; keep a grant like it, or no one can manage the install | Both |
| `access/users.yaml` | Custom fields on the staff user record | Both |
| `analytics/dashboards.yaml` | The organisation dashboards and the metrics staff enter by hand | Both |
| `analytics/reports.yaml` | Scheduled member and organisation reports | `engine-dmo` (Member report) |
| `analytics/bots.txt` | User agent substrings added to the shipped list of bots, one per line | Both |
| `crm/organisation.yaml`, `crm/person.yaml` | Custom fields on organisations and people | `engine-dmo` (CRM) |
| `portal/portal.yaml` | The member portal's install-wide settings | `engine-dmo` (Member portal) |
| `portal/enquiries.yaml` | Custom fields on enquiries | `engine-dmo` (Member portal) |
| `portal/roles.yaml` | Partner roles: what a person may do for an organisation in the portal | `engine-dmo` (CRM) |
| `tags/vocabulary.yaml` | The starting tag vocabulary. Loaded into the database by `engine-dmo tags import` or a seed; the admin edits it after that | Both |
| `tags/smartlists.yaml` | The starting smart lists, loaded the same way | Both |
| `search/synonyms.yaml` | The starting search synonyms, loaded by `engine-dmo search synonyms` or a seed | Both |
| `ai/prompts/<key>.yaml` | Your override of one of the engine's AI prompts | Both (AI) |
| `guidance/<site>.md`, `guidance/<site>/<type>.md` | Editorial guidance in Markdown that the content MCP gives an agent writing content for that site or type | Both |

A file that belongs to a module the binary does not compile is an error at the file, naming the module. On `engine-cms`, `config/memberships.yaml` gives:

```text
config/memberships.yaml:1:1: memberships.yaml belongs to the memberships module, which this bundle (cms) does not compile
    1 | tiers:
      | ^
      = use a bundle that compiles memberships, such as the DMO platform's bin/engine-dmo, or remove it
      = error code MRD-1006
```

A module's section of `engine.yaml` (such as `portal:`) is refused the same way.

### config/sites/ [#configsites]

One directory per site; the directory name is the site's key. An install with one site still has `config/sites/<key>/`.

| Path | Holds | Bundle |
|---|---|---|
| `site.yaml` | The site's name, domains, enabled locales and URL strategy, template roots, SEO, navigation slots, widgets, delivery mode and settings. Required | Both |
| `routes.yaml` | Which types the site routes and at which URI patterns, index pages, feeds, calendars, landing pages, redirects, special pages and the home page. Without it no type is routable on the site | Both |
| `schema/` | Types and fields that belong to this site alone | Both |
| `images.yaml` | Image transforms added to the install's, or replacing one by name | Both |
| `endpoints.yaml` | Declared endpoints: fragment, JSON, stream or redirect responses built from a fixed set of steps | Both |
| `sources.yaml` | Configured, cached, allowlisted upstream data sources the endpoints read | Both |
| `importers.yaml` | Scheduled feed imports | Both |
| `webhooks.yaml` | Outbound webhooks on content events | Both |
| `plugins.yaml` | Plugin binaries the endpoints call (an experimental protocol) | Both |
| `portal.yaml` | This site's portal over the install's: path, routes, screens and actions | `engine-dmo` (Member portal) |
| `promotions.yaml` | Promotion slots and the label each promoted placement shows | `engine-dmo` (Promotions) |

[Sites, locales and routes](/concepts/sites-locales-and-routes) explains how `site.yaml` and `routes.yaml` work together.

## templates/ [#templates]

Pongo2 templates (a Django-like syntax), autoescaped. `templates/_shared/` holds what every site uses, and `templates/<site>/` holds a site's overrides. A site resolves each template along its chain of roots, most specific first: `[<site>, _shared]` unless `templates.roots` in `site.yaml` says otherwise. Every root a site names must exist as a directory.

| Path in a root | Holds |
|---|---|
| `base.html` (or any layout) | Layouts other templates extend |
| `<type>/entry.html` | A document of the type (the default; a type or variant may name another template) |
| `<type>/index.html` | The type's index page, for a route with `index:` |
| `errors/404.html`, `errors/500.html` | The not found and error pages |
| `blocks/<block>.html` | One block of a `blocks` field |
| `components/<name>/` | A component: `<name>.html`, its contract `component.yaml`, and optionally co-located CSS |
| `ptext/<set>/<type>.html` | A custom Portable Text block in a rich text field |
| `emails/` | Transactional mail templates, overriding the engine's own |
| `partials/` | Fragments your templates include; the name is yours |
| `portal/` | The member portal's screens (`engine-dmo`) |

`engine-dmo check` refuses a routed type with no template on a site's chain, an index route without its `index.html`, and any template that does not compile, uses an unknown variable root or an unknown filter. [Templates](/templates) and [Multisite templates](/templates/multisite) cover the rest.

## public/ [#public]

Static files served as they are, at the same path. A request resolves along the site's chain: `public/<site>/`, then `public/_shared/`, then `public/`. Built and versioned files (under `public/build/`) are cached for a year, anything else for an hour; the build's manifest is never served. `public.mounts` in `engine.yaml` serves a directory outside `public/` at a path prefix.

## seed/ [#seed]

Content to load into a database with `engine-dmo seed apply`. It goes through the same validation and revision history as an editor's save. `engine-dmo seed verify` checks it against the schema without a database, and is what CI runs. It needs every `${VAR}` in the configuration set (a placeholder is enough), and it checks types, fields and locales, not values: a value a field would refuse fails only in `seed apply`.

| Path | Holds |
|---|---|
| `seed.yaml` | The manifest: `name`, `description`, `locales`, optional generated `analytics`, named `profiles`, and a media `library` to import photographs from. `locales` limits only the generated analytics; documents load every locale their files give |
| `documents/<type>/<key>.yaml` | One document: its values per locale, which locales to publish, and optionally its history, schedule, tags and site sharing |
| `users/<key>.yaml` | A staff user for development: email, name, groups, password and authenticator secret. Never created in production |
| `navigation/<slot>.yaml` | The items of a navigation slot |
| `assets/` | Media files the seed uploads |
| `organisations/`, `people/` | Organisations and people (`engine-dmo`) |
| `generate.yaml`, `generate/` | Rules for `engine-dmo seed write`, which writes generated records into the seed |
| `<set>/` | Another seed set, applied with `--set <set>` |

A starter seed document:

```yaml
# seed/documents/page/home.yaml
locales:
  en:
    title: Welcome
    slug: home
publish: [en]
```

## Frontend build files [#frontend-build-files]

The starter has no frontend build: no `package.json`, `src/` or `vite.config.js`, and its CSS and JavaScript, if any, go in `public/`. A project with its own CSS and JavaScript build keeps its sources in `src/` (entries in `src/entries/`, one per site by default: `src/entries/<site>.js`), with `package.json` and `vite.config.js` at the project root. The `vite` extension, named in `engine.yaml` as `extensions: [vite]`, runs Vite's dev server beside `engine-dmo serve --dev`, and `engine-dmo build` runs the production build and then `check`. Output goes to `public/build/`. [The frontend build](/templates/frontend-build) covers it.

## tests/ [#tests]

`tests/templates/*.test.yaml` are template tests: pages to render through the real pipeline against the seeded database, each with what it must contain. `engine-dmo template test` runs them. [Testing templates](/templates/testing) covers the format.

## Agent and editor files [#agent-and-editor-files]

| Path | Written by | Holds |
|---|---|---|
| `AGENTS.md` | `engine-dmo init`, refreshed by the `dev` verbs | Working guidance for a coding agent, generated from this project by `engine-dmo guide` |
| `.claude/skills/meridian-project/SKILL.md` | The same | The same guidance as a skill file |
| `.claude/skills/meridian/SKILL.md` | `engine-dmo init`, refreshed by the `dev` verbs | The handbook's [For agents](/agents) page as a skill, matching the engine version |
| `.meridian/schema/*.json` | `engine-dmo init`, `engine-dmo config schema --write` | JSON Schemas of every configuration file, for your editor |
| `.vscode/settings.json`, `.zed/settings.json` | `engine-dmo init --editors` | Editor mappings from each configuration file to its schema |

Regenerate `AGENTS.md` by hand with `engine-dmo guide --out AGENTS.md`, the project skill with `engine-dmo guide --skill --out .claude/skills/meridian-project/SKILL.md`, and the `meridian` skill with `engine-dmo docs skill --out .claude/skills/meridian/SKILL.md`. `init --agents=false` writes none of them.

The starter's `README.md` points at this page. Its hints, and the engine's, name handbook pages or commands. Earlier builds, including the 0.8.0 release images, also cite internal design documents in some hints, such as `(27-frontend-toolkit.md)` or `(ADR-0019)`; those are not part of the handbook and not published, so search the handbook for the topic instead.

## What not to commit [#what-not-to-commit]

The starter's `.gitignore`:

```text
/storage/
/node_modules/
/public/build/
/.meridian/
.env
```

| Path | Why it is local |
|---|---|
| `storage/` | Uploaded media and image derivatives with the `filesystem` storage driver (`storage.filesystem.root`, `./storage` by default). Back it up with the database, never commit it |
| `node_modules/` | Installed frontend packages |
| `public/build/` | Frontend build output, rebuilt by `engine-dmo build` |
| `.meridian/` | Editor schemas, and `dev-status.json`, the last result of `engine-dmo dev up` |
| `.env` | Local environment variables. The engine never reads it; your shell or process manager does |


# Upgrading the engine (/getting-started/upgrading-the-engine)

How to move a project to a new engine version, covering engine.version, the template contract and check --contract-report, migrations as an explicit deploy step, and the order to run things in.

Upgrading Meridian means running a new binary (or image) against your project and database. Your project files do not change unless the release notes say so. Three things tie a project to an engine: the engine major version it targets, the template contract its templates are written against, and the database migrations the engine has applied.

## What ties a project to an engine [#what-ties-a-project-to-an-engine]

| | Where it is | What checks it |
|---|---|---|
| The engine major version | `engine.version` in `config/engine.yaml`, such as `"1.x"` | `engine-dmo check` and every boot |
| The template contract | `template.contract` in `config/engine.yaml`, `1` when unset | `engine-dmo check` and every boot |
| The engine's own tables | The database, recorded per migration | `engine-dmo migrate status`, every boot, the readiness check |

`engine-dmo version` prints the binary's version and the template contract it implements:

```text
meridian v0.8.0 (vips) go1.27.3
  ...
  template contract 1
```

### engine.version [#engineversion]

```yaml
engine:
  version: "1.x"
```

`engine.version` names the engine major version the project is written for, as a major number followed by `.x`. Any other form is an error. A release binary from 1.0.0 on also refuses a project whose major differs from its own, with the error at this line and a hint to run the matching engine or upgrade the project and change the value. Releases before 1.0.0 check only the form, so on a 0.x engine the starter's `"1.x"` is accepted and the value protects nothing yet; it starts to matter at 1.0.0.

### The template contract [#the-template-contract]

The template contract is the versioned surface your templates use: the context, the globals, the functions and the filters. `template.contract` in `engine.yaml` selects it; it is `1` when unset, and `1` is the only contract this engine supports, so any other value is an error:

```text
config/engine.yaml:23:13: template.contract 2 is not supported by this engine; supported: 1
```

Before an engine supports a new contract, anything the next contract removes is reported as deprecated. List every such use in your templates, each with the form to write instead:

```bash
engine-dmo check --no-db --contract-report
```

```text
contract report: nothing the next contract version removes
```

Work through the list before you raise `template.contract`, then run `engine-dmo check` again.

## Migrations are a deploy step [#migrations-are-a-deploy-step]

A new engine version usually brings migrations: changes to the engine's own tables, separate from your schema. They are numbered per stream (core, and each module the binary compiles), they only move forward, and they run when you say so:

```bash
engine-dmo migrate status   # applied and pending; exits 2 if any are pending
engine-dmo migrate up       # apply every pending migration
engine-dmo migrate to 12    # apply up to and including core version 12
engine-dmo migrate to crm/3 # or up to a module's version 3
```

By default the server refuses to start while a migration is pending. Two settings change that, and neither is recommended in production because they hide the migration inside a restart:

| Setting | Effect |
|---|---|
| `engine-dmo serve --migrate` | Apply pending migrations, then serve, for this run |
| `migrate.on_boot: apply` in `engine.yaml` | Apply pending migrations on every boot. The default is `refuse` |

`migrate up` refuses a database whose encoding is not `UTF8`, and refuses to continue if an applied migration's file has changed since it ran. Migrations have no down step: to go back after one, restore the database backup you took before it.

`engine-dmo health --readiness` exits 0 only when startup is complete, the database answers and every migration the binary knows is applied, so a load balancer or deploy step never sends traffic to a process whose tables are not ready. `--wait 60s` keeps trying for that long.

## Schema drift at boot [#schema-drift-at-boot]

At boot the engine also compares your configuration with the schema in the database. What it does with a difference is `schema.on_drift`:

| Value | Effect |
|---|---|
| `refuse` | Refuse to start and print the plan. The default |
| `apply` | Apply the plan at boot; a destructive plan still needs its approval file |
| `warn` | Log the difference and start without applying it. Refused in production |

Run `engine-dmo schema apply` as its own step, after the migrations, so a schema change is planned and reviewed like any other.

## Upgrade a project [#upgrade-a-project]

The order matters: the new binary checks the project before anything changes, the backup comes before the migrations, and the new version serves only once its tables and schema are ready.

```mermaid
flowchart LR
  notes["Read the<br/>release notes"] --> check["check --no-db<br/>with the new binary"]
  check --> backup["Back up the<br/>database and media"]
  backup --> migrate["migrate up"]
  migrate --> schema["schema plan<br/>and apply"]
  schema --> start["Start serve and wait<br/>for health --readiness"]
  start --> refresh["Refresh editor schemas,<br/>AGENTS.md and skills"]
```

<Steps>
<Step>
### Read the release notes [#read-the-release-notes]

They list the migrations the release brings and anything you must change.
</Step>
<Step>
### Check the project against the new binary [#check-the-project-against-the-new-binary]

```bash
engine-dmo version
engine-dmo check --no-db --contract-report
```

Fix every error before going further. Run it in CI with the new image, so a project that does not pass never reaches a server.
</Step>
<Step>
### Back up the database [#back-up-the-database]

Take a backup you have restored before. Migrations cannot be undone any other way. The engine has no backup command: back up the database with `pg_dump` and, with the `filesystem` storage driver, copy the storage directory beside it ([Backups and restore](/deploying/backups-and-restore)).
</Step>
<Step>
### Migrate, then apply the schema [#migrate-then-apply-the-schema]

```bash
engine-dmo migrate up
engine-dmo schema plan
engine-dmo schema apply
```

Run these with the new binary, as one-off steps, before the new version starts serving.
</Step>
<Step>
### Start the new version [#start-the-new-version]

Start `engine-dmo serve` with the new binary and wait for `engine-dmo health --readiness`.
</Step>
<Step>
### Refresh the generated files [#refresh-the-generated-files]

```bash
engine-dmo config schema --write            # the editor schemas in .meridian/schema
engine-dmo guide --out AGENTS.md            # the project guide, which names the engine version
engine-dmo docs skill --out .claude/skills/meridian/SKILL.md
```

The `meridian` skill is the handbook's agents page from the binary that wrote it, so an agent reading it follows the engine you now run. Any `engine-dmo dev` verb also rewrites the agent files a project has.
</Step>
</Steps>

In a container deployment, run the migration and schema steps as one-off containers of the new image before the engine container starts. [Single-node deployment](/deploying/single-node) has a Compose file that does exactly this, [Upgrades](/deploying/upgrades) covers rolling upgrades and rolling back, and [Backups and restore](/deploying/backups-and-restore) covers backups and restores.

## Extensions [#extensions]

An extension is a Go plugin, and it opens only in an engine built with the same Go toolchain, platform, build flags and `meridian-extend` version; the engine refuses a mismatch and names it. `engine-dmo version` prints what the engine was built with on its `extensions:` line. Rebuild your own extensions for each engine upgrade; the first-party extensions ship inside the `-vips` image and always match it. See [Extending](/extending).


# Meridian (/)

What Meridian is, what the engine-cms and engine-dmo bundles each include, how this handbook is organised and where to start.

Meridian is a self-hosted content engine for place-based websites. You describe your content types, sites, locales and routes in YAML files, write templates, and run one binary against a PostgreSQL database. The same binary serves the public pages, the staff admin, the APIs and the background jobs.

This handbook is for the developer or integrator building a site on Meridian, and for the coding agent working alongside them. It describes the current engine, and only what is built.

## The two bundles [#the-two-bundles]

Meridian ships as one binary per bundle. A bundle is the core content platform plus a fixed set of modules compiled into it. Both binaries take the same commands and read the same project layout; a project written for `engine-cms` runs on `engine-dmo` unchanged.

| Binary | For | Modules compiled in |
|---|---|---|
| `engine-cms` | Any content site: pages, news, events, guides and collections | AI, Forms, Newsletter, Translation |
| `engine-dmo` | Destination marketing: everything in `engine-cms`, plus a directory of places and the businesses behind them | AI, Forms, Newsletter, Translation, Directory, CRM, Memberships, Member portal, Claims, Promotions, Member report, Affiliates, Paid listings |

Every module of `engine-cms` is also in `engine-dmo`, so the DMO bundle is a superset:

```mermaid
flowchart TB
  subgraph dmo["engine-dmo"]
    subgraph cms["engine-cms"]
      core["Core platform<br/>types, fields, locales, sites, publishing,<br/>media, search, API, MCP, admin, templates"]
      cmsmods["AI, Forms, Newsletter, Translation"]
    end
    dmomods["Directory, CRM, Memberships, Member portal,<br/>Claims, Promotions, Member report,<br/>Affiliates, Paid listings"]
  end
```

Both bundles include the core platform: the five core document types (`page`, `article`, `event`, `guide`, `collection`) and your own custom types, every field type, localisation with a shared structure and per-locale text, revisions and scheduled publishing, multiple sites on one install, the media library and image pipeline, search, navigation, redirects, declared endpoints, analytics, the content API, the content MCP, staff accounts with scoped roles, and the template language with its tooling.

`engine-dmo` adds the `listing` and `area` types, landing pages and embeddable widgets, organisations and people, membership tiers, the member portal and member API, ownership claims, paid promotion slots, member reports, affiliate links and paid listings. See [Modules and bundles](/concepts/modules-and-bundles) for what each module owns.

Run `engine-dmo version` (or `engine-cms version`) to see which bundle and modules a binary has:

```bash
engine-dmo version
```

## How this handbook is organised [#how-this-handbook-is-organised]

| Section | What it covers |
|---|---|
| [Getting started](/getting-started) | Getting and installing the engine, your first project, the project layout, the day-to-day development loop and upgrading |
| [Concepts](/concepts) | The ideas everything else rests on: sites, locales and routes; documents and publishing; modules and bundles; stable ids; users and permissions |
| [Content modelling](/content-modelling) | Content types, every field type, validation, relations, localisation, and planning and applying schema changes |
| [Templates](/templates) | The template language, the context, filters and tags, components, images, links, SEO, forms, multisite templates, the frontend build and template tests |
| [Features](/features) | Media, search, navigation, forms and enquiries, redirects, analytics, newsletters and AI assistance |
| [DMO](/dmo) | What `engine-dmo` adds: the directory, partners and the portal, CRM, claims, promotions, landing pages, affiliates, paid listings and member reports |
| [Extending](/extending) | Extensions built as Go plugins, and the first-party extensions |
| [Integrating](/integrating) | The content API, the content MCP, webhooks, and moving content in from another system |
| [Deploying](/deploying) | Configuration and secrets, the container images, a single-node deployment, backups, upgrades and monitoring |
| [Reference](/reference) | Every command, every configuration file, the template API and every error code |
| [For agents](/agents) | Rules, the order of work and recipes for a coding agent building a Meridian site |

## Reading the handbook as Markdown [#reading-the-handbook-as-markdown]

This handbook is published at https://docs.cherwell.studio and describes the current engine. `engine-dmo version` says which engine you have; if a page describes something your binary does not do, upgrade the engine to get the newer behaviour.

| Address | What it is |
|---|---|
| `https://docs.cherwell.studio/llms.txt` | Every page by title, address and description |
| `https://docs.cherwell.studio/llms-full.txt` | The whole handbook as one Markdown file |
| `https://docs.cherwell.studio/llms.mdx/concepts/stable-ids/content.md` | One page as Markdown |

Inside a project, `engine-dmo docs serve` serves that project's generated [template API](/reference/template-api) on localhost.

## Where to start [#where-to-start]

<Cards>
  <Card title="Install the engine" href="/getting-started/install">
    What you need: the binary or a container image, PostgreSQL, and optionally a search service and a mail service.
  </Card>
  <Card title="Your first project" href="/getting-started/first-project">
    Create a project, apply it to a database, seed it, serve it and sign in to the admin.
  </Card>
  <Card title="The development loop" href="/getting-started/development-loop">
    The commands you run every day: dev up, check, schema plan and apply, render and guide.
  </Card>
  <Card title="Concepts" href="/concepts">
    Sites, locales, routes, documents, revisions, publishing, modules, ids and permissions.
  </Card>
  <Card title="For agents" href="/agents">
    The working rules and recipes for a coding agent building a site with this handbook.
  </Card>
</Cards>


# Content API (/integrating/content-api)

The read-only JSON content API at /api/content/v1: turning it on, publishable and secret keys and their capabilities, CORS, every operation and parameter, the document representation and each field type's delivered shape, queries with filters, facets and cursors, caching headers and cache tags, every error code, and the rate limits.

The content API delivers a site's published content as JSON, for a frontend you build yourself (see [Headless sites](/integrating/headless-sites)), a static site generator, a mobile app or a sync job. It is read-only: it answers what an anonymous visitor to the site may see, never drafts (except through a preview token), never CRM records, and nothing a key's holder could not see on a rendered page. Its only writes are form posts and analytics events, each behind a capability.

`engine-cms` serves the same API.

## A first request [#a-first-request]

<Steps>
<Step>
Turn it on in `engine.yaml` (it is off by default):

```yaml
# config/engine.yaml
server:
  api:
    content:
      enabled: true
```
</Step>
<Step>
Issue a key for the site. The value is printed once:

```bash
engine-dmo api keys create --name "Astro frontend (production)" --kind secret --site main --project .
```
</Step>
<Step>
Read with it, sending the key as a bearer token:

```bash
curl -H "Authorization: Bearer $MERIDIAN_KEY" \
  "https://cms.example.org/api/content/v1/sites/main/resolve?path=%2Fwhats-on%2Fsummer-fair"
```
</Step>
</Steps>

The answer to `resolve` tells the frontend what the path is (a document, an index, a redirect, gone or not found), with the document's representation and the page's metadata. [Headless sites](/integrating/headless-sites) walks through building a frontend on it.

## Configuration [#configuration]

| Key in `engine.yaml` | Default | Limits | Meaning |
|---|---|---|---|
| `server.api.content.enabled` | `false` | | Serves `/api/content/v1/`. A headless site with it off is a check error. |
| `server.api.content.public_reads` | `false` | | `true` serves a published read that carries no key as the anonymous visitor, rate limited per address, with CORS for the site's frontend origin only. A key, when sent, is checked as always; preview, events, forms and the change feed always need a key. |
| `server.api.content.cache.s_maxage` | `60s` | `0s` to `24h` | How long a shared cache (a CDN) may serve a published response. |
| `server.api.content.cache.stale_while_revalidate` | `10m` | `0s` to `168h` | How long past that a cache may serve it while fetching a fresh one. |
| `server.api.content.cache.tag_header` | `Cache-Tag` | `Cache-Tag`, `Surrogate-Key` or `none` | The response header the cache tags travel in. |
| `server.api.content.preview_ttl` | `30m` | `1m` to `2h` | A preview token's life. |
| `server.api.content.change_retention` | `90d` | `1d` to `400d` | How far back the change feed reaches. |

The API answers on any host that reaches the engine. You may give it a host of its own (such as `api.example.org`) so a CDN can cache and limit it without path rules.

## Keys [#keys]

| | Publishable | Secret |
|---|---|---|
| Prefix | `mrd_pub_` | `mrd_sec_` |
| Lives in | Browser code, an app, a static build | The frontend's server, and nowhere else |
| Reads published content | Yes | Yes |
| Capability `preview` (redeems preview tokens) | Not allowed | Optional |
| Capability `events` (posts analytics events) | Not allowed | Optional |
| Capability `forms` (form descriptions and posts) | Optional, from an allowed origin | Optional, forwarding the visitor's address |
| Reads the change feed | No | Yes |
| CORS | For its listed origins only | Never: a request with an `Origin` header is refused and the key is marked exposed |
| Rate limited | Per key and per visitor address | Per key |

- **Sent as `Authorization: Bearer <key>`**, never in a query string.
- **A key names the sites it reads.** A request for another site is `key_not_for_site`.
- **Shown once.** The engine keeps only a hash; lists show the prefix and the last four characters.
- **Rotation needs no downtime.** Any number of keys can be live for a site, each with an optional expiry. `rotate` issues a new key like an existing one and keeps the old one working for a grace period.
- **An exposed secret key** (one sent from a browser with an `Origin` header) is refused, marked exposed in `api keys list` and the admin, and reported in `engine-dmo doctor`. It is not revoked automatically: rotate it.
- **CORS.** A publishable key's origins are its allowlist; a key with none allows the frontend origin of each headless site it reads, and nothing else. An allowed origin gets `Access-Control-Allow-Origin` naming it, with `ETag`, `RateLimit`, `RateLimit-Policy` and `Retry-After` exposed. Every site operation answers `Vary: Origin`. A preflight (`OPTIONS`) answers 204 for an allowed origin with `GET, HEAD` (and `POST` with `Content-Type` for a form), the `Authorization` and `If-None-Match` headers, and a ten minute `Access-Control-Max-Age`. `Meridian-Preview` is never allowed from a browser.
- **A key carries no person.** It cannot reach any staff or member capability.

Keys are managed by staff holding `api.keys.manage` (seeing them needs `api.keys.view`), in the admin under **Settings, API keys** (`<admin_path>/api/keys`) or from the command line. Each change is audited with the key's id, never its value.

```bash
engine-dmo api keys create --kind publishable --name "Site search widget" --site main \
  --capability forms --origin https://www.example.org --expires 2160h --project .
engine-dmo api keys list [--site main] --project .
engine-dmo api keys rotate --id <key-id> --grace 24h --project .
engine-dmo api keys revoke --id <key-id> --confirm --project .
```

| Flag of `create` | Meaning |
|---|---|
| `--kind` | `publishable` or `secret`. |
| `--name` | What the key is for. |
| `--site` | A site the key reads; repeat or comma separate for several. |
| `--capability` | `preview` (secret keys), `events` (secret keys) or `forms`; reading published content is implied. |
| `--origin` | A publishable key's allowed browser origin; repeat for several. None allows each headless site's frontend origin. |
| `--expires` | A duration (`2160h`) or a time (`2027-01-01T00:00:00Z`); never when absent. |

`rotate --grace` is how long the old key keeps working (default `24h`; `0` ends it now). `revoke` needs `--confirm`; requests with a revoked key answer `invalid_key`.

## Operations [#operations]

Every path is under `/api/content/v1`. Every read takes `locale` (a locale the site enables; the site's default when absent, `invalid_parameter` for any other).

| Method and path | Answers | Notes |
|---|---|---|
| `GET /openapi.json` | The OpenAPI 3.1 contract, the install's types included | No key; cacheable |
| `GET /sites/{site}` | The site: key, name, `delivery_mode`, `origin`, `default_locale`, locales with their fallback chains, direction and prefix, routes with their URI patterns and index paths, singletons by type (ids), navigation trees in the locale, SEO defaults, robots rules | |
| `GET /sites/{site}/schema` | JSON Schema (draft 2020-12) of each of the site's types as delivered | Generate typed clients from it |
| `GET /sites/{site}/resolve?path=` | A path's outcome, as the rendered site would resolve it | See [Resolve](#resolve) |
| `GET /sites/{site}/documents/{id}` | One published document | `expand`, `fields`, `occurrences_window` |
| `GET /sites/{site}/documents/{type}/{slug}` | One document of a type by its slug in the locale, or down the site's locale chain | As above |
| `GET /sites/{site}/singletons/{type}` | The site's one document of a singleton type | 404 when the type is not a singleton on the site, or nothing is published in the locale |
| `GET /sites/{site}/documents?type=` | A query over published documents | See [Queries](#queries) |
| `GET /sites/{site}/curations/{id}` | A guide's items, or a page of a collection's list, as summaries | `page` |
| `GET /sites/{site}/lists/{key}` | A public smart list as the site sees it | A list that is not public, or another site's, is `not_found` |
| `GET /sites/{site}/search?q=` | The search service | See [Search](#search) |
| `GET /sites/{site}/tags` | The public tag vocabulary as a tree, labelled in the locale | |
| `GET /sites/{site}/sitemap` | Sitemap entries, 1,000 a page: every published, indexable, unredirected URL with its alternates and images | `locale`, `cursor` |
| `GET /sites/{site}/redirects` | The compiled redirect rules in the order they are tried, for an edge function | `resolve` applies them anyway |
| `GET /sites/{site}/strings` | The interface strings of `config/strings` resolved down the locale's chain, plural forms intact | |
| `GET /sites/{site}/preview` | The document a preview token names, with its working revisions | Secret key with `preview`; see [Headless sites](/integrating/headless-sites#preview) |
| `GET`, `POST /sites/{site}/forms/{key}` | A declared public `post` endpoint's form description, and its submission | Key with `forms`; see [Headless sites](/integrating/headless-sites#forms) |
| `POST /sites/{site}/events` | Analytics events from the frontend's server | Secret key with `events`; see [Headless sites](/integrating/headless-sites#analytics) |
| `GET /sites/{site}/changes?since=` | The change feed | Secret key; see [Headless sites](/integrating/headless-sites#the-change-feed) |

`engine-dmo api openapi` prints the generic contract from this binary; with `--types`, the document `/openapi.json` serves, your types included. `engine-dmo api schema --site <key> [--format jsonschema|openapi]` prints a site's types alone.

## Resolve [#resolve]

```text
GET /api/content/v1/sites/main/resolve?path=%2Fja%2Fwhats-on%2Fsummer-fair
```

| Parameter | Meaning |
|---|---|
| `path` | The visitor's request path with its query string, URL-encoded as one parameter, so facets, `page` and `sort` resolve as on a rendered site. |
| `host` | The request host, for a site whose locales are by domain. |
| `record` | `false` records no miss in the 404 report: for builds and link checkers. |
| `expand`, `fields`, `occurrences_window` | As for a document. |

The locale comes from the path by the site's strategy. Redirects are matched first, in the rendered site's precedence. The answer is always HTTP 200; what to send the visitor is in the body:

| `outcome` | `status` to send | Carries |
|---|---|---|
| `document` | 200 | `document`, `page`, `analytics` |
| `index` | 200 | `type`, `items` (summaries), `pagination`, `facets`, `page` |
| `redirect` | 301, 302, 307 or 308 | `location`, and the `origin` of the rule that matched (or the engine's own answer: `auto_case`, `auto_segment`) |
| `gone` | 410 | `page` |
| `not_found` | 404 | Nothing; the miss is recorded in the 404 report unless `record=false` |

Every answer also carries `site`, `path` and `locale`.

`page` is the page metadata the rendered site's `head()` and `jsonld()` would print:

| Key | Meaning |
|---|---|
| `title`, `description` | The title (with the site's `seo.title_template` applied) and description. |
| `canonical` | The canonical URL, for paginated and filtered pages too. |
| `robots` | Such as `index, follow`; `noindex` on staging and past the facet depth. |
| `content_language` | The page's language. |
| `alternates` | `{hreflang, url}` for each locale published on the site, and `x-default`. |
| `open_graph` | `title`, `description`, `type`, `url`, `site_name`, `locale` and `image` (`url`, `width`, `height`, `alt`). |
| `twitter_card` | The card type. |
| `breadcrumbs` | `{title, url}` from the root. |
| `prev`, `next` | Pagination links, or null. |
| `json_ld` | The page's structured data as one `@graph`. |

`analytics` is `{view, collect}`: a signed view token for the document and the path to report it to. See [Headless sites](/integrating/headless-sites#analytics).

`engine-dmo api resolve <path> [--site key] [--host host] --project .` prints the same answer from the command line, recording no miss.

## The document representation [#the-document-representation]

```json
{
  "id": "0191f0c2-7a51-7c3e-9d0a-5b2f6c1e4a88",
  "type": "event",
  "variant": null,
  "site": "main",
  "locale": "en-GB",
  "requested_locale": "en-GB",
  "fallback": false,
  "uri": "/whats-on/summer-fair",
  "url": "https://www.example.org/whats-on/summer-fair",
  "slug": "summer-fair",
  "title": "Summer fair",
  "published_at": "2026-08-14T09:12:00Z",
  "updated_at": "2026-09-02T16:40:11Z",
  "translations": {
    "ja-JP": { "uri": "/ja/whats-on/summer-fair", "url": "https://www.example.org/ja/whats-on/summer-fair" }
  },
  "tags": [ { "key": "family", "label": "Family", "kind": "topic", "parent": null } ],
  "fields": {
    "summary": "Stalls, music and a dog show on the green.",
    "location": { "lat": 52.0629, "lon": -1.3398, "precision": "exact" },
    "ticketPrice": { "amount": "5.00", "currency": "GBP", "formatted": "£5.00" }
  }
}
```

- Envelope keys are snake_case. Field values are under `fields` by the schema's own field names, so a field never collides with an envelope key.
- `locale` is the language the content is in; `requested_locale` what was asked for. `fallback` is true when the whole document fell back along the site's locale chain.
- `translations` lists the other locales published on this site.
- `tags` are public vocabulary tags only, labelled in the response locale.
- The representation carries no organisation, no parent document and no analytics impression or click tokens. On `engine-dmo`, the member report's referral figures for a listing delivered through the API come only from the events the frontend reports with the `resolve` answer's analytics token (see [Analytics](/integrating/headless-sites#analytics)); the tracked member links a rendered page writes are not available.
- `variant` is the entry variant where the type declares variants, and `fields` holds that variant's fields.
- Site overrides are applied for the site in the path.
- Every field of the type is present under `fields`, `null` when empty, and every key of a delivered object is present, `null` when it has no value: test values, not keys.

### Field values [#field-values]

| Field type | Delivered as |
|---|---|
| `text`, `slug` | A string. |
| `number` | A number. |
| `boolean` | A boolean. |
| `date` | `"YYYY-MM-DD"`. |
| `datetime` | `{iso, zone, local, all_day}`: RFC 3339 UTC, the IANA zone, the wall clock as `YYYY-MM-DDTHH:MM:SS`, and whether it is a whole day. |
| `select` | `{value, label}` with the label in the locale, or a list of them. |
| `portable_text` | `{blocks, plain}`: Portable Text JSON (no HTML), and the plain text for descriptions and snippets. A link annotation is resolved as a link field is; a mention is reduced to `{_key, _type: "mention"}`; an object block is `{_type, _key, ...fields}`, each field delivered by its own type. |
| `relation` | A summary `{id, type, title, slug, uri, url, locale}`, or a list. A target not visible on the site in the locale is `null`, or left out of a list; `slug`, `uri` and `url` are null for a target with no route on the site. Expanded, the full representation. |
| `asset` | An image: `{id, kind, url, mime, alt, alt_lang, decorative, caption, caption_lang, credit, width, height, focal, hotspot, crop, preview, dominant, transforms}`. `transforms` holds each of the site's configured image transforms as `{width, height, src, srcset: [{url, width, format}]}`; there are no size parameters. `preview` is a blur placeholder as a data URI and `dominant` the colour as `#rrggbb`. A document, audio or video file is `{id, kind, url, filename, bytes, mime}`. A list with `multiple: true`. |
| `link` | `{kind, of, url, uri, label, title, aria_label, new_tab, rel, style, external, live, document, asset, tracked, tracked_url}`, or a list. `url` is the address to write; `uri` the site-relative path for a router. A link whose target is not live is null, or left out of a list. `tracked` and `tracked_url` are always null in this release, including for a member's destination link. |
| `video` | `{id, source, url, watch_url, embed_url, title, poster, duration, start, captions, transcript}`. |
| `geo` | `{lat, lon, precision}`. |
| `geo_shape` | `{geometry, bbox, centroid, area_km2}`: GeoJSON geometry, `bbox` as `[west, south, east, north]`. |
| `address` | `{lines, one_line, country, country_name, components, geo}`. |
| `phone` | `{e164, national, international, display, region, type, tel_href}`; a number that does not parse keeps what was typed as `display`, with `e164` and `tel_href` null. |
| `opening_hours` | `{timezone, by_appointment, note, days, rules, valid_until}`. `days` is the next 14 days, resolved through seasons, exceptions and holidays: `{date, closed, source, note, periods: [{opens, closes, opens_at, closes_at}]}`, wall times and UTC instants both, so "open now" is a comparison. `valid_until` is the next local midnight. |
| `recurrence` | `{rule, occurrences, valid_until}`: the next 90 days of occurrences (more with `occurrences_window`), cancelled and moved ones included with their `status` and `note`. |
| `money` | `{amount, currency, formatted}`: the amount as a decimal string, the ISO 4217 currency, and the amount written for the locale. |
| `seo` | `{title, description, og_title, og_description}`. |
| `repeater` | A list of objects, each with `_key` and its fields. |
| `blocks` | A list of `{_type, _key, ...fields}`; a block the field no longer declares is left out. |

The exact schema of every shape is in `engine-dmo api openapi` under `components.schemas` (`Field.<type>`), and your own types' in `engine-dmo api schema`.

### Expansion and sparse fields [#expansion-and-sparse-fields]

- `expand=area,organiser` replaces the named relations with full representations, to two levels (`expand=area.parent`) and at most 100 expanded documents per response. An expanded document obeys the same visibility.
- `fields=title,heroImage,area.title` limits `fields`, inside expansions too. The envelope is always present. A name that is not a field is `invalid_parameter` naming it.
- `occurrences_window=180d` delivers that many days of recurrence occurrences (default 90), up to the range the engine has materialised.

## Queries [#queries]

```text
GET /api/content/v1/sites/main/documents
  ?type=event
  &locale=en-GB
  &tag=family
  &where[free]=true
  &where[startDate][gte]=2026-11-01
  &near=52.0629,-1.3398&radius=10
  &order=distance
  &per_page=24&page=2
  &facets=category
  &fields=title,startDate,heroImage
```

| Parameter | Meaning |
|---|---|
| `type` | Required; may repeat. |
| `tag` | A public tag's key, or `key.*` for it and every tag below; may repeat, and each must match. |
| `where[field]=value`, `where[field][op]=value` | A filter on an `index: true` field. `op` is `eq` (the default), `ne`, `in` (comma separated), `gt`, `gte`, `lt`, `lte` or `exists` (`true` or `false`). A field that is not indexed is `unindexed_filter`, naming the field. |
| `near`, `radius` | A point `lat,lon` over the type's indexed `geo` field, and kilometres (10 by default). |
| `order` | `title`, `published_at`, `-published_at`, `updated_at`, `distance` (with `near`), or an indexed field; `-` for descending. The type's declared ordering by default. |
| `page`, `per_page` | Numbered pages: `per_page` is 24 by default and at most 100; numbered pages reach the first 2,000 results. |
| `cursor` | Iterates the whole set by id in a stable order with no total: empty to begin, then each answer's `next_cursor`. Use it for a build or a sync. |
| `facets` | Indexed fields to count values of over the filtered set, comma separated. |
| `fields`, `expand`, `occurrences_window` | As for a document. |

The answer is `{items, pagination, facets, next_cursor}`: `items` are full representations, `pagination` is `{page, pages, total, per_page}` (null when iterating by cursor), and `facets` maps each field to its values with counts. Only published documents of types on the site, available in the locale with its fallback, are ever returned.

## Search [#search]

`GET /sites/{site}/search` calls the site's search service, with its query log, visibility and facets. Parameters: `q` (below the configured minimum length it is browse), `type` and `tag` (each may repeat), `near` and `radius`, `sort` (`relevance`, `name`, `distance` or `recent`), `page` and `per_page` (20 by default, at most 100). The answer is `{query, sort, backend, degraded, total, items, pagination, facets}`; each item is `{id, type, title, summary, uri, url, tags, position, distance, highlight}`. `degraded: true` means the search backend is down and the answer is browse mode, so the frontend can say so.

## Caching [#caching]

- **Published responses** carry `Cache-Control: public, max-age=0, s-maxage=<s_maxage>, stale-while-revalidate=<stale_while_revalidate>` and a strong `ETag`; a request with a matching `If-None-Match` is answered 304. They do not vary by key (the site is in the path), so a CDN may cache them despite the `Authorization` header. They vary by `Origin`.
- **Cache tags** in the configured header (`Cache-Tag`, comma separated, or `Surrogate-Key`, space separated) name what the response holds: `site:<key>`, `type:<key>`, `doc:<id>`, and the like. The change feed and the frontend webhooks carry the tags to purge.
- **Time-bounded values**: a response holding `opening_hours` days or `recurrence` occurrences caps `s-maxage` at its earliest `valid_until`, so a cached week of opening times is never served past the midnight it describes.
- **Preview, form, events and change feed responses** are `private, no-store`.

## Errors [#errors]

Every failure is an RFC 9457 problem with `Content-Type: application/problem+json`:

```json
{
  "type": "urn:meridian:content-api:problem:unindexed_filter",
  "code": "unindexed_filter",
  "title": "...",
  "status": 400,
  "detail": "...",
  "parameter": "where[price]"
}
```

| `code` | Status | When |
|---|---|---|
| `invalid_key` | 401 | Missing, unknown, expired or revoked key |
| `key_exposed` | 401 | A secret key sent with an `Origin` header |
| `key_not_for_site` | 403 | The key does not name the site |
| `origin_not_allowed` | 403 | A publishable key from an origin it does not allow, or a disallowed preflight |
| `capability_missing` | 403 | Preview, events, forms or the change feed without the capability or key kind |
| `preview_expired` | 401 | A preview token past its life, or its staff session has ended |
| `preview_invalid` | 401 | A preview token altered, from another install, or for another site |
| `unknown_site` | 404 | No such site |
| `not_found` | 404 | A document, list or form that does not exist or is not visible, answered alike |
| `unindexed_filter` | 400 | A filter or order on a field without `index: true` |
| `invalid_parameter` | 400 | A bad parameter, named in `parameter`; unknown names in `fields` and `expand` included |
| `limit_exceeded` | 400 | `per_page`, the 2,000 result window, or the expansion ceiling |
| `validation_failed` | 422 | A form post's input, with `field_errors` as `{path, code, message}` |
| `rate_limited` | 429 | With `Retry-After` and `RateLimit` headers |
| `internal` | 500, 503 | The engine could not answer; 503 when the key store could not be read, which a client retries |

## Rate limits [#rate-limits]

| Surface | Limit |
|---|---|
| Publishable key | 1,200 weighted requests a minute per key, and 120 a minute per visitor address |
| Secret key | 6,000 weighted requests a minute per key |
| Keyless reads under `public_reads` | Per visitor address |
| Weights | A query 2, a search 5, every other operation 1; facets add 1; each level of `expand` adds 1 |
| Events | 20 requests a second per key |
| Form posts | The endpoint's own `rate_limit`, keyed on the visitor |
| Failed key authentication | 20 an hour per address, then refused before the key is looked up |
| Preview token redemption | 600 an hour per token |

Rate limits are operational and fail open if they cannot be counted, except failed authentication, which fails closed.

## Versioning [#versioning]

The path carries the major version, `/api/content/v1/`. Changes within a version are additive: new operations, parameters, envelope keys and field shape keys may appear, so a client must ignore keys it does not know. `info.version` in the OpenAPI document names the contract's revision. Your own types are part of the contract: removing or renaming a field of a type a frontend reads changes what the API delivers, so plan schema changes with the frontend.

## Static export [#static-export]

`engine-dmo export content --site <key> --out ./content --project .` writes the API's own answers to disk for a static build: `site.json`, `strings/<locale>.json`, `sitemap.json`, `redirects.json`, `pages/<path>.json` (the `resolve` outcome of every index and every published path in every enabled locale, the root as `pages/index.json`) and `manifest.json`, which records the change feed's `cursor` when the export began. `--since <cursor>` writes only what changed after a previous export's cursor, removes the files of paths that went away and lists them in `deleted.json`; a cursor older than the change retention fails and asks for a full export. Images are not exported: they stay on the engine's (or your CDN's) origin.


# Content MCP (/integrating/content-mcp)

How to connect an AI agent (Claude or any Model Context Protocol client) to a Meridian site: turning the endpoint on, OAuth sign-in and the consent choices, the mcp configuration block, registering clients, personal access tokens and engine-dmo mcp call for scripts, engine-dmo mcp over stdio for local development, the tools, resources and prompts, limits, and what to tell a data protection officer.

The content MCP lets a member of staff connect their own AI agent to a site, through the Model Context Protocol, so the agent can read content and write drafts **as that person and never as more**: it sees what they may see, writes where they may write, and publishes only where they could publish in the admin, through the same review workflow and checks. Everything it writes is recorded as written through an agent, for whom and by which client.

Meridian does not choose the model, send content to one through this channel, or see the agent's reasoning: the person chooses the client, and the client its model. Meridian's own AI assistance features are separate (see [AI assistance](/features/ai-assistance)).

There are two ways in:

| | Remote endpoint | `engine-dmo mcp` over stdio |
|---|---|---|
| For | Staff and their agents, on a running install | A coding agent working on a project on your machine |
| Address | `https://<admin host><admin_path>/mcp` | A child process the agent starts |
| Sign-in | OAuth 2.1 with PKCE through the admin's sign-in, or a personal access token | None: every call acts as the staff user `--as` names |
| Allowed in | Every environment, when `mcp.enabled` | Development; in staging only with `dev.authoring: true`; never in production |

`engine-cms` serves the same MCP, with the toolsets of its own modules.

## Turning it on [#turning-it-on]

```yaml
# config/engine.yaml
mcp:
  enabled: true
  personal_data: refuse     # the default
```

Then decide who may connect. The verb `mcp.connect`, judged per site, is held by the built-in Administrator and Editor roles and not by Translator or Contributor; move it in your roles like any permission. A person without it on a site cannot connect an agent for that site, and losing it takes the site out of their connections on the next call.

Before deciding, list what an agent can do on your bundle:

```bash
engine-dmo mcp tools --project .          # tools, resources and prompts, with their toolsets
engine-dmo mcp tools --json --project .   # with every tool's input and output schema
```

## Connecting a client [#connecting-a-client]

The endpoint is a standard remote MCP server with OAuth discovery, so a client finds the sign-in by itself. Give it the endpoint's address, such as `https://studio.example.org/studio/mcp`.

- **Claude Code**: `claude mcp add --transport http meridian https://studio.example.org/studio/mcp`, then `/mcp` in a session to sign in. The browser opens the admin's sign-in, then the consent screen.
- **Claude on the web or the desktop app**: add a custom connector with the endpoint's address; sign-in and consent open in the browser.
- **Any other client** supporting the MCP authorisation flow (protocol revision 2025-06-18 or later; the endpoint answers 2026-07-28, 2025-11-25 and 2025-06-18).

The endpoint publishes its OAuth metadata at `/.well-known/oauth-protected-resource<admin_path>/mcp` and `/.well-known/oauth-authorization-server<admin_path>/oauth`.

The client does the whole sign-in itself, from the first refused call to the first tool call; the person sees only the admin's sign-in and the consent screen. The diagram uses the default admin path, `/studio`:

```mermaid
sequenceDiagram
  participant C as MCP client
  participant B as Browser
  participant E as Engine
  C->>E: POST /studio/mcp (no token)
  E-->>C: 401, WWW-Authenticate: resource_metadata
  C->>E: GET the protected resource and server metadata
  E-->>C: authorize and token endpoints, S256 only
  C->>B: open /studio/oauth/authorize<br/>with code_challenge
  B->>E: authorize request
  E->>E: identify the client (metadata document,<br/>configured, or registered)
  E-->>B: admin sign-in and second factor, if needed
  E-->>B: consent screen
  B->>E: approve choices
  E-->>B: redirect to redirect_uri with a code
  B-->>C: code
  C->>E: POST /studio/oauth/token<br/>code and code_verifier
  E-->>C: access token (1 hour) and refresh token
  C->>E: POST /studio/mcp, Bearer token
  E-->>C: tool results, as the person
```

When the access token lapses the client exchanges its refresh token at the same token endpoint; refresh tokens rotate, and one used twice ends the connection.

### How clients register [#how-clients-register]

| Way | Configuration | Consent screen shows |
|---|---|---|
| Client metadata document (the client's `client_id` is a URL of a JSON document describing it) | `mcp.registration.metadata_documents: true`, the default | The host of the metadata document |
| A client an administrator configured | `mcp.clients` | Its configured `name` |
| Dynamic registration (RFC 7591) | `mcp.registration.dynamic: true`; off by default | The name it registered |

Configure a client when your organisation's agent platform cannot register itself:

```yaml
# config/engine.yaml
mcp:
  enabled: true
  clients:
    - id: acme-agents                 # the client_id the client sends
      name: Acme agent platform       # shown on the consent screen
      redirect_uris:
        - https://agents.acme.example/oauth/callback
        - http://127.0.0.1:33418/callback
```

A client's `id` must not be a URL (a URL client id is a metadata document, which needs no configuration) and must be unique; `name` and at least one redirect URI are required; each redirect URI is `https`, or `http` on a loopback address, with no fragment.

## The consent screen [#the-consent-screen]

Every choice only takes away from what the person may already do; none grants anything.

| Choice | What it means | Default |
|---|---|---|
| Sites | Which sites the agent may work on, among those where the person holds `mcp.connect` | The site they were on |
| Locales | Which languages it may edit | All the person may edit |
| What it may do | Toolsets. *Read* is always on. *Create and edit drafts* (`content`), *Media*, *Notes*, *Tags, smart lists and navigation* (`structure`), *Bulk changes*, and one for each module the bundle has | Read, content, media and notes |
| Typed tools | Up to eight content types given their own `create_<type>` and `update_<type>` tools, which some models use more reliably | None |
| Publishing | *As my permissions allow*: when asked, it publishes where the person could and sends to review where their changes go to review. *Drafts only*: it never publishes | As my permissions allow; every write is still a draft unless a call asks to publish |
| Expires | 1, 7, 30 or 90 days, at most `mcp.tokens.connection_max` | 30 days |

The screen also says, in plain sentences, what the agent will be able to do, that it acts as the person and is recorded under their name, and that what it reads leaves the install for the client and its model. A connection that is *Drafts only* and asked to publish is refused in a way the client can show ("connect again with publishing allowed").

The *People* toolset (CRM personal data, `engine-dmo` only) is offered only when `mcp.personal_data: allow`.

## Seeing and ending connections [#seeing-and-ending-connections]

- **You, Agents and tokens** (`<admin_path>/you/agents`): your own connections and tokens, with the client, the sites and toolsets chosen, when each was last used and how many writes it made this week. End one, or all.
- **Settings, Agent connections** (`<admin_path>/settings/agents`, for people with `users.manage`): every connection on the install, filterable by person, client and site. End any, or block a client.
- The editor and the revision history name the agent on every revision it wrote, the approvals queue marks agent-written changes, and content lists can be filtered to "written by an agent".

Suspending a person ends their connections at once.

## Personal access tokens for scripts [#personal-access-tokens-for-scripts]

A script that moves content (a nightly sync, a one-off bulk tag) uses a **personal access token**, made on **You, Agents and tokens** with the same choices as consent plus a kind: *agent* (a model drives it) or *script* (deterministic code, whose writes are not counted as AI assisted). It is sent as `Authorization: Bearer mrd_pat_...` to the same endpoint. A token belongs to a person and ends with them: there are no service accounts.

From a shell:

```bash
export MERIDIAN_TOKEN=mrd_pat_...
engine-dmo mcp call documents_search \
  --url https://studio.example.org/studio/mcp \
  --args '{"site": "main", "query": "summer fair"}'
```

| Flag | Meaning |
|---|---|
| `--url` | The endpoint's address (required). |
| `--token-env` | The environment variable holding the token, `MERIDIAN_TOKEN` by default. The token is never a command line argument. |
| `--args` | The tool's arguments as a JSON object. |

It prints the tool's structured result as JSON; a tool error exits non-zero with its JSON on standard output. Read a tool's arguments with `engine-dmo mcp tools --json`.

## engine-dmo mcp over stdio [#engine-dmo-mcp-over-stdio]

For a coding agent working on a project locally, the engine serves the same tools over standard input and output (newline-delimited JSON-RPC), every call acting as one staff user with exactly their grants:

```bash
engine-dmo mcp --as editor@example.org --project /path/to/project
```

```bash
claude mcp add meridian -- engine-dmo mcp --as editor@example.org --project /path/to/project
```

The process needs the project's environment (`DATABASE_URL` and the rest) and a migrated database.

| Flag | Meaning |
|---|---|
| `--as` | The staff user every call acts as, by email (required). |
| `--site` | The site a call that names none is for; the project's default site when absent, the first of `--sites` when that is set. |
| `--sites` | Narrow to these sites, comma separated. |
| `--toolsets` | Narrow to these toolsets, comma separated; `read` is always included. |
| `--types` | Give these types typed tools, comma separated, at most eight. |
| `--drafts-only` | Never publish, as a *Drafts only* connection. |

It is refused when `engine.environment` is `production`, and in `staging` unless `dev.authoring: true`. The narrowing flags only remove, as consent does.

## What an agent can do [#what-an-agent-can-do]

`engine-dmo mcp tools` lists exactly what your bundle offers. On `engine-dmo`:

| Toolset | Tools |
|---|---|
| `read` (always) | `sites_list`, `types_list`, `type_describe`, `documents_search`, `document_get`, `document_history`, `singleton_get`, `translation_status`, `notes_list`, `picker_search`, `media_search`, `media_get`, `tags_list`, `smart_lists_list`, `smart_list_get`, `content_check`, `preview_link`, `bulk_status` |
| `content` | `document_create`, `document_update`, `document_clone`, `document_trash`, `document_restore`, `document_sites_set`, `document_override_set`, `document_variant_set`, `publish`, `unpublish`, `review_request`, `schedule_cancel`, `landing_content_get`, `landing_content_set` |
| `media` | `media_upload`, `media_upload_url`, `media_upload_page`, `media_upload_page_get`, `media_text_set`, `media_rights_set` |
| `notes` | `note_add` |
| `structure` | `tag_create`, `smart_list_save`, `navigation_get`, `navigation_edit` |
| `bulk` | `bulk_plan`, `bulk_apply` |
| `crm` | `organisations_search`, `organisation_get`, `organisation_update` |
| `people` | `people_search`, `person_get` (only with `mcp.personal_data: allow`) |
| `newsletter` | `newsletter_campaigns_list`, `newsletter_campaign_get`, `newsletter_campaign_draft` |
| `affiliates` | `affiliate_programmes_list`, `affiliate_links_list`, `affiliate_link_create` |
| `claims` | `claims_list`, `claim_get` (read only) |
| `promotions` | `promotions_list`, `promotion_request_get`, `promotion_slots_list` (read only) |
| `paidlistings` | `paid_orders_list`, `paid_order_get` (read only) |

Resources: `meridian://rules` (rules for agents), `meridian://sites`, `meridian://sites/{site}/schema`, `meridian://sites/{site}/guidance` and `meridian://sites/{site}/guidance/{type}` (the site's editorial guidance), `meridian://types/{type}` and `meridian://documents/{id}`. Prompts: `draft_article` (site, type, topic, sources), `fix_content_health` (site, type) and `translate_document` (document, target locale, source locale), each in the `content` toolset.

An agent cannot purge or export content, change users, settings or permissions, read the audit log, act as a member, call Meridian's own AI features, send a newsletter or broadcast, change a price, create an order, or decide a claim, a promotion or a membership. Those stay with a person in the admin.

### Photos from a phone [#photos-from-a-phone]

An agent in a chat app cannot pass a photo's file to the install, so `media_upload_page` gives the person a one-time link instead. They open it on their phone, pick photos (20 unless the agent asked for another number, never more than 30), and go back to the conversation; the agent then sees the photos with `media_upload_page_get`, writes their alt text and puts them where asked. The link needs no sign-in (the link is the key), works for an hour, and ends when the connection ends. The photos are stripped of location and camera metadata like any upload, and are not published until a published page uses them; a page with a photo still missing alt text cannot be published. The agent needs the *Media* toolset and the person must be allowed to upload.

## Configuration [#configuration]

| Key in `engine.yaml` | Default | Limits | Meaning |
|---|---|---|---|
| `mcp.enabled` | `false` | | Serves `<admin_path>/mcp` and its OAuth endpoints. |
| `mcp.personal_data` | `refuse` | `refuse` or `allow` | Whether a toolset that returns CRM personal data may be chosen and called. |
| `mcp.registration.metadata_documents` | `true` | | Accept clients identified by a metadata document URL. |
| `mcp.registration.dynamic` | `false` | | Accept dynamic client registration. |
| `mcp.clients` | none | `id`, `name`, `redirect_uris` each required | Configured clients. |
| `mcp.tokens.access_ttl` | `1h` | `5m` to `24h` | An access token's life. |
| `mcp.tokens.refresh_idle` | `30d` | `1d` to `180d` | How long a refresh token may go unused. |
| `mcp.tokens.connection_max` | `90d` | `1d` to `180d` | The longest a connection or personal token may live. |
| `mcp.media.fetch` | `true` | | Whether `media_upload_url` may fetch a file from an address. |
| `mcp.media.fetch_hosts` | any | Host names | When set, only these hosts and their subdomains may be fetched from. |
| `mcp.limits.*` | See below | See below | The operational limits. |

```yaml
# config/engine.yaml
mcp:
  enabled: true
  personal_data: refuse
  registration: { metadata_documents: true, dynamic: false }
  tokens: { access_ttl: 1h, refresh_idle: 30d, connection_max: 90d }
  media: { fetch: true, fetch_hosts: [images.example.org] }
  limits: { calls_per_minute: 600, writes_per_minute: 60, writes_per_day: 2000, bulk_items: 200, media_by_url_per_hour: 20 }
```

## Limits [#limits]

| Limit | Default | Ceiling | Key |
|---|---|---|---|
| Weighted calls per connection a minute (a read 1, a search 2, `content_check` 3, a write 5, `bulk_plan` 1 an item) | 600 | 1,200 | `calls_per_minute` |
| Writes per person a minute, across every connection | 60 | 120 | `writes_per_minute` |
| Writes per person a day, across every connection | 2,000 | 5,000 | `writes_per_day` |
| Operations in one bulk plan | 200 | 500 | `bulk_items` |
| Uploads by address per connection an hour | 20 | 100 | `media_by_url_per_hour` |

A value above its ceiling, or zero or below, is a check error; leave a key out for its default. The weighted call limit is counted in each engine process's memory, so with several replicas behind a load balancer a connection can make up to `calls_per_minute` on each replica: with three, up to three times the figure. The write limits are counted in the database and hold across replicas. A call past a limit is refused `rate_limited` with the seconds to wait. The arguments of one write are at most 1 MB. Sign-in, token and registration attempts have fixed limits of their own. The operational limits fail open if they cannot be counted; the security limits fail closed.

## What to tell your data protection officer [#what-to-tell-your-data-protection-officer]

This section describes the install as shipped; your configuration and choice of clients decide the rest.

- **Who decides where content goes.** The person who connects an agent chooses the client, and the client chooses its model provider. Meridian sends nothing to any model through this channel and proxies nothing: content an agent reads goes from your install to that person's client, under their own account with it. Treat each client your organisation approves as a processor you have assessed, and tell staff which clients are approved.
- **What can leave.** By default only what the person can already see in the admin: the site's content, drafts included, its media and the notes on its documents. CRM personal data about people is refused by default (`mcp.personal_data: refuse`) and no tool returns it. Organisations' public profile fields are reachable through the CRM toolset. A claim's claimant contact details are left out while personal data is refused. Fields marked sensitive in the CRM are never returned.
- **If you allow personal data** (`mcp.personal_data: allow`), people with the CRM permissions may choose the *People* toolset, and every read through it that returns records is written to the audit log. Add "CRM personal data to the person's MCP client" to your record of processing and your DPIA, naming the approved clients and their providers.
- **What is recorded.** Every write is in the audit log as the person via the client, with the connection, the tool and the call's key; every revision it made says it came through an agent and for whom; consent, token issue, token reuse and every ending of a connection are audited. Reads are counted per connection and day rather than logged one by one, except personal data reads. The audit log's retention is `retention.audit_log`.
- **Tokens and sign-in.** Connections use OAuth 2.1 with PKCE through the admin's own sign-in and second factor. Tokens are random, held only as hashes, and access tokens live an hour by default; refresh tokens rotate, and one used twice ends the whole connection. Tokens are never put in a URL or a log.
- **Prompt injection.** Content written by members or imported from feeds may contain text addressed to a model. The engine never treats content as an instruction, and marks untrusted content it hands a prompt. An agent misled by such text can still do only what its connection allows, publishing only as its person's workflow allows, and anything it trashes stays in the trash for `content.trash_retention` (30 days by default).


# Headless sites (/integrating/headless-sites)

How to run a site's public pages from a frontend you build (Astro, Next.js, Nuxt or a static generator) on the content API: delivery.mode headless in site.yaml and what check enforces, the resolve loop, preview from the editor, revalidation webhooks and the change feed, forms, analytics collection, and static export.

A site is **rendered** by default: the engine serves its pages from your templates. A **headless** site is served by a frontend someone else builds, which reads the [content API](/integrating/content-api). The admin, the content model, publishing, redirects, search and analytics stay the engine's; the frontend owns the markup.

Rendered delivery is the better default. With it the engine writes the structured data, responsive images, accessibility defaults and analytics on every page without anyone remembering to. Choose headless when your organisation has already decided on a frontend framework, and use this page to give that frontend everything a rendered page would have had.

## Configuration [#configuration]

```yaml
# config/engine.yaml
server:
  api:
    content:
      enabled: true
```

```yaml
# config/sites/<site>/site.yaml
delivery:
  mode: headless
  frontend:
    origin: https://www.example.org
    preview_url: https://www.example.org/api/preview?token={token}&path={path}
    webhooks:
      - url: https://www.example.org/api/revalidate
        secret: ${FRONTEND_WEBHOOK_SECRET}
        events: [content.published, content.unpublished, content.uri_changed, redirects.changed]

embed:
  enabled: false
```

| Key | Default | Meaning |
|---|---|---|
| `delivery.mode` | `rendered` | `rendered` or `headless`. |
| `delivery.frontend.origin` | (required when headless) | The frontend's origin: a scheme and host, no path. Every canonical and absolute URL the API delivers is built on it, and a publishable key with no origins of its own allows it for CORS. |
| `delivery.frontend.preview_url` | none | Where the editor's "preview on the frontend" opens. Must contain `{token}`; `{path}`, `{document}` and `{locale}` are filled too, each URL-encoded. |
| `delivery.frontend.webhooks` | none | Revalidation webhooks: `url`, `secret` and `events`. See [Revalidation](#revalidation-webhooks). |

`engine-dmo check` enforces, each as an error unless marked:

- `server.api.content.enabled` is true (`site main is headless and server.api.content.enabled is false, so nothing serves it`).
- `delivery.frontend.origin` is an origin with no path, query or credentials, and `https` in production.
- `preview_url` contains `{token}`, is an absolute `http` or `https` URL, and is `https` in production. One on another origin than the frontend's is a **warning**, since the admin's preview pane frames only the frontend's origin.
- Each webhook `url` is absolute, `https` in production and listed once; its `secret` is a bare `${VAR}` of at least 16 characters; each event is one the engine emits.
- `embed.enabled` is not true: a headless site serves no widgets.
- `delivery.frontend` on a rendered site is an error (set `delivery.mode: headless` or remove it).
- A public `post` endpoint's `respond` is unused on a headless site, since it is posted through the API's forms operation: a **warning**. You may leave `respond` out.

Media addresses in the representation are on the engine's own `server.base_url` (or your storage's `public_base_url`), since the frontend does not serve `/media/`.

## The request loop [#the-request-loop]

Every page a visitor asks for is one `resolve` call from the frontend's server, and, for a document, one view report after the response has gone:

```mermaid
sequenceDiagram
  participant V as Visitor
  participant F as Frontend server
  participant E as Engine content API
  V->>F: GET /whats-on?page=2
  F->>E: GET .../sites/main/resolve?path=...<br/>Bearer secret key
  E-->>F: outcome, document or index, page metadata
  alt document or index
    F-->>V: 200, the page rendered from the answer
  else redirect
    F-->>V: status and location from the answer
  else gone or not_found
    F-->>V: its own 410 or 404 page
  end
  opt a document was served
    F->>E: POST .../sites/main/events<br/>its analytics.view token
    E-->>F: 202 accepted
  end
```

For each page request, the frontend's server:

<Steps>
<Step>
Calls `resolve` with the visitor's path and query string, with its secret key:

```text
GET /api/content/v1/sites/main/resolve?path=%2Fwhats-on%3Fpage%3D2
Authorization: Bearer mrd_sec_...
```
</Step>
<Step>
Switches on `outcome`: renders the `document` or `index` with the `page` metadata in the head; answers `redirect` with `status` and `location`; renders its 410 page for `gone` and its 404 page for `not_found`.
</Step>
<Step>
Reports the view, after the response, with the `analytics.view` token (see [Analytics](#analytics)).
</Step>
</Steps>

`GET /sites/{site}` gives the frontend the locales, routes, navigation and robots rules it needs once per build or cache period; `strings` its interface text; `sitemap` the entries for its `sitemap.xml`; `redirects` the compiled rules for an edge function. The [content API](/integrating/content-api) page describes each.

`engine-dmo api resolve /whats-on --site main --project .` shows what the API answers for a path while you build the frontend.

## Preview [#preview]

When staff preview a document of a headless site from the editor, the admin issues a preview token for that document and locale (audited), and opens `preview_url` with the token in the admin's preview pane or a tab.

Your frontend's preview route must:

1. **Keep the token on the server.** Turn on the framework's draft mode, keep the token in an HTTP-only cookie or the draft mode's state, and redirect to `{path}` (or a page of your own for a draft that has never been published and has no path). Never put the token in markup or a client bundle.
2. **Read with a secret key holding `preview`**, sending the token in the `Meridian-Preview` header:
   - `GET /sites/{site}/resolve?path=...` answers the token's document with its working revisions when the path resolves to it, and what is published otherwise;
   - `GET /sites/{site}/preview` answers the token's document directly, with its page metadata, for a draft with no path.

   Both carry a `preview` block (`document`, `locale`, `shared_revision`, `locale_revision`, `expires_at`, `substituted`), are `private, no-store`, say `noindex`, and record no 404 miss.
3. **Refetch on every request in draft mode** and cache nothing read with a token: the token reads the working revisions each time, so a refresh after an autosave shows it.
4. **Leave draft mode** on `preview_expired` (401: past `server.api.content.preview_ttl`, or the staff session it was issued in ended), `preview_invalid` (401), `capability_missing` (403: a publishable key, or a secret key without `preview`), or `not_found` once the document is trashed or its issuer may no longer read it.

Only that one document in that one locale is unpublished in the answer: everything else it refers to is published content. To be framed in the admin's preview pane, your frontend's own `Content-Security-Policy` must allow the admin's origin in `frame-ancestors`; the admin's policy already allows the frontend's origin in `frame-src` when the site has a `preview_url`.

## Revalidation webhooks [#revalidation-webhooks]

Each entry of `delivery.frontend.webhooks` receives a signed `POST` when the site's public content changes, so the frontend can purge or rebuild exactly what moved.

| Event | When |
|---|---|
| `content.published` | A locale of a document went live, including a scheduled publish |
| `content.unpublished` | A live locale was taken down |
| `content.uri_changed` | A live document's address changed |
| `content.trashed` | A live document was trashed |
| `content.restored` | A document was restored from the trash |
| `redirects.changed` | The engine wrote automatic redirect rules (with an address change or a trash) |

A webhook with no `events` receives all six. Changes are batched, up to 1,000 a delivery, one delivery per event kind: a bulk publish of 400 documents is one `content.published` delivery with 400 changes.

```json
{
  "id": "0191f3a0-6c4e-7f12-9b1d-2a7e5c3d1f00",
  "type": "content.published",
  "occurred_at": "2026-09-16T10:12:00Z",
  "site": "main",
  "cursor": "184467",
  "changes": [
    {
      "cursor": "184467",
      "document_id": "0191f0c2-7a51-7c3e-9d0a-5b2f6c1e4a88",
      "type": "event",
      "locale": "en-GB",
      "kind": "published",
      "uri_before": null,
      "uri_after": "/whats-on/summer-fair",
      "occurred_at": "2026-09-16T10:11:58Z",
      "cache_tags": ["doc:0191f0c2-7a51-7c3e-9d0a-5b2f6c1e4a88", "type:event", "site:main"]
    }
  ]
}
```

`cache_tags` are the tags the published answers holding that document were sent with: purge them in your CDN. A `redirects.changed` change also carries `redirects:<site>`. Signing, retries, the delivery log and replay are the same as for every [webhook](/integrating/webhooks): verify `Meridian-Signature` before acting, and deduplicate on `Meridian-Delivery`.

## The change feed [#the-change-feed]

Webhooks are an announcement; the change feed is the record. A frontend that must not miss a change (a static build, a search index, a sync) reads it with a secret key:

```text
GET /api/content/v1/sites/main/changes?since=184400&limit=500
```

| Parameter | Meaning |
|---|---|
| `since` | A cursor from the feed, a webhook or an export's manifest: the changes after it. Without it, the answer holds no changes and `next` is the site's head, where a client that has just rebuilt from the queries starts. |
| `limit` | Changes a page, 500 by default and at most 1,000. |

The answer is `{changes, next, resync_required}`, in cursor order, each change in the webhook's shape. `kind` is `published`, `unpublished`, `uri_changed`, `trashed`, `restored` or `purged`. Rows older than `server.api.content.change_retention` (90 days by default) are swept; a `since` older than that answers `resync_required: true`, and the client rebuilds from the queries. A publishable key, or a keyless read, is `capability_missing`.

## Forms [#forms]

A declared `post` endpoint with `access: public` (see [Forms and submissions](/features/forms-and-submissions)) is drawn by the frontend from a description and posted as JSON. Both need a key holding `forms`.

```text
GET /api/content/v1/sites/main/forms/contact-listing?locale=en-GB&subject=<listing-id>
```

```json
{
  "key": "contact-listing",
  "locale": "en-GB",
  "action": "/api/content/v1/sites/main/forms/contact-listing?subject=...",
  "fields": [
    { "name": "name", "type": "text", "label": "Your name", "required": true },
    { "name": "email", "type": "text", "label": "Your email address", "required": true }
  ],
  "challenge": {
    "token": "v1.c8G...",
    "min_fill_ms": 3000,
    "honeypot": "website_url",
    "proof_of_work": { "algorithm": "sha256", "difficulty": 8, "salt": "v1.c8G..." }
  }
}
```

- The labels and consent wording are the declaration's, in the locale. File inputs are left out, since a JSON post carries no file. `subject` fills the endpoint's path inputs (the listing an enquiry is about).
- The `challenge.token` replaces the CSRF token. It is bound to the endpoint, dated for `min_fill_ms`, single use once the input is good, and accepted for twelve hours. Post `honeypot`'s field empty. When `proof_of_work` is present, find a `proof` such that `sha256(token + proof)` has at least `difficulty` leading zero bits.
- Post the result:

```text
POST /api/content/v1/sites/main/forms/contact-listing?subject=<listing-id>
Content-Type: application/json

{ "fields": { "name": "Sian", "email": "sian@example.org", "message": "...", "consent": true },
  "challenge": "v1.c8G...", "proof": "4821" }
```

- Success is `{"outcome": "sent", "signals": {...}}`. A honeypot hit also looks like success, so a bot learns nothing. A field error is `422 validation_failed` with `field_errors` as `{path, code, message}`; posting faster than `min_fill_ms` is the same problem at `_form`. The endpoint's own rate limit answers `429 rate_limited` with `Retry-After`.
- **From a browser**, use a publishable key holding `forms`, from an allowed origin; the rate limits key on the visitor's address.
- **From the frontend's server**, use a secret key holding `forms` and forward the visitor's address in `Meridian-Visitor-IP`. The header is trusted on that combination only, hashed for the limiter and never stored.

The endpoint's steps run as on a rendered site: `store`, `mail`, `audit`, `analytics` and `subscribe` behave the same. A member endpoint, a `get` endpoint and an unknown key all answer `not_found`; a member's forms go through the [member API](/integrating/member-api).

## Analytics [#analytics]

A rendered page records its view as it renders. A headless frontend must report views, or the site's analytics (and, on `engine-dmo`, the member report) have none. `resolve`'s document outcome carries `analytics: {view, collect}`: a signed view token naming the site, the document, its type and the locale. Use one of two paths.

**From the frontend's server** (recommended for a frontend that renders per request), with a secret key holding `events`, after the response has gone:

```text
POST /api/content/v1/sites/main/events
Authorization: Bearer mrd_sec_...
Content-Type: application/json

{ "events": [
  { "name": "view",
    "view": "v1.p9L...",
    "path": "/whats-on/summer-fair",
    "occurred_at": "2026-09-16T10:04:12Z",
    "visitor": { "ip": "203.0.113.7", "user_agent": "Mozilla/5.0 ...", "referrer": "https://www.google.com/", "accept_language": "en-GB,en;q=0.8" },
    "campaign": { "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "autumn" } }
] }
```

| Rule | |
|---|---|
| Names | `view` (or `page_view`, `listing_view`, `event_view`, which are the same), which needs the `view` token; or a client event the beacon accepts: `listing_impression`, `website_click`, `phone_reveal`, `email_click`, `directions_click`, `booking_click`, `social_click`, `share`, `search`, `search_zero`, `search_click`, `filter_apply`, `event_click`, `download`, `widget_impression`, `offer_impression`, `promotion_impression`, whose subject the token gives when sent. |
| `occurred_at` | RFC 3339, up to a day old and five minutes ahead; now when absent. |
| `visitor` | The visitor's address is hashed under the day's salt and discarded; the user agent feeds bot filtering. |
| Limits | At most 100 events and 512 KiB a request; 20 requests a second per key. |
| Answer | `202 {"accepted": n, "rejected": m}`. An event that cannot be recorded (a bad or foreign token, a time outside the window, an unknown name) is counted in `rejected` and never fails the request. |

**The beacon, proxied** (required for a static frontend, allowed for any): proxy the engine's analytics paths `/_e`, `/_e.gif` and `/_e.js` under your own domain, and report each view with its token from the page. See [Analytics](/features/analytics).

Collection is checked. `engine-dmo analytics collection --site main [--days 7] --project .` reports the events received by path (rendered, beacon, api) and the site's collection health. When a headless site's `resolve` has served documents for a day with no view events arriving, the engine logs a warning and notifies the site's administrators.

## Static export [#static-export]

A static frontend can build from files rather than requests: `engine-dmo export content --site main --out ./content` writes every answer the frontend needs, and `--since <cursor>` an incremental update. See [Static export](/integrating/content-api#static-export).

## What stays on the engine [#what-stays-on-the-engine]

The admin, the content API, `/media/` (or your storage's public address), the analytics paths, the tracked link redirects under `/r/`, declared `get` endpoints at their own paths, mail provider webhooks, `/health`, and, on `engine-dmo`, the [member API](/integrating/member-api) and the member sign-in screens. Your frontend proxies the visitor-facing ones (the analytics paths, `/r/`, the member API and sign-in) under its own domain, so they are first party.

The engine does not switch its own page routes off for a headless site. A request for one of the site's page paths that reaches the engine on a host it serves for that site is answered from the project's templates, as on a rendered site, or with the engine's 404 page where nothing matches. Send only the paths listed above to the engine, and keep the site's page traffic on the frontend.


# Integrating (/integrating)

How other systems reach a Meridian site: the read-only content API for headless frontends and builds, outbound webhooks, upstream data sources and scheduled feed imports, the content MCP for AI agents, the member API for a custom portal, and moving content in from WordPress or Sanity.

Meridian talks to other systems through a small set of documented surfaces. Each has its own credentials, limits and contract, and none of them reaches the database or the admin's internals.

| Surface | Direction | For | Credentials | Bundle |
|---|---|---|---|---|
| [Content API](/integrating/content-api) | Out (read) | A headless frontend, a static build, an app, a sync job | Content API keys (`mrd_pub_`, `mrd_sec_`) | Both |
| [Headless sites](/integrating/headless-sites) | Out | Running a public site from a frontend you build: resolve, preview, revalidation, forms and analytics | As above | Both |
| [Webhooks](/integrating/webhooks) | Out (push) | Telling another system that content changed, or that an endpoint ran | An HMAC secret per webhook | Both |
| [Sources and importers](/integrating/sources-and-importers) | In | Reading another service's JSON on a page or in an endpoint; importing a feed into documents on a schedule | Headers from the environment | Both |
| [Content MCP](/integrating/content-mcp) | Both | A person's AI agent reading and drafting content as that person | OAuth 2.1, or a personal access token | Both |
| [Member API](/integrating/member-api) | Both | A member portal you build yourself | The member's session cookie | `engine-dmo` |
| [Migration](/integrating/migration) | In | Moving content, media and old addresses from WordPress, Sanity or another CMS | Command line access to the install | Both |

## Principles that hold everywhere [#principles-that-hold-everywhere]

- **Every address is configuration.** The engine fetches only URLs written in reviewed YAML (`sources.yaml`, `importers.yaml`, `webhooks.yaml`, `site.yaml`); nothing a request supplies becomes an outbound address. A redirect is followed only to the same scheme and host.
- **Secrets are environment variables.** Keys, tokens and signing secrets are written `${VAR}` and set in the engine's environment. A literal secret in configuration is a check error.
- **Errors are structured.** The JSON APIs answer failures as RFC 9457 problem details with a stable `code`.
- **Contracts are printable.** `engine-dmo api openapi`, `engine-dmo api schema`, `engine-dmo api member openapi` and `engine-dmo mcp tools --json` print exactly what this binary serves, so a client can be generated and checked against the version you run.

## Reference commands [#reference-commands]

```bash
engine-dmo api openapi --types --project .   # the content API's OpenAPI 3.1 document with your types
engine-dmo api schema --site <key> --project . # JSON Schema of each type as delivered
engine-dmo api resolve /some/path --project .  # what the content API answers for a path
engine-dmo api keys list --project .           # content API keys
engine-dmo webhooks deliveries --project .     # the outbound delivery log
engine-dmo mcp tools --project .               # what an agent sees
```

Commands that read the install (`api resolve`, `api keys`, `webhooks`, `mcp` and the imports) need a migrated database at `DATABASE_URL`. `api openapi`, `api schema` and `mcp tools` read only the project and connect to nothing, though `engine.yaml` still needs its variables set (any value for `DATABASE_URL` will do).


# Member API (/integrating/member-api)

How to build your own member portal (a single-page app or a headless site's account area) on the member API at /api/member/v1: what it requires, signing members in through the engine's sign-in screens, the same-origin session cookie and CSRF token, a worked request sequence, the form description, errors, rate limits and the OpenAPI contract.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The member API is the JSON surface behind the member portal: everything a business's people do in the reference portal (edit their organisation and listings, upload photos, invite colleagues, read their member report) is available to a portal you build with another toolchain. It serves the same data under the same rules as the reference portal: the tier's editable fields, the approval workflow and the partner role permissions are the engine's, not the client's.

The full list of operations, with the permission each needs, is in [Portal screens and actions](/dmo/portal-screens-and-actions#the-member-api). This page is about calling it.

## Requirements [#requirements]

| Setting | Value |
|---|---|
| `server.api.member.enabled` in `engine.yaml` | `true` (the default) |
| `portal.mode` | `api` or `both` (the default). `api` serves only the member API and the sign-in screens; `both` serves the reference portal too. |
| Origin | Your portal must be served from the same origin as the API, so the session cookie reaches it. On a headless site, proxy `/api/member/v1/` and the member sign-in paths under the frontend's domain. |

## Signing in [#signing-in]

The member API does not sign anyone in. Members sign in through the engine's own sign-in screens under the portal path (`server.portal_path`, `/members` by default): `<portal_path>/login`, with the methods `auth.member` enables (magic link, passkeys, password). These screens, and the pages members reach from links in mail, are always rendered by the engine and restyled in `templates/portal/`.

Sign-in sets the session cookie `__Host-mrd_member`: secure, host-only and sent only to the same origin. Every API call carries it automatically when your portal runs on that origin and sends credentials.

## A request sequence [#a-request-sequence]

```js
// 1. Who is signed in, which organisations they act for, and the CSRF token.
const me = await fetch("/api/member/v1/me", { credentials: "same-origin" }).then((r) => r.json());
// me.person, me.organisations[] ({id, name, role, partner_role, permissions, sites, is_primary}),
// me.capabilities, me.csrf

// 2. The organisation's listings.
const org = me.organisations[0];
const listings = await fetch(`/api/member/v1/organisations/${org.id}/listings`, { credentials: "same-origin" }).then((r) => r.json());

// 3. The form this person may fill for one listing at their tier.
const form = await fetch(`/api/member/v1/listings/${listingId}/form`, { credentials: "same-origin" }).then((r) => r.json());

// 4. Save field values. Unsafe methods carry the CSRF token.
const res = await fetch(`/api/member/v1/listings/${listingId}`, {
  method: "PATCH",
  credentials: "same-origin",
  headers: { "Content-Type": "application/json", "X-CSRF-Token": me.csrf },
  body: JSON.stringify({ summary: "Riverside pub with a garden", website: "https://redlion.example" }),
});
// 200: {saved, discarded, status, approval}; 422: a problem with field_errors
```

| Rule | |
|---|---|
| Base path | `/api/member/v1` on the site's host. |
| Authentication | The `__Host-mrd_member` session cookie; a request without a valid session is refused. |
| Unsafe requests | `POST`, `PATCH` and `DELETE` carry the CSRF token from `GET /me` in `X-CSRF-Token`. |
| Bodies | JSON, except `POST /assets`, which is `multipart/form-data` (`file`, `organisation`, `licence_accepted` required; `alt` unless `decorative`; optional `caption`, `listing`, `field`). |
| Language | Listing values are read and written in the site's source locale. |

## The form description [#the-form-description]

`GET /listings/{id}/form` is the contract a portal draws its listing editor from: the schema's fields this person may edit at their organisation's tier, in the locale.

| Key | Meaning |
|---|---|
| `locale` | The locale the form edits. |
| `groups` | `{key, label, fields}`: the fields in the editor's groups. |
| `fields[]` | Each `{name, type, label, help, required, required_when, visible_when, value, options, max, multiple, constraints, params, fields, blocks, asset, link}`: `type` is the field type, `value` the working value, `options` for a select, `fields` and `blocks` for containers, `asset` and `link` the rules of those field types. `visible_when` and `required_when` are JSON predicate trees, never strings. |
| `validation` | Cross-field rules: `{rule, fields, message, severity}`. |
| `approval` | `{mode, expected_turnaround_hours, review_window_hours, always_review}`: whether a save goes to staff review or is published at once with a review window. |

`engine-dmo api member form --listing <id> --person <id> --project .` prints the description a given member would receive.

A `PATCH /listings/{id}` body is field values by field name. Fields the tier does not permit are discarded and named in `discarded`, never an error. The answer is `{saved, discarded, status, approval}`; `status` is `{live, last_live_at, pending, returned, approval}`, also served by `GET /listings/{id}/status`.

## Errors [#errors]

Every failure is an RFC 9457 problem detail (`type`, `title`, `status`, `detail`). A `422` carries `field_errors`, each `{path, code, message}`, with structured paths such as `stages[2].title`.

## Rate limits [#rate-limits]

Every write is limited per session by `endpoints.defaults.rate_limit.member` in `engine.yaml` (`60/hour/session` by default), and four times that per address.

```yaml
# config/engine.yaml
endpoints:
  defaults:
    rate_limit:
      member: 120/hour/session
```

## The contract [#the-contract]

```bash
engine-dmo api member routes --project .    # every operation and whether this project serves it
engine-dmo api member openapi --project .   # the OpenAPI 3.1 document
```

The same document is served at `GET /api/member/v1/openapi.json`. The path carries the major version; changes within `v1` are additive, so ignore keys you do not know.

## What it does not cover [#what-it-does-not-cover]

Declared portal screens and actions are portal features and are not exposed through the API, and event submission has no API operation yet (`GET /events` lists the organisations' event documents). Forms on the public site are posted through the [content API](/integrating/headless-sites#forms), not this one.


# Migration (/integrating/migration)

How to move an existing site into Meridian without losing content, media or search rankings: the engine's three imports (media manifests, content files with the HTML path, redirect CSVs) and their formats, the meridian-migrate toolkit for WordPress and Sanity exports, crawling the old site and matching its addresses, and a rehearsed cutover runbook.

A migration moves a live site's content, media and addresses into a Meridian install. The engine imports three kinds of file, each with a dry run, each safe to run again:

| File | Imported with | Holds |
|---|---|---|
| A media manifest (`meridian.media.v1`) | `engine-dmo media import` | Files, with the ids they are to have, alt text, captions, framing and rights |
| A content file (`meridian.content.v1`) | `engine-dmo content import` | Documents and their locales' values; rich text as Portable Text or as HTML |
| A redirect CSV | `engine-dmo redirects import` | The old addresses and where each now goes |

You can write these files with any tool. For WordPress and Sanity, the **migration toolkit** (`meridian-migrate`) writes them from the platform's own export through a mapping file, and maps the old site's addresses to the new documents. Organisations, people and memberships (on `engine-dmo`) come in through `engine-dmo crm import`, described in [CRM](/dmo/crm).

`engine-cms` behaves the same for content, media and redirects.

## The order [#the-order]

1. Configure the project's types, routes and locales, and apply them: `engine-dmo schema apply`.
2. Import the media, so content can refer to it by id.
3. Import the content, in an order where a document comes after those it refers to; forward references in a second pass.
4. Review the drafts, then publish.
5. Import the redirects, once the documents they point at exist.

Every import writes through the same validation, permissions and audit as the admin, and nothing is published by an import.

## Media manifests [#media-manifests]

```json
{
  "format": "meridian.media.v1",
  "assets": [
    {
      "id": "6f1c2b9e-3d4a-5b6c-8d7e-9f0a1b2c3d4e",
      "file": "files/6f1c2b9e-3d4a-5b6c-8d7e-9f0a1b2c3d4e.jpg",
      "filename": "harbour-at-dawn.jpg",
      "alt": { "en-GB": "Fishing boats in the harbour at dawn" },
      "caption": { "en-GB": "The harbour in October" },
      "focal": { "x": 0.5, "y": 0.4 },
      "rights": { "holder": "Jo Smith", "licence": "CC-BY-4.0", "credit": "Photo: Jo Smith" },
      "source": "https://old.example.org/wp-content/uploads/2024/10/harbour.jpg",
      "tags": ["harbour"],
      "source_id": "attachment:1042"
    }
  ]
}
```

| Key | Required | Meaning |
|---|---|---|
| `format` | Yes | `meridian.media.v1`. |
| `assets[].id` | Yes | The UUID the asset will have, chosen by you so content can name it first. Unique in the file. |
| `assets[].file` | Yes | The original, relative to the manifest; it may not leave the manifest's directory. |
| `filename` | | The name the library shows; the file's own name when absent. |
| `alt`, `caption` | | By locale. |
| `decorative` | | An image with no alt text by intent. |
| `focal` | | `{x, y}`, each 0 to 1. |
| `hotspot`, `crop` | | `{x, y, w, h}` in fractions of the whole image from its top left; a rectangle outside the image is refused. |
| `rights` | | `holder`, `licence`, `uses`, `territory`, `from` and `until` (`YYYY-MM-DD`), `credit`, `source`. |
| `rights_review` | | Why the asset needs its rights established; counted in the report. |
| `source` | | Where the original came from, recorded as the rights source when the record names none. |
| `tags` | | Tag keys of the vocabulary; a key it does not hold is left out. |
| `source_id` | | The asset's id in the old system, for the report. |

A manifest holds at most 20,000 assets, and unknown keys are refused.

```bash
engine-dmo media import --manifest out/media/manifest.json --dry-run --project .
engine-dmo media import --manifest out/media/manifest.json --project .
```

Each file goes through the media pipeline as an upload does: its type sniffed, its size checked, its metadata (camera location included) stripped. An id the library already holds is reported `exists` and left alone, so a rehearsal never undoes work done in the library since. The report counts the assets without a licence; the library's **No rights recorded** filter is the queue to work through. See [Media](/features/media).

## Content files [#content-files]

```json
{
  "format": "meridian.content.v1",
  "site": "main",
  "type": "article",
  "documents": [
    {
      "id": "1b4e28ba-2fa1-51d2-883f-0016d3cca427",
      "locales": {
        "en-GB": {
          "values": {
            "title": "The harbour in winter",
            "slug": "harbour-in-winter",
            "summary": "What to see when the boats are in.",
            "publishedAt": "2024-12-02T09:00:00Z",
            "body": { "html": "<p>The boats come in at dusk.</p><img src=\"asset:6f1c2b9e-3d4a-5b6c-8d7e-9f0a1b2c3d4e\" alt=\"Boats at dusk\">" }
          }
        }
      }
    }
  ]
}
```

| Key | Meaning |
|---|---|
| `format` | `meridian.content.v1`. |
| `site` | The site the file was written for. |
| `type` | The type of every document that names none of its own. |
| `documents[].id` | The document's UUID. |
| `documents[].type` | Its type, overriding the file's. |
| `documents[].variant` | Its entry variant, where the type declares variants. |
| `documents[].locales` | By locale code: `{values}`, each value by field name in the shape the admin saves. `status` (written by an export) is ignored. |

At most 2,000 documents a file. `engine-dmo content export` writes the same shape, so an export is the best template for your own files.

```bash
engine-dmo content import --site main --file out/content/0001.json --dry-run --project .
engine-dmo content import --site main --file out/content/0001.json --project .
```

| Flag | Meaning |
|---|---|
| `--file` | The file; `-` reads standard input. |
| `--site` | The site; the default site when absent. |
| `--match` | `id` (the default): a document is matched by its `id`, which is then required, and created with that id when new. `slug`: matched by its slug, and created with a new id when none matches. |
| `--dry-run` | Say what would happen to each locale and write nothing. |

Each locale of each document is `create`, `update`, `unchanged` or `reject`, with a reason for a rejection: an unknown type, a type not on the site, a locale the site does not enable, a missing or malformed id, an id that belongs to another type or site or is in the trash, field validation errors, or a permission the person running it lacks. Values are validated as a save in the admin is, and a slug another document already holds is a validation error. An import never publishes; a second run of the same file reports every locale unchanged.

### Rich text as HTML [#rich-text-as-html]

A `portable_text` field's value may be `{"html": "..."}` instead of Portable Text blocks. The import converts it with the same converter the editor uses for pasted HTML, then normalises the blocks to what the field allows (its styles, lists and marks); every adjustment is a note on the row, so nothing changes silently.

- An `<img>` whose `src` is `asset:<uuid>` becomes the field's image block pointing at that library asset, with the HTML's alt text. Import the media first and write the ids into the HTML.
- Any other `<img>` is left out and counted in a note. The import never fetches a file from an address in an import file.
- Only top-level `portable_text` fields convert; a rich text field inside a `blocks` or `repeater` field must be given as Portable Text.

### Publishing what you imported [#publishing-what-you-imported]

```bash
engine-dmo content publish --ids-from out/ids.txt --all-locales --project .
```

`--ids-from` reads one document id a line. `--all-locales` publishes every locale with a working revision, the source locale first, through the publish checks; a locale whose checks fail is skipped and named.

## Redirect CSVs [#redirect-csvs]

```csv
source,target,status,locale,note
/2019/05/harbour-walk,document:1b4e28ba-2fa1-51d2-883f-0016d3cca427,301,,from the old blog
/visit-us,/visit,301,,
/old-shop,,410,,the shop closed
```

| Column | Meaning |
|---|---|
| `source` | The old path, without the site's locale prefix. |
| `target` | A path on the site, an absolute URL, `document:<uuid>` (the rule follows the document if its address changes), or empty with status 410. |
| `status` | 301 (the default), 302, 307, 308 or 410. |
| `locale` | The locale the rule applies to, or empty for every locale. |
| `note` | Free text, kept with the rule. |

Other columns are ignored.

```bash
engine-dmo redirects import --site main --file redirects.csv --dry-run --project .
engine-dmo redirects import --site main --file redirects.csv --project .
engine-dmo redirects list --site main --origin imported --project .
engine-dmo redirects rollback --site main --batch <batch-id> --project .
```

Every row is checked: the source and status, the locale, a duplicate in the file or in the site's rules, that a target document exists, that a target path is one the site answers, and loops and chains through every rule the site has. Any error refuses the whole import unless `--skip-invalid`. A document target not yet published is a warning (the rule serves once it is), and a row whose document is already published at that address is `unneeded`. The import is one transaction with origin `imported` and a batch id, which `rollback --batch` disables. The import writes exact rules only; prefix and wildcard rules belong in `routes.yaml`. See [Redirects and URLs](/features/redirects-and-urls).

## The migration toolkit [#the-migration-toolkit]

<Callout title="A separate program">`meridian-migrate` is a command of its own, not part of the engine binary or the container images. It runs on a workstation beside the export, never connects to the engine's database, and writes the files above. It imports nothing of the engine, so its version need not match the engine's. A release does not publish a build of it: today it is built from the Meridian source repository, so ask Cherwell Studio for it. Without it, write the three import formats above with any tool; they are the engine's contract and need only the binary.</Callout>

```bash
meridian-migrate run --mapping mapping.yaml --source <export> --out out [--dry-run] [--uploads dir]
meridian-migrate crawl --start https://old.example.org --out crawl.json [--delay 1s] [--max 10000]
meridian-migrate redirects --crawl crawl.json --urls out/urls.json --out redirects.csv --review redirects-review.csv
```

Every id it writes is a UUID derived from the mapping's `namespace` and the source's own id, so a second run writes the same files, a second media import finds every asset present, and a second content import reports every locale unchanged. A rehearsal can run any number of times against the same staging database.

### The mapping file [#the-mapping-file]

```yaml
format: meridian.migrate.v1
source: wordpress              # or sanity
namespace: example-org-2026    # seeds every id; keep it for every rehearsal and the cutover
site: main                     # the Meridian site the import files name
locales:
  default: en-GB               # a record with no locale, and the first locale a document is created in
  map: { en: en-GB, fr: fr-FR } # source code to Meridian code; a code not named is rejected
media:                         # dotted paths into each asset's metadata
  credit: creditLine
  holder: source.name
  licence: license
  source_url: source.url
  review_tag: rights-review    # optional: a tag key for every asset without a licence
types:
  - from: post                 # the source type: a WordPress post_type or taxonomy, a Sanity _type
    to: article                # the Meridian type
    statuses: [publish]        # the states imported; empty imports the published state only
    dedupe: [slug]             # slug, title or both: later duplicates are rejected
    fields:                    # a field of the Meridian type: a source field (dotted path), or { from, as }
      title: title
      slug: slug
      summary: excerpt
      publishedAt: { from: date, as: value }
      hero: { from: featured_image, as: asset }
      topics: { from: categories, as: reference }
      body: { from: content, as: html }
  - from: category
    to: topic
    fields:
      title: title
      slug: slug
```

The whole file is checked before anything runs, and every problem is listed together.

| Key | Meaning |
|---|---|
| `format` | `meridian.migrate.v1`. |
| `source` | `wordpress` or `sanity`. |
| `namespace` | Required; seeds every derived id. Never change it between rehearsals. |
| `site` | The site key the import files name. |
| `locales.default`, `locales.map` | As above. With an empty map, a source code that is already a locale code is kept. |
| `i18n.document_field`, `i18n.metadata_type` | Sanity's document-level internationalisation: the field holding the language (`language` is the plugin's default) and the type of the documents linking translations (`translation.metadata`). |
| `media.*` | Dotted paths into each asset's metadata for its rights record, and an optional review tag. |
| `types[].from`, `types[].to` | The source type and the Meridian type. Each source type is mapped once. |
| `types[].url` | The old address pattern with `{slug}` and `{locale}`, for a source that does not record addresses (Sanity). |
| `types[].statuses` | The source states imported; others are rejected with the reason. |
| `types[].dedupe` | `slug`, `title` or both. A later duplicate is rejected, and references to it follow the first. |
| `types[].fields` | Meridian field handle to a source field. `as` is `text` (the default: a string, a slug's `current`, a number), `portable_text` (Portable Text passed through and mapped, or HTML sent down the HTML path), `html` (always the HTML path), `asset` (an image object or a WordPress featured image, one or a list), `reference` (to the document the source id became) or `value` (any JSON, with references and assets inside it resolved). |
| `types[].styles`, `types[].decorators` | Rename Portable Text block styles and decorators; a decorator mapped to `""` is dropped. |
| `types[].annotations` | Portable Text mark definitions by source `_type`: `link` or `drop`. A mark that holds a reference becomes a document link. |
| `types[].blocks` | Portable Text object blocks by source `_type`: `{to, asset_field, fields}` (`fields` is Meridian field to source field), or `drop`. |

### What a run writes [#what-a-run-writes]

| File | What it is |
|---|---|
| `content/0001.json`, `0002.json`, ... | Content files, at most 2,000 documents each, ordered so a document comes after those it refers to |
| `content/NNNN-references.json` | References that would point forward (a cycle, or a document naming itself), set as updates once every document exists. Import it last. |
| `media/manifest.json`, `media/files/` | The media manifest and each original under its Meridian id |
| `urls.json` | Every imported document's old addresses per locale, with its id, title and slug: the input for address matching |
| `ids.txt` | Every document id in import order, for `content publish --ids-from` |
| `rejects.csv` | `level, source_id, type, reason`: each record or asset left out (`reject`) or kept with something lost (`warning`), rejects first |
| `summary.json` | Counts: records, documents and locales by type, duplicates, assets, duplicate files, rights review, deferred references, addresses |

`--dry-run` writes only `rejects.csv` and `summary.json` and downloads nothing. Start every migration with it, and treat each reject as a decision: map the type, change a status, or accept the loss.

Records of one translation group become the locales of one document, the default locale first. Within a Meridian type, a document whose first locale has the same slug (or normalised title) as an earlier one is rejected as a duplicate. Media are deduplicated by content: two files with the same SHA-256 import once.

### WordPress [#wordpress]

`source: wordpress` reads a WXR export (Tools, Export, All content), versions 1.0 to 1.2.

- **Posts, pages and custom post types** are records of their `post_type`, with `title`, `slug`, `content` (HTML), `excerpt`, `author` (display name, as text), `date` and `modified` (UTC), `parent`, `featured_image`, `categories`, `tags`, each custom taxonomy by its name, and `meta` (post meta without a leading underscore). WordPress's own types (menu items, revisions, templates) are skipped.
- **Categories, tags and terms** are records of type `category`, `post_tag` or the taxonomy, with `title`, `slug`, `description` and `parent`. An unmapped type is rejected, which is a decision: map it, or leave it.
- **Attachments** are assets, with alt text from `_wp_attachment_image_alt` and the caption from the excerpt. Originals are read from `--uploads` (a copy of `wp-content/uploads`) when given, else downloaded politely (one request at a time, `--delay` apart, default `1s`, with `--user-agent`; add a contact address to it).
- **HTML** is cleaned for the engine's HTML path: classic editor paragraphs restored, `[caption]` turned into the image and a paragraph, `[embed]` into a link, any other shortcode reported once per post and left as text. Each `<img>` of an imported attachment, including a resized copy (`photo-300x200.jpg` is `photo.jpg`), is rewritten to `asset:<id>`; any other image is reported.
- Multilingual plugins (WPML, Polylang) are not read: every record takes the default locale.

### Sanity [#sanity]

`source: sanity` reads the output of `sanity dataset export`, the `.tar.gz` or its unpacked directory (`data.ndjson`, `assets.json`, `images/`, `files/`).

- `_id` is the source id (a `drafts.` prefix removed) and `_type` the source type; system documents are skipped. A draft of a published document is ignored in favour of the published version; a draft with no published version has status `draft`.
- `slug.current` is read where a text or slug field names a slug object; `{_ref}` anywhere is a reference by source id.
- Both asset forms are read, with `originalFilename`, `altText`, `description` (or `title`) as the caption, `creditLine`, `source {name, id, url}` and any custom metadata the mapping's `media` paths name. The CDN address is recorded, never fetched.
- Portable Text passes through with its keys, styles, lists and marks; what is Sanity's is mapped by the mapping, and anything it does not name is left out with a warning.
- Document-level internationalisation (`@sanity/document-internationalization`) and the two common field-level shapes (`sanity-plugin-internationalized-array`, and locale objects such as `localeString`) become locales.

### Crawling the old site and matching addresses [#crawling-the-old-site-and-matching-addresses]

```bash
meridian-migrate crawl --start https://old.example.org --out crawl.json --user-agent "Example migration; ops@example.org"
meridian-migrate redirects --crawl crawl.json --urls out/urls.json --out redirects.csv --review redirects-review.csv
```

The crawl keeps to robots.txt (its `Crawl-delay` wins when longer than `--delay`), reads the sitemaps it names, `/sitemap.xml` and any `--sitemap`, and follows same-host links one request at a time: no `nofollow` links, no files, fragments and tracking parameters removed, query strings dropped unless `--keep-query`. It records each page's status, title and canonical address, and each redirect with its target. `--max` (default 10,000) stops it and says so.

`redirects` maps every old address (the source's own from `urls.json`, and each crawled page that answered 200) to a document:

- an address the source recorded for a document matches it outright, with confidence 1;
- any other is scored against every document of its locale by the similarity of its last path segment to the slug and of its page title to the title;
- two candidates within 0.05 of each other always go to review;
- the home page is left alone.

A match at or above `--threshold` (default `0.8`) goes to `redirects.csv` with a `document:<id>` target and a `confidence` column; the rest go to the review file with the best candidate, the others and an empty `decision` column for a person to fill: redirect (copy the row into the redirects file), recreate, or 410. `--locale-prefix /fr=fr-FR` (repeatable) removes an old locale prefix from the source and sets the locale column.

## The runbook [#the-runbook]

Do every step against staging first, and rehearse the whole cutover at least twice.

<Steps>
<Step>
**Export and assess.** Take the export (`sanity dataset export production export.tar.gz`; or WordPress's All content export with a copy of `wp-content/uploads`). Record the counts by type.
</Step>
<Step>
**Write the mapping** against the project's schema, already applied. Choose the `namespace` once.
</Step>
<Step>
**Dry run the toolkit** and work through `rejects.csv` until it holds only what is meant to be left. Then run it for real.
</Step>
<Step>
**Crawl the live site**, record the ranking baseline of its top pages, run `meridian-migrate redirects`, and work through the review file.
</Step>
<Step>
**Import into staging, dry runs first:** the media manifest; each content file in order, the references file last; on `engine-dmo`, the CRM; review the drafts in the admin; `content publish --ids-from out/ids.txt --all-locales`; then the redirects until the dry run is clean.
</Step>
<Step>
**Work the rights queue** (the library's **No rights recorded** filter) until every image in published content has a rights record.
</Step>
<Step>
**Rehearse again** from a fresh export and a reset staging database, timing each step. Because ids derive from source ids, every rehearsal and the cutover write the same ids.
</Step>
<Step>
**Cut over.** Freeze editing at the source, take the final export, run the toolkit and the imports against production, check a sample of old addresses answer 301 to the right page (`engine-dmo redirects list --origin imported`), switch DNS, then watch the 404 report daily for two weeks and compare rankings after 30 days.
</Step>
</Steps>

Before DNS moves, a rollback is a database restore; a redirect batch alone is `engine-dmo redirects rollback --batch <id>`.

## Not handled [#not-handled]

- Links inside migrated rich text that point at the old site stay as addresses; the redirect set serves them.
- Old media addresses (`/wp-content/uploads/...`, the Sanity CDN) get no redirects to the imported assets.
- Multilingual WordPress (WPML, Polylang).
- Sources other than WordPress and Sanity need their files written by your own tool, in the formats above.


# Sources and importers (/integrating/sources-and-importers)

How to bring another service's data into a site without code: sources.yaml for cached, allowlisted upstream JSON read by templates and endpoints (with caching, failure modes and the circuit breaker), and importers.yaml for scheduled feed imports that create and update documents by external id, with every option, default and limit.

Two kinds of inbound integration need only configuration:

- A **source** is another service's JSON that a page or an endpoint reads at request time: a weather forecast, a tide table, a booking system's availability. The engine fetches it, caches it and protects the page from the service failing.
- An **importer** fetches a JSON feed on a schedule and turns each item into a document of one of your types, matched by the item's id in the feed, so a second run updates what the first created. It never publishes.

Both fetch only the addresses written in configuration. A request can never make the engine fetch an address it supplies, and a redirect is followed only to the same scheme and host.

`engine-cms` behaves the same.

## Sources [#sources]

```yaml
# config/sites/<site>/sources.yaml
sources:
  weather:
    url: https://api.example.org/forecast?lat=52.06&lon=-1.34
    headers:
      Authorization: "Bearer ${WEATHER_TOKEN}"
    ttl: 10m
    timeout: 3s
    max_bytes: 256KB
    on_error: stale_then_empty
    circuit_breaker: { failures: 5, window: 1m, cooldown: 30s }
```

Run `engine-dmo check --fix` to give it its stable `id` (`src_...`). Rename one with `engine-dmo dev source rename <old> <new>`, which also updates every endpoint step that names it.

| Key | Default | Limits | Meaning |
|---|---|---|---|
| `url` | (required) | An absolute `http` or `https` URL, no credentials in it | The address fetched with `GET` and `Accept: application/json`. |
| `headers` | none | | Request headers. A header whose name contains `auth`, `key`, `token`, `secret`, `password` or `cookie` must be a `${VAR}` interpolation, never a literal. |
| `ttl` | `5m` | At most `24h` | How long a fetched answer is reused. |
| `timeout` | `5s` | At most `30s` | How long one fetch may take. |
| `max_bytes` | `1MB` | At most `10MB` | The largest answer accepted; a larger one is a failure. |
| `on_error` | `stale_then_empty` | `stale_then_empty`, `stale_then_fail`, `empty`, `fail` | What a failed fetch answers. See below. |
| `circuit_breaker.failures` | `5` | 1 to 100 | Failures inside `window` that open the breaker. |
| `circuit_breaker.window` | `1m` | At most `1h` | |
| `circuit_breaker.cooldown` | `30s` | At most `1h` | While open, the source answers as `on_error` says without calling the service. |

The answer must be JSON with a `2xx` status. Each engine process caches each source in memory for `ttl`, and fetches it once at a time: a burst of requests after the ttl lapses waits for the first fetch rather than each calling the service. The cache is not shared: each replica fetches for itself, and a restarted process starts empty, with no last good answer for the `stale_` choices below to fall back on until its first successful fetch.

| `on_error` | When the fetch fails or the breaker is open |
|---|---|
| `stale_then_empty` | The last good answer if there is one, else empty. |
| `stale_then_fail` | The last good answer if there is one, else a failure. |
| `empty` | Empty. |
| `fail` | A failure. |

Empty is nothing (`null`). A failure fails an endpoint's `source` step with HTTP 502 ("This information is not available just now. Try again in a moment."); in a template, `source()` is simply empty.

### In a template [#in-a-template]

```jinja
{% set forecast = source('weather') %}
{% if forecast %}
  <p>{{ forecast.summary }}, {{ forecast.temperature }}°C</p>
{% endif %}
```

`source('name')` returns the parsed JSON, or nothing when the source is not declared or cannot answer, so always handle the empty case. See [Functions](/templates/functions#source).

### In an endpoint [#in-an-endpoint]

```yaml
# config/sites/<site>/endpoints.yaml
endpoints:
  - key: forecast
    path: /api/forecast.json
    methods: [get]
    access: public
    steps:
      - source: { name: weather, as: forecast }
    respond:
      json: { from: forecast, fields: [summary, temperature] }
    cache: 5m
```

The `source` step takes `name` (a source in this site's `sources.yaml`) and `as` (the name later steps and `respond` read it by; the source's name when left out). `respond: json:` exposes only the `fields` it lists. See [Forms and submissions](/features/forms-and-submissions) for endpoints.

## Importers [#importers]

```yaml
# config/sites/<site>/importers.yaml
importers:
  partner-events:
    url: https://feeds.example.org/events.json
    headers:
      Authorization: "Bearer ${EVENTS_FEED_TOKEN}"
    schedule: "0 4 * * *"
    type: notice
    locale: en-GB
    items: data.events
    external_id: id
    map:
      title: name
      summary: description.short
      startDate: dates.start
    status: in_review
    max_items: 500
```

Here `notice` is a type of the project's with `title`, `slug`, `summary` (text) and `startDate` (date) fields. With a feed like this, each object under `data.events` becomes a `notice` document in `en-GB`, its `title` from `name`, its `summary` from `description.short` and its `startDate` from `dates.start`:

```json
{ "data": { "events": [
  { "id": "ev-1042", "name": "Summer fair", "description": { "short": "Stalls, music and a dog show." }, "dates": { "start": "2026-07-18" } }
] } }
```

Run `engine-dmo check --fix` to give it its `id` (`imp_...`). Its import records are keyed by that id, so a renamed importer (`engine-dmo dev importer rename <old> <new>`) keeps matching the documents it made.

| Key | Default | Limits | Meaning |
|---|---|---|---|
| `url` | (required) | An absolute `http` or `https` URL, no credentials | The feed, fetched with `GET`. |
| `headers` | none | Credentials only as `${VAR}` | Request headers. |
| `schedule` | (required) | A five-field cron expression, read in UTC | When it runs: `"0 4 * * *"` is 04:00 UTC daily. |
| `type` | (required) | A type on this site | The type each item becomes. |
| `locale` | The site's default locale | A locale the site enables | The locale written. |
| `items` | The body itself | A dotted path | Where the list of items is in the feed's JSON. |
| `external_id` | (required) | A dotted path into an item; the value at most 200 characters | The item's id in the feed, which the import matches by. |
| `map` | (required, at least one) | Field name to a dotted path into the item | The fields the import writes. A `blocks`, `repeater`, `portable_text`, `asset` or `video` field cannot be imported from a feed. |
| `status` | `in_review` | `draft` or `in_review` | What an imported document is left as. An import never publishes. |
| `timeout` | `30s` | At most `5m` | How long the fetch may take. |
| `max_bytes` | `10MB` | At most `50MB` | The largest feed accepted. |
| `max_items` | `1000` | 1 to 10,000 | The most items one run imports; the rest are reported and left. |

### What a run does [#what-a-run-does]

For each item:

1. It reads the external id. An item without one is skipped and reported.
2. It reads each mapped field. When `slug` is not mapped, the slug is made from the mapped `title` (or `item-<external id>` when there is none).
3. If nothing mapped has changed since the last run, the item is **unchanged**.
4. If the item was imported before, the document's working revision in the locale is **updated**: the import owns the fields it maps and nothing else, so an editor's work on any other field survives the next run. A document that was trashed or purged since is created again.
5. Otherwise a document is **created**, owned by the site.
6. With `status: in_review`, the document is sent to review.

The values are validated as an editor's save is; an item whose values fail is skipped with the reason. Each revision is recorded as written by the import (`Imported by <key>`). A run reports how many items were created, updated, unchanged and skipped, with up to 50 problems, in the job's progress.

### Running an importer now [#running-an-importer-now]

Each importer is a scheduled task named `importer.<site>.<key>`:

```bash
engine-dmo schedule list --project .
engine-dmo schedule run importer.main.partner-events --now --project .
```

A staff endpoint can also queue a run with a `job` step, which is the one job kind an endpoint may queue:

```yaml
steps:
  - job: { name: importer.run, with: { importer: partner-events } }
```

A burst of runs of one importer collapses into one.


# Webhooks (/integrating/webhooks)

How Meridian tells other systems that something happened: webhooks.yaml with every option and limit, the content events and the endpoint webhook step, the request body and headers, verifying the HMAC signature, retries and backoff, the delivery log, and replaying a delivery.

An outbound webhook is a signed JSON `POST` the engine sends to an address you declare, when content is published or changes, or when a declared endpoint runs a `webhook` step. Deliveries are queued and sent from the job runner, never inline, so a slow or failing receiver delays nothing a person or a publish is waiting on. Every attempt is written to a delivery log you can read and replay from.

A headless site's revalidation webhooks (`delivery.frontend.webhooks` in `site.yaml`) use the same signing, retries, log and replay with a body of their own; they are described in [Headless sites](/integrating/headless-sites#revalidation-webhooks).

`engine-cms` behaves the same.

## A minimal webhook [#a-minimal-webhook]

```yaml
# config/sites/<site>/webhooks.yaml
webhooks:
  crm:
    url: https://hooks.example.org/meridian
    secret: ${CRM_WEBHOOK_SECRET}
    events: [content.published, content.changed]
    types: [event]
```

```bash
export CRM_WEBHOOK_SECRET="$(openssl rand -hex 32)"
engine-dmo check --fix --project .   # writes the webhook's id, then checks
```

From now on, each time a document of type `event` on this site is published, or anything changes where it is live, `https://hooks.example.org/meridian` receives a signed post.

## webhooks.yaml [#webhooksyaml]

One file per site, `config/sites/<site>/webhooks.yaml`. Keys are lowercase letters, digits and hyphens. Each webhook gets a stable `id` (`whk_...`) written by `engine-dmo check --fix`; its delivery log is keyed by it, so renaming the key keeps the log. Rename one with `engine-dmo dev webhook rename <old> <new>`, which also updates every endpoint step that names it.

| Key | Default | Limits | Meaning |
|---|---|---|---|
| `url` | (required) | An absolute `http` or `https` URL, with no credentials in it | Where deliveries go. Written in configuration, never built from a request. A `${VAR}` interpolation is allowed. |
| `secret` | (required) | A bare `${VAR}` interpolation; the value at least 16 characters | The HMAC key every delivery is signed with. A literal is a check error. |
| `events` | none | `content.published`, `content.changed` | The content events this webhook receives. A webhook with none receives only what endpoint steps send it. |
| `types` | all types | Type keys; needs `events` | Narrows the content events to documents of these types. |
| `timeout` | `10s` | At most `30s` | How long one attempt waits for the receiver. |
| `max_attempts` | `8` | 1 to 20 | Attempts before a delivery is marked failed. |

## What triggers a delivery [#what-triggers-a-delivery]

### Content events [#content-events]

| Event | When | `data` |
|---|---|---|
| `content.published` | A locale of a document goes live on a site this webhook belongs to, including a scheduled publish | `{"document": {"id", "type"}, "locale"}` |
| `content.changed` | After anything that changes where a document is live: publish, unpublish, archive, trash, restore, purge, and adding it to or removing it from a site | `{"document": {"id", "type"}, "placements": [{"site", "locale", "live"}]}`: each of the document's placements on this webhook's site, and whether it is live there now |

`content.changed` tells the receiver where to look again rather than what happened, as the search index is told: read the document from the [content API](/integrating/content-api) to see its current state.

### The endpoint webhook step [#the-endpoint-webhook-step]

A declared endpoint can send to a webhook as one of its steps:

```yaml
# config/sites/<site>/endpoints.yaml
endpoints:
  - key: refresh-events
    path: /api/refresh-events
    methods: [post]
    access: staff
    steps:
      - job: { name: importer.run, with: { importer: partner-events } }
      - webhook: { to: crm, event: events.refreshed, body: { importer: partner-events } }
    respond:
      location: /studio
```

| Key | Meaning |
|---|---|
| `to` | A webhook declared in this site's `webhooks.yaml`. |
| `event` | The event name: lowercase `area.verb` (`enquiry.received`). `endpoint.<key>` when left out. |
| `body` | A mapping of names to references (`$email`, `$listing.title`) or literals, sent as `data`. Without it, `data` holds the endpoint's resolved values. When an earlier `store` step saved a submission, `data.submission` is its id. |

The step queues the delivery and never fails the endpoint: a receiver that is down costs nothing to the visitor.

## The request [#the-request]

```text
POST /meridian HTTP/1.1
Host: hooks.example.org
Content-Type: application/json
User-Agent: Meridian-Webhook
Meridian-Delivery: 0191f3a0-6c4e-7f12-9b1d-2a7e5c3d1f00
Meridian-Event: content.published
Meridian-Signature: t=1758017520,v1=5f2b0c...

{"id":"0191f3a0-6c4e-7f12-9b1d-2a7e5c3d1f00","event":"content.published","site":"main","occurred_at":"2026-09-16T10:12:00Z","data":{"document":{"id":"0191f0c2-7a51-7c3e-9d0a-5b2f6c1e4a88","type":"event"},"locale":"en-GB"}}
```

| Body key | Meaning |
|---|---|
| `id` | The delivery's id, the same as `Meridian-Delivery`. |
| `event` | The event name, the same as `Meridian-Event`. |
| `site` | The site's key. |
| `occurred_at` | When the event happened, RFC 3339 UTC. |
| `data` | The event's data, as above. |

The body is fixed when the delivery is queued: every retry and every replay sends the same bytes under the same `Meridian-Delivery` id, newly signed. Deduplicate on that id.

Any `2xx` answer is success. Anything else, a timeout or a connection failure is a failed attempt. A redirect is followed only to the same scheme and host. The first 2 KiB of the receiver's answer is kept in the delivery log.

## Verifying the signature [#verifying-the-signature]

`Meridian-Signature` is `t=<unix seconds>,v1=<hex>`, where the hex is the HMAC-SHA256, keyed with the webhook's secret, of the timestamp, a full stop and the raw body: `HMAC_SHA256(secret, t + "." + body)`. A receiver must:

1. Read the raw body before parsing it.
2. Compute the HMAC over `t + "." + body` and compare it with `v1` in constant time.
3. Refuse a timestamp more than five minutes from its own clock, so a captured delivery cannot be replayed later.

```go
func verify(secret, header string, body []byte, now time.Time) error {
	var ts, sig string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch k {
		case "t":
			ts = v
		case "v1":
			sig = v
		}
	}
	unix, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || sig == "" {
		return errors.New("malformed signature")
	}
	m := hmac.New(sha256.New, []byte(secret))
	m.Write([]byte(ts + "."))
	m.Write(body)
	got, err := hex.DecodeString(sig)
	if err != nil || !hmac.Equal(got, m.Sum(nil)) {
		return errors.New("signature does not match")
	}
	if d := now.Sub(time.Unix(unix, 0)); d > 5*time.Minute || d < -5*time.Minute {
		return errors.New("signature is stale")
	}
	return nil
}
```

```js
// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, header, rawBody, now = Date.now()) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) throw new Error("malformed signature");
  const want = createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest();
  const got = Buffer.from(parts.v1, "hex");
  if (got.length !== want.length || !timingSafeEqual(got, want)) throw new Error("signature does not match");
  if (Math.abs(now / 1000 - t) > 300) throw new Error("signature is stale");
}
```

Each attempt is signed when it is sent, with the secret the engine holds at that moment. To rotate a secret, set the new value in the engine's environment and restart it, and have the receiver accept both secrets while you switch.

## Retries [#retries]

A failed attempt is retried with exponential backoff: about 2 seconds after the first failure, doubling each time, at most an hour apart, until `max_attempts` attempts have been made. The last failure marks the delivery `failed` in the log, and the engine logs a warning for each failed attempt. With the default 8 attempts, the retries span about four minutes, so a receiver that is down for longer than that needs a [replay](#replaying-a-delivery).

A delivery for a webhook that has since been removed from `webhooks.yaml`, or whose secret is no longer set, is marked failed without being sent.

A delivery moves through three states. Only a replay takes it out of `delivered` or `failed`, and a replay sends the same id and body again:

```mermaid
stateDiagram-v2
  [*] --> pending: event queued
  pending --> pending: attempt fails,<br/>retry after a backoff
  pending --> delivered: a 2xx answer
  pending --> failed: max_attempts used,<br/>or the webhook is gone
  delivered --> pending: replay
  failed --> pending: replay
  delivered --> [*]: kept 30 days
  failed --> [*]: kept 30 days
```

There is no alert beyond the warning logged for each failed attempt. Watch for those warnings, or list failed deliveries on a schedule (`engine-dmo webhooks deliveries --status failed`), and replay what a long outage lost.

## The delivery log [#the-delivery-log]

Every delivery and its attempts are kept for 30 days: its status (`pending`, `delivered` or `failed`), the event, the body, the headers it was sent with (the signature shown as `[redacted]`), the receiver's status code and the start of its answer.

```bash
engine-dmo webhooks deliveries --site main --project .
engine-dmo webhooks deliveries --site main --status failed --webhook crm --limit 50 --project .
engine-dmo webhooks deliveries --site main --id <delivery-id> --project .
```

| Flag | Meaning |
|---|---|
| `--site` | The site; the default site when absent. |
| `--status` | `pending`, `delivered` or `failed`. |
| `--webhook` | One webhook, by its key or its config id. |
| `--limit` | At most this many, newest first, up to 500 (default 100). |
| `--id` | Print one delivery in full, with its headers, body and the receiver's answer. |

In the admin, the log is under the site's **Settings, Webhooks** (`<admin_path>/s/<site>/settings/webhooks`) for staff holding `webhooks.view`.

## Replaying a delivery [#replaying-a-delivery]

```bash
engine-dmo webhooks replay --site main --id <delivery-id> --project .
```

A replay sends a delivery again with the same id and body, newly signed, with a fresh set of attempts. It needs `webhooks.replay` on the site and is audited as `webhook.replay`. A delivery still pending cannot be replayed. Staff can also replay from the delivery's page in the admin.


# a11y (/reference/cli/a11y)

engine-dmo a11y: Accessibility statements, the issues register and the conformance scaffold. Every subcommand, argument and flag.

Accessibility statements, the issues register and the conformance scaffold.

| Command | What it does |
|---|---|
| [`engine-dmo a11y audit`](#engine-dmo-a11y-audit) | Render a sample or all of a site's pages through the real pipeline and run the automated accessibility checks; exits 1 on a failure |
| [`engine-dmo a11y issues`](#engine-dmo-a11y-issues) | The known issues register, with owners and target dates |
| [`engine-dmo a11y report`](#engine-dmo-a11y-report) | The Accessibility Conformance Report scaffold, EN 301 549 clause by clause, from the automated checks and the known issues register |
| [`engine-dmo a11y statement`](#engine-dmo-a11y-statement) | A PSBAR and WAD conformant accessibility statement scaffold from `site.yaml` |

## engine-dmo a11y audit [#engine-dmo-a11y-audit]

Render a sample or all of a site's pages through the real pipeline and run the automated accessibility checks; exits 1 on a failure.

```bash
engine-dmo a11y audit [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all` | bool |  | check every page instead of a sample |
| `--path` | strings |  | a page to check; with no `--sample` or `--all`, only the pages named |
| `--sample` | int | `20` | how many pages to check, spread across the site's routes |
| `--site` | string |  | site key (default: the default site) |
| `--surface` | string | `site` | what to audit: site |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo a11y issues [#engine-dmo-a11y-issues]

The known issues register, with owners and target dates.

```bash
engine-dmo a11y issues
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo a11y report [#engine-dmo-a11y-report]

The Accessibility Conformance Report scaffold, EN 301 549 clause by clause, from the automated checks and the known issues register.

```bash
engine-dmo a11y report [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all` | bool |  | render every page for the automated checks |
| `--format` | string | `md` | md, json or vpat (the VPAT 2.5 table as HTML) |
| `--no-audit` | bool |  | leave out the automated checks, which need the database, and report from the register alone |
| `--out` | string |  | where to write; empty prints to the terminal |
| `--sample` | int | `20` | how many pages the automated checks render |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo a11y statement [#engine-dmo-a11y-statement]

A PSBAR and WAD conformant accessibility statement scaffold from `site.yaml`.

```bash
engine-dmo a11y statement [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--format` | string | `html` | html or md |
| `--out` | string |  | where to write; empty prints to the terminal |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# access (/reference/cli/access)

engine-dmo access: The effective permission matrix. Every subcommand, argument and flag.

The effective permission matrix.

| Command | What it does |
|---|---|
| [`engine-dmo access matrix`](#engine-dmo-access-matrix) | Every active user's effective permissions, by group |

## engine-dmo access matrix [#engine-dmo-access-matrix]

Every active user's effective permissions, by group.

```bash
engine-dmo access matrix [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | one site's view |

`--json` prints the command's own JSON document. Runs in a project.


# affiliates (/reference/cli/affiliates)

engine-dmo affiliates: Affiliate networks, conversion imports and postback secrets. Every subcommand, argument and flag.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

Affiliate networks, conversion imports and postback secrets.

| Command | What it does |
|---|---|
| [`engine-dmo affiliates connect`](#engine-dmo-affiliates-connect) | Store a network's reporting API secret for a site, read from an environment variable or standard input |
| [`engine-dmo affiliates import`](#engine-dmo-affiliates-import) | Import a network's transaction export (CSV) as conversions, matched to their clicks |
| [`engine-dmo affiliates networks`](#engine-dmo-affiliates-networks) | Every network, the settings a site's account and a programme need, and the export columns it reads |
| [`engine-dmo affiliates postback-key`](#engine-dmo-affiliates-postback-key) | Make a site's postback secret for a network, replacing any it had, and print it once |
| [`engine-dmo affiliates sync`](#engine-dmo-affiliates-sync) | Read the connected networks' conversions now, as the scheduler does |

## engine-dmo affiliates connect [#engine-dmo-affiliates-connect]

Connects the site to the network's reporting API: Awin's token, Impact's auth token (with the Account SID set on the Networks screen), or Tiqets' token. The secret is sealed with the install's key and never printed. It is read from `--secret-env`, or from standard input, never from an argument, so it stays out of the shell's history.

```bash
engine-dmo affiliates connect [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--network` | string |  | the network: awin, impact, tiqets |
| `--secret-env` | string |  | the environment variable holding the secret; standard input when not given |
| `--site` | string |  | the site; the default site when not given |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo affiliates import [#engine-dmo-affiliates-import]

Reads the export through the network's column mapping (engine-dmo affiliates networks lists it). A transaction imported before is updated in place, so importing an export again, or a later one that moves pending to approved, never counts a conversion twice. `--column` names a column by hand: `--column` id="Order Ref" `--column` occurred_at=Created. A date that is not ISO 8601 needs `--date-layout`, in Go's reference layout: `02/01/2006` for day first.

```bash
engine-dmo affiliates import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--column` | string, repeatable |  | field=column, naming a column by hand (repeatable) |
| `--date-layout` | string |  | a Go time layout for the dates, when they are not ISO 8601 |
| `--dry-run` | bool |  | read the export and report what it holds, writing nothing |
| `--file` | string |  | the export, as CSV |
| `--network` | string |  | the network the export is from: awin, booking, cj, direct, getyourguide, impact, partnerize, tiqets, tracked, viator |
| `--programme` | string |  | the programme id a conversion with no known click is credited to |
| `--site` | string |  | the site the conversions are for; the default site when not given |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo affiliates networks [#engine-dmo-affiliates-networks]

Every network, the settings a site's account and a programme need, and the export columns it reads.

```bash
engine-dmo affiliates networks
```

`--json` prints the command's own JSON document. Needs no project.

## engine-dmo affiliates postback-key [#engine-dmo-affiliates-postback-key]

Turns on the signed postback for the site and network. The secret is printed once and stored sealed; give it to whoever signs the postbacks. Running this again replaces it, which is how a leaked secret is rotated.

```bash
engine-dmo affiliates postback-key [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--network` | string |  | the network: awin, booking, cj, direct, getyourguide, impact, partnerize, tiqets, tracked, viator |
| `--site` | string |  | the site; the default site when not given |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo affiliates sync [#engine-dmo-affiliates-sync]

Read the connected networks' conversions now, as the scheduler does.

```bash
engine-dmo affiliates sync [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--days` | int | `45` | how many days back to read |
| `--network` | string |  | only this network |
| `--site` | string |  | only this site |

`--json` prints the command's own JSON document. Runs in a project.


# ai (/reference/cli/ai)

engine-dmo ai: The AI provider, its budget, the review queue and the activity log. Every subcommand, argument and flag.

The AI provider, its budget, the review queue and the activity log.

| Command | What it does |
|---|---|
| [`engine-dmo ai budget`](#engine-dmo-ai-budget) | Spend by feature and by user against the caps, for a month (default this one) |
| [`engine-dmo ai bulk alt-text`](#engine-dmo-ai-bulk-alt-text) | Queue an alt text draft for every image missing alt text in a locale, after printing the estimate |
| [`engine-dmo ai data-flow-statement`](#engine-dmo-ai-data-flow-statement) | A DPIA annex generated from config: which features, which provider, where, and what is sent |
| [`engine-dmo ai log`](#engine-dmo-ai-log) | The AI activity log: feature, user, model, tokens, cost, outcome and the data classes sent |
| [`engine-dmo ai queue`](#engine-dmo-ai-queue) | Suggestions waiting for a person to accept, edit or reject |
| [`engine-dmo ai status`](#engine-dmo-ai-status) | Provider, models, capabilities, health and spend this month |
| [`engine-dmo ai test`](#engine-dmo-ai-test) | One round trip with no content, which confirms the endpoint, the key and the model |

## engine-dmo ai budget [#engine-dmo-ai-budget]

Spend by feature and by user against the caps, for a month (default this one)

```bash
engine-dmo ai budget [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--period` | string |  | the month, such as 2026-09 |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo ai bulk alt-text [#engine-dmo-ai-bulk-alt-text]

Queue an alt text draft for every image missing alt text in a locale, after printing the estimate.

```bash
engine-dmo ai bulk alt-text [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | print the count and the estimate and queue nothing |
| `--locale` | string |  | the locale (default the source locale) |
| `--site` | string |  | a site key: draft that site's own wording for the images its documents use (default the defaults every site shows) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo ai data-flow-statement [#engine-dmo-ai-data-flow-statement]

A DPIA annex generated from config: which features, which provider, where, and what is sent.

```bash
engine-dmo ai data-flow-statement [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | write to this file instead of standard output |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo ai log [#engine-dmo-ai-log]

The AI activity log: feature, user, model, tokens, cost, outcome and the data classes sent.

```bash
engine-dmo ai log [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--from` | string |  | the first day, such as 2026-09-01 (default 30 days ago) |
| `--limit` | int | `1000` | the most rows to print |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo ai queue [#engine-dmo-ai-queue]

Suggestions waiting for a person to accept, edit or reject.

```bash
engine-dmo ai queue
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo ai status [#engine-dmo-ai-status]

Provider, models, capabilities, health and spend this month.

```bash
engine-dmo ai status
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo ai test [#engine-dmo-ai-test]

One round trip with no content, which confirms the endpoint, the key and the model.

```bash
engine-dmo ai test
```

`--json` prints the text output in the JSON envelope. Runs in a project.


# analytics (/reference/cli/analytics)

engine-dmo analytics: Rollups, recompute, retention and member reports. Every subcommand, argument and flag.

Rollups, recompute, retention and member reports.

| Command | What it does |
|---|---|
| [`engine-dmo analytics collection`](#engine-dmo-analytics-collection) | Report the events a site received by collection path (rendered, beacon, api) over the last days, and a headless site's collection health |
| [`engine-dmo analytics digest`](#engine-dmo-analytics-digest) | Queue the member report digest for the current period |
| [`engine-dmo analytics export`](#engine-dmo-analytics-export) | Export a dashboard or one metric over a range as CSV or JSON, as the Insight screen's export does; audited |
| [`engine-dmo analytics partitions`](#engine-dmo-analytics-partitions) | List the monthly raw partitions, create them ahead, and drop expired ones with `--drop-expired` |
| [`engine-dmo analytics prune`](#engine-dmo-analytics-prune) | Apply retention: raw partitions past raw_retention_days, hourly rollups and search log rows past theirs |
| [`engine-dmo analytics recompute`](#engine-dmo-analytics-recompute) | Rebuild every rollup level from raw events for a range, idempotently, under the rules in force |
| [`engine-dmo analytics report`](#engine-dmo-analytics-report) | One member's report, as text or as a PDF |
| [`engine-dmo analytics report-run`](#engine-dmo-analytics-report-run) | Queue an organisation report from `analytics/reports.yaml` for its current period |
| [`engine-dmo analytics rollup`](#engine-dmo-analytics-rollup) | Roll raw events up into the hourly, daily and monthly tables for a range |

## engine-dmo analytics collection [#engine-dmo-analytics-collection]

Report the events a site received by collection path (rendered, beacon, api) over the last days, and a headless site's collection health.

```bash
engine-dmo analytics collection [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--days` | int | `7` | how many days back, 1 to 90 |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo analytics digest [#engine-dmo-analytics-digest]

Queue the member report digest for the current period.

```bash
engine-dmo analytics digest [flags]
```

Available in `engine-dmo` only.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--run` | bool |  | work through the mail queue here rather than leaving it to the server |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo analytics export [#engine-dmo-analytics-export]

Export a dashboard or one metric over a range as CSV or JSON, as the Insight screen's export does; audited.

```bash
engine-dmo analytics export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--as` | string |  | export as this staff account (email), which needs analytics.export on the site |
| `--compare` | string |  | previous_year \| previous_period \| none (default: the dashboard's) |
| `--dashboard` | string |  | a dashboard from `analytics/dashboards.yaml`; default is the overview |
| `--format` | string | `csv` | csv \| json |
| `--from` | string |  | the first day of a custom range, YYYY-MM-DD, in the site's zone |
| `--metric` | string |  | one metric of the catalogue, as a single tile |
| `--out` | string |  | file to write; standard output when empty or - |
| `--range` | string |  | a range preset: today, 7d, 30d, 90d, 12m, this_month, previous_month, this_quarter, previous_quarter, this_financial_year, previous_financial_year, previous_year (default: the dashboard's) |
| `--site` | string |  | site key (default: the default site) |
| `--to` | string |  | the last day of a custom range, inclusive |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo analytics partitions [#engine-dmo-analytics-partitions]

List the monthly raw partitions, create them ahead, and drop expired ones with `--drop-expired`.

```bash
engine-dmo analytics partitions [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--drop-expired` | bool |  | also apply retention, as engine-dmo analytics prune does |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo analytics prune [#engine-dmo-analytics-prune]

Apply retention: raw partitions past raw_retention_days, hourly rollups and search log rows past theirs.

```bash
engine-dmo analytics prune [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | report what would go and change nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo analytics recompute [#engine-dmo-analytics-recompute]

Rebuild every rollup level from raw events for a range, idempotently, under the rules in force.

```bash
engine-dmo analytics recompute [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--from` | string |  | first day, YYYY-MM-DD |
| `--to` | string |  | last day, inclusive, YYYY-MM-DD (default today) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo analytics report [#engine-dmo-analytics-report]

One member's report, as text or as a PDF.

```bash
engine-dmo analytics report [flags]
```

Available in `engine-dmo` only.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--format` | string | `text` | text, html or pdf |
| `--from` | string |  | start date, such as 2026-01-01 (default: a year ago) |
| `--organisation` | string |  | the organisation's id |
| `--out` | string |  | where to write; empty prints text and HTML to the terminal and writes a PDF to report.pdf, and - writes any format to standard output |
| `--site` | string |  | site key (default: the default site) |
| `--to` | string |  | end date (default: today) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo analytics report-run [#engine-dmo-analytics-report-run]

Queue an organisation report from `analytics/reports.yaml` for its current period.

```bash
engine-dmo analytics report-run [flags]
```

Available in `engine-dmo` only.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--report` | string |  | the report's key in `analytics/reports.yaml` |
| `--run` | bool |  | work through the mail queue here rather than leaving it to the server |
| `--site` | string |  | the site; the default site when empty |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo analytics rollup [#engine-dmo-analytics-rollup]

Roll raw events up into the hourly, daily and monthly tables for a range.

```bash
engine-dmo analytics rollup [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--from` | string |  | first day, YYYY-MM-DD |
| `--to` | string |  | last day, inclusive, YYYY-MM-DD (default today) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# api (/reference/cli/api)

engine-dmo api: The content API: its contract, a site's project contract, and what it answers for a path. Every subcommand, argument and flag.

The content API: its contract, a site's project contract, and what it answers for a path.

| Command | What it does |
|---|---|
| [`engine-dmo api keys create`](#engine-dmo-api-keys-create) | Issue a key and print it once: a publishable key for browser code (CORS for its origins) or a secret key for the frontend's server |
| [`engine-dmo api keys list`](#engine-dmo-api-keys-list) | Every key, live first: its id, name, kind, the key masked to its prefix and last four characters, sites, capabilities, origins and state |
| [`engine-dmo api keys revoke`](#engine-dmo-api-keys-revoke) | End a key now; requests carrying it answer invalid_key |
| [`engine-dmo api keys rotate`](#engine-dmo-api-keys-rotate) | Issue a key like an existing one and print it once; the old key keeps working for `--grace`, so the new one is deployed first |
| [`engine-dmo api member form`](#engine-dmo-api-member-form) | Print the form description a given member would receive for a listing |
| [`engine-dmo api member openapi`](#engine-dmo-api-member-openapi) | Print the member API's OpenAPI 3.1 document, generated from the route table in this binary |
| [`engine-dmo api member routes`](#engine-dmo-api-member-routes) | List the member API's operations and whether this project serves them |
| [`engine-dmo api openapi`](#engine-dmo-api-openapi) | Print the content API's OpenAPI 3.1 document: the generic contract from the route table in this binary, or with `--types` this project's, its types included |
| [`engine-dmo api resolve`](#engine-dmo-api-resolve) | Print what the content API answers for a path on a site: the outcome, the document and the page metadata, recording no miss |
| [`engine-dmo api schema`](#engine-dmo-api-schema) | Print a site's project contract: the JSON Schema of each of its types as delivered, or an OpenAPI document with them |

## engine-dmo api keys create [#engine-dmo-api-keys-create]

Issue a key and print it once: a publishable key for browser code (CORS for its origins) or a secret key for the frontend's server.

```bash
engine-dmo api keys create [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--capability` | strings |  | preview (secret keys), events (secret keys) or forms; reading published content is implied |
| `--expires` | string |  | when the key stops: a duration such as 2160h or a time such as 2027-01-01T00:00:00Z; never when absent |
| `--kind` | string |  | publishable (browser code) or secret (the frontend's server) |
| `--name` | string |  | what the key is for, such as "Astro frontend (production)" |
| `--origin` | strings |  | a publishable key's allowed browser origin, such as https://www.example.org; none allows the frontend origin of a headless site it reads |
| `--site` | strings |  | a site the key reads; repeat or comma separate for several |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo api keys list [#engine-dmo-api-keys-list]

Every key, live first: its id, name, kind, the key masked to its prefix and last four characters, sites, capabilities, origins and state.

```bash
engine-dmo api keys list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | only the keys that read this site |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo api keys revoke [#engine-dmo-api-keys-revoke]

End a key now; requests carrying it answer invalid_key.

```bash
engine-dmo api keys revoke [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | confirm the key should stop working now |
| `--id` | string |  | the key's id, from engine-dmo api keys list |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo api keys rotate [#engine-dmo-api-keys-rotate]

Issue a key like an existing one and print it once; the old key keeps working for `--grace`, so the new one is deployed first.

```bash
engine-dmo api keys rotate [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--grace` | duration | `24h0m0s` | how long the old key keeps working; 0 ends it now |
| `--id` | string |  | the key's id, from engine-dmo api keys list |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo api member form [#engine-dmo-api-member-form]

Print the form description a given member would receive for a listing.

```bash
engine-dmo api member form [flags]
```

Available in `engine-dmo` only.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--listing` | string |  | the listing's document id |
| `--person` | string |  | the person's id |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo api member openapi [#engine-dmo-api-member-openapi]

Print the member API's OpenAPI 3.1 document, generated from the route table in this binary.

```bash
engine-dmo api member openapi
```

Available in `engine-dmo` only.

`--json` prints the text output in the JSON envelope. Needs no project.

## engine-dmo api member routes [#engine-dmo-api-member-routes]

List the member API's operations and whether this project serves them.

```bash
engine-dmo api member routes [flags]
```

Available in `engine-dmo` only.

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo api openapi [#engine-dmo-api-openapi]

Print the content API's OpenAPI 3.1 document: the generic contract from the route table in this binary, or with `--types` this project's, its types included.

```bash
engine-dmo api openapi [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--api` | string | `content` | the API whose contract to print: content |
| `--types` | bool |  | include the project's types: the document GET /api/content/v1/openapi.json serves |

`--json` prints the text output in the JSON envelope. Needs no project.

## engine-dmo api resolve [#engine-dmo-api-resolve]

Print what the content API answers for a path on a site: the outcome, the document and the page metadata, recording no miss.

```bash
engine-dmo api resolve <path> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `path` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--host` | string |  | the request host, for a site whose locales are by domain |
| `--site` | string |  | the site's key; the default site when absent |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo api schema [#engine-dmo-api-schema]

Print a site's project contract: the JSON Schema of each of its types as delivered, or an OpenAPI document with them.

```bash
engine-dmo api schema [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--format` | string | `jsonschema` | jsonschema or openapi |
| `--site` | string |  | the site's key |

`--json` prints the text output in the JSON envelope. Runs in a project.


# assets (/reference/cli/assets)

engine-dmo assets: The frontend build as the engine resolves it: the manifest a build reads. Every subcommand, argument and flag.

The frontend build as the engine resolves it: the manifest a build reads.

| Command | What it does |
|---|---|
| [`engine-dmo assets manifest`](#engine-dmo-assets-manifest) | Each site's resolved components, blocks, template globs and entries, for the Vite plugin |

## engine-dmo assets [#engine-dmo-assets]

The frontend build as the engine resolves it: the manifest a build reads.

```bash
engine-dmo assets
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | one site |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo assets manifest [#engine-dmo-assets-manifest]

Each site's resolved components, blocks, template globs and entries, for the Vite plugin.

```bash
engine-dmo assets manifest
```

`--json` prints the command's own JSON document. Runs in a project.


# audit (/reference/cli/audit)

engine-dmo audit: The audit log's integrity: walk its hash chain and report every break. Every subcommand, argument and flag.

The audit log's integrity.

| Command | What it does |
|---|---|
| [`engine-dmo audit verify`](#engine-dmo-audit-verify) | Walk the audit log's hash chain: every row's content, every link, and holes where rows were deleted |

## engine-dmo audit verify [#engine-dmo-audit-verify]

Walk each realm's hash chain in link order: each row's content hash recomputed, each link recomputed from the one before, and the sequence checked for holes.

```bash
engine-dmo audit verify [flags]
```

It takes no flags of its own. The chain exists only with [`audit.hash_chain`](/reference/configuration/engine#audit) on. `--json` prints the command's own JSON document. Runs in a project and needs the database.

```text
member: 412 links from 1 to 412, head 7c1e...
staff: 1842 links from 1 to 1842, head 9f2c..., 2 rewritten by erasure
system: 9120 links from 1 to 9120, head 41ab...
```

Each line gives the realm's links, where the walk starts, its head, how many rows an erasure rewrote and how many were written while the chain was off. The walk starts later than 1 once retention has pruned the oldest rows, which is not a break. Each break follows on its own line:

| Break | Means |
|---|---|
| `content` | A row changed with the database trigger off |
| `rewrite` | A row rewritten in a transaction that recorded no erasure |
| `link` | A forged or recomputed link |
| `gap` | Rows deleted from inside the chain |

| Exit | When |
|---|---|
| `0` | Every realm is intact |
| `1` | Any break, or no database connection |
| `3` | Nothing is chained: set `audit.hash_chain: true` and restart the engine |

Each run writes `audit.verify` to the audit log, with whether the chain was intact.

Under `--json`:

```json
{
  "enabled": true,
  "realms": [
    {
      "realm": "staff",
      "links": 1842,
      "first_seq": 1,
      "head_seq": 1842,
      "head_hash": "9f2c...",
      "head_at": "2026-11-02T09:14:03Z",
      "erased": 2,
      "unchained": 0,
      "breaks": [{ "kind": "gap", "seq": 17, "id": 0, "missing": 3 }]
    }
  ]
}
```

A gap's `seq` is the first missing link and its `missing` how many; any other break's `id` is the row. See [Data protection duties](/deploying/data-protection#the-audit-chain).


# broadcast (/reference/cli/broadcast)

engine-dmo broadcast: The crm module's broadcasts: list, show, draft, test-send, schedule, send, cancel, report. Every subcommand, argument and flag.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The crm module's broadcasts: list, show, draft, test-send, schedule, send, cancel, report.

| Command | What it does |
|---|---|
| [`engine-dmo broadcast cancel`](#engine-dmo-broadcast-cancel) | Cancel a draft, a scheduled broadcast or the rest of a sending one; messages already queued still go |
| [`engine-dmo broadcast draft`](#engine-dmo-broadcast-draft) | Write a draft from a YAML or JSON file (subject, preheader, format, body, list); a new one, or with `--id` the draft it names |
| [`engine-dmo broadcast list`](#engine-dmo-broadcast-list) | List a site's broadcasts, newest first |
| [`engine-dmo broadcast report`](#engine-dmo-broadcast-report) | A broadcast's figures: recipients by delivery state, who was left out, unsubscribes, clicks per link and opens |
| [`engine-dmo broadcast schedule`](#engine-dmo-broadcast-schedule) | Schedule a draft to go at a time (RFC 3339, or 2006-01-02T15:04 in the site's zone); needs `--confirm` |
| [`engine-dmo broadcast send`](#engine-dmo-broadcast-send) | Send a draft now; needs `--confirm`, since a send cannot be taken back |
| [`engine-dmo broadcast show`](#engine-dmo-broadcast-show) | Show a broadcast, its body and who its list reaches now, with who it leaves out and why |
| [`engine-dmo broadcast test-send`](#engine-dmo-broadcast-test-send) | Send a test of the broadcast to one address, with [Test] before its subject and placeholder merge fields |

## engine-dmo broadcast cancel [#engine-dmo-broadcast-cancel]

Cancel a draft, a scheduled broadcast or the rest of a sending one; messages already queued still go.

```bash
engine-dmo broadcast cancel [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | broadcast id |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo broadcast draft [#engine-dmo-broadcast-draft]

Write a draft from a YAML or JSON file (subject, preheader, format, body, list); a new one, or with `--id` the draft it names.

```bash
engine-dmo broadcast draft [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--file` | string |  | the draft as YAML or JSON |
| `--id` | string |  | rewrite this draft rather than start one |
| `--site` | string |  | site key, for a new draft |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo broadcast list [#engine-dmo-broadcast-list]

List a site's broadcasts, newest first.

```bash
engine-dmo broadcast list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key |
| `--status` | string |  | draft \| scheduled \| sending \| sent \| cancelled |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo broadcast report [#engine-dmo-broadcast-report]

A broadcast's figures: recipients by delivery state, who was left out, unsubscribes, clicks per link and opens.

```bash
engine-dmo broadcast report [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | broadcast id |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo broadcast schedule [#engine-dmo-broadcast-schedule]

Schedule a draft to go at a time (RFC 3339, or 2006-01-02T15:04 in the site's zone); needs `--confirm`.

```bash
engine-dmo broadcast schedule [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--at` | string |  | when it goes |
| `--confirm` | bool |  | schedule it |
| `--id` | string |  | broadcast id |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo broadcast send [#engine-dmo-broadcast-send]

Send a draft now; needs `--confirm`, since a send cannot be taken back.

```bash
engine-dmo broadcast send [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | send it |
| `--id` | string |  | broadcast id |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo broadcast show [#engine-dmo-broadcast-show]

Show a broadcast, its body and who its list reaches now, with who it leaves out and why.

```bash
engine-dmo broadcast show [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | broadcast id |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo broadcast test-send [#engine-dmo-broadcast-test-send]

Send a test of the broadcast to one address, with [Test] before its subject and placeholder merge fields.

```bash
engine-dmo broadcast test-send [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | broadcast id |
| `--to` | string |  | the address the test goes to |

`--json` prints the text output in the JSON envelope. Runs in a project.


# build (/reference/cli/build)

engine-dmo build: Run the project's frontend build, then engine-dmo check. Every subcommand, argument and flag.

Run the project's frontend build, then engine-dmo check.

```bash
engine-dmo build [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--command` | string |  | the build command, instead of the `package.json` build script |
| `--no-check` | bool |  | build only |
| `--no-db` | bool |  | engine-dmo check without the database checks |
| `--strict` | bool |  | engine-dmo check with warnings as errors |

`--json` prints the text output in the JSON envelope. Runs in a project.


# check (/reference/cli/check)

engine-dmo check: The CI gate: validate config, schema, templates and the deployment. Exit 3 on invalid configuration. Every subcommand, argument and flag.

The CI gate: validate config, schema, templates and the deployment. Exit 3 on invalid configuration.

```bash
engine-dmo check [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--contract-report` | bool |  | list template usage the next contract version removes, each with its replacement |
| `--fix` | bool |  | write an id for every element without one, keeping comments, then check |
| `--no-db` | bool |  | skip checks that need a database |
| `--strict` | bool |  | promote warnings to errors |

`--json` prints the command's own JSON document. Runs in a project.

See [The development loop](/getting-started/development-loop) and [Configuration and secrets](/deploying/configuration-and-secrets). `--no-db` also accepts an unset variable in a secret path, so CI and image builds need no secrets.

## Reading the output [#reading-the-output]

Every problem is printed with its file, line and column, then a summary line such as `0 errors, 0 warnings. Configuration is valid.` The exit code follows the errors: 0 when there are none, 3 when there is one.

<Callout type="warn" title="The summary does not count template warnings">
Warnings about templates (a layout with no `head()`, a missing `t()` string) are printed above the summary but are not counted in it, and `--strict` does not promote them: a project with template warnings still ends `0 errors, 0 warnings` and exits 0. Read every printed line, not only the summary. A fresh starter project shows one such warning, for its placeholder layout.
</Callout>

`--strict` makes the warnings the summary counts (such as `server.admin_path` being `/admin`) fail the check: the summary still reads `0 errors, 1 warning.`, and the exit code is 3.

Two quirks of the output: a problem in `endpoints.yaml`, and a missing `t()` string in a component, are reported at column 0 (`endpoints.yaml:2:0`), so go by the line; and a template error may be printed twice, in two formats, which is one problem, not two.

`--fix` writes an id for every configuration element that has none. It accepts any well-formed id already in a file, including one typed by hand, so the rule that ids are written only by `--fix` and the `dev` verbs is yours to keep: never write or copy an id yourself.

Some mistakes are found only when a page renders, not by `check`: a query on a field that is not indexed, a field read on a loop variable or a component prop, and a required component slot left out. Render the pages that use them with [render](/reference/cli/render) before you deploy.


# completion (/reference/cli/completion)

engine-dmo completion: Generate the autocompletion script for the specified shell. Every subcommand, argument and flag.

Generate the autocompletion script for engine-dmo for the specified shell. See each sub-command's help for details on how to use the generated script.

| Command | What it does |
|---|---|
| [`engine-dmo completion bash`](#engine-dmo-completion-bash) | Generate the autocompletion script for bash |
| [`engine-dmo completion fish`](#engine-dmo-completion-fish) | Generate the autocompletion script for fish |
| [`engine-dmo completion powershell`](#engine-dmo-completion-powershell) | Generate the autocompletion script for powershell |
| [`engine-dmo completion zsh`](#engine-dmo-completion-zsh) | Generate the autocompletion script for zsh |

## engine-dmo completion bash [#engine-dmo-completion-bash]

```text
Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

	source <(engine-dmo completion bash)

To load completions for every new session, execute once:

#### Linux:

	engine-dmo completion bash > /etc/bash_completion.d/engine-dmo

#### macOS:

	engine-dmo completion bash > $(brew --prefix)/etc/bash_completion.d/engine-dmo

You will need to start a new shell for this setup to take effect.
```

```bash
engine-dmo completion bash
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--no-descriptions` | bool |  | disable completion descriptions |

`--json` prints the text output in the JSON envelope. Needs no project.

## engine-dmo completion fish [#engine-dmo-completion-fish]

```text
Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

	engine-dmo completion fish | source

To load completions for every new session, execute once:

	engine-dmo completion fish > ~/.config/fish/completions/engine-dmo.fish

You will need to start a new shell for this setup to take effect.
```

```bash
engine-dmo completion fish [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--no-descriptions` | bool |  | disable completion descriptions |

`--json` prints the text output in the JSON envelope. Needs no project.

## engine-dmo completion powershell [#engine-dmo-completion-powershell]

```text
Generate the autocompletion script for powershell.

To load completions in your current shell session:

	engine-dmo completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command
to your powershell profile.
```

```bash
engine-dmo completion powershell [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--no-descriptions` | bool |  | disable completion descriptions |

`--json` prints the text output in the JSON envelope. Needs no project.

## engine-dmo completion zsh [#engine-dmo-completion-zsh]

```text
Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

	echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

	source <(engine-dmo completion zsh)

To load completions for every new session, execute once:

#### Linux:

	engine-dmo completion zsh > "${fpath[1]}/_engine-dmo"

#### macOS:

	engine-dmo completion zsh > $(brew --prefix)/share/zsh/site-functions/_engine-dmo

You will need to start a new shell for this setup to take effect.
```

```bash
engine-dmo completion zsh [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--no-descriptions` | bool |  | disable completion descriptions |

`--json` prints the text output in the JSON envelope. Needs no project.


# config (/reference/cli/config)

engine-dmo config: Configuration tools. Every subcommand, argument and flag.

Configuration tools.

| Command | What it does |
|---|---|
| [`engine-dmo config render`](#engine-dmo-config-render) | Print the fully resolved config, secrets redacted |
| [`engine-dmo config schema`](#engine-dmo-config-schema) | JSON Schema (draft 2020-12) of each configuration file, generated from the structs the loaders decode |
| [`engine-dmo config validate`](#engine-dmo-config-validate) | Validate config only, no database |

## engine-dmo config render [#engine-dmo-config-render]

Print the fully resolved config, secrets redacted.

`config render` and `config validate` load the whole configuration, so every `${VAR}` without a default must be set, secrets included, even though neither connects to the database. See [Commands and the environment](/reference/cli#commands-and-the-environment).

```bash
engine-dmo config render
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo config schema [#engine-dmo-config-schema]

JSON Schema (draft 2020-12) of each configuration file, generated from the structs the loaders decode.

```bash
engine-dmo config schema [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--anywhere` | bool |  | with `--write`, match config directories anywhere under the root (`**/config`/...), for a repository of several projects |
| `--editors` | strings |  | with `--write`, merge the file-pattern mappings into these editors' project settings: zed, vscode |
| `--file` | string |  | one kind of file: its kind (`engine`, `site`, `routes`, `schema` and the rest), or a real path such as `config/sites/town/site.yaml`. A bare file name is refused: `--file site.yaml` exits 3, `--file site` works |
| `--write` | string |  | write every kind's schema as `<dir>/<kind>.json`, for editors (default for a project:.`meridian/schema`) |

`--json` prints the command's own JSON document. Needs no project.

## engine-dmo config validate [#engine-dmo-config-validate]

Validate config only, no database.

```bash
engine-dmo config validate
```

`--json` prints the text output in the JSON envelope. Runs in a project.

See [Configuration](/reference/configuration).


# content (/reference/cli/content)

engine-dmo content: Content operations: list, get, create, update, trash, restore, hold, purge, clone, reproject, reindex, publish, structure, variant, prune-revisions, legal-hold. Every subcommand, argument and flag.

Content operations: list, get, create, update, trash, restore, hold, purge, clone, reproject, reindex, publish, structure, variant, prune-revisions, legal-hold.

There is no command to unpublish a locale or to schedule a publish: `content publish` publishes now. Unpublish or schedule in the admin, or through the [content MCP](/integrating/content-mcp) (its `publish` tool takes `publish_at`, and `unpublish` takes a redirect destination). A seed can leave a document scheduled with `schedule:`. Taking a page down from the terminal is `content trash`, which takes `--redirect` (`parent`, a path or `none`) when a locale is live.

| Command | What it does |
|---|---|
| [`engine-dmo content clone`](#engine-dmo-content-clone) | Copy a document as a new draft on a site |
| [`engine-dmo content create`](#engine-dmo-content-create) | Create a document from a JSON object of field values, validated as the admin validates a save; `--publish` runs the publish checks |
| [`engine-dmo content export`](#engine-dmo-content-export) | Export a type's documents on a site, or a selection, as JSON or CSV with their working values per locale; audited |
| [`engine-dmo content get`](#engine-dmo-content-get) | A document's working and published values by field handle, and its status per locale |
| [`engine-dmo content hold`](#engine-dmo-content-hold) | Keep a trashed document until someone decides, or `--until` a date, or `--release` |
| [`engine-dmo content import`](#engine-dmo-content-import) | Import a JSON export file as drafts, matched by id or slug, never published; `--dry-run` writes nothing |
| [`engine-dmo content legal-hold`](#engine-dmo-content-legal-hold) | Place a legal hold on a document, keeping every revision and refusing its purge; `--release` removes it |
| [`engine-dmo content list`](#engine-dmo-content-list) | List documents, one line each |
| [`engine-dmo content prune-revisions`](#engine-dmo-content-prune-revisions) | Run the revision retention sweep now, resuming an interrupted run; `--dry-run` says what would go |
| [`engine-dmo content publish`](#engine-dmo-content-publish) | Publish a locale through the publish checks, or every locale whose checks pass with `--all-locales` |
| [`engine-dmo content purge`](#engine-dmo-content-purge) | Hard delete, irreversible; `--expired` runs the nightly sweep now |
| [`engine-dmo content reindex`](#engine-dmo-content-reindex) | Queue search indexing for every published document, on every site and locale |
| [`engine-dmo content reproject`](#engine-dmo-content-reproject) | Rewrite the projection index, relations, shapes and occurrences under the current schema |
| [`engine-dmo content restore`](#engine-dmo-content-restore) | Reinstate, re-resolve URIs, republish what was live |
| [`engine-dmo content structure`](#engine-dmo-content-structure) | Override how one document holds a container field, shared or per_locale; audited |
| [`engine-dmo content trash`](#engine-dmo-content-trash) | Soft delete; `--redirect` is required when any locale is live |
| [`engine-dmo content update`](#engine-dmo-content-update) | Merge field values over a locale's working revision and save; only the fields given change, and null clears one |
| [`engine-dmo content variant set`](#engine-dmo-content-variant-set) | Move documents to another entry variant, by `--id` or every one of `--type` in `--from`; values the new variant does not show are set aside, not deleted |

## engine-dmo content clone [#engine-dmo-content-clone]

Copy a document as a new draft on a site.

```bash
engine-dmo content clone [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--no-tags` | bool |  | leave taggings behind |
| `--site` | string |  | target site (default: the source's owner site) |
| `--title` | string |  | title of the copy in the source locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content create [#engine-dmo-content-create]

Create a document from a JSON object of field values, validated as the admin validates a save; `--publish` runs the publish checks.

```bash
engine-dmo content create [values] [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `values` | no | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--data` | string |  | the field values as a JSON object, or - for standard input |
| `--locale` | string |  | locale of the values (default: the source locale) |
| `--publish` | bool |  | publish the locale through the publish checks |
| `--site` | string |  | owner site (default: the default site) |
| `--type` | string |  | type key |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content export [#engine-dmo-content-export]

Export a type's documents on a site, or a selection, as JSON or CSV with their working values per locale; audited.

```bash
engine-dmo content export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--format` | string | `json` | json \| csv |
| `--id` | string, repeatable |  | a selection: only this document (repeatable) |
| `--ids-from` | string |  | a selection: a file with one document id a line |
| `--locale` | string, repeatable |  | only this locale (repeatable); every locale when left out |
| `--out` | string |  | file to write; standard output when empty or - |
| `--site` | string |  | site key (default: the default site) |
| `--type` | string |  | type key |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content get [#engine-dmo-content-get]

A document's working and published values by field handle, and its status per locale.

```bash
engine-dmo content get <id> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `id` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | one locale (default: every locale the document has) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content hold [#engine-dmo-content-hold]

Keep a trashed document until someone decides, or `--until` a date, or `--release`.

```bash
engine-dmo content hold [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--release` | bool |  | restore the retention window from now |
| `--until` | string |  | purge on this date (YYYY-MM-DD) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content import [#engine-dmo-content-import]

Import a JSON export file as drafts, matched by id or slug, never published; `--dry-run` writes nothing.

```bash
engine-dmo content import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | say what would happen to each locale and write nothing |
| `--file` | string |  | the JSON file an export wrote; - reads standard input |
| `--match` | string | `id` | id \| slug: how a document in the file finds the one it updates |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content legal-hold [#engine-dmo-content-legal-hold]

Place a legal hold on a document, keeping every revision and refusing its purge; `--release` removes it.

```bash
engine-dmo content legal-hold [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | document id |
| `--reason` | string |  | why the document is held; recorded with the hold and in the audit log |
| `--release` | bool |  | remove the hold |
| `--until` | string |  | the last day the hold protects (YYYY-MM-DD); omitted, it holds until released |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content list [#engine-dmo-content-list]

List documents, one line each.

```bash
engine-dmo content list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | locale code |
| `--site` | string |  | site key (default: the default site) |
| `--status` | string |  | draft \| in_review \| published \| scheduled \| archived |
| `--trashed` | bool |  | list the trash instead |
| `--type` | string |  | type key |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content prune-revisions [#engine-dmo-content-prune-revisions]

Run the revision retention sweep now, resuming an interrupted run; `--dry-run` says what would go.

```bash
engine-dmo content prune-revisions [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | delete nothing and print what would go |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content publish [#engine-dmo-content-publish]

Publish a locale through the publish checks, or every locale whose checks pass with `--all-locales`.

```bash
engine-dmo content publish [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all-locales` | bool |  | every locale with a working revision, source first; a locale whose checks fail is skipped and named |
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--locale` | string |  | locale code |
| `--no-redirect` | string |  | the reason a changed live path gets no redirect; audited |
| `--no-shared` | bool |  | leave the shared draft unpublished |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content purge [#engine-dmo-content-purge]

Hard delete, irreversible; `--expired` runs the nightly sweep now.

```bash
engine-dmo content purge [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--expired` | bool |  | every trashed document past its purge_after |
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--yes` | bool |  | confirm |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content reindex [#engine-dmo-content-reindex]

Queue search indexing for every published document, on every site and locale.

```bash
engine-dmo content reindex [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--type` | string |  | type key (default: every type) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content reproject [#engine-dmo-content-reproject]

Rewrite the projection index, relations, shapes and occurrences under the current schema.

```bash
engine-dmo content reproject [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--field` | string |  | a field of `--type`; the whole document is reprojected, the flag checks the field exists |
| `--type` | string |  | type key (default: every type) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content restore [#engine-dmo-content-restore]

Reinstate, re-resolve URIs, republish what was live.

```bash
engine-dmo content restore [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--slug-on-conflict` | string | `suffix` | suffix \| fail |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content structure [#engine-dmo-content-structure]

Override how one document holds a container field, shared or per_locale; audited.

```bash
engine-dmo content structure [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--field` | string |  | a top-level repeater or blocks field |
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--mode` | string | `per_locale` | shared \| per_locale |
| `--reason` | string |  | why this document differs; recorded in the audit log |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content trash [#engine-dmo-content-trash]

Soft delete; `--redirect` is required when any locale is live.

```bash
engine-dmo content trash [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--hold` | bool |  | clear purge_after |
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--redirect` | string |  | parent \| /path \| none |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo content update [#engine-dmo-content-update]

Merge field values over a locale's working revision and save; only the fields given change, and null clears one.

```bash
engine-dmo content update <id> [values] [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `id` | yes | no |
| `values` | no | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--data` | string |  | the field values as a JSON object, or - for standard input |
| `--locale` | string |  | locale to save (default: the source locale) |
| `--publish` | bool |  | publish the locale through the publish checks |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo content variant set [#engine-dmo-content-variant-set]

Move documents to another entry variant, by `--id` or every one of `--type` in `--from`; values the new variant does not show are set aside, not deleted.

```bash
engine-dmo content variant set [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | write nothing and say what each move would set aside |
| `--from` | string |  | move every live document of `--type` in this variant (the default variant also holds documents naming none) |
| `--id` | string, repeatable |  | document id (repeatable) |
| `--ids-from` | string |  | file with one id per line |
| `--site` | string |  | with `--from`, only documents this site owns |
| `--to` | string |  | the variant to move to |
| `--type` | string |  | type key, with `--from` |

`--json` prints the text output in the JSON envelope. Runs in a project.


# crm (/reference/cli/crm)

engine-dmo crm: The CRM from the command line: organisations, memberships, duplicate candidates, invitations and claims. Every subcommand, argument and flag.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The CRM from the command line: organisations, memberships, duplicate candidates, invitations and claims.

| Command | What it does |
|---|---|
| [`engine-dmo crm claims list`](#engine-dmo-crm-claims-list) | Claims by site: verified and held by default, or `--status` verified\|held\|pending\|decided |
| [`engine-dmo crm claims rescore`](#engine-dmo-crm-claims-rescore) | Recompute open claims' confidence under the current weights; never approves |
| [`engine-dmo crm claims show`](#engine-dmo-crm-claims-show) | One claim: the score, every signal, the contacts' answers and the letter |
| [`engine-dmo crm dedupe`](#engine-dmo-crm-dedupe) | Candidate duplicate pairs with scores, offered for review in the admin |
| [`engine-dmo crm erase`](#engine-dmo-crm-erase) | Erase a person, irreversibly: personal columns and fields cleared, sessions and links ended, the address suppressed, every mention replaced by a tombstone |
| [`engine-dmo crm import`](#engine-dmo-crm-import) | Import organisations, people and memberships from a CSV or XLSX file through a source's mapping; `--dry-run` plans every row and writes nothing |
| [`engine-dmo crm invite`](#engine-dmo-crm-invite) | Send a portal invitation: the contact is linked as the organisation's owner and the invitation mail is queued |
| [`engine-dmo crm membership set`](#engine-dmo-crm-membership-set) | Give an organisation a tier on a site: changes its pending or active membership there, or starts one |
| [`engine-dmo crm merge`](#engine-dmo-crm-merge) | Merge one organisation or person into another: what points at it moves, blank fields are filled, and it goes to the trash |
| [`engine-dmo crm organisation create`](#engine-dmo-crm-organisation-create) | Create an organisation from a JSON object: name, legal_name, status, email, website, address, phone, social, hours, custom, lat, lon |

## engine-dmo crm claims list [#engine-dmo-crm-claims-list]

Claims by site: verified and held by default, or `--status` verified\|held\|pending\|decided.

```bash
engine-dmo crm claims list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | one site (default: every site) |
| `--status` | string |  | verified \| held \| pending \| decided (default: the open queue) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo crm claims rescore [#engine-dmo-crm-claims-rescore]

Recompute open claims' confidence under the current weights; never approves.

```bash
engine-dmo crm claims rescore [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | print what would change without writing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm claims show [#engine-dmo-crm-claims-show]

One claim: the score, every signal, the contacts' answers and the letter.

```bash
engine-dmo crm claims show <id>
```

| Argument | Required | Repeatable |
|---|---|---|
| `id` | yes | no |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo crm dedupe [#engine-dmo-crm-dedupe]

Candidate duplicate pairs with scores, offered for review in the admin.

```bash
engine-dmo crm dedupe [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | print the candidate pairs and offer nothing for review; the embedding requests are still made and charged |
| `--subject` | string | `organisation` | what to compare: organisation |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm erase [#engine-dmo-crm-erase]

Erase a person, irreversibly: personal columns and fields cleared, sessions and links ended, the address suppressed, every mention replaced by a tombstone.

```bash
engine-dmo crm erase [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | confirm the erasure |
| `--person` | string |  | the person's id |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm import [#engine-dmo-crm-import]

Import organisations, people and memberships from a CSV or XLSX file through a source's mapping; `--dry-run` plans every row and writes nothing.

```bash
engine-dmo crm import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | plan every row and print what would be created, updated, skipped and rejected; nothing is written |
| `--file` | string |  | the CSV or XLSX file |
| `--map` | string |  | the column mapping, YAML or JSON; saved on the source for its next file (default: the source's saved mapping) |
| `--name` | string |  | a new source's name |
| `--network` | string |  | a new source's network, by key (default: the default site's) |
| `--source` | string |  | the source the file comes from, by key; created when new |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm invite [#engine-dmo-crm-invite]

Send a portal invitation: the contact is linked as the organisation's owner and the invitation mail is queued.

```bash
engine-dmo crm invite [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | the contact's address |
| `--name` | string |  | the contact's name |
| `--organisation` | string |  | the organisation id |
| `--role` | string |  | their role, such as Landlord |
| `--site` | string |  | the site the invitation is from (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm membership set [#engine-dmo-crm-membership-set]

Give an organisation a tier on a site: changes its pending or active membership there, or starts one.

```bash
engine-dmo crm membership set <organisation-id> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `organisation-id` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--reason` | string |  | why, for the membership history |
| `--site` | string |  | site key (default: the default site) |
| `--status` | string |  | pending \| active \| lapsed \| cancelled (default: active for a new membership, unchanged otherwise) |
| `--tier` | string |  | the membership tier |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo crm merge [#engine-dmo-crm-merge]

Merge one organisation or person into another: what points at it moves, blank fields are filled, and it goes to the trash.

```bash
engine-dmo crm merge [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | print what would move and be filled, and change nothing |
| `--keep` | string |  | the id of the record to keep |
| `--merge` | string |  | the id of the record merged into it |
| `--subject` | string | `organisation` | organisation or person |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo crm organisation create [#engine-dmo-crm-organisation-create]

Create an organisation from a JSON object: name, legal_name, status, email, website, address, phone, social, hours, custom, lat, lon.

```bash
engine-dmo crm organisation create [values] [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `values` | no | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--data` | string |  | the organisation as a JSON object, or - for standard input |

`--json` prints the command's own JSON document. Runs in a project.


# describe (/reference/cli/describe)

engine-dmo describe: Describe the project, a content type, the field types, a route or a template, with ids, as text or --json. Every subcommand, argument and flag.

Describe the project, a content type, the field types, a route or a template, with ids, as text or `--json`.

`describe project` and `describe type` read the project without its secrets, so they run with `DATABASE_URL` and `SIGNING_KEY` unset. `describe template` loads the whole configuration and needs every variable set; `describe route` also connects to the database. See [Commands and the environment](/reference/cli#commands-and-the-environment).

`describe type` on a core type lists the core fields (marked `core`) and the fields your `config/schema/<type>.yaml` adds. `describe project` lists every module the bundle compiles as enabled, such as `portal /members, both` on `engine-dmo`; turn a module's feature off in its own configuration (for the portal, `portal.mode: "off"` in [the portal files](/reference/configuration/portal)).

| Command | What it does |
|---|---|
| [`engine-dmo describe fieldtypes`](#engine-dmo-describe-fieldtypes) | Every field type, what it stores, its parameters and its default translate mode |
| [`engine-dmo describe project`](#engine-dmo-describe-project) | Networks, sites, locales, types, routes, endpoints, reports, tiers, partner roles and staff roles, with their ids |
| [`engine-dmo describe route`](#engine-dmo-describe-route) | Which route answers a path, the template the site's chain resolved, and the whole template context with real values |
| [`engine-dmo describe template`](#engine-dmo-describe-template) | A template's file along the site's chain, what it extends and includes, the type it renders and the contract it is checked against |
| [`engine-dmo describe type`](#engine-dmo-describe-type) | A content type's fields at every depth with ids, types, params, groups, blocks, options, sites and member rules |

## engine-dmo describe fieldtypes [#engine-dmo-describe-fieldtypes]

Every field type, what it stores, its parameters and its default translate mode.

```bash
engine-dmo describe fieldtypes
```

`--json` prints the command's own JSON document. Needs no project.

## engine-dmo describe project [#engine-dmo-describe-project]

Networks, sites, locales, types, routes, endpoints, reports, tiers, partner roles and staff roles, with their ids.

```bash
engine-dmo describe project
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo describe route [#engine-dmo-describe-route]

Which route answers a path, the template the site's chain resolved, and the whole template context with real values.

```bash
engine-dmo describe route <path> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `path` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--host` | string |  | the Host the request carries (default: the site's first domain, or the locale's under the domain strategy) |
| `--locale` | string |  | locale code; the path is then the unprefixed URI and the locale's prefix or domain is added |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo describe template [#engine-dmo-describe-template]

A template's file along the site's chain, what it extends and includes, the type it renders and the contract it is checked against.

```bash
engine-dmo describe template <name> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo describe type [#engine-dmo-describe-type]

A content type's fields at every depth with ids, types, params, groups, blocks, options, sites and member rules.

```bash
engine-dmo describe type <key>
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

`--json` prints the command's own JSON document. Runs in a project.


# dev (/reference/cli/dev)

engine-dmo dev: Local development: the serve, check and apply loop, and the authoring verbs. Every subcommand, argument and flag.

Local development: the serve, check and apply loop, and the authoring verbs.

| Command | What it does |
|---|---|
| [`engine-dmo dev config set`](#engine-dmo-dev-config-set) | Set one value in a configuration file (search.driver meilisearch), checked like any verb |
| [`engine-dmo dev config unset`](#engine-dmo-dev-config-unset) | Remove one key from a configuration file, checked like any verb |
| [`engine-dmo dev endpoint add`](#engine-dmo-dev-endpoint-add) | Add a declared endpoint from a recipe (recipe:enquiry, recipe:newsletter) |
| [`engine-dmo dev field add`](#engine-dmo-dev-field-add) | Add a field to a type, or a custom field to organisation or person, with its id |
| [`engine-dmo dev field remove`](#engine-dmo-dev-field-remove) | Remove a field; its values stay under its id, and the plan says how many documents hold one |
| [`engine-dmo dev field rename`](#engine-dmo-dev-field-rename) | Rename a field: its handle changes, its id and values stay, the old handle stays an alias |
| [`engine-dmo dev field set`](#engine-dmo-dev-field-set) | Change a field's label, help or a parameter |
| [`engine-dmo dev group add`](#engine-dmo-dev-group-add) | Add a group to a type's editor layout |
| [`engine-dmo dev importer rename`](#engine-dmo-dev-importer-rename) | Rename a importer: its key changes in `importers.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays |
| [`engine-dmo dev locale add`](#engine-dmo-dev-locale-add) | Declare a locale in `locales.yaml` with its id, and enable it on a site |
| [`engine-dmo dev network add`](#engine-dmo-dev-network-add) | Declare a network in `networks.yaml` with its id, and join sites to it |
| [`engine-dmo dev option add`](#engine-dmo-dev-option-add) | Add an option, with its id, to a select field, or a style to a link field |
| [`engine-dmo dev portal action add`](#engine-dmo-dev-portal-action-add) | Declare a portal action on a site, with its id, target, fields, permission and tiers |
| [`engine-dmo dev portal screen add`](#engine-dmo-dev-portal-screen-add) | Declare a portal screen on a site, with its id, path, template, permission, tiers and data; `--scaffold` writes its template |
| [`engine-dmo dev role add`](#engine-dmo-dev-role-add) | Declare a partner role in `portal/roles.yaml` with its id and grants; a built-in key restates that role with the grants given |
| [`engine-dmo dev route add`](#engine-dmo-dev-route-add) | Route a type on a site, with its id; `--scaffold` writes its template |
| [`engine-dmo dev site add`](#engine-dmo-dev-site-add) | Add a site directory with its `site.yaml` and `routes.yaml` |
| [`engine-dmo dev site rename`](#engine-dmo-dev-site-rename) | Rename a site: its directory moves, its id and data stay, old admin and public URLs redirect |
| [`engine-dmo dev slot add`](#engine-dmo-dev-slot-add) | Declare a promotion slot on a site, with its id, the types it promotes, its capacity and its rules |
| [`engine-dmo dev source rename`](#engine-dmo-dev-source-rename) | Rename a source: its key changes in `sources.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays |
| [`engine-dmo dev status`](#engine-dmo-dev-status) | What engine-dmo dev up last found: the check, the plan, live aliases, the address and the images the sizing check found oversized |
| [`engine-dmo dev tier add`](#engine-dmo-dev-tier-add) | Declare a membership tier in `memberships.yaml` with its id, ranked last or after another tier |
| [`engine-dmo dev tier rename`](#engine-dmo-dev-tier-rename) | Rename a tier: its key changes in `memberships.yaml` and every rule naming it, its id and memberships stay |
| [`engine-dmo dev type add`](#engine-dmo-dev-type-add) | A custom type with a title, a slug and a summary |
| [`engine-dmo dev up`](#engine-dmo-dev-up) | Serve with the config watcher: on every change write missing ids, check, plan, apply what is safe and reload |
| [`engine-dmo dev webhook rename`](#engine-dmo-dev-webhook-rename) | Rename a webhook: its key changes in `webhooks.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays |

## How the verbs behave [#how-the-verbs-behave]

Each authoring verb makes its change in a copy of the configuration, loads that copy the way `check` does, and writes the files only when the configuration is still valid; otherwise it prints the problems and exits 3 with `nothing was written`. It writes the ids of the elements it adds, so never write an id by hand. `--dry-run` prints the diff and writes nothing.

The verbs run without a database and without the deployment's secrets (see [Commands and the environment](/reference/cli#commands-and-the-environment)), in `development`, in `staging` only with `dev.authoring: true`, and never in `production`.

What the configuration check does not cover, and how to finish the job:

| Verb | What happens | What to do |
|---|---|---|
| `dev endpoint add` | Writes `endpoints.yaml` and exits 0, saying the recipe's templates are the site's to write. `check` then fails until the response partials and mail templates exist | Write the templates the message names, then run `check` |
| `dev route add --scaffold` | Writes `routes.yaml` first, then the entry template, which loads the whole configuration. With `DATABASE_URL` (or another variable without a default) unset, the route is written and the command exits 3 with no template. Run again, it answers `nothing to change` and still writes no template | Set the placeholders from [Commands and the environment](/reference/cli#commands-and-the-environment) first. If the route is already written, run `engine-dmo new template <type>/entry.html` |
| `dev route add --index ... --scaffold` | Writes `<type>/entry.html` only. `check` then fails: `type "walk" has an index route and no walk/index.html` | Run `engine-dmo new template <type>/index.html`. The file it writes is an empty block with no heading; give it an `h1` and the list before you render it |
| `dev field add <core type> ... --after <core field>` | On a core type (`page`, `article` and the other built-in types) whose `config/schema/<type>.yaml` already exists, `--after` names only fields in that file: `--after names "slug", which is not a field in schema/page.yaml`, exit 3 | Leave out `--after` (the field goes last), or name a field you added. `engine-dmo describe type <type>` lists the core fields, marked `core` |

`dev config set` rewrites the map it changes and may reorder its keys (setting `site.name.cy` can put `cy` before `en`). The order has no meaning.

## engine-dmo dev config set [#engine-dmo-dev-config-set]

Set one value in a configuration file (search.driver meilisearch), checked like any verb.

```bash
engine-dmo dev config set <file> <path> <value> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `file` | yes | no |
| `path` | yes | no |
| `value` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev config unset [#engine-dmo-dev-config-unset]

Remove one key from a configuration file, checked like any verb.

```bash
engine-dmo dev config unset <file> <path> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `file` | yes | no |
| `path` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev endpoint add [#engine-dmo-dev-endpoint-add]

Add a declared endpoint from a recipe (recipe:enquiry, recipe:newsletter)

```bash
engine-dmo dev endpoint add <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--from` | string | `recipe:enquiry` | the recipe |
| `--site` | string |  | the site (default: the default site) |
| `--subject` | string |  | for an enquiry, the type it is about, taken from the path |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev field add [#engine-dmo-dev-field-add]

Add a field to a type, or a custom field to organisation or person, with its id.

```bash
engine-dmo dev field add <type> <name> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--after` | string |  | place it after this field |
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--group` | string |  | add it to this group of the editor |
| `--help-text` | string |  | its help text in the source locale |
| `--index` | bool |  | projected for listing, filtering and sorting |
| `--label` | string |  | its label in the source locale |
| `--options` | strings |  | a select's option values, each given an id |
| `--param` | string, repeatable |  | a type parameter as key=value in YAML (max=280, multiline=true); repeatable |
| `--required` | bool |  | required at publish |
| `--site` | string |  | a field this site alone offers, on a shared type |
| `--translate` | string |  | none \| locale \| language \| group |
| `--type` | string |  | the field type (engine-dmo describe fieldtypes) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev field remove [#engine-dmo-dev-field-remove]

Remove a field; its values stay under its id, and the plan says how many documents hold one.

```bash
engine-dmo dev field remove <type> <name> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev field rename [#engine-dmo-dev-field-rename]

Rename a field: its handle changes, its id and values stay, the old handle stays an alias.

```bash
engine-dmo dev field rename <type> <old> <new> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--no-alias` | bool |  | do not keep the old handle as an alias |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev field set [#engine-dmo-dev-field-set]

Change a field's label, help or a parameter.

```bash
engine-dmo dev field set <type> <name> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--help-text` | string |  | its help text in the source locale |
| `--label` | string |  | its label in the source locale |
| `--param` | string, repeatable |  | set key=value on the field (required=true, max=120); repeatable |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev group add [#engine-dmo-dev-group-add]

Add a group to a type's editor layout.

```bash
engine-dmo dev group add <type> <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--fields` | strings |  | the fields it holds, in order |
| `--label` | string |  | the group's label in the source locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev importer rename [#engine-dmo-dev-importer-rename]

Rename a importer: its key changes in `importers.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays.

```bash
engine-dmo dev importer rename <old> <new> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--site` | string |  | the site whose `importers.yaml` it is; omitted, the default site |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev locale add [#engine-dmo-dev-locale-add]

Declare a locale in `locales.yaml` with its id, and enable it on a site.

```bash
engine-dmo dev locale add <code> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `code` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--fallback` | strings |  | locales it falls back to, in order |
| `--label` | string |  | the locale's name in its own language |
| `--site` | string |  | enable it on this site |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev network add [#engine-dmo-dev-network-add]

Declare a network in `networks.yaml` with its id, and join sites to it.

```bash
engine-dmo dev network add <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--name` | string |  | the network's name in the source locale |
| `--site` | strings |  | a site to join the network; repeatable |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev option add [#engine-dmo-dev-option-add]

Add an option, with its id, to a select field, or a style to a link field.

```bash
engine-dmo dev option add <type> <field> <value> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `field` | yes | no |
| `value` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--class` | string |  | a link style's class |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--label` | string |  | the option's label in the source locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev portal action add [#engine-dmo-dev-portal-action-add]

Declares a portal action in `config/sites/<site>/portal.yaml`: a form posted to \{portal path\}/actions/&lt;key>. The key is `<subject>`.`<verb>`, the verb one of create, update, remove, add, submit, request, invite. The target is one of `--document` `<type>` (with `--create` for a new document of the active organisation, or the document named by ?id=), `--organisation` or `--person` (their custom fields, named custom.`<name>`). `--can` is the permission a partner's role must grant (default action.`<key>`), and `--tiers` or `--min-tier` the tiers whose organisations may use it (default every tier and none).

```bash
engine-dmo dev portal action add <subject.verb> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `subject.verb` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--approval` | string |  | tier (the tier's member_editable rule, the default) or required |
| `--can` | string |  | the partner permission the action needs (default action.`<key>`) |
| `--create` | bool |  | with `--document`, create a new document of the active organisation |
| `--document` | string |  | a document target: the type it writes |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--fields` | strings |  | the fields it writes; repeatable or comma separated |
| `--label` | string |  | the action's name in the source locale, where a screen lists it |
| `--min-tier` | string |  | the lowest tier that may use it, and every tier ranked above |
| `--organisation` | bool |  | write the active organisation's custom fields |
| `--person` | bool |  | write the signed-in person's custom fields |
| `--rate-limit` | string |  | a limit such as `20/hour/person` |
| `--respond` | string |  | a reference screen to redirect to after a good post |
| `--site` | string |  | the site (default: the default site) |
| `--tiers` | strings |  | the tiers whose organisations may use it, none included; repeatable or comma separated |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev portal screen add [#engine-dmo-dev-portal-screen-add]

```text
Declares a portal screen in config/sites/<site>/portal.yaml: a page under the portal path rendered from a template
under the site's portal template directory, with declared data the engine reads scoped to the partner's organisation.
--path carries {org}, {id} or neither (default /organisations/{org}/<key>); --template defaults to <key>.html.
--data is repeatable: a name, the source and its parameters, such as
  --data 'offers=documents type=offer states=draft,published sort=-updatedAt limit=50'
The sources are documents, document, published, report, enquiries, pending, people, membership, organisation, promotions, first_session.
A key that is a reference screen's (dashboard, organisation, report, contact_details, people, membership, contact_team, enquiries, events, promotions, listing_edit, photos, hours) replaces that screen's template
and takes only --template.
```

```bash
engine-dmo dev portal screen add <key> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--can` | string |  | the partner permission the screen needs (default screen.`<key>`) |
| `--data` | string, repeatable |  | a data source: '`<name>`=`<source>` [`<param>`=`<value>`...]'; repeatable |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--min-tier` | string |  | the lowest tier that may open it, and every tier ranked above |
| `--nav-group` | string |  | put the screen in the portal navigation under this group (default business with `--nav-order`) |
| `--nav-order` | int | `0` | the screen's place in its navigation group |
| `--path` | string |  | the path under the portal path, with `{org}`, `{id}` or neither (default /organisations/\{org\}/&lt;key>) |
| `--scaffold` | bool |  | write the screen's template under the site's first template root, unless the chain already has it |
| `--site` | string |  | the site (default: the default site) |
| `--template` | string |  | the template under the site's portal template directory (default `<key>`.html) |
| `--tiers` | strings |  | the tiers whose organisations may open it, none included; repeatable or comma separated |
| `--title` | string |  | the screen's title in the source locale, which the navigation shows |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev role add [#engine-dmo-dev-role-add]

Declares a partner role: what a person may do for an organisation in the portal and the member API. `--can` takes the permissions it grants (profile.update, organisation.update, listing.update, photos.add, photos.remove, hours.update, event.submit, people.invite, people.manage, promotion.request, billing.pay, enquiries.manage, report.view, enquiries.view, membership.view, pending.view) and patterns such as listing.* or *. A key that is owner, manager, contact or billing restates the built-in role, which keeps the engine's id; owner always holds every permission.

```bash
engine-dmo dev role add <key> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--can` | strings |  | a permission or pattern the role grants; repeatable or comma separated |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--label` | string |  | the role's name in the source locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev route add [#engine-dmo-dev-route-add]

Route a type on a site, with its id; `--scaffold` writes its template.

```bash
engine-dmo dev route add <type> <uri> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `type` | yes | no |
| `uri` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--index` | string |  | the index route's uri |
| `--scaffold` | bool |  | write the type's template from its fields (engine-dmo new template) |
| `--site` | string |  | the site (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev site add [#engine-dmo-dev-site-add]

Add a site directory with its `site.yaml` and `routes.yaml`.

```bash
engine-dmo dev site add <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--domain` | strings |  | a host the site answers; repeatable |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--locales` | strings |  | the locales it enables, the first its default |
| `--name` | string |  | the site's name |
| `--network` | string |  | the network it joins, declared when new; omitted, the default network |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev site rename [#engine-dmo-dev-site-rename]

Rename a site: its directory moves, its id and data stay, old admin and public URLs redirect.

```bash
engine-dmo dev site rename <old> <new> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev slot add [#engine-dmo-dev-slot-add]

Declares a slot in `config/sites/<site>/promotions.yaml`: a place on the site's pages where a promotion can appear, rendered by promoted('`<key>`') and labelled by promotionLabel(item). `--types` names the document types it may promote; `--capacity` how many are live at once (default 1); `--min-days` and `--max-days` bound a promotion's length; `--lead-time` is the earliest a request may start after it is made (3d); `--tiers` or `--min-tier` say whose organisations may request it (default every tier and none); `--price` is shown to the partner, with `--currency` (default the site's) and `--per` week, day or placement.

```bash
engine-dmo dev slot add <key> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--capacity` | int | `0` | how many promotions are live in it at once (default 1) |
| `--currency` | string |  | the price's currency (default the site's) |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--lead-time` | string |  | the earliest a request may start after it is made, such as 3d |
| `--max-days` | int | `0` | the longest promotion in days (default no limit) |
| `--min-days` | int | `0` | the shortest promotion in days (default 1) |
| `--min-tier` | string |  | the lowest tier that may request it, and every tier ranked above |
| `--name` | string |  | the slot's name in the source locale, as staff and partners see it |
| `--per` | string |  | what the price is for: week, day or placement (default placement) |
| `--price` | string |  | the price shown to the partner, a decimal such as 150.00 |
| `--site` | string |  | the site (default: the default site) |
| `--tiers` | strings |  | the tiers whose organisations may request it, none included; repeatable or comma separated |
| `--types` | strings |  | the document types it may promote; repeatable or comma separated |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev source rename [#engine-dmo-dev-source-rename]

Rename a source: its key changes in `sources.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays.

```bash
engine-dmo dev source rename <old> <new> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--site` | string |  | the site whose `sources.yaml` it is; omitted, the default site |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev status [#engine-dmo-dev-status]

What engine-dmo dev up last found: the check, the plan, live aliases, the address and the images the sizing check found oversized.

```bash
engine-dmo dev status
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo dev tier add [#engine-dmo-dev-tier-add]

Declare a membership tier in `memberships.yaml` with its id, ranked last or after another tier.

```bash
engine-dmo dev tier add <key> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--after` | string |  | rank it directly above this tier; omitted, it ranks highest |
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--label` | string |  | the tier's name in the source locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev tier rename [#engine-dmo-dev-tier-rename]

Rename a tier: its key changes in `memberships.yaml` and every rule naming it, its id and memberships stay.

```bash
engine-dmo dev tier rename <old> <new> [flags]
```

Available in `engine-dmo` only.

| Argument | Required | Repeatable |
|---|---|---|
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev type add [#engine-dmo-dev-type-add]

A custom type with a title, a slug and a summary.

```bash
engine-dmo dev type add <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--label` | string |  | the type's name in the source locale |
| `--plural` | string |  | its plural |
| `--site` | string |  | declare it in this site's schema directory, so it is that site's alone |
| `--sites` | strings |  | declare it in `config/schema`/ on these sites only (sites:); each site's directory may then extend it |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev up [#engine-dmo-dev-up]

dev up runs serve `--dev` and watches config/. On a change it writes any missing ids (engine-dmo check `--fix`), loads and checks the whole project, computes the schema plan, and applies it if it is not destructive, then reloads the engine in this process. A failed check or a destructive plan leaves the engine on the last good configuration and prints why. engine-dmo dev status reads what it last found.

```bash
engine-dmo dev up [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--listen` | string |  | override server.listen |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo dev webhook rename [#engine-dmo-dev-webhook-rename]

Rename a webhook: its key changes in `webhooks.yaml` and in every endpoint step naming it, and its id, with what is stored under it, stays.

```bash
engine-dmo dev webhook rename <old> <new> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `old` | yes | no |
| `new` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply` | bool |  | after writing, apply the schema plan when it is not destructive |
| `--dry-run` | bool |  | print the diff of every file it would change, and write nothing |
| `--site` | string |  | the site whose `webhooks.yaml` it is; omitted, the default site |

`--json` prints the text output in the JSON envelope. Runs in a project.


# docs (/reference/cli/docs)

engine-dmo docs: The template API of this project, and the skill that points an agent at the handbook. Every subcommand, argument and flag.

The template API of this project, and the skill that points an agent at the handbook.

This handbook is not part of the binary. It is at https://docs.cherwell.studio, with its Markdown for agents at https://docs.cherwell.studio/llms.txt.

| Command | What it does |
|---|---|
| [`engine-dmo docs serve`](#engine-dmo-docs-serve) | Serve this project's generated template API on localhost. Development only |
| [`engine-dmo docs skill`](#engine-dmo-docs-skill) | Write the meridian skill for coding agents, which points at the handbook, for `.claude/skills/meridian/SKILL.md` |

## engine-dmo docs serve [#engine-dmo-docs-serve]

Serve this project's generated template API on localhost. Development only.

```bash
engine-dmo docs serve [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--listen` | string | `127.0.0.1:6061` | the loopback address to serve on |
| `--site` | string |  | one site's template API only (default: every site) |

`--json` prints the text output in the JSON envelope. Exits 3 outside a project.

## engine-dmo docs skill [#engine-dmo-docs-skill]

Write the meridian skill for coding agents, which points at the handbook, for `.claude/skills/meridian/SKILL.md`.

```bash
engine-dmo docs skill [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | write to a file, such as `.claude/skills/meridian/SKILL.md`, instead of the terminal |

`--json` prints the text output in the JSON envelope. Needs no project.


# doctor (/reference/cli/doctor)

engine-dmo doctor: The support bundle: one pasteable text file. Every subcommand, argument and flag.

The support bundle: one pasteable text file.

```bash
engine-dmo doctor [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--include-logs` | int | `0` | include the N most recent error groups the serving engine recorded |
| `--mail-to` | string |  | send a live test message through the configured mail driver to this address |
| `--out` | string |  | write the bundle to a file |
| `--redact-level` | string | `standard` | standard redacts secrets by declaration; paranoid also redacts host names, the database host and name, email and IP addresses |
| `--telemetry-test` | bool |  | send a test event to the error reporter and an empty export to the OTLP endpoint |

`--json` prints the text output in the JSON envelope. Runs in a project.

See [Monitoring](/deploying/monitoring#the-doctor-bundle).


# dpia (/reference/cli/dpia)

engine-dmo dpia: Write a data protection impact assessment with every technical fact filled from engine.yaml and the bundle. Every subcommand, argument and flag.

Write a data protection impact assessment as Markdown, every technical fact filled from `engine.yaml` and the bundle, the controller's questions left to complete.

```bash
engine-dmo dpia [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | the Markdown file to write; standard output when absent or `-` |

`--json` prints the text output in the JSON envelope. Runs in a project. It reads the configuration and never connects to the database, though every `${VAR}` in `engine.yaml` must be set ([Commands and the environment](/reference/cli#commands-and-the-environment)).

A file is overwritten if it exists.

See [Data protection duties](/deploying/data-protection#the-impact-assessment).


# export (/reference/cli/export)

engine-dmo export: Export a site's content for a static build: the content API's answers, or the embed widgets' fragments. Every subcommand, argument and flag.

Export a site's content for a static build: the content API's answers, or the embed widgets' fragments.

| Command | What it does |
|---|---|
| [`engine-dmo export content`](#engine-dmo-export-content) | Write a site's content API answers for a static build: `site.json`, strings, the sitemap, the redirects and every published path's resolve outcome; `--since` writes only what changed |
| [`engine-dmo export embeds`](#engine-dmo-export-embeds) | Write the embed widgets' HTML fragments and a JSON manifest for a static build |

## engine-dmo export content [#engine-dmo-export-content]

Write a site's content API answers for a static build: `site.json`, strings, the sitemap, the redirects and every published path's resolve outcome; `--since` writes only what changed.

```bash
engine-dmo export content [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | the directory to write to, such as./content |
| `--since` | string |  | write only what changed after this cursor, the cursor of a previous export's `manifest.json` |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo export embeds [#engine-dmo-export-embeds]

Write the embed widgets' HTML fragments and a JSON manifest for a static build.

```bash
engine-dmo export embeds [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--host` | string |  | the embedding site's host, credited with the impressions the static pages record |
| `--locale` | strings |  | locales to write, or all (default: the site's default locale) |
| `--out` | string |  | the directory to write to, such as./dist/embeds |
| `--site` | string |  | site key (default: the default site) |
| `--widget` | string, repeatable |  | a widget as `widget/id`?options, such as `list/things-to-do`?layout=list&limit=6 or search; repeatable (default: a list of each type with an index, and search) |

`--json` prints the command's own JSON document. Runs in a project.


# guide (/reference/cli/guide)

engine-dmo guide: Working guidance for this project, generated from its schema, routes and the engine's template contract. Every subcommand, argument and flag.

Working guidance for this project, generated from its schema, routes and the engine's template contract.

```bash
engine-dmo guide [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | write to a file, such as AGENTS.md, instead of the terminal |
| `--skill` | bool |  | write it as a skill file (front matter with a name and description), for agents that read skills |

`--json` prints the text output in the JSON envelope. Runs in a project.


# health (/reference/cli/health)

engine-dmo health: Liveness and readiness against a running server, for a load balancer or a deploy step. Every subcommand, argument and flag.

Liveness and readiness against a running server, for a load balancer or a deploy step.

```bash
engine-dmo health [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--readiness` | bool |  | exit 0 only when startup is complete, the database answers and every migration is applied; not while shutting down |
| `--wait` | duration | `0s` | keep trying for this long |

`--json` prints the command's own JSON document. Runs in a project.

See [Monitoring](/deploying/monitoring#health). The command requests `/health` on `server.listen`, so it runs beside the server with the same environment; it exits 4 when the server does not answer 200.


# CLI (/reference/cli)

Every engine-dmo and engine-cms command by purpose, the global flags, --json output (data or envelope), --quiet, how a command finds its project, and how to list the whole command tree as JSON.

Both binaries take the same commands, flags and arguments, except the commands of the DMO modules, which only `engine-dmo` has. This reference uses `engine-dmo`; for a core command, `engine-cms` behaves the same.

```bash
engine-dmo <command> [subcommand] [arguments] [flags]
engine-dmo <command> --help        # one command's flags
engine-dmo help --json             # every command, argument and flag, as JSON
```

Some `--help` and `help --json` texts cite documents by internal names, such as `(07-auth-and-permissions.md)`, `(ADR-0019)` or `make check`. Those documents are not published and those make targets are not yours; this reference and the rest of the handbook describe the same behaviour.

## Global flags [#global-flags]

Every command takes these:

| Flag | Default | Meaning |
|---|---|---|
| `--project` | `.` | The project directory. Commands that need a project read `config/` under it |
| `--config` | `config` | The configuration directory, relative to the project |
| `--json` | off | Machine-readable output on standard output (below) |
| `--quiet` | off | Print only errors. A command that prints data (a list, a report, a document) still prints it |
| `--no-colour` | off | No colour. A non-empty `NO_COLOR` environment variable does the same; colour is only ever used on a terminal |

## Output and exit codes [#output-and-exit-codes]

Under `--json` every command prints exactly one JSON document on standard output, in one of two shapes:

| Shape | Commands | What it is |
|---|---|---|
| Data | Commands whose job is to return something: `content get`, `describe type`, `migrate status`, `version`, `template api` and the other lists, reports and documents | The command's own document |
| Envelope | Commands that act and report what they did: `migrate up`, `schema apply`, `content publish`, `user create` and the rest | `{"command": "...", "exit": 0, "error": "...", "lines": ["..."]}`: the text output as lines, the exit code, and the error when there was one |

Each command's section below says which shape it prints. Errors, warnings and prompts go to standard error. The exit code is always meaningful:

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Error |
| `2` | Changes pending, or refused for want of confirmation |
| `3` | Configuration invalid, or a flag value that cannot be used (an unknown command or flag exits 1) |
| `4` | Degraded but running |

[Exit codes](/reference/exit-codes) says which commands use 2 and 4, and when.

## Commands by purpose [#commands-by-purpose]

### Projects and development [#projects-and-development]

| Command | Purpose |
|---|---|
| [init](/reference/cli/init) | Start a project: the bare starter, or a copy of a project with `--from` |
| [check](/reference/cli/check) | The CI gate: configuration, schema, routes, templates. Exit 3 on invalid configuration |
| [dev](/reference/cli/dev) | `dev up` (serve with the config watcher) and the authoring verbs that change configuration safely |
| [new](/reference/cli/new) | Scaffold a type, a template, a component or a block |
| [describe](/reference/cli/describe) | The project, a type, the field types, a route or a template, with ids |
| [guide](/reference/cli/guide) | Working guidance for this project, for a person or an agent |
| [render](/reference/cli/render) | Render one public page in process, with errors, queries and findings |
| [template](/reference/cli/template) | The generated template API and template tests |
| [build](/reference/cli/build) | Run the project's frontend build, then `check` |
| [assets](/reference/cli/assets) | The frontend build as the engine resolves it |
| [lsp](/reference/cli/lsp) | The template language server for an editor |
| [docs](/reference/cli/docs) | This handbook in the terminal, and served with the project's template API |
| [config](/reference/cli/config) | The resolved configuration, its validation, and the JSON Schema of every file |
| [seed](/reference/cli/seed) | Seed sets: validated content with history, assets and analytics |
| [plugin](/reference/cli/plugin) | Build the project's plugins |
| [completion](/reference/cli/completion) | Shell completion scripts |

### Deploying and operating [#deploying-and-operating]

| Command | Purpose |
|---|---|
| [serve](/reference/cli/serve) | Start the server |
| [migrate](/reference/cli/migrate) | Engine migrations, as a deploy step |
| [schema](/reference/cli/schema) | Plan and apply configuration against the database |
| [health](/reference/cli/health) | Liveness and readiness against a running server |
| [warm](/reference/cli/warm) | After a deploy: repair search, queue derivatives, warm the page cache |
| [doctor](/reference/cli/doctor) | The support bundle |
| [jobs](/reference/cli/jobs) | The job queue |
| [schedule](/reference/cli/schedule) | Scheduled tasks |
| [telemetry](/reference/cli/telemetry) | Test the error reporter and the OTLP endpoint |
| [version](/reference/cli/version) | Version, bundle, modules, variant and capabilities |
| [site](/reference/cli/site) | Export a site as a standalone install, or retire it |
| [sar](/reference/cli/sar) | A subject access request bundle for one email address |
| [dpia](/reference/cli/dpia) | A data protection impact assessment filled from the configuration |
| [audit](/reference/cli/audit) | Verify the audit log's hash chain |

### Content and data [#content-and-data]

| Command | Purpose |
|---|---|
| [content](/reference/cli/content) | Documents: list, get, create, update, publish, trash, restore, export, import |
| [media](/reference/cli/media) | The media library: import, stats, transforms, warm, prune |
| [search](/reference/cli/search) | The search index and the query log |
| [redirects](/reference/cli/redirects) | The redirect rules table |
| [locale](/reference/cli/locale) | Locales: coverage, drift, adding a locale's drafts |
| [translate](/reference/cli/translate) | Translation jobs, the glossary and the memory |
| [tags](/reference/cli/tags) | The tag vocabulary |
| [export](/reference/cli/export) | Static exports of the content API and embed widgets |
| [api](/reference/cli/api) | The content API's contract, keys and answers |
| [analytics](/reference/cli/analytics) | Rollups, retention, exports and reports |
| [webhooks](/reference/cli/webhooks) | Outbound webhook deliveries |
| [ai](/reference/cli/ai) | The AI provider, budget, review queue and activity log |
| [a11y](/reference/cli/a11y) | Accessibility audit, statement, issues and conformance report |

### People, mail and access [#people-mail-and-access]

| Command | Purpose |
|---|---|
| [user](/reference/cli/user) | Staff users and groups |
| [access](/reference/cli/access) | The effective permission matrix |
| [mail](/reference/cli/mail) | Transactional mail: status, test, templates, suppression |
| [newsletter](/reference/cli/newsletter) | Newsletter subscribers, campaigns and deliverability |
| [lists](/reference/cli/lists) | Smart lists |
| [mcp](/reference/cli/mcp) | The content MCP for a local agent, and a client for a remote one |

### DMO bundle only [#dmo-bundle-only]

| Command | Purpose |
|---|---|
| [crm](/reference/cli/crm) | Organisations, memberships, duplicates, invitations, claims, imports, erasure |
| [portal](/reference/cli/portal) | The member portal's templates |
| [broadcast](/reference/cli/broadcast) | CRM broadcasts |
| [affiliates](/reference/cli/affiliates) | Affiliate networks and conversions |

Some subcommands of shared commands are also `engine-dmo` only, such as `analytics report`, `api member` and the `dev` verbs for tiers, roles, slots and the portal; each is marked on its page.

## Commands and the environment [#commands-and-the-environment]

Commands differ in how much of the project they read, and so in which environment variables must be set. A `${VAR}` with no default is an error (`environment variable VAR is not set`, exit 3) in any command that loads the configuration with its secrets, even one that never connects to the database.

| Reads | Commands | Needs |
|---|---|---|
| Nothing of a project | `init`, `docs`, `version`, `help`, `completion`, `config schema`, `describe fieldtypes` | Nothing |
| The configuration, with secrets left out | `check --no-db`, `describe project`, `describe type`, `template api`, `guide`, and the `dev` verbs without `--scaffold` or `--apply` | Every `${VAR}` without a default set, except those in a [secret path](/deploying/configuration-and-secrets#the-secret-rule) such as `database.url` and `server.security.signing_key` |
| The whole configuration, without connecting | `config validate`, `config render`, `dpia`, `new`, `seed verify`, `seed write`, `describe template`, and `dev route add --scaffold` | Every `${VAR}` without a default set, and each secret valid: `server.security.signing_key`, when the file names it, must be empty or at least 32 characters |
| The database | `check` without `--no-db`, `render`, `describe route`, `serve`, `migrate`, `schema`, `seed apply`, `template test`, `a11y audit`, `lists`, and every command that reads or writes content, users or jobs | A reachable database in `database.url`, plus the above |

To work without a database, set placeholders in your shell. The commands in the first three rows never connect with them:

```bash
export DATABASE_URL=postgres://localhost/placeholder
export SIGNING_KEY=""     # only when engine.yaml names ${SIGNING_KEY}; empty means a development key
```

An empty `SIGNING_KEY` is accepted outside production, where the engine derives a development key; a value of 1 to 31 characters is refused (`signing_key must be at least 32 characters`). An empty `DATABASE_URL` is refused (`database.url is required`), so it needs a placeholder address. The engine does not read `.env` files. `--help` on any command needs neither variable.


# init (/reference/cli/init)

engine-dmo init: Start a new project directory: a bare starter, or a copy of a project with --from; the files it writes, the guidance for coding agents, and what is and is not available outside a Meridian checkout. Every subcommand, argument and flag.

Init writes a new project into `dir` (default the current directory). With no flag it is the bare starter: one locale, one site, a route for the core `page` type, a home page in the seed and four templates, the smallest project that passes `engine-dmo check` and serves a page. With `--from` it copies a project directory instead, without `node_modules`, the Vite build output (`public/build`), local storage or `.env` files, and gives the copy's configuration elements ids of their own.

```bash
engine-dmo init [dir] [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `dir` | no | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--agents` | bool | `true` | write `AGENTS.md` and the `meridian` and `meridian-project` skills for coding agents; `--agents=false` for none |
| `--editors` | strings | `[zed,vscode]` | editors whose project settings map the config files to their schemas; empty for none |
| `--from` | string |  | copy this project directory in place of the starter |

`--json` prints the text output in the JSON envelope. Needs no project.

## What the starter writes [#what-the-starter-writes]

| Path | What it is |
|---|---|
| `config/engine.yaml` | The install settings, every secret an environment variable. `database.url: ${DATABASE_URL}` has no default, so commands that load the configuration need `DATABASE_URL` set (see [Commands and the environment](/reference/cli#commands-and-the-environment)) |
| `config/locales.yaml` | One locale, `en` |
| `config/sites/main/site.yaml`, `routes.yaml` | One site, with `page` routed at `/{slug}` and the home page set to the page with slug `home` |
| `config/access/grants.yaml` | Who may do what on the site. See [access](/reference/configuration/access) |
| `seed/seed.yaml`, `seed/documents/page/home.yaml` | The seed set: one published home page, in `en` |
| `templates/_shared/base.html` | The layout |
| `templates/_shared/page/entry.html` | The page template |
| `templates/_shared/errors/404.html`, `errors/500.html` | The error pages |
| `public/.keep`, `.gitignore`, `README.md` | |
| `AGENTS.md`, `.claude/skills/meridian/SKILL.md`, `.claude/skills/meridian-project/SKILL.md` | Guidance for coding agents, pointing at this handbook. Left out with `--agents=false` |
| `.meridian/schema/*.json`, `.vscode/`, `.zed/` | The configuration files' JSON Schemas, mapped for each editor in `--editors` |

The core `page` type has only `title` and `slug`. Extend it (`engine-dmo dev field add page summary --type text`) before you write pages with a body. See [Types](/content-modelling/types).

<Callout type="warn" title="The starter layout warns">
`engine-dmo check` on a fresh starter prints `this head has no head() and its own tags miss a meta description` for `templates/_shared/base.html` and still exits 0. The starter layout is a placeholder meant to be replaced: print `{{ head() }}` in its `<head>` and the warning goes.
</Callout>

The `.gitignore` lists `.env`, but the engine never reads a `.env` file: set variables in your shell or process manager. See [Configuration and secrets](/deploying/configuration-and-secrets#environment-variables-in-configuration).

## Starting from an example [#starting-from-an-example]

`--from` copies any project directory. The example projects (a CMS site, a minimal DMO project, a destination site and others) live in the Meridian source repository, not in the binary or the container images, so `--from examples/...` works only in a checkout of that repository. With the binary alone, start from the bare starter.


# jobs (/reference/cli/jobs)

engine-dmo jobs: The job queue: list what waits, fails and died, and retry dead jobs. Every subcommand, argument and flag.

The job queue: list what waits, fails and died, and retry dead jobs.

| Command | What it does |
|---|---|
| [`engine-dmo jobs list`](#engine-dmo-jobs-list) | Jobs not yet complete, and dead ones, newest first |
| [`engine-dmo jobs retry`](#engine-dmo-jobs-retry) | Run dead jobs again, with a fresh set of attempts, once the cause is fixed |

## engine-dmo jobs list [#engine-dmo-jobs-list]

Jobs not yet complete, and dead ones, newest first.

```bash
engine-dmo jobs list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--failed` | bool |  | only dead jobs and jobs waiting to retry after an error |
| `--kind` | string |  | only this kind |
| `--limit` | int | `50` | at most this many |
| `--queue` | string |  | only this queue |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo jobs retry [#engine-dmo-jobs-retry]

Run dead jobs again, with a fresh set of attempts, once the cause is fixed.

```bash
engine-dmo jobs retry [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--all-failed` | bool |  | every dead job the other flags select |
| `--id` | string |  | the dead job to retry |
| `--kind` | string |  | only this kind |
| `--queue` | string |  | only this queue |

`--json` prints the command's own JSON document. Runs in a project.

See [Monitoring](/deploying/monitoring#jobs-and-scheduled-tasks).


# lists (/reference/cli/lists)

engine-dmo lists: Smart lists: check every saved query, count one, or run one to a file. Every subcommand, argument and flag.

Smart lists: check every saved query, count one, or run one to a file.

| Command | What it does |
|---|---|
| [`engine-dmo lists check`](#engine-dmo-lists-check) | Validate every smart list, saved and seeded, against the schema and the vocabulary |
| [`engine-dmo lists count`](#engine-dmo-lists-count) | How many rows a list matches now |
| [`engine-dmo lists run`](#engine-dmo-lists-run) | The full set of ids, to a CSV file, audited as an export |

## engine-dmo lists check [#engine-dmo-lists-check]

Validate every smart list, saved and seeded, against the schema and the vocabulary.

```bash
engine-dmo lists check [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--key` | string |  | one list |

`--json` prints the text output in the JSON envelope. Runs in a project.

`lists check` needs the database, and checks the lists saved there as well as the seeded ones. A seeded list in `config/tags/smartlists.yaml` is also checked by `engine-dmo check`, with `--no-db` against the tags in `config/tags/vocabulary.yaml`, and with a database against the tags it holds.

## engine-dmo lists count [#engine-dmo-lists-count]

How many rows a list matches now.

```bash
engine-dmo lists count [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--key` | string |  | the list |
| `--locale` | string |  | reading locale (default: the source locale) |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo lists run [#engine-dmo-lists-run]

The full set of ids, to a CSV file, audited as an export.

```bash
engine-dmo lists run [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--key` | string |  | the list |
| `--locale` | string |  | reading locale (default: the source locale) |
| `--out` | string |  | CSV file to write (default: stdout) |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# locale (/reference/cli/locale)

engine-dmo locale: Locales: list, coverage, what has drifted, rebuild the staleness table, add a locale's drafts. Every subcommand, argument and flag.

Locales: list, coverage, what has drifted, rebuild the staleness table, add a locale's drafts.

| Command | What it does |
|---|---|
| [`engine-dmo locale add`](#engine-dmo-locale-add) | Queue a run that seeds a new locale with drafts of the chosen types, and a translation job that owns them |
| [`engine-dmo locale coverage`](#engine-dmo-locale-coverage) | The translation dashboard, as data |
| [`engine-dmo locale list`](#engine-dmo-locale-list) | Codes, source, groups, fallback and coverage |
| [`engine-dmo locale rebuild-state`](#engine-dmo-locale-rebuild-state) | Recompute translation_field_state for every document |
| [`engine-dmo locale remove`](#engine-dmo-locale-remove) | Report what removing a locale takes off the sites, and write the redirects to its fallback |
| [`engine-dmo locale stale`](#engine-dmo-locale-stale) | What has drifted in a locale, by document and field |

## engine-dmo locale add [#engine-dmo-locale-add]

Queues a locale.add run: the documents enabled on every site that enables the locale are seeded in batches from `--seed`, resumable from where a batch stopped, and a translation job is made for the documents. `--dry-run` counts by type and writes nothing; `--wait` works the batches in this process and reports progress.

```bash
engine-dmo locale add <code> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `code` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--assign` | string |  | group to queue the job for (default: the locale's translators group) |
| `--dry-run` | bool |  | count by type without writing |
| `--job` | string |  | name of the translation job to create |
| `--no-job` | bool |  | seed without creating a translation job |
| `--seed` | string |  | source locale (default: the source) |
| `--strategy` | string | `draft` | absent \| draft |
| `--types` | string |  | comma separated type keys (default: every type) |
| `--wait` | bool |  | work the batches in this process and report progress |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo locale coverage [#engine-dmo-locale-coverage]

The translation dashboard, as data.

```bash
engine-dmo locale coverage [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo locale list [#engine-dmo-locale-list]

Codes, source, groups, fallback and coverage.

```bash
engine-dmo locale list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site for the coverage figure |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo locale rebuild-state [#engine-dmo-locale-rebuild-state]

Recompute translation_field_state for every document.

```bash
engine-dmo locale rebuild-state
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo locale remove [#engine-dmo-locale-remove]

Lists every live path the locale answers with the fallback path that serves the same document, and the paths with no fallback, which will 404. `--apply-redirects` writes a permanent redirect for each path with a fallback; it takes effect when the locale leaves config/ and engine-dmo schema apply runs. Content is never deleted: the locale's rows are kept, so enabling it again recovers everything.

```bash
engine-dmo locale remove <code> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `code` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--apply-redirects` | bool |  | write the proposed redirects |
| `--dry-run` | bool |  | report without writing (the default unless `--apply-redirects`) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo locale stale [#engine-dmo-locale-stale]

What has drifted in a locale, by document and field.

```bash
engine-dmo locale stale [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | the target locale |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.


# lsp (/reference/cli/lsp)

engine-dmo lsp: The template language server over stdio, for an editor: engine-dmo check's diagnostics as you type, completion, hover and go to definition. Development only. Every subcommand, argument and flag.

The template language server speaks the Language Server Protocol on standard input and output. An editor starts it in the project directory (or names the project as the workspace root). It refuses a project whose engine.environment is production.

```bash
engine-dmo lsp [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--stdio` | bool | `true` | talk on standard input and output (the only transport) |

`--json` prints the text output in the JSON envelope. Needs no project.


# mail (/reference/cli/mail)

engine-dmo mail: Transactional mail: status, a real test send, the templates, and the suppression list. Every subcommand, argument and flag.

Transactional mail: status, a real test send, the templates, and the suppression list.

| Command | What it does |
|---|---|
| [`engine-dmo mail status`](#engine-dmo-mail-status) | Driver, from address, webhook path, queue depth, bounce and complaint figures |
| [`engine-dmo mail suppression add`](#engine-dmo-mail-suppression-add) | Suppress an address |
| [`engine-dmo mail suppression check`](#engine-dmo-mail-suppression-check) | Is this address suppressed, why, and since when |
| [`engine-dmo mail suppression list`](#engine-dmo-mail-suppression-list) | Suppressed addresses (as hashes) by reason and age |
| [`engine-dmo mail suppression remove`](#engine-dmo-mail-suppression-remove) | Lift a suppression, audited; erasure rows cannot be removed |
| [`engine-dmo mail templates`](#engine-dmo-mail-templates) | Every transactional template, which root resolved it, and whether `a.txt` alternative exists |
| [`engine-dmo mail test`](#engine-dmo-mail-test) | A real send through the configured driver with sample context; prints the provider's response |

## engine-dmo mail status [#engine-dmo-mail-status]

Driver, from address, webhook path, queue depth, bounce and complaint figures.

```bash
engine-dmo mail status
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo mail suppression add [#engine-dmo-mail-suppression-add]

Suppress an address.

```bash
engine-dmo mail suppression add [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | address |
| `--reason` | string | `manual` | hard_bounce \| complaint \| manual \| unsubscribe_all \| erasure |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo mail suppression check [#engine-dmo-mail-suppression-check]

Is this address suppressed, why, and since when.

```bash
engine-dmo mail suppression check [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | address |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo mail suppression list [#engine-dmo-mail-suppression-list]

Suppressed addresses (as hashes) by reason and age.

```bash
engine-dmo mail suppression list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--reason` | string |  | hard_bounce \| complaint \| manual \| unsubscribe_all \| erasure |
| `--since` | string |  | 30d |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo mail suppression remove [#engine-dmo-mail-suppression-remove]

Lift a suppression, audited; erasure rows cannot be removed.

```bash
engine-dmo mail suppression remove [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | confirm |
| `--email` | string |  | address |
| `--reason` | string |  | why |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo mail templates [#engine-dmo-mail-templates]

Every transactional template, which root resolved it, and whether `a.txt` alternative exists.

```bash
engine-dmo mail templates [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo mail test [#engine-dmo-mail-test]

A real send through the configured driver with sample context; prints the provider's response.

```bash
engine-dmo mail test [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | recipient locale |
| `--site` | string |  | site key (default: the default site) |
| `--template` | string | `magic-link` | template name |
| `--to` | string |  | recipient |

`--json` prints the text output in the JSON envelope. Runs in a project.


# mcp (/reference/cli/mcp)

engine-dmo mcp: Serve the content MCP over standard input and output as a staff user, for a coding agent in development (refused in production). Every subcommand, argument and flag.

Serve the content MCP over standard input and output as a staff user, for a coding agent in development (refused in production)

| Command | What it does |
|---|---|
| [`engine-dmo mcp call`](#engine-dmo-mcp-call) | Call one tool on a remote content MCP endpoint with a personal access token from the environment, printing its JSON result: a thin client for shell scripts |
| [`engine-dmo mcp tools`](#engine-dmo-mcp-tools) | List the content MCP's tools, resources and prompts for this project and bundle, with `--json` the tools' input and output schemas: what an agent sees, without serving |

## engine-dmo mcp [#engine-dmo-mcp]

Serve the content MCP's tools over standard input and output, newline-delimited JSON-RPC, every call acting as the staff user `--as` names with exactly their grants, narrowed as a connection's consent narrows them: `--sites`, `--toolsets` and `--drafts-only` only ever remove. For a coding agent working on a project locally; refused when engine.environment is production, and in staging without dev.authoring. The remote endpoint at `/<admin_path>/mcp` is mcp.enabled's, with OAuth.

```bash
engine-dmo mcp [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--as` | string |  | the staff user every call acts as, by email (required) |
| `--drafts-only` | bool |  | never publish, as a Drafts only connection: content.publish is taken out of the person's grants |
| `--site` | string |  | the site a call that names none is for; the project's default site when absent, the first of `--sites` when that is set |
| `--sites` | strings |  | narrow to these sites, comma separated, as a connection's consent does; every site when absent |
| `--toolsets` | strings |  | narrow to these toolsets, comma separated (read is always included); every toolset the bundle declares when absent |
| `--types` | strings |  | give these types typed tools (create_&lt;type> and update_&lt;type>), comma separated, at most eight, as a connection's consent does |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo mcp call [#engine-dmo-mcp-call]

Call one tool on the content MCP endpoint at `--url` (`https://<admin origin>/<admin_path>/mcp`) with the personal access token in the environment variable `--token-env` names, never on the command line. Prints the tool's structured result as JSON; a tool error exits non-zero with its JSON on standard output. It acts as the token's person, as every MCP call does.

```bash
engine-dmo mcp call <tool> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `tool` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--args` | string |  | the tool's arguments as a JSON object |
| `--token-env` | string | `MERIDIAN_TOKEN` | the environment variable holding the personal access token |
| `--url` | string |  | the endpoint's address (required) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo mcp tools [#engine-dmo-mcp-tools]

List the content MCP's tools, resources and prompts for this project and bundle, with `--json` the tools' input and output schemas: what an agent sees, without serving.

```bash
engine-dmo mcp tools
```

`--json` prints the command's own JSON document. Runs in a project.


# media (/reference/cli/media)

engine-dmo media: The media library: its size and alt text coverage, and the image pipeline's resolved transforms. Every subcommand, argument and flag.

The media library: its size and alt text coverage, and the image pipeline's resolved transforms.

| Command | What it does |
|---|---|
| [`engine-dmo media import`](#engine-dmo-media-import) | Upload the files a media manifest lists through the pipeline, under the manifest's ids, with alt text, captions and rights; `--dry-run` writes nothing |
| [`engine-dmo media prune`](#engine-dmo-media-prune) | Remove image derivatives not served since a period, of deleted assets, of old asset versions or of retired definitions |
| [`engine-dmo media stats`](#engine-dmo-media-stats) | The library's size, its stored derivatives by transform and format, and alt text and caption coverage by site and locale |
| [`engine-dmo media transforms`](#engine-dmo-media-transforms) | The resolved image transforms of the install or a site, each with its width ladder and the formats this build serves |
| [`engine-dmo media warm`](#engine-dmo-media-warm) | Render published pages in process and generate the image derivatives they reference, with progress |

## engine-dmo media import [#engine-dmo-media-import]

Reads a meridian.media.v1 manifest and uploads each file beside it through the media pipeline: sniffed, size-checked, its metadata stripped, recorded under the id the manifest gives it. An id the library already holds is reported as exists and left alone, so the import runs again safely. Assets without a licence are counted for rights review; the library's No rights recorded filter lists them.

```bash
engine-dmo media import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | check every file and say what would happen, writing nothing |
| `--manifest` | string |  | the meridian.media.v1 manifest; its files are read relative to it |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo media prune [#engine-dmo-media-prune]

Removes every derivative of a deleted asset; those not served or warmed for `--older-than` (default media.derivatives.keep_unused, 90d); and, once unused for a day, those of an old asset version or of a definition no transform produces any more. The record and the stored file both go; the bytes freed are reported. `--dry-run` removes nothing.

```bash
engine-dmo media prune [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | remove nothing; report what would go and the bytes it would free |
| `--older-than` | string |  | remove derivatives not served for this long, such as 90d (default media.derivatives.keep_unused) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo media stats [#engine-dmo-media-stats]

Counts the assets and their bytes, then for the defaults every site shows and for each site, in each locale it enables, how many images have alt text of their own in the locale (the site's wording or the default), how many show it from a fallback locale and how many have none. A site counts the images its documents use; the defaults count every image. Decorative images are counted apart. `--site` narrows the report to one site. The derivatives are counted by the transform name they were generated under and their format, with their bytes.

```bash
engine-dmo media stats [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | a site key: its coverage alone |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo media transforms [#engine-dmo-media-transforms]

Lists every transform a template can name, resolved over the defaults of `config/images.yaml` and, with `--site`, the site's own `images.yaml`. Each ladder is shown for a nominal 4000 pixel source and, with `--source-width`, for a source of that width: nothing is upscaled, so a narrower source drops the steps above its width and serves its own width as the top step.

```bash
engine-dmo media transforms [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | a site key: its transforms, with its `images.yaml` applied |
| `--source-height` | int | `0` | the source's height, with `--source-width`, for crops the height limits |
| `--source-width` | int | `0` | also show each ladder for a source this many pixels wide |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo media warm [#engine-dmo-media-warm]

Renders each published page through the real pipeline with no visitor, as engine-dmo render does, collects every derivative its markup references (src, srcset, a picture's sources, the preloads) and generates the ones not stored, JPEG before WebP before AVIF. `--dry-run` generates nothing and counts what is missing; it reports nothing to do once every derivative the pages use is stored. Progress goes to standard error.

```bash
engine-dmo media warm [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--document` | string |  | a document id: its pages alone |
| `--dry-run` | bool |  | generate nothing; count the derivatives not yet stored |
| `--shard` | string |  | `i/n`: this run's share of the pages, every nth from the ith (`0/4`, `1/4`, `2/4`, `3/4` split them four ways) |
| `--site` | string |  | a site key: its pages alone |
| `--type` | string |  | a type key: its documents' pages alone |

`--json` prints the command's own JSON document. Runs in a project.


# migrate (/reference/cli/migrate)

engine-dmo migrate: Database migrations: forward only, applied as an explicit deploy step. Every subcommand, argument and flag.

Database migrations: forward only, applied as an explicit deploy step.

| Command | What it does |
|---|---|
| [`engine-dmo migrate status`](#engine-dmo-migrate-status) | Applied and pending migrations. Exit 2 if any are pending |
| [`engine-dmo migrate to`](#engine-dmo-migrate-to) | Apply pending migrations up to and including a version, 12 for core or `crm/3` for a module; forward only |
| [`engine-dmo migrate up`](#engine-dmo-migrate-up) | Apply pending migrations |

## engine-dmo migrate status [#engine-dmo-migrate-status]

Applied and pending migrations. Exit 2 if any are pending.

```bash
engine-dmo migrate status
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo migrate to [#engine-dmo-migrate-to]

Apply pending migrations up to and including a version, 12 for core or `crm/3` for a module; forward only.

```bash
engine-dmo migrate to <version>
```

| Argument | Required | Repeatable |
|---|---|---|
| `version` | yes | no |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo migrate up [#engine-dmo-migrate-up]

Apply pending migrations.

```bash
engine-dmo migrate up
```

`--json` prints the text output in the JSON envelope. Runs in a project.

See [Database and migrations](/deploying/database-and-migrations) and [Upgrades](/deploying/upgrades).


# new (/reference/cli/new)

engine-dmo new: Scaffold a type, a template, a component or a block. Every subcommand, argument and flag.

Scaffold a type, a template, a component or a block.

Every `new` command loads the whole configuration, so `DATABASE_URL` and every other variable without a default must be set, even though none connects to the database; a placeholder will do (see [Commands and the environment](/reference/cli#commands-and-the-environment)).

| Command | What it does |
|---|---|
| [`engine-dmo new block`](#engine-dmo-new-block) | A block template, and the schema stub that declares the block |
| [`engine-dmo new component`](#engine-dmo-new-component) | A component: its contract, markup and co-located CSS |
| [`engine-dmo new template`](#engine-dmo-new-template) | A template: a starter for a type, or a site's copy of the shared one with `--from-shared` |
| [`engine-dmo new type`](#engine-dmo-new-type) | A schema file for a custom type, and its template |

## engine-dmo new block [#engine-dmo-new-block]

A block template, and the schema stub that declares the block.

```bash
engine-dmo new block <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--field` | string |  | the blocks field that declares it |
| `--type` | string |  | the type whose blocks field declares the block |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo new component [#engine-dmo-new-component]

A component: its contract, markup and co-located CSS.

```bash
engine-dmo new component <name>
```

| Argument | Required | Repeatable |
|---|---|---|
| `name` | yes | no |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo new template [#engine-dmo-new-template]

A template: a starter for a type, or a site's copy of the shared one with `--from-shared`.

```bash
engine-dmo new template <name> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--from-shared` | bool |  | copy the template the site resolves today into its own root, recording where it came from so engine-dmo check reports when the original changes |

`--json` prints the text output in the JSON envelope. Runs in a project.

`new template <type>/entry.html` writes a starter that prints the type's fields. `new template <type>/index.html` writes only an empty `body` block naming the file, with no heading and no list: write the page's `h1`, the list and its pager before you render it, or the accessibility checks fail on it. [Context](/templates/context) shows what an index page has to work with.

## engine-dmo new type [#engine-dmo-new-type]

A schema file for a custom type, and its template.

```bash
engine-dmo new type <key>
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

`--json` prints the text output in the JSON envelope. Runs in a project.


# newsletter (/reference/cli/newsletter)

engine-dmo newsletter: The newsletter's subscribers, campaigns and deliverability. Every subcommand, argument and flag.

The newsletter's subscribers, campaigns and deliverability.

| Command | What it does |
|---|---|
| [`engine-dmo newsletter campaigns`](#engine-dmo-newsletter-campaigns) | List a site's campaigns |
| [`engine-dmo newsletter deliverability`](#engine-dmo-newsletter-deliverability) | Check SPF, DKIM and DMARC for each site's sending domain, record the results, and show the complaint rate |
| [`engine-dmo newsletter export`](#engine-dmo-newsletter-export) | Export a site's subscribers, or with `--topics` the recipients of that segment, as CSV; audited with the row count |
| [`engine-dmo newsletter hygiene`](#engine-dmo-newsletter-hygiene) | Report a site's list health: active, dormant, never confirmed, unsubscribed and bounced |
| [`engine-dmo newsletter import`](#engine-dmo-newsletter-import) | Import subscribers from a CSV file under a declared lawful basis, recorded on every row; `--dry-run` counts and writes nothing |
| [`engine-dmo newsletter send`](#engine-dmo-newsletter-send) | Send a draft campaign now; needs `--confirm`, since a send cannot be taken back |
| [`engine-dmo newsletter subscribers`](#engine-dmo-newsletter-subscribers) | List a site's subscribers; `--dormant 12m` lists the active ones with no click in that period |
| [`engine-dmo newsletter suppress`](#engine-dmo-newsletter-suppress) | Suppress an address on every channel: an alias for engine-dmo mail suppression add |

## engine-dmo newsletter campaigns [#engine-dmo-newsletter-campaigns]

List a site's campaigns.

```bash
engine-dmo newsletter campaigns [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key |
| `--status` | string |  | draft \| scheduled \| sending \| sent \| cancelled |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter deliverability [#engine-dmo-newsletter-deliverability]

Check SPF, DKIM and DMARC for each site's sending domain, record the results, and show the complaint rate.

```bash
engine-dmo newsletter deliverability
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter export [#engine-dmo-newsletter-export]

Export a site's subscribers, or with `--topics` the recipients of that segment, as CSV; audited with the row count.

```bash
engine-dmo newsletter export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | file to write; standard output when empty |
| `--site` | string |  | site key |
| `--status` | string |  | only subscribers in this status |
| `--topics` | string |  | a segment: the recipients interested in any of these topics, comma separated |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter hygiene [#engine-dmo-newsletter-hygiene]

Report a site's list health: active, dormant, never confirmed, unsubscribed and bounced.

```bash
engine-dmo newsletter hygiene [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--report` | bool |  | print the report |
| `--site` | string |  | site key |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter import [#engine-dmo-newsletter-import]

Import subscribers from a CSV file under a declared lawful basis, recorded on every row; `--dry-run` counts and writes nothing.

```bash
engine-dmo newsletter import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--basis` | string |  | the lawful basis: consent \| legitimate_interest \| contract |
| `--dry-run` | bool |  | count what would happen and write nothing |
| `--file` | string |  | CSV file with an email column, and optionally name, locale, topics and consented_at |
| `--site` | string |  | site key |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter send [#engine-dmo-newsletter-send]

Send a draft campaign now; needs `--confirm`, since a send cannot be taken back.

```bash
engine-dmo newsletter send [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--campaign` | string |  | campaign id |
| `--confirm` | bool |  | send it |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter subscribers [#engine-dmo-newsletter-subscribers]

List a site's subscribers; `--dormant 12m` lists the active ones with no click in that period.

```bash
engine-dmo newsletter subscribers [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dormant` | string |  | a period such as 12m: active subscribers with no click since |
| `--site` | string |  | site key |
| `--status` | string |  | pending \| active \| unsubscribed \| bounced \| complained \| suppressed |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo newsletter suppress [#engine-dmo-newsletter-suppress]

Suppress an address on every channel: an alias for engine-dmo mail suppression add.

```bash
engine-dmo newsletter suppress [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | address |
| `--reason` | string | `manual` | hard_bounce \| complaint \| manual \| unsubscribe_all \| erasure |

`--json` prints the text output in the JSON envelope. Runs in a project.


# plugin (/reference/cli/plugin)

engine-dmo plugin: The project's plugins: build them. Every subcommand, argument and flag.

The project's plugins: build them.

| Command | What it does |
|---|---|
| [`engine-dmo plugin build`](#engine-dmo-plugin-build) | Compile each plugin's Go program (its build: directory) to its command with go build, and print the binary's sha256 to pin |

## engine-dmo plugin build [#engine-dmo-plugin-build]

Compile each plugin's Go program (its build: directory) to its command with go build, and print the binary's sha256 to pin.

```bash
engine-dmo plugin build [key...] [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key...` | no | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | only this site's plugins |

`--json` prints the text output in the JSON envelope. Runs in a project.


# portal (/reference/cli/portal)

engine-dmo portal: The member portal. Every subcommand, argument and flag.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The member portal.

| Command | What it does |
|---|---|
| [`engine-dmo portal check`](#engine-dmo-portal-check) | Check the project's portal templates against the portal context |
| [`engine-dmo portal scaffold`](#engine-dmo-portal-scaffold) | Copy the reference portal into the project to be restyled |
| [`engine-dmo portal status`](#engine-dmo-portal-status) | What each site's portal is serving and which templates the project overrides |

## engine-dmo portal check [#engine-dmo-portal-check]

Check the project's portal templates against the portal context.

```bash
engine-dmo portal check
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo portal scaffold [#engine-dmo-portal-scaffold]

Copy the reference portal into the project to be restyled.

```bash
engine-dmo portal scaffold [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--force` | bool |  | overwrite a template that is already there |
| `--out` | string |  | where to write, relative to the project (default `templates/portal`) |
| `--site` | string |  | write to the site's portal directory, `templates/<root>/<template_dir>`: the site's first template root and its portal template directory |

`--json` prints the text output in the JSON envelope. Runs in a project.

<Callout type="warn" title="Pass --site">
With no flag, `portal scaffold` writes to `templates/portal/`, which is on no site's template chain: nothing there renders, and `check` warns about the folder. Run it with `--site <key>` so the files land where that site's portal reads them, such as `templates/main/portal/` for the site `main`, whose first template root is `main`.
</Callout>

## engine-dmo portal status [#engine-dmo-portal-status]

What each site's portal is serving and which templates the project overrides.

```bash
engine-dmo portal status
```

`--json` prints the command's own JSON document. Runs in a project.


# redirects (/reference/cli/redirects)

engine-dmo redirects: The redirect rules table: list, import a CSV with a dry run, roll an import back. Every subcommand, argument and flag.

The redirect rules table: list, import a CSV with a dry run, roll an import back.

| Command | What it does |
|---|---|
| [`engine-dmo redirects import`](#engine-dmo-redirects-import) | Import exact redirect rules from a CSV (source, target, status, locale, note); `--dry-run` writes nothing |
| [`engine-dmo redirects list`](#engine-dmo-redirects-list) | A site's redirect rules from the table, newest first, of one origin with `--origin` |
| [`engine-dmo redirects rollback`](#engine-dmo-redirects-rollback) | Disable every rule an import batch wrote; audited |

## engine-dmo redirects import [#engine-dmo-redirects-import]

Reads a CSV with a header row naming source and target, and optionally status, locale and note (other columns are ignored). A target is a path on the site, an absolute URL, document:`<uuid>` (the rule follows the document if its address changes), or empty with status 410. Each row is checked: the source and status, the locale, a duplicate in the file or the table, the target (a document that exists, a path the site answers), and loops and chains through every rule the site has. Any error refuses the whole import unless `--skip-invalid`; the import is one transaction, and engine-dmo redirects rollback `--batch` disables it.

```bash
engine-dmo redirects import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | check every row and write nothing |
| `--file` | string |  | the CSV file |
| `--site` | string |  | site key (default: the default site) |
| `--skip-invalid` | bool |  | import the rows without errors when some have them |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo redirects list [#engine-dmo-redirects-list]

A site's redirect rules from the table, newest first, of one origin with `--origin`.

```bash
engine-dmo redirects list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--origin` | string |  | only this origin: managed, imported, auto_slug, auto_trash and the rest |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo redirects rollback [#engine-dmo-redirects-rollback]

Disable every rule an import batch wrote; audited.

```bash
engine-dmo redirects rollback [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--batch` | string |  | the batch id the import printed |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# render (/reference/cli/render)

engine-dmo render: Render a public page through the real pipeline, in process; --json adds errors, queries, assets, accessibility findings and the image report. Every subcommand, argument and flag.

Render a public page through the real pipeline, in process; `--json` adds errors, queries, assets, accessibility findings and the image report.

```bash
engine-dmo render <path> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `path` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--fragment` | string |  | render only these fragments of the page, comma separated, as a script's request for them gets them |
| `--host` | string |  | the Host the request carries (default: the site's first domain, or the locale's under the domain strategy) |
| `--locale` | string |  | locale code; the path is then the unprefixed URI and the locale's prefix or domain is added |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.

`render` boots the engine in process, so it needs a reachable database and every variable the configuration names. It prints the engine's start-up log lines to standard error before the page; when the database cannot be reached it prints those lines, then the error (`MRD-3001`), and exits 1. Read the exit code, not the first line of output. With no database there is no way to render a page; [check](/reference/cli/check) with `--no-db` is the furthest a project can be verified.

Under `render`, `csrfToken()`, `csrfInput()` and the `csrf` global print empty, because no request key exists outside a running server. A form is complete only when served by `engine-dmo serve`.


# sar (/reference/cli/sar)

engine-dmo sar: A subject access request bundle: everything the install holds about the person an email address belongs to, as one archive. Every subcommand, argument and flag.

A subject access request bundle: everything the install holds about the person an email address belongs to, as one archive (GDPR Article 15).

```bash
engine-dmo sar --email someone@example.com --out sar.zip
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | the person's email address (required) |
| `--out` | string |  | the archive to write, which must not exist yet (required) |

`--json` prints the command's own JSON document: the path, the records found and the row count of each section. Runs in a project and needs the database.

| Exit | When |
|---|---|
| `0` | The archive is written |
| `1` | A required flag is missing, there is no database connection, or the archive could not be written |
| `3` | The address has no `@`, `--out` already exists, or a read failed while building the bundle |

See [Data protection duties](/deploying/data-protection#subject-access-requests) for what the archive holds and how to answer a request.


# schedule (/reference/cli/schedule)

engine-dmo schedule: The scheduled tasks: list them with their last success, and run one now. Every subcommand, argument and flag.

The scheduled tasks: list them with their last success, and run one now.

| Command | What it does |
|---|---|
| [`engine-dmo schedule list`](#engine-dmo-schedule-list) | Every scheduled task, its cadence, and, from the running engine's metrics, its last success and the leader |
| [`engine-dmo schedule run`](#engine-dmo-schedule-run) | Run one scheduled task once, in this process, now; audited |

## engine-dmo schedule list [#engine-dmo-schedule-list]

Every scheduled task, its cadence, and, from the running engine's metrics, its last success and the leader.

```bash
engine-dmo schedule list
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo schedule run [#engine-dmo-schedule-run]

Run one scheduled task once, in this process, now; audited.

```bash
engine-dmo schedule run <name> --now [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `name` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--now` | bool |  | run it now (required) |

`--json` prints the text output in the JSON envelope. Runs in a project.

See [Monitoring](/deploying/monitoring#jobs-and-scheduled-tasks).


# schema (/reference/cli/schema)

engine-dmo schema: Plan and apply configuration against the database. Every subcommand, argument and flag.

Plan and apply configuration against the database.

| Command | What it does |
|---|---|
| [`engine-dmo schema adopt-ids`](#engine-dmo-schema-adopt-ids) | Give a database made before ids the ids the files carry: write missing ids, then bind |
| [`engine-dmo schema alias list`](#engine-dmo-schema-alias-list) | Every live alias: the old handle, the field it names, and where it is declared |
| [`engine-dmo schema alias retire`](#engine-dmo-schema-alias-retire) | Remove an alias from its field; refused while a template still uses it |
| [`engine-dmo schema apply`](#engine-dmo-schema-apply) | Apply the plan in one transaction. Refuses destructive changes unless approved |
| [`engine-dmo schema plan`](#engine-dmo-schema-plan) | Read-only diff between config/ and the database. Exit 2 if changes are pending |

## engine-dmo schema adopt-ids [#engine-dmo-schema-adopt-ids]

adopt-ids writes an id for every element of the files that has none, as engine-dmo check `--fix` does, then applies a plan that may hold only binds: each row and stored definition made before ids takes the id its file gives it, and nothing else changes. A plan holding any other change is refused; apply it with engine-dmo schema apply first.

```bash
engine-dmo schema adopt-ids
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo schema alias list [#engine-dmo-schema-alias-list]

Every live alias: the old handle, the field it names, and where it is declared.

```bash
engine-dmo schema alias list
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo schema alias retire [#engine-dmo-schema-alias-retire]

Remove an alias from its field; refused while a template still uses it.

```bash
engine-dmo schema alias retire <type.alias>
```

| Argument | Required | Repeatable |
|---|---|---|
| `type.alias` | yes | no |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo schema apply [#engine-dmo-schema-apply]

Apply the plan in one transaction. Refuses destructive changes unless approved.

```bash
engine-dmo schema apply [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--allow-destructive` | bool |  | apply destructive changes without an approval file, after confirming them |
| `--replace` | string, repeatable |  | let the element the file gives a new id replace the stored one with this handle (listing.priceRange); repeatable |
| `--yes` | bool |  | confirm a destructive plan when no terminal can ask |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo schema plan [#engine-dmo-schema-plan]

Read-only diff between config/ and the database. Exit 2 if changes are pending.

```bash
engine-dmo schema plan
```

`--json` prints the command's own JSON document. Runs in a project.

See [Database and migrations](/deploying/database-and-migrations#the-schema) for drift, destructive plans and the approval file.


# search (/reference/cli/search)

engine-dmo search: The search index and the query log. Every subcommand, argument and flag.

The search index and the query log.

| Command | What it does |
|---|---|
| [`engine-dmo search capabilities`](#engine-dmo-search-capabilities) | What the configured backend supports |
| [`engine-dmo search rebuild`](#engine-dmo-search-rebuild) | Reindex every published document, resumable and online |
| [`engine-dmo search status`](#engine-dmo-search-status) | The configured backend, its health and what is indexed |
| [`engine-dmo search synonyms import`](#engine-dmo-search-synonyms-import) | Seed synonyms from `config/search/synonyms.yaml`; rules already held are left alone |
| [`engine-dmo search synonyms list`](#engine-dmo-search-synonyms-list) | The synonym rules the database holds |
| [`engine-dmo search test`](#engine-dmo-search-test) | Run a query and show what came back |
| [`engine-dmo search verify`](#engine-dmo-search-verify) | Compare the index with what is published and report any drift |
| [`engine-dmo search zero-results`](#engine-dmo-search-zero-results) | What visitors searched for and did not find |

## engine-dmo search capabilities [#engine-dmo-search-capabilities]

What the configured backend supports.

```bash
engine-dmo search capabilities [flags]
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo search rebuild [#engine-dmo-search-rebuild]

Reindex what is published, then delete what is indexed and no longer published. The run is recorded where the admin's search index screen shows it; a rebuild that failed or whose process stopped is resumed from where it got to unless `--fresh` is given.

```bash
engine-dmo search rebuild [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--fresh` | bool |  | start over rather than resume a rebuild that did not finish |
| `--site` | string |  | rebuild one site's indexes (default: every site) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo search status [#engine-dmo-search-status]

The configured backend, its health and what is indexed.

```bash
engine-dmo search status
```

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo search synonyms import [#engine-dmo-search-synonyms-import]

Load the seed file's rules into the database, origin seed. A rule the site and locale already holds (the same one-way source, or the same terms) is left as it is, whoever wrote it, so a second import creates nothing. Every rule is checked first and nothing is written when one is refused. New rules are queued for the search backend, which the running server's workers push; nothing is reindexed.

```bash
engine-dmo search synonyms import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | report what would be created and write nothing |
| `--file` | string |  | the seed file (default: `config/search/synonyms.yaml`) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo search synonyms list [#engine-dmo-search-synonyms-list]

The synonym rules the database holds.

```bash
engine-dmo search synonyms list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | one locale's rules (default: every locale) |
| `--site` | string |  | one site's rules (default: every site) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo search test [#engine-dmo-search-test]

Run a query and show what came back.

```bash
engine-dmo search test <query> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `query` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | locale (default: the site's default) |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo search verify [#engine-dmo-search-verify]

Compare the index with what is published and report any drift.

```bash
engine-dmo search verify
```

Aliases: `check`. `--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo search zero-results [#engine-dmo-search-zero-results]

What visitors searched for and did not find.

```bash
engine-dmo search zero-results [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--limit` | int | `50` | how many to list |
| `--since` | string | `30d` | window, such as 30d or 168h |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project.


# seed (/reference/cli/seed)

engine-dmo seed: Seed sets: validated content with history, assets and generated analytics. Every subcommand, argument and flag.

Seed sets: validated content with history, assets and generated analytics.

| Command | What it does |
|---|---|
| [`engine-dmo seed apply`](#engine-dmo-seed-apply) | Apply a seed set through the same validation and revision machinery as an editor |
| [`engine-dmo seed generate`](#engine-dmo-seed-generate) | Generate documents of a type whose values pass each field's validation, from seeded word lists and placeholder images |
| [`engine-dmo seed list`](#engine-dmo-seed-list) | Available seed sets and what they contain |
| [`engine-dmo seed reset`](#engine-dmo-seed-reset) | Remove all content, media and analytics; keep users and configuration |
| [`engine-dmo seed verify`](#engine-dmo-seed-verify) | Check the seed set loads and matches the current schema (the CI check) |
| [`engine-dmo seed write`](#engine-dmo-seed-write) | Write the seed set's generated records from `seed/generate.yaml`, or with `--check` report how the files differ from it |

## engine-dmo seed apply [#engine-dmo-seed-apply]

Apply a seed set through the same validation and revision machinery as an editor.

```bash
engine-dmo seed apply [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--i-know-what-i-am-doing` | bool |  | allow seeding an empty production database |
| `--profile` | string |  | apply only a profile of `seed.yaml`'s profiles, with everything it depends on |
| `--scale` | string | `small` | small \| medium \| large, scales the generated analytics |
| `--set` | string |  | seed set directory name under seed/ (default: seed/ itself) |
| `--timeout` | duration | `30m0s` | give up after this long; a seed with thousands of assets against a remote database can need more |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo seed generate [#engine-dmo-seed-generate]

Generate documents of a type whose values pass each field's validation, from seeded word lists and placeholder images.

```bash
engine-dmo seed generate [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--count` | int | `10` | how many documents |
| `--locale` | string |  | locale (default: the source locale) |
| `--near` | string |  | latitude,longitude that generated points fall around, where a field has no bounds of its own |
| `--publish` | bool |  | publish each document through the publish checks |
| `--seed` | int64 | `1` | the generator's seed; the same seed over the same database gives the same values |
| `--site` | string |  | owner site (default: the default site) |
| `--type` | string |  | type key |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo seed list [#engine-dmo-seed-list]

Available seed sets and what they contain.

```bash
engine-dmo seed list
```

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo seed reset [#engine-dmo-seed-reset]

Remove all content, media and analytics; keep users and configuration.

```bash
engine-dmo seed reset [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | confirm the reset |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo seed verify [#engine-dmo-seed-verify]

Check the seed set loads and matches the current schema (the CI check)

```bash
engine-dmo seed verify [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--profile` | string |  | verify only a profile, with everything it depends on |
| `--set` | string |  | seed set directory name under seed/ |

`--json` prints the text output in the JSON envelope. Runs in a project.

`seed verify` never connects to the database, but it loads the whole configuration, so `DATABASE_URL` and every other variable without a default must be set, a placeholder will do (see [Commands and the environment](/reference/cli#commands-and-the-environment)).

<Callout type="warn" title="Matches the schema is not proof the seed applies">
`seed verify` checks that the set loads, and that every type, field and locale it names exists. It does not validate field values: a select value that is not an option, or a number below the field's `min`, passes with `Matches the schema`. `seed apply` validates every value as an editor's save does and refuses the first bad one (`seed/documents/page/home.yaml: publish en refused: distanceKm: Must be 0 or more`). To prove a seed, apply it to a scratch database.
</Callout>

## engine-dmo seed write [#engine-dmo-seed-write]

```text
Write renders the content spec beside seed.yaml (generate.yaml) into ordinary seed files, each
marked as generated, and removes the generated files the spec no longer makes. Hand-written files are
never touched. The same spec writes the same files on every machine.

Placeholders a recipe may use:
  {$var}
      a let variable, or $n, $index, $count, $key, $locale
  {pick LIST}
      a word from a list, the same position in every locale's list
  {lookup LIST KEYS KEY}
      the word of LIST at the position KEY has in the list KEYS, in the locale: a place's name from its key
  {at VALUE KEY}
      one key of a mapping value, such as a let variable holding a route
  {route PLACE KM [N] [loop|line] [LOW] [HIGH] [LABEL]}
      a walk's route near a place: start, points (point, km, elevationM), km, minutes, length (short, medium, long), ascent, highest, lowest and corridor, the box around it
  {pickn LIST N [M]}
      N to M different words from a list, as a list
  {uniq LIST}
      a word no other record of the recipe drew here, until the list runs out: for names
  {nth LIST}
      the word at the record's own position in a list, the same position in every locale's list: a record's name and its place together
  {phrase NAME}
      a sentence pattern from phrases, in the locale, its placeholders rendered
  {sentences NAME N [M]}
      N to M patterns of NAME, joined with spaces
  {pt NAME N [M]}
      Portable Text: N to M paragraphs, each two or three patterns of NAME
  {slug X}
      X as a slug
  {lower X | upper X | cap X}
      X in lower case, upper case, or with a capital first letter
  {int A B}
      a whole number from A to B
  {float A B [DP]}
      a number from A to B, rounded to DP places (default 1)
  {chance P}
      true for a share P of records
  {oneof A B C}
      one of the words given
  {eq A B | not A | and A B... | or A B... | if C A B}
      conditions for ?$var keys: equal, not, all, any, and A when C is true else B
  {cycle A B C}
      the words in turn by record, so each is used evenly
  {n | index | count}
      the record's number from 1, from 0, and the recipe's count
  {point [PLACE]}
      {lat, lon} inside a place's radius, or inside bounds
  {polygon PLACE [KM]}
      a GeoJSON polygon around a place
  {photo CATEGORY [ORIENTATION]}
      {asset: key} of a photograph from the index
  {photokey CATEGORY [ORIENTATION]}
      a photograph's key alone
  {photos CATEGORY N [M]}
      a list of N to M photographs, as asset items
  {video POSTER_CATEGORY [TITLE_PHRASE [TRANSCRIPT_PHRASE]]}
      a video field value from the pool with a title, a start time, a poster and a transcript
  {ref RECIPE | refnth RECIPE}
      a key of another recipe's record: any, or the one with this record's number
  {relation RECIPE | relationnth RECIPE}
      {id, type} of another recipe's document
  {relations RECIPE N [M]}
      a list of N to M different relations
  {relationsby RECIPE PATH VALUE N [M]}
      N to M different relations to RECIPE's records whose rendered PATH (locales.en-GB.area, or area, read in the source locale) names VALUE, such as $key: a village's own listings
  {date A B}
      a seed date from A to B days from the day of applying, such as +12d
  {absdate A B | abstime A B HH:MM}
      an absolute date or wall clock A to B days from the spec's anchor
  {digits PATTERN}
      PATTERN with each # a digit: 01632 ### ###
  {data NAME | pickdata NAME | nthdata NAME}
      a value from data, whole, one item of a list, or the item at the record's own position
  {locales}
      the locales this record is written in, the source first
  {omit}
      leave this key or item out
```

```bash
engine-dmo seed write [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--check` | bool |  | write nothing; exit 3 when the files differ from the spec |
| `--set` | string |  | seed set directory name under seed/ |

`--json` prints the text output in the JSON envelope. Runs in a project.


# serve (/reference/cli/serve)

engine-dmo serve: start the server (public sites, admin, portal, APIs, jobs and scheduled tasks in one process), its boot sequence, what it refuses, and its flags.

Start the server. One process serves every site's public pages, the admin, the member portal and the APIs, runs background jobs, and competes for the scheduler lease to run scheduled tasks.

```bash
engine-dmo serve [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--listen` | string |  | Override `server.listen` for this run, such as `0.0.0.0:8080` |
| `--migrate` | bool |  | Apply pending migrations before serving, for this run |
| `--dev` | bool |  | Development: reparse templates on every request, the development error page, the config watcher (a valid change restarts the engine in this process), the extensions' development servers as children (the Vite extension's Vite), and the profiler at `/_debug/pprof/`. The profiler and debug endpoints stay off in production |
| `--role` | string | `all` | Accepted values `web`, `worker`, `all`. In this release every value runs everything; there is no process that only serves or only runs jobs |

`--json` prints the text output in the JSON envelope. Runs in a project.

## What happens at boot [#what-happens-at-boot]

1. The configuration is loaded and validated. Any problem is printed with its file, line and column, and the process exits 3.
2. The extensions named in `extensions:` are loaded.
3. The database is connected, and a server older than PostgreSQL 14 is refused.
4. Migrations are checked. Pending migrations stop the boot with exit 2 unless `migrate.on_boot: apply` or `--migrate`; an applied migration whose file changed stops it with exit 1.
5. The project is loaded and compared with the schema in the database. A difference is handled by `schema.on_drift` (refuse by default: exit 2 with the plan).
6. The storage is proved writable (filesystem) or proved to accept a write, read and delete (S3). Failure stops the boot.
7. Templates are compiled; a template error stops the boot with exit 3.
8. The listener binds, the metrics listener binds on `telemetry.metrics.bind`, the page cache warms when enabled, and readiness turns true.

On `SIGINT` or `SIGTERM` readiness turns false at once, in-flight requests have up to `server.shutdown_grace` to finish, and the process exits.

## Exit codes [#exit-codes]

| Code | When |
|---|---|
| `0` | Stopped by a signal after a clean shutdown |
| `1` | Boot failed (database unreachable, storage not writable, a migration file changed), or the server failed |
| `2` | Refused: migrations pending, or configuration drift with `schema.on_drift: refuse`. The output names the command that fixes it |
| `3` | The configuration or a template is invalid |

## Examples [#examples]

```bash
engine-dmo serve                               # production: after migrate up and schema apply
engine-dmo serve --listen 127.0.0.1:8090 --dev # local development
engine-dmo serve --migrate                     # a simple single-process install
```

For local development, `engine-dmo dev up` adds checking, id writing and safe schema applies on every configuration change. See [Database and migrations](/deploying/database-and-migrations) and [Monitoring](/deploying/monitoring).


# site (/reference/cli/site)

engine-dmo site: A site leaving the install: export it as a standalone install, then retire it here. Every subcommand, argument and flag.

A site leaving the install: export it as a standalone install, then retire it here.

| Command | What it does |
|---|---|
| [`engine-dmo site export`](#engine-dmo-site-export) | Write a standalone install of one site: its database, media and configuration, verified by restoring it and serving its home page |
| [`engine-dmo site retire`](#engine-dmo-site-retire) | Remove a site from the install: its rows, analytics and search indexes, and the people and organisations connected only to it, erased |

## engine-dmo site export [#engine-dmo-site-export]

Write a standalone install of one site: its database, media and configuration, verified by restoring it and serving its home page.

```bash
engine-dmo site export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | the directory to write, created 0700; it must be empty or absent |
| `--plan` | bool |  | print what would be copied and stop |
| `--scratch-database-url` | string |  | a PostgreSQL server the export may create two databases on and drop them; its database is used to connect |
| `--signing-key-env` | string |  | an environment variable holding the receiving install's signing key, to reseal second factors with; without it they are cleared |
| `--site` | string |  | the site's key |
| `--staff` | strings |  | a staff user whose grants reach every site, by address, to copy as well; repeatable |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo site retire [#engine-dmo-site-retire]

Remove a site from the install: its rows, analytics and search indexes, and the people and organisations connected only to it, erased.

```bash
engine-dmo site retire [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--plan` | bool |  | print what would be removed and erased, and stop |
| `--site` | string |  | the site's key |
| `--yes` | bool |  | retire without asking |

`--json` prints the command's own JSON document. Runs in a project.

See [Backups and restore](/deploying/backups-and-restore#exporting-one-site).


# tags (/reference/cli/tags)

engine-dmo tags: The tag vocabulary: import the seed, review candidates, promote, merge and reject. Every subcommand, argument and flag.

The tag vocabulary: import the seed, review candidates, promote, merge and reject.

| Command | What it does |
|---|---|
| [`engine-dmo tags add`](#engine-dmo-tags-add) | Add a vocabulary tag under an existing parent, with its label in one locale; a key already there is left as it is |
| [`engine-dmo tags candidates`](#engine-dmo-tags-candidates) | Freeform tags awaiting promotion, with usage per subject type |
| [`engine-dmo tags export`](#engine-dmo-tags-export) | Capture the live vocabulary as a seed file; a directory gets `vocabulary.yaml` |
| [`engine-dmo tags import`](#engine-dmo-tags-import) | Seed the vocabulary from `config/tags/vocabulary.yaml`; existing keys are left alone |
| [`engine-dmo tags merge`](#engine-dmo-tags-merge) | Fold one vocabulary tag into another, rewriting its taggings |
| [`engine-dmo tags promote`](#engine-dmo-tags-promote) | Promote a candidate into the vocabulary (`--as` key) or merge it into an existing tag (`--into` key) |
| [`engine-dmo tags reject`](#engine-dmo-tags-reject) | Reject a candidate: it and its taggings are removed, with a reason for the audit log |
| [`engine-dmo tags unused`](#engine-dmo-tags-unused) | Tags applied to nothing, candidates included |

## engine-dmo tags add [#engine-dmo-tags-add]

Add a vocabulary tag under an existing parent, with its label in one locale; a key already there is left as it is.

```bash
engine-dmo tags add <key> [flags]
```

| Argument | Required | Repeatable |
|---|---|---|
| `key` | yes | no |

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--kind` | string | `topic` | topic \| audience \| operational \| internal |
| `--label` | string |  | the label |
| `--locale` | string |  | the label's locale (default: the source locale) |
| `--public` | bool | `true` | render publicly |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo tags candidates [#engine-dmo-tags-candidates]

Freeform tags awaiting promotion, with usage per subject type.

```bash
engine-dmo tags candidates [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--ready` | bool |  | only candidates at or over the threshold |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo tags export [#engine-dmo-tags-export]

Capture the live vocabulary as a seed file; a directory gets `vocabulary.yaml`.

```bash
engine-dmo tags export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | a file, or a directory such as `config/tags`/; standard output when empty |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo tags import [#engine-dmo-tags-import]

Seed the vocabulary from `config/tags/vocabulary.yaml`; existing keys are left alone.

```bash
engine-dmo tags import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | report without writing |
| `--file` | string |  | vocabulary file (default `config/tags/vocabulary.yaml`) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo tags merge [#engine-dmo-tags-merge]

Fold one vocabulary tag into another, rewriting its taggings.

```bash
engine-dmo tags merge [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | report without writing |
| `--keep` | string |  | the tag that survives |
| `--merge` | string |  | the tag folded into it |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo tags promote [#engine-dmo-tags-promote]

Promote a candidate into the vocabulary (`--as` key) or merge it into an existing tag (`--into` key)

```bash
engine-dmo tags promote [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--as` | string |  | the new vocabulary key |
| `--into` | string |  | an existing tag to merge into instead |
| `--key` | string |  | the candidate key, pending.something |
| `--kind` | string | `topic` | topic \| audience \| operational \| internal |
| `--label` | string, repeatable |  | locale=text, repeatable |
| `--public` | bool | `true` | render publicly |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo tags reject [#engine-dmo-tags-reject]

Reject a candidate: it and its taggings are removed, with a reason for the audit log.

```bash
engine-dmo tags reject [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--key` | string |  | the candidate key |
| `--reason` | string |  | why |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo tags unused [#engine-dmo-tags-unused]

Tags applied to nothing, candidates included.

```bash
engine-dmo tags unused [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--days` | int | `0` | leave out tags created in the last this many days |

`--json` prints the command's own JSON document. Runs in a project.


# telemetry (/reference/cli/telemetry)

engine-dmo telemetry: Telemetry export and error reporting: send a test event. Every subcommand, argument and flag.

Telemetry export and error reporting: send a test event.

| Command | What it does |
|---|---|
| [`engine-dmo telemetry test`](#engine-dmo-telemetry-test) | Send a test event to the error reporter and an empty export to the OTLP endpoint, and say whether each was accepted |

## engine-dmo telemetry test [#engine-dmo-telemetry-test]

Send a test event to the error reporter and an empty export to the OTLP endpoint, and say whether each was accepted.

```bash
engine-dmo telemetry test [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--note` | string |  | a note added to the test event's message, such as a ticket number |

`--json` prints the text output in the JSON envelope. Runs in a project.


# template (/reference/cli/template)

engine-dmo template: The template contract's tooling: the generated API and template tests. Every subcommand, argument and flag.

The template contract's tooling: the generated API and template tests.

| Command | What it does |
|---|---|
| [`engine-dmo template api`](#engine-dmo-template-api) | The complete template surface for a site of this project, including its own types and fields; `--json` for all of it |
| [`engine-dmo template test`](#engine-dmo-template-test) | Render the pages `tests/templates/*.test.yaml` name, through the real pipeline against the database's seed, and check each |

## engine-dmo template api [#engine-dmo-template-api]

The complete template surface for a site of this project, including its own types and fields; `--json` for all of it.

```bash
engine-dmo template api [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--site` | string |  | site key (default: the default site) |

`--json` prints the command's own JSON document. Runs in a project. It reads the project without its secrets and needs no database.

## engine-dmo template test [#engine-dmo-template-test]

Render the pages `tests/templates/*.test.yaml` name, through the real pipeline against the database's seed, and check each.

```bash
engine-dmo template test [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--filter` | string |  | only the tests whose name or file contains this |
| `--snapshots` | bool |  | record or compare a snapshot for every test, not only those with snapshot: true |
| `--update` | bool |  | record the snapshots again instead of comparing them |

`--json` prints the command's own JSON document. Runs in a project. It renders against the database, so it needs one, migrated, with the schema applied and the seed loaded.

See [Template API](/reference/template-api).


# translate (/reference/cli/translate)

engine-dmo translate: Translation jobs, the glossary and the memory. Every subcommand, argument and flag.

Translation jobs, the glossary and the memory.

| Command | What it does |
|---|---|
| [`engine-dmo translate glossary export`](#engine-dmo-translate-glossary-export) | Write the pair's terms as TBX |
| [`engine-dmo translate glossary import`](#engine-dmo-translate-glossary-import) | Add manual terms from a CSV of term,translation,rule |
| [`engine-dmo translate glossary list`](#engine-dmo-translate-glossary-list) | Terms for a pair |
| [`engine-dmo translate glossary seed`](#engine-dmo-translate-glossary-seed) | Rebuild the auto-seeded terms from the CRM, the content and the tags |
| [`engine-dmo translate jobs`](#engine-dmo-translate-jobs) | List translation jobs |
| [`engine-dmo translate memory export`](#engine-dmo-translate-memory-export) | Write the pair's units as TMX |

## engine-dmo translate glossary export [#engine-dmo-translate-glossary-export]

Write the pair's terms as TBX.

```bash
engine-dmo translate glossary export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | file to write (default: stdout) |
| `--target` | string |  | target locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo translate glossary import [#engine-dmo-translate-glossary-import]

Add manual terms from a CSV of term,translation,rule.

```bash
engine-dmo translate glossary import [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--file` | string |  | CSV file |
| `--target` | string |  | target locale |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo translate glossary list [#engine-dmo-translate-glossary-list]

Terms for a pair.

```bash
engine-dmo translate glossary list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--target` | string |  | target locale (default: every row) |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo translate glossary seed [#engine-dmo-translate-glossary-seed]

Rebuild the auto-seeded terms from the CRM, the content and the tags.

```bash
engine-dmo translate glossary seed [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--dry-run` | bool |  | count only |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo translate jobs [#engine-dmo-translate-jobs]

List translation jobs.

```bash
engine-dmo translate jobs [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--locale` | string |  | only this target locale |
| `--status` | string |  | only this status |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo translate memory export [#engine-dmo-translate-memory-export]

Write the pair's units as TMX.

```bash
engine-dmo translate memory export [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--out` | string |  | file to write (default: stdout) |
| `--target` | string |  | target locale |

`--json` prints the text output in the JSON envelope. Runs in a project.


# user (/reference/cli/user)

engine-dmo user: Staff users and groups. Every subcommand, argument and flag.

Staff users and groups.

| Command | What it does |
|---|---|
| [`engine-dmo user create`](#engine-dmo-user-create) | Add a local staff user and print a single-use enrolment link |
| [`engine-dmo user grant-explain`](#engine-dmo-user-grant-explain) | Why a user may or may not do something, with the working |
| [`engine-dmo user list`](#engine-dmo-user-list) | List users, optionally in one group |
| [`engine-dmo user reset-mfa`](#engine-dmo-user-reset-mfa) | Clear a user's second factor, revoke sessions, and print a new enrolment link |
| [`engine-dmo user suspend`](#engine-dmo-user-suspend) | Suspend a user and revoke every session |

## engine-dmo user create [#engine-dmo-user-create]

Add a local staff user and print a single-use enrolment link.

```bash
engine-dmo user create [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | email address (required) |
| `--group` | strings |  | group key, repeatable; the first user defaults to administrators |
| `--name` | string |  | display name |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo user grant-explain [#engine-dmo-user-grant-explain]

Why a user may or may not do something, with the working.

```bash
engine-dmo user grant-explain [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--action` | string |  | the permission, e.g. content.publish |
| `--email` | string |  | the user |
| `--locale` | string |  | locale, or which locale of the document |
| `--owner` | string |  | hypothetical owner user id |
| `--resource` | string |  | type:&lt;document id>; reads site, type, locale, state, owner and tags from the row |
| `--site` | string |  | hypothetical site |
| `--state` | string |  | hypothetical state |
| `--tag` | string |  | hypothetical tags, comma separated |
| `--type` | string |  | hypothetical type |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo user list [#engine-dmo-user-list]

List users, optionally in one group.

```bash
engine-dmo user list [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--group` | string |  | only this group |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo user reset-mfa [#engine-dmo-user-reset-mfa]

Clear a user's second factor, revoke sessions, and print a new enrolment link.

```bash
engine-dmo user reset-mfa [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--confirm` | bool |  | confirm the reset |
| `--email` | string |  | email address (required) |

`--json` prints the text output in the JSON envelope. Runs in a project.

## engine-dmo user suspend [#engine-dmo-user-suspend]

Suspend a user and revoke every session.

```bash
engine-dmo user suspend [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--email` | string |  | email address (required) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# version (/reference/cli/version)

engine-dmo version: Version, bundle and modules, commit, build date, Go version, image variant and what it can encode, contract versions. Every subcommand, argument and flag.

Version, bundle and modules, commit, build date, Go version, image variant and what it can encode, contract versions.

```bash
engine-dmo version [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--require` | strings |  | exit 1 unless this build has these: formats the image pipeline encodes (webp, avif), heic, icc, pdf (a browser that prints a tagged PDF), and extension:`<name>` (a first-party extension that opens). An image build's smoke test |

`--json` prints the command's own JSON document. Needs no project.

See [Container images](/deploying/container-images) for `--require` in an image build.


# warm (/reference/cli/warm)

engine-dmo warm: After a deploy: repair the search index, queue image derivatives and warm the page cache, with each page's time. Every subcommand, argument and flag.

Queues an index job for every document the search index holds wrongly, and with `--media` a media warm job for every published page, for the workers to run. Then requests every page cache.pages.warm names (each site's configured paths, its routes' indexes and its most visited pages) from the running release, concurrency at a time, and reports each page's status, whether the page cache answered, and its time. `--origin` sends the requests to another address than the page's own, with the page's host, as a load balancer would.

```bash
engine-dmo warm [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--concurrency` | int | `4` | pages requested at once |
| `--header` | string, repeatable |  | a header every request carries, Name: value (repeatable) |
| `--media` | bool |  | also queue a media warm job for every published page |
| `--no-pages` | bool |  | warm no pages |
| `--no-search` | bool |  | leave the search index alone |
| `--origin` | string |  | send the requests here (scheme, host and port), with each page's own Host |

`--json` prints the text output in the JSON envelope. Runs in a project.

See [Upgrades](/deploying/upgrades) and [Scaling](/deploying/scaling#caches-across-replicas).


# webhooks (/reference/cli/webhooks)

engine-dmo webhooks: The outbound webhook delivery log: deliveries, replay. Every subcommand, argument and flag.

The outbound webhook delivery log: deliveries, replay.

| Command | What it does |
|---|---|
| [`engine-dmo webhooks deliveries`](#engine-dmo-webhooks-deliveries) | A site's outbound deliveries, newest first; `--id` prints one with its headers, body and the receiver's answer |
| [`engine-dmo webhooks replay`](#engine-dmo-webhooks-replay) | Send a delivery again with the same id and body, newly signed; audited as webhook.replay |

## engine-dmo webhooks deliveries [#engine-dmo-webhooks-deliveries]

A site's outbound deliveries, newest first; `--id` prints one with its headers, body and the receiver's answer.

```bash
engine-dmo webhooks deliveries [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | print one delivery in full |
| `--limit` | int | `100` | at most this many, up to 500 |
| `--site` | string |  | site key (default: the default site) |
| `--status` | string |  | pending \| delivered \| failed |
| `--webhook` | string |  | one webhook, by its key or config id |

`--json` prints the command's own JSON document. Runs in a project.

## engine-dmo webhooks replay [#engine-dmo-webhooks-replay]

Send a delivery again with the same id and body, newly signed; audited as webhook.replay.

```bash
engine-dmo webhooks replay [flags]
```

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--id` | string |  | the delivery id |
| `--site` | string |  | site key (default: the default site) |

`--json` prints the text output in the JSON envelope. Runs in a project.


# access/roles.yaml and grants.yaml (/reference/configuration/access)

Every key of config/access/roles.yaml (staff roles and their permissions) and config/access/grants.yaml (roles granted to staff groups under a scope).

`config/access/roles.yaml` defines staff roles and `config/access/grants.yaml` grants them to staff groups, optionally scoped to sites, types, locales, tags, states or ownership. Scope is enforced in every query, not filtered afterwards.

```yaml
grants:
  - group: editors
    role: editor
    scope:
      site: [wyndmouth]
```

`engine-dmo access matrix` prints every active user's effective permissions, and `engine-dmo user grant-explain` says why a user may or may not do something. `schema apply` refuses a change that would leave nobody able to manage users. See [Users, roles and permissions](/concepts/users-roles-and-permissions).

## access/roles.yaml [#accessrolesyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `roles` | list of objects |  | Staff roles: your own, or a built-in role restated with new permissions |
| `roles[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `roles[].key` | string | Required | The role's key; a built-in key replaces that role |
| `roles[].name` | map of string |  | Its name per locale |
| `roles[].permissions` | list of string | Required | The permissions the role grants, such as `content.publish`. `engine-dmo access matrix` shows the effect |

## access/grants.yaml [#accessgrantsyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `grants` | list of objects |  | Grants of a role to a staff group, optionally narrowed by a scope |
| `grants[].group` | string | Required | The staff group key |
| `grants[].role` | string | Required | The role key |
| `grants[].scope` | object | Everything | Narrows where the role applies; each key given must match |
| `grants[].scope.locale` | list of string |  | Locale codes |
| `grants[].scope.owner` | string | `any` | `any`, `self` (documents the person created) or `own_group` (documents created by anyone in the granted group) |
| `grants[].scope.site` | list of string |  | Site keys |
| `grants[].scope.state` | list of string |  | Document states |
| `grants[].scope.tag` | list of string |  | Tag keys |
| `grants[].scope.type` | list of string |  | Content type keys |


# accessibility.yaml (/reference/configuration/accessibility)

Every key of config/accessibility.yaml, the known accessibility issues register the statement and conformance report read.

`config/accessibility.yaml` is the register of known accessibility issues. `engine-dmo a11y issues` lists it, and `a11y statement` and `a11y report` include it.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `issues` | list of objects | `[]` | The known accessibility issues register, which the accessibility statement and conformance report read |
| `issues[].clause` | string |  | A WCAG or EN 301 549 clause, where one applies |
| `issues[].found` | string |  | When it was found |
| `issues[].key` | string | Required | The issue's key |
| `issues[].owner` | string |  | Who is fixing it |
| `issues[].reason` | string |  | Why it is not fixed yet, for the statement |
| `issues[].severity` | blocker, major, minor, note |  | `blocker`, `major`, `minor` or `note` |
| `issues[].summary` | string | Required | What is wrong |
| `issues[].surface` | admin, pdf, portal, site |  | Where: `site`, `admin`, `portal` or `pdf` |
| `issues[].target` | string |  | A date, or empty with a reason |

See [Accessibility](/features/accessibility).


# AI prompt overrides (/reference/configuration/ai-prompts)

Every key of an AI prompt override file in config/ai/prompts/<key>.yaml.

A YAML file in `ai.prompts_dir` (default `config/ai/prompts/`) replaces the engine's prompt with the same `key`.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `key` | string | Required | The key of the engine prompt this file replaces |
| `system` | string | Required | The system prompt text |
| `version` | integer | Required | The override's version, above zero |

Every problem in an override is reported with its file and line. See [AI assistance](/features/ai-assistance).


# analytics/reports.yaml and dashboards.yaml (/reference/configuration/analytics)

Every key of config/analytics/reports.yaml (scheduled member and organisation reports) and config/analytics/dashboards.yaml (organisation dashboards and manually entered figures).

`config/analytics/reports.yaml` declares scheduled member and organisation reports. `config/analytics/dashboards.yaml` declares the organisation dashboards and the figures staff enter per period.

`engine-dmo analytics report-run` queues a report for its current period, and `engine-dmo analytics export` exports a dashboard. Reports to members need `engine-dmo`. See [Analytics](/features/analytics).

## analytics/reports.yaml [#analyticsreportsyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `reports` | list of objects | `[]` | Scheduled reports |
| `reports[].audience` | member, organisation | Required | `member` (a report a member organisation receives) or `organisation` (a report about the destination's own organisation) |
| `reports[].compare` | none, previous_period, previous_year | `none` | `none`, `previous_period` or `previous_year` |
| `reports[].dashboard` | string |  | The dashboard it is built from |
| `reports[].format` | any |  | The output format or formats |
| `reports[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `reports[].key` | string | Required | The report's key |
| `reports[].metrics` | list of objects |  | The figures it carries, each with `key`, `kind`, `label` and an optional `target` |
| `reports[].metrics[].key` | string |  | See `reports[].metrics` |
| `reports[].metrics[].kind` | string |  | See `reports[].metrics` |
| `reports[].metrics[].label` | map of string |  | See `reports[].metrics` |
| `reports[].metrics[].target` | number |  | See `reports[].metrics` |
| `reports[].name` | map of string |  | Its name per locale |
| `reports[].range` | previous_financial_year, previous_month, previous_quarter, previous_year, this_financial_year, this_month, this_quarter |  | The period it covers: `this_month`, `previous_month`, `this_quarter`, `previous_quarter`, `previous_year`, `this_financial_year`, `previous_financial_year` |
| `reports[].schedule` | string |  | When it runs, as a cron schedule |
| `reports[].sites` | list of string | Every site | The sites it covers |
| `reports[].tiers` | any | Every tier | The membership tiers it goes to: a list of keys or `{ min: <tier> }` |
| `reports[].to` | string |  | Where an organisation report is sent |

## analytics/dashboards.yaml [#analyticsdashboardsyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `dashboards` | list of objects | `[]` | Organisation dashboards on the Insight screen |
| `dashboards[].compare` | string |  | The comparison it opens with |
| `dashboards[].default_range` | string |  | The range it opens on |
| `dashboards[].key` | string | Required | The dashboard's key |
| `dashboards[].name` | map of string |  | Its name per locale |
| `dashboards[].widgets` | list of objects |  | The tiles: each a `type` with its `metric`, `dimension`, `breakdown`, `interval`, `limit`, `order`, `size`, `steps`, `label` and `highlight` |
| `metrics` | list of objects | `[]` | Figures staff enter by hand per period, beside the measured ones |
| `metrics[].description` | map of string |  | What it measures, per locale |
| `metrics[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `metrics[].key` | string | Required | The figure's key |
| `metrics[].kind` | string |  | Its kind |
| `metrics[].label` | map of string |  | Its name per locale |
| `metrics[].period` | string |  | How often it is entered |
| `metrics[].unit` | string |  | Its unit |


# endpoints.yaml (/reference/configuration/endpoints)

Every top-level key of config/sites/<key>/endpoints.yaml: declared endpoints with their path, methods, access, rate limit, spam controls, inputs, validation, steps and response.

`config/sites/<key>/endpoints.yaml` declares the site's endpoints: enquiry and contact forms, newsletter sign-up and other actions a page posts to. Each validates its inputs, runs its steps in order and responds with a fragment or a redirect.

```yaml
endpoints:
  - key: contact
    path: /contact
    methods: [post]
    access: public
    rate_limit: 5/hour/ip
    input:
      email: { type: text, format: email, required: true, label: { en-GB: Your email address } }
      message: { type: text, multiline: true, max: 2000, label: { en-GB: Your message } }
    steps:
      - store: { as: enquiry, retention: 90d }
      - mail: { template: enquiry-receipt, to: $email }
    respond:
      fragment: partials/contact-sent.html
      on_error: partials/contact-form.html
```

`engine-dmo dev endpoint add <key> --from recipe:enquiry` (or `recipe:newsletter`) adds one from a recipe. [Forms and submissions](/features/forms-and-submissions) covers inputs, steps and responses in full.

The verb writes the endpoint and exits 0, but leaves its templates to you, so `engine-dmo check` fails until they exist: the `respond` fragments under `partials/`, and one email template for each `mail` step. A mail step's `template: enquiry-receipt` is the file `emails/enquiry-receipt.html` in one of the site's template roots, such as `templates/_shared/emails/enquiry-receipt.html`; the check's message (`which is not under templates/emails/`) means the `emails/` folder of any root.

Give each input's `label` in every locale the site serves. `check` warns about a schema label missing a locale, but not about an endpoint input's.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `endpoints` | list of objects | `[]` | The site's declared endpoints |
| `endpoints[].access` | member, public, staff | `public` | `public`, `member` or `staff` |
| `endpoints[].cache` | string |  | A duration a `get` response may be cached for |
| `endpoints[].csrf` | boolean | `true` | Require the CSRF token. `false` only for a machine caller with its own authentication |
| `endpoints[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `endpoints[].input` | object |  | The inputs by name, each with a `type` (`text`, `boolean`, `relation` and the rest), `required`, limits, `label` per locale and where it is read `from` |
| `endpoints[].key` | string | Required | The endpoint's key: lower case letters, digits and hyphens. Templates name it, as in `enquiryForm('contact')` |
| `endpoints[].methods` | list of string | Required | `get` and or `post` |
| `endpoints[].path` | string | Required | The path it answers on, with placeholders such as `{listing}` that `input` can read `from: path` |
| `endpoints[].permission` | string |  | The permission a staff or member caller needs |
| `endpoints[].rate_limit` | any | The class default | `<count>/<window>/<key>`: window `second`, `minute`, `hour` or `day`; key `ip`, `session`, `person`, `organisation` or `endpoint`. Such as `5/hour/ip` |
| `endpoints[].respond` | map of any | Required | Exactly one shape: `fragment` (a template), `location` (a redirect), `json` (a projection) or `stream`; plus `on_error`, the template for a submission with errors (not with `json`) |
| `endpoints[].spam.honeypot` | boolean | `endpoints.defaults.spam.honeypot` | The hidden field |
| `endpoints[].spam.min_fill_time` | string | `endpoints.defaults.spam.min_fill_time` | The shortest believable time to fill the form |
| `endpoints[].spam.proof_of_work` | boolean | `endpoints.defaults.spam.proof_of_work` | The proof-of-work challenge |
| `endpoints[].steps` | list of map of any | Required | What a valid submission does, in order. Core steps: `mail`, `audit`, `signal`, `analytics`, `query`, `source`, `job`, `webhook`, `plugin`; the Forms module adds `store` and the Newsletter module `subscribe` |
| `endpoints[].validation` | list of objects | `[]` | Cross-field rules, as in a schema's `validation` |
| `endpoints[].validation[].fields` | list of string |  | The inputs the message is shown against |
| `endpoints[].validation[].message` | map of string | Required | The message per locale |
| `endpoints[].validation[].rule` | string | Required | The rule expression, such as `message != empty` |
| `endpoints[].validation[].severity` | string | `error` | `error` or `warning` |


# engine.yaml: analytics and AI (/reference/configuration/engine-analytics-ai)

Every key of engine.yaml's analytics section (cookieless ingest, bot filtering, retention, reporting time zone, PDF reports), its ai section (provider, models, data boundary, budget, features, disclosure) and its translation section, with type, default and meaning.

## analytics [#analytics]

Meridian's analytics are cookieless and first-party: page views and interactions are recorded by the engine itself, with visitor addresses discarded after a salted hash that rotates daily.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `analytics.enabled` | boolean | `true` | Record analytics events |
| `analytics.ingest_buffer` | integer | `10000` | Events buffered in memory before they are written. When it is full, new events are dropped and counted (`meridian_analytics_events_dropped_total`) |
| `analytics.salt_rotation` | string | `daily` | Must be `daily`: the salt that pseudonymises visitors rotates every UTC day and the old one is destroyed |
| `analytics.raw_retention_days` | integer | `90` | Raw events are kept this many days, 30 to 400 |
| `analytics.hourly_retention_days` | integer | `400` | Hourly rollups are kept this many days. At least 30. Daily and monthly rollups are kept |
| `analytics.search_log_retention_days` | integer | `400` | The search query log is kept this many days. At least 30 |
| `analytics.reporting_timezone` | string | Empty | The IANA time zone days and months are counted in, such as `Europe/London`, for a site that does not set its own. Empty is UTC |
| `analytics.financial_year_start` | integer | `0` | The month (1 to 12) the financial year starts in, for reports; `0` takes the default site's country's convention |
| `analytics.bot_filtering` | string | `strict` | `off` keeps only deduplication and the anti-gaming rules; `standard` adds a request-rate rule; `strict` adds rules no real browser trips |
| `analytics.dedupe_window` | duration | `30m` | A repeat of the same event by the same visitor within this window counts once |
| `analytics.respect_dnt` | boolean | `false` | Drop requests carrying `DNT: 1` or `Sec-GPC: 1` before anything is recorded |
| `analytics.exclude_ips` | string | Empty | Addresses and CIDR ranges, separated by commas or spaces, whose requests are flagged (your office, your monitoring) and left out of reports |
| `analytics.country_header` | string | Empty | The header a trusted proxy or CDN writes the visitor's ISO country code into, such as `CF-IPCountry`. Read only from `server.trusted_proxies`, which must not be empty; without it the country is not recorded |
| `analytics.statement_timeout` | duration | `10s` | The time limit on report and dashboard queries. Above zero and below `database.statement_timeout` |
| `analytics.pdf.renderer` | string | `auto` | How member reports become PDF: `browser` (a headless Chromium, as in the `-vips` image), `builtin` (the engine's own writer), or `auto` (the browser when one is found, else built in) |
| `analytics.pdf.browser_binary` | string | Empty | The Chromium or Chrome binary to use; empty looks for one on the path |
| `analytics.pdf.timeout` | duration | `1m` | The time limit on rendering one PDF |

A file of extra user-agent substrings to filter, one per line, can be added at `config/analytics/bots.txt`; it extends the list shipped with the engine. Rollups run every ten minutes on the scheduler leader; `engine-dmo analytics recompute` rebuilds them for a range.

## ai [#ai]

The AI features are off unless `ai.enabled` is `true` and a provider is named. You bring your own provider account; nothing is sent anywhere else. Every AI output is a suggestion a person accepts, edits or rejects.

```yaml
ai:
  enabled: ${AI_ENABLED:-false}
  provider: openai_compatible
  openai_compatible:
    base_url: https://api.example-provider.eu/v1
    api_key: ${AI_API_KEY}
    model_text: example-large
    model_vision: example-vision
    model_embedding: example-embed
  budget:
    monthly_cost_cap: "50"
  pricing:
    input_per_million: "0.40"
    output_per_million: "1.60"
```

### Provider [#provider]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.enabled` | string | `"false"` | `"true"` or `"false"`. A string so it can be written as `${AI_ENABLED:-false}`. Enabled with `provider: none` is still off |
| `ai.provider` | string | `none` | `azure_openai`, `anthropic`, `openai`, `mistral`, `openai_compatible` or `none`. `bedrock` is reserved and refused |
| `ai.timeout` | duration | `30s` | Each provider request's time limit |
| `ai.models` | map of strings | `{}` | A model per feature, overriding the provider block's text or vision model for that feature alone (for Azure OpenAI, a deployment name). Keys are feature names; `duplicate_detection` uses the embedding model and cannot be set here |
| `ai.prompts_dir` | string | `config/ai/prompts` | Where prompt overrides are read from (see [AI prompts](/reference/configuration/ai-prompts)) |

Each endpoint-shaped provider has the same keys under its own name, `ai.openai`, `ai.mistral`, `ai.anthropic` and `ai.openai_compatible`:

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.<provider>.base_url` | string | `https://api.openai.com/v1`, `https://api.mistral.ai/v1`, `https://api.anthropic.com`; empty for `openai_compatible` | The API's base URL. Required for `openai_compatible` (Ollama, vLLM or any compatible service) |
| `ai.<provider>.api_key` | secret | Empty | The API key |
| `ai.<provider>.model_text` | string | Empty | The text model. Required |
| `ai.<provider>.model_vision` | string | Empty | The model that reads images (alt text drafting) |
| `ai.<provider>.model_embedding` | string | Empty | The embedding model (duplicate detection). The Anthropic adapter has none |

Azure OpenAI, in your own tenancy:

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.azure_openai.endpoint` | string | Empty | The resource endpoint. Required |
| `ai.azure_openai.api_key` | secret | Empty | The resource key |
| `ai.azure_openai.deployment_text` | string | Empty | The text deployment. Required |
| `ai.azure_openai.deployment_vision` | string | Empty | The vision deployment |
| `ai.azure_openai.deployment_embedding` | string | Empty | The embedding deployment |
| `ai.azure_openai.api_version` | string | `2024-10-21` | The API version |

`ai.bedrock.*` (`region`, `access_key_id`, `secret_access_key`, `model_text`, `model_vision`) is accepted for a provider that is not in this release.

### Data boundary [#data-boundary]

What may leave the install, enforced before a request is built.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.data_boundary.allow_content` | boolean | `true` | Content may be sent |
| `ai.data_boundary.allow_personal_data` | boolean | `false` | CRM personal fields may be sent. `true` is a warning; record it in your data protection assessment (`engine-dmo ai data-flow-statement` writes one) |
| `ai.data_boundary.allow_analytics` | string | `aggregate_only` | `aggregate_only` or `none`. Raw events are never sent |
| `ai.data_boundary.redact_before_send` | boolean | `true` | Replace email addresses and telephone numbers in text before it is sent. While `allow_personal_data` is `false` they are replaced whatever this says |
| `ai.data_boundary.exclude_fields` | list of strings | `[]` | Fields never sent, as `type.field` or `*.field`, such as `listing.internalNotes` |

### Budget and pricing [#budget-and-pricing]

The budget is a hard stop, not a report: a feature that would exceed it is refused.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.budget.monthly_cost_cap` | string | `"50"` | The monthly cost cap in the site currency, as a decimal (`"12.50"`); `"0"` is no cap |
| `ai.budget.monthly_tokens` | integer | `5000000` | The monthly token cap |
| `ai.budget.per_user_daily_requests` | integer | `200` | Requests one person may make a day |
| `ai.budget.per_feature_monthly_requests` | map of integers | `{}` | A monthly request cap per feature |
| `ai.budget.sites` | map of strings | `{}` | A monthly cost cap per site key |
| `ai.budget.estimate_before_bulk` | boolean | `true` | Accepted; bulk runs always print an estimate first |
| `ai.budget.estimated_tokens_per_call` | map of integers | `{}` | The tokens one call of a feature is estimated at, for bulk estimates |
| `ai.pricing.input_per_million` | string | Empty | What your provider charges per million input tokens, in the site currency, so spend can be held against the cap |
| `ai.pricing.output_per_million` | string | Empty | The same for output tokens |
| `ai.cache.enabled` | boolean | `true` | Answer a feature run again on unchanged content, with the same prompt and model, from the cache at no cost |
| `ai.cache.ttl` | duration | `720h` | How long a cached answer is kept |
| `ai.circuit_breaker.failures` | integer | `3` | Failures within `window` that stop the engine calling the provider |
| `ai.circuit_breaker.window` | duration | `1m` | The window failures are counted in |
| `ai.circuit_breaker.cooldown` | duration | `2m` | How long calls stay stopped |

### Features [#features]

Each feature switches on separately.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.features.alt_text` | boolean | `true` | Draft alt text for images (needs a vision model) |
| `ai.features.hours_extraction` | boolean | `true` | Read opening hours from pasted text |
| `ai.features.tag_suggestion` | boolean | `true` | Suggest tags |
| `ai.features.seo_drafting` | boolean | `true` | Draft SEO titles and descriptions |
| `ai.features.duplicate_detection` | boolean | `true` | Offer likely duplicate records (needs an embedding model) |
| `ai.features.translation` | boolean | `false` | Draft translations for a translator to review |
| `ai.features.summarisation` | boolean | `false` | Draft summaries |
| `ai.features.zero_result_briefs` | boolean | `false` | Draft content briefs from searches that found nothing |
| `ai.features.member_improvement` | boolean | `false` | Suggestions to members for improving their listings (`engine-dmo`) |
| `ai.features.quality_review` | boolean | `false` | Accepted; no feature reads it in this release |
| `ai.features.image_generation` | boolean | `false` | Not in this release; `true` is refused |
| `ai.duplicates.threshold` | number | `0.9` | The similarity, 0.5 to 1, at which a pair is offered as a duplicate |

### Translation drafting and disclosure [#translation-drafting-and-disclosure]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `ai.translation.memory_examples` | integer | `8` | Translation memory units sent with a request as examples, 0 to 50 |
| `ai.translation.length_ratio_bands` | map | `{}` | Per language pair (`"en:de"`), the shortest and longest expected length ratio, such as `[0.9, 1.5]`; a draft outside it is flagged |
| `ai.translation.quality_signals` | list of strings | `[]` | Accepted; every quality signal runs |
| `ai.disclosure.public` | string | `drafted_only` | Whether public pages disclose AI assistance: `never`, `drafted_only` (text an AI drafted) or `all` |
| `ai.disclosure.admin` | string | `always` | Always `always`: the admin always shows what an AI drafted |

`engine-dmo ai status`, `ai test` and `ai budget` check a configuration. See [AI assistance](/features/ai-assistance).

## translation [#translation]

The translator tools that work with no AI provider: the glossary and the translation memory.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `translation.glossary.auto_seed` | list of strings | `[organisation, listing, area, tag]` | Where glossary terms are seeded from automatically: organisation names, listing and area titles, tags |
| `translation.glossary.refresh_on_change` | boolean | `true` | Refresh seeded terms when their source changes |
| `translation.memory.enabled` | boolean | `true` | Keep a translation memory of approved translations |
| `translation.memory.suggest_exact_matches` | boolean | `true` | Offer an exact memory match as a suggestion |
| `translation.memory.fuzzy_threshold` | number | `0.75` | The similarity from which a near match is offered |
| `translation.memory.fuzzy_matches` | integer | `3` | The most near matches offered |


# engine.yaml: authentication and the MCP (/reference/configuration/engine-auth)

Every key of engine.yaml's auth section (local staff accounts, OpenID Connect single sign-on, staff and member sessions, member sign-in) and its mcp section (the remote content MCP endpoint, its clients, tokens and limits), with type, default and meaning.

Staff and members are two separate realms with their own sign-in and sessions. Staff sign in to the admin with a local account (password plus a second factor) or through your identity provider over OpenID Connect; members (`engine-dmo`) sign in to the portal with a magic link or a passkey. The `mcp` section switches on the content MCP endpoint that lets a person connect an AI agent to the admin.

## auth.staff.local [#authstafflocal]

```yaml
auth:
  staff:
    local:
      enabled: true
      require_mfa: true
      breach_check: local
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `auth.staff.local.enabled` | boolean | `true` | Staff may sign in with an email address and password |
| `auth.staff.local.allowlist` | string | Empty | Comma-separated email addresses. When set, only these may sign in with a local account |
| `auth.staff.local.require_mfa` | boolean | `true` | Every local account must enrol a second factor. `false` is refused in production |
| `auth.staff.local.password_min_length` | integer | `12` | The shortest password accepted. At least 12 |
| `auth.staff.local.breach_check` | string | `local` | `local` checks a new password against the breached-password filter shipped in the binary, with no network request; `hibp` checks that, then the Have I Been Pwned range API; `off` checks nothing (a warning in production) |
| `auth.staff.local.hibp_url` | string | Empty | The range endpoint for `hibp`, to which the SHA-1 prefix is appended, such as a mirror behind an egress proxy. Empty is the public service. `https` (or `http` outside production) |
| `auth.staff.local.argon2.memory_kb` | integer | `65536` | Argon2id memory per hash, in KiB. At least 19456 |
| `auth.staff.local.argon2.time` | integer | `3` | Argon2id iterations. At least 2 |
| `auth.staff.local.argon2.threads` | integer | `2` | Argon2id parallelism. At least 1 |

`engine-dmo doctor` reports the measured time of one password hash with these parameters.

## auth.staff.oidc [#authstaffoidc]

Single sign-on through your identity provider (Microsoft Entra ID, Google Workspace, Okta, Keycloak, Auth0 and any other OpenID Connect provider). A user's groups in the provider map to Meridian staff groups.

```yaml
auth:
  staff:
    oidc:
      enabled: true
      issuer: https://login.microsoftonline.com/<tenant id>/v2.0
      client_id: ${OIDC_CLIENT_ID}
      client_secret: ${OIDC_CLIENT_SECRET}
      group_claim: groups
      group_map:
        "a1b2c3d4-web-editors": editors
        "e5f6a7b8-marketing": [editors, analysts]
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `auth.staff.oidc.enabled` | boolean | `false` | Offer sign-in through the provider. Needs `issuer` and `client_id` |
| `auth.staff.oidc.issuer` | string | Empty | The provider's issuer URL; its discovery document is read from it |
| `auth.staff.oidc.client_id` | string | Empty | The client registered with the provider |
| `auth.staff.oidc.client_secret` | secret | Empty | Its secret |
| `auth.staff.oidc.scopes` | list of strings | `[openid, profile, email]` | The scopes requested |
| `auth.staff.oidc.group_claim` | string | `groups` | The ID token claim that lists the user's groups |
| `auth.staff.oidc.group_map` | map | `{}` | Provider group value to one Meridian group key, or a list of keys |
| `auth.staff.oidc.unmatched_groups` | string | `ignore` | A provider group not in `group_map`: `ignore` or `warn` (logged) |
| `auth.staff.oidc.no_mapped_group` | string | `refuse` | A user none of whose groups is mapped: `refuse` the sign-in, or `provision` them with `provision.groups` alone |
| `auth.staff.oidc.auto_provision` | boolean | `true` | Create a staff user on first sign-in |
| `auth.staff.oidc.link_existing_by_email` | string | `verified_only` | Link a first sign-in to an existing staff user with the same email: `verified_only` when the provider says the email is verified, or `never` |
| `auth.staff.oidc.provision.display_name_claim` | string | `name` | The claim a new user's display name is read from |
| `auth.staff.oidc.provision.locale_claim` | string | `locale` | The claim their admin language is read from |
| `auth.staff.oidc.provision.groups` | list of strings | `[]` | Groups every provisioned user joins |
| `auth.staff.oidc.deprovision_on` | string | `absent` | Group memberships always follow the provider at each sign-in, and a change ends the user's other sessions. `absent`: a user who signs in with no mapped group at all, and holds no admin membership, is suspended (a later sign-in with a mapped group restores them); `never`: not suspended |
| `auth.staff.oidc.required_acr` | string | Empty | An authentication context class the provider must assert (sent as `acr_values` and checked in the token), to require the provider's own MFA |

## auth.staff.session [#authstaffsession]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `auth.staff.session.absolute_lifetime` | duration | `12h` | The longest a staff session lives |
| `auth.staff.session.idle_timeout` | duration | `2h` | A session unused for this long ends. Positive and not longer than `absolute_lifetime` |

## auth.member [#authmember]

Members are the people behind partner organisations, signing in to the member portal (`engine-dmo`).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `auth.member.enabled` | boolean | `true` | Members may sign in |
| `auth.member.magic_link.enabled` | boolean | `true` | Sign in with a single-use link sent by email |
| `auth.member.magic_link.ttl` | duration | `15m` | How long a link works |
| `auth.member.passkeys.enabled` | boolean | `true` | Members may add and use passkeys |
| `auth.member.password.enabled` | boolean | `false` | Member passwords are not built; `true` is refused |
| `auth.member.registration` | string | `claim` | How a member relationship starts: `claim` (staff invitations and the public claim form) or `invite_only` (staff invitations alone). `open` is refused |
| `auth.member.session.absolute_lifetime` | duration | `720h` | The longest a member session lives (30 days) |
| `auth.member.session.idle_timeout` | duration | `336h` | A member session unused for this long ends (14 days) |

## mcp [#mcp]

The content MCP endpoint lets a staff member connect an AI agent (a Model Context Protocol client) to the admin, acting as themselves with their own permissions, after a consent screen. It is off unless `mcp.enabled` is `true`; off, there is no endpoint, no metadata and no admin screen for it. It is served on the admin's origin at `<admin_path>/mcp`. `engine-dmo mcp` over standard input and output, for a local agent in development, does not read this section except `personal_data`.

```yaml
mcp:
  enabled: true
  personal_data: refuse
  clients:
    - id: acme-agents
      name: Acme agent platform
      redirect_uris: ["https://agents.acme.example/callback"]
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mcp.enabled` | boolean | `false` | Serve the endpoint and its OAuth authorisation server |
| `mcp.registration.metadata_documents` | boolean | `true` | Accept clients that identify themselves by a client ID metadata document (a URL `client_id`) |
| `mcp.registration.dynamic` | boolean | `false` | Accept dynamic client registration |
| `mcp.clients` | list | `[]` | Pre-registered public clients using PKCE |
| `mcp.clients[].id` | string | Required | The `client_id` the client sends, such as `acme-agents`. Not a URL; unique |
| `mcp.clients[].name` | string | Required | The name the consent screen shows |
| `mcp.clients[].redirect_uris` | list of strings | Required | `https` URLs, or `http` on a loopback address, with no fragment |
| `mcp.tokens.access_ttl` | duration | `1h` | An access token's life, `5m` to `24h`. Every call looks the token up, so revocation is immediate |
| `mcp.tokens.refresh_idle` | retention | `30d` | How long a refresh token may go unused, `1d` to `180d` |
| `mcp.tokens.connection_max` | retention | `90d` | The longest a connection or a personal access token lives, `1d` to `180d` |
| `mcp.personal_data` | string | `refuse` | `refuse` keeps CRM personal data away from agents; `allow` lets a person choose the toolsets that return it on the consent screen |
| `mcp.media.fetch` | boolean | `true` | Allow uploading media by URL; off refuses every upload by URL |
| `mcp.media.fetch_hosts` | list of strings | `[]` | When set, only these hosts (and their subdomains) may be fetched from |
| `mcp.limits.calls_per_minute` | integer | `600` | A connection's weighted calls a minute (a read weighs 1, a search 2, a content check 3, a write 5, a bulk plan 1 an item), counted per replica. At most 1200 |
| `mcp.limits.writes_per_minute` | integer | `60` | A person's writes a minute across all their connections. At most 120 |
| `mcp.limits.writes_per_day` | integer | `2000` | A person's writes a day. At most 5000 |
| `mcp.limits.bulk_items` | integer | `200` | The most operations one bulk plan carries. At most 500 |
| `mcp.limits.media_by_url_per_hour` | integer | `20` | A connection's uploads by URL an hour. At most 100 |

A limit left out (or `0`) takes its default. See [The content MCP](/integrating/content-mcp).


# engine.yaml: content, media and search (/reference/configuration/engine-content)

Every key of engine.yaml's content, media, events, tags, approvals, endpoints, forms, search, maps, admin and notifications sections, with type, default and meaning.

These sections of `config/engine.yaml` tune how content, media, search and the admin behave for the whole install. Per-site and per-type settings live in the site and schema files. Value formats (durations, retention periods, sizes) are explained on [engine.yaml](/reference/configuration/engine#value-formats).

## content [#content]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `content.trash_retention` | retention | `30d` | How long a trashed document waits before the nightly purge deletes it. A document on hold is kept until released |
| `content.revisions.prune` | boolean | `true` | Prune old revisions daily. `false` keeps every revision and does not schedule the task |
| `content.revisions.keep_all` | retention | `90d` | Every revision younger than this is kept. At least `1d` |
| `content.revisions.keep_last` | integer | `20` | And the newest N of each document's revision chain. At least 1 |
| `content.revisions.keep_monthly` | boolean | `true` | And the newest revision of each calendar month (UTC) of each chain |
| `content.health.stale_after` | retention | `12m` | A live page older than this fails the content health staleness signal. At least `1d` |

A type's own `revisions:` block in its schema file overrides `content.revisions` key by key. A document under legal hold keeps every revision. `engine-dmo content prune-revisions --dry-run` shows what the sweep would remove.

## media [#media]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `media.max_upload_bytes` | size | `50MB` | The largest file an upload may carry |
| `media.max_pixels` | integer | `50000000` | The largest image, in pixels, the pipeline decodes. At least 1,000,000 |
| `media.accept` | list of strings | `[image/jpeg, image/png, image/webp, image/avif, application/pdf, application/gpx+xml]` | The media types an upload may have. An asset field's own `accept` narrows it further |
| `media.strip_exif_gps` | boolean | `true` | Remove GPS coordinates from uploaded images |
| `media.require_alt_text` | boolean | `true` | An image used on a page needs alt text before the page publishes |
| `media.signing_key` | secret | Derived | The key derivative addresses are signed with. Unset, a key derived from `server.security.signing_key` is used. Changing it changes every derivative address |
| `media.derivatives.keep_unused` | retention | `90d` | A derivative nothing has served or warmed for this long is removed by the nightly prune. At least `1d` |
| `media.rights.terms` | map | The four built-in terms | The licence vocabulary staff choose from, by key. Setting it replaces the built-in terms |
| `media.rights.terms.<key>.label` | map of strings | | The term's name per locale, such as `{en-GB: "Stock, website only, 2 years"}` |
| `media.rights.terms.<key>.uses` | list of strings | | Where an asset under the term may be used: `website`, `social`, `newsletter`, `print`, `editorial`, `press`, `partner`, `handover` |
| `media.rights.terms.<key>.territory` | list of strings | | Where it may be used: `WORLD` or country codes |
| `media.rights.terms.<key>.duration` | string | Empty | How long the licence runs from its start, such as `2y` or `18m`; empty is perpetual |
| `media.rights.terms.<key>.credit_required` | boolean | `false` | The credit must be shown wherever the asset is |
| `media.rights.expiry_warnings` | list of strings | `[180d, 90d, 30d, 0d]` | When, before a licence ends, the people who manage media rights are told |
| `media.rights.block_publish_when_expired` | boolean | `true` | An asset whose licence has ended blocks publishing a page that uses it. `false` makes it a warning |
| `media.rights.warn_publish_when_expiring` | boolean | `true` | Warn at publish when a licence ends while the page stays live |
| `media.rights.on_expiry` | string | `warn` | What a live page does once an asset's licence has ended: `warn` (nothing changes on the page) or `placeholder` (the image renders as absent) |
| `media.orphans.scan_schedule` | string | `0 3 * * *` | When the full reference scan, which finds assets nothing uses, runs. Cron, UTC |
| `media.duplicates.threshold` | integer | `10` | How many of a perceptual hash's 64 bits may differ for two images to be offered as near duplicates |

The built-in licence terms are `commissioned-perpetual` (every use, worldwide, perpetual), `stock-2yr-web` (website and social, two years), a member-supplied term (website, social and newsletter, credit required) and `press-only` (press and editorial, credit required).

## events [#events]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `events.occurrence_window.behind` | retention | `90d` | How far into the past a recurring event's occurrences are kept |
| `events.occurrence_window.ahead` | retention | `540d` | How far ahead they are generated. At most five years |
| `events.roll_at` | time of day | `03:30` | When the window rolls forward each day, in the default site's reporting time zone |

## tags [#tags]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `tags.promotion.threshold` | integer | `0` (meaning 5) | How many distinct subjects a freeform tag must be on before it is offered for promotion into the vocabulary and the people who manage tags are told |

## approvals [#approvals]

How the moderation queue treats changes members submit through the portal (`engine-dmo`). Which fields a member may edit, and whether a tier's changes need review, are set in the schema.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `approvals.review_window_poll` | duration | `15m` | How often review windows are closed and returned drafts expired |
| `approvals.returned_expiry` | retention | `30d` | A draft returned to its member and left untouched this long is discarded as if rejected, and the member is told |
| `approvals.expected_turnaround` | duration | `24h` | The review time members are told to expect; a change waiting longer is overdue |
| `approvals.bulk_approve.enabled` | boolean | `true` | Reviewers may approve several low-risk changes at once |
| `approvals.bulk_approve.low_risk_types` | list of strings | `[opening_hours, phone, link, boolean, number, date, datetime, select, address, geo]` | The field types whose changes count as low risk |

## endpoints [#endpoints]

Install-wide defaults for declared endpoints (forms, enquiries, newsletter sign-up and the rest in each site's `endpoints.yaml`). A site's endpoint may tighten these and may not loosen a security-relevant one.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `endpoints.defaults.rate_limit.public_get` | rate limit | `60/minute/ip` | Public `GET` endpoints, per client address |
| `endpoints.defaults.rate_limit.public_post` | rate limit | `10/hour/ip` | Public `POST` endpoints, per client address |
| `endpoints.defaults.rate_limit.public_mail` | rate limit | `500/day/endpoint` | Mail sent by public endpoints, per endpoint |
| `endpoints.defaults.rate_limit.member` | rate limit | `60/hour/session` | Member endpoints, per session |
| `endpoints.defaults.rate_limit.staff` | rate limit | `600/minute/session` | Staff endpoints, per session |
| `endpoints.defaults.rate_limit.embed` | rate limit | `600/minute/origin` | Embeddable widgets, per embedding origin. Must be `<count>/<window>/origin` |
| `endpoints.defaults.spam.proof_of_work` | boolean | `true` | Public forms carry a small proof-of-work challenge the browser solves. There is never a CAPTCHA |
| `endpoints.defaults.spam.honeypot` | boolean | `true` | Public forms carry a hidden field a person leaves empty |
| `endpoints.defaults.spam.min_fill_time` | duration | `2s` | A submission faster than this after the form loaded is treated as automated |
| `endpoints.max_input_bytes` | size | `256KB` | The largest non-upload body an endpoint accepts |

## forms [#forms]

The Forms module's retention of stored submissions.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `forms.max_retention` | retention | `2y` | The longest any endpoint's store step may keep a submission |
| `forms.orphan_retention` | retention | `30d` | How long submissions outlive their endpoint leaving the configuration |
| `forms.purge_schedule` | string | `0 2 * * *` | When the purge of expired submissions runs. Cron, UTC |

## search [#search]

The search backend is always an external service. `driver: none` is a valid, explicit choice: the search route then serves browse mode.

```yaml
search:
  driver: meilisearch
  meilisearch:
    url: ${MEILISEARCH_URL}
    api_key: ${MEILISEARCH_API_KEY}
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `search.driver` | string | `none` | `meilisearch`, `elasticsearch`, `opensearch` or `none` |
| `search.log_queries` | boolean | `true` | Record queries for the zero-result and search reports. `false` is refused in production |
| `search.min_query_length` | integer | `2` | Shorter queries are not sent to the backend |
| `search.degraded_mode` | string | `browse` | What the search route does while the backend is failing: `browse` (serve browse results) or `error` |
| `search.runs_kept` | integer | `20` | Finished rebuild, purge and sweep runs kept per site and kind, 1 to 1000 |
| `search.circuit_breaker.failures` | integer | `5` | Failures within `window` that stop the engine asking the backend |
| `search.circuit_breaker.window` | duration | `30s` | The window failures are counted in |
| `search.circuit_breaker.cooldown` | duration | `1m` | How long the breaker stays open before trying again |
| `search.meilisearch.url` | string | Empty | The Meilisearch base URL. Required with that driver |
| `search.meilisearch.api_key` | secret | Empty | Its API or master key. Set the variable empty for a server with no key |
| `search.meilisearch.index_prefix` | string | `meridian` | Prefix of every index name, so several installs can share one server |
| `search.meilisearch.timeout` | duration | `2s` | Each request's timeout |
| `search.elasticsearch.addresses` | list of strings | `[]` | The cluster's URLs. Required with that driver; the first is used |
| `search.elasticsearch.username` | string | Empty | Basic authentication user |
| `search.elasticsearch.password` | secret | Empty | Basic authentication password |
| `search.elasticsearch.index_prefix` | string | `meridian` | Index name prefix |
| `search.elasticsearch.timeout` | duration | `3s` | Each request's timeout |
| `search.opensearch.*` | | | The same keys as `elasticsearch`, with the same defaults. With `driver: opensearch` and no `opensearch.addresses`, the `elasticsearch` block is used |

Also accepted and not used in this release: `search.meilisearch.addresses`, `.username` and `.password`; `search.elasticsearch.url` and `.api_key` (and the same under `opensearch`). Their secret forms are still held to the secret rule.

## maps [#maps]

Static maps are drawn on the server from a tile provider and cached as an image, so a visitor's browser never contacts the provider. With no `tiles`, a static map renders nothing.

```yaml
maps:
  tiles: https://api.maptiler.com/maps/streets-v2/{z}/{x}/{y}.png?key={key}
  key: ${MAP_TILES_KEY}
  attribution: "© MapTiler © OpenStreetMap contributors"
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `maps.tiles` | string | Empty | The tile URL template, with `{z}`, `{x}`, `{y}`, and `{key}` where the provider takes the key in the address. Any service on the standard tile scheme works, including your own |
| `maps.key` | secret | Empty | The provider's key, written into `{key}` |
| `maps.attribution` | string | Empty | The credit the provider's licence requires, shown beneath every map |
| `maps.max_zoom` | integer | `0` (meaning 18) | The highest zoom a template may ask for |
| `maps.tile_size` | integer | `0` (meaning 256) | The provider's tile edge in pixels |
| `maps.timeout` | duration | `0s` (meaning 10s) | The time limit for fetching one map's tiles |

## admin [#admin]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `admin.rich_text_editor` | string | Empty (Editor.js) | The rich text editing surface in the admin and the portal: `editorjs` (the default) or `native` |
| `admin.rich_text_input_rules` | boolean | `false` | Markdown-style shortcuts in the editor: `## ` starts a heading, `- ` a list, `**bold** ` bolds, where the field allows the result |
| `admin.theme.brand_name` | string | Empty | The name the admin shows in place of the product's |
| `admin.theme.logo` | string | Empty | The logo: a path under the project's `public/` starting with `/` (`/branding/logo.svg` for `public/branding/logo.svg`), SVG or PNG |
| `admin.theme.logo_dark` | string | Empty | The logo for the dark colour scheme, as `logo` |
| `admin.theme.favicon` | string | Empty | The admin's favicon, as `logo`; ICO is also accepted |
| `admin.theme.css_variables` | map of strings | `{}` | Brand tokens as CSS custom properties; `engine-dmo check` lists the themeable names when one is not. Every colour pair is checked against WCAG 2.2 AA contrast when the configuration loads; tokens that carry target size, focus, spacing, type or motion cannot be set |
| `admin.theme.custom_css` | string | Empty | A `.css` file under `public/`, as `logo`, loaded after the admin's own stylesheet |
| `admin.theme.contrast_check` | string | Empty (`enforce`) | `enforce` makes a failing pair an error; `warn` a warning (itself a warning in production) |

## notifications [#notifications]

When staff are emailed about what the admin already shows them.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `notifications.mention_email_delay` | duration | `15m` | A mention still unread after this long is emailed |
| `notifications.digest_hour` | time of day | `08:00` | When the daily digest of everything else goes, in each user's own time zone |
| `notifications.email_includes_body` | boolean | `true` | Include the comment or change in the email; `false` sends a summary and a link only |
| `notifications.retention` | retention | `90d` | Read notifications are deleted after this |


# engine.yaml: DMO modules (/reference/configuration/engine-dmo)

Every key of engine.yaml's claims section (ownership claim methods, signal weights, auto-approval) and membership section (renewal reminders), with type, default and meaning, and where the portal settings live.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

These sections belong to modules only `engine-dmo` compiles. `engine-cms` refuses them by the module's name.

## claims [#claims]

How a business proves it owns a listing. Each verification method adds a signal with a weight to the claim's confidence score; staff decide, unless auto-approval is on and the score clears the threshold.

```yaml
claims:
  verification_ttl: 7d
  methods:
    post:
      enabled: true
      code_ttl: 30d
  auto_approve:
    enabled: true
    threshold: 120
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `claims.verification_ttl` | retention | `7d` | A claim not verified in this long expires |
| `claims.methods.email_domain.enabled` | boolean | `true` | The claimant's email domain matching the listing's website domain counts |
| `claims.methods.listed_email.enabled` | boolean | `true` | A confirmation sent to the email address on the listing counts |
| `claims.methods.contact_approval.enabled` | boolean | `true` | An existing contact of the organisation approving the claim counts |
| `claims.methods.phone_callback.enabled` | boolean | `true` | Staff calling the listed number and confirming counts |
| `claims.methods.post.enabled` | boolean | `true` | A code posted to the listed address and entered by the claimant counts |
| `claims.methods.post.code_ttl` | retention | `30d` | How long a posted code works |
| `claims.methods.post.max_attempts` | integer | `5` | Wrong entries allowed for a posted code |
| `claims.methods.phone_auto.enabled` | boolean | `false` | Automated phone verification. Reserved: `true` is refused, as no telephony driver ships |
| `claims.signals` | map of integers | See below | Each signal's weight. Writing the map replaces the listed weights by key |
| `claims.auto_approve.enabled` | boolean | `false` | Approve a claim automatically when its score reaches the threshold |
| `claims.auto_approve.threshold` | integer | `80` | The score that approves. A warning when it is not above the largest automated signal's weight, since one signal could then approve a claim |
| `claims.notify_existing_contacts` | boolean | `true` | Tell the organisation's existing contacts that someone has claimed it |
| `claims.free_provider_list` | string | `bundled` | The free email providers (whose domains prove nothing): `bundled`, the list shipped with the engine, or a path relative to the project of a text file with one domain per line and `#` comments |

The default signal weights:

| Signal | Weight |
|---|---|
| `email_domain_match` | 50 |
| `listed_email_match` | 60 |
| `contact_approval` | 70 |
| `contact_objection` | -100 |
| `phone_callback` | 60 |
| `post_code_returned` | 60 |
| `free_provider_only` | -20 |
| `prior_rejection` | -30 |
| `manual` | 100 |

`engine-dmo crm claims rescore` recomputes open claims under changed weights; it never approves one. See [Claims](/dmo/claims).

## membership [#membership]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `membership.renewal.reminders` | list of strings | `[60d, 30d, 7d, 0d]` | When, before a membership renews, the renewal notice is sent: whole days from `0d` to `366d`, counted in the site's time zone |

The tiers themselves are in [`config/memberships.yaml`](/reference/configuration/networks-and-memberships#membershipsyaml).

## portal [#portal]

The member portal's settings live in [`config/portal/portal.yaml`](/reference/configuration/portal). A `portal:` block left in `engine.yaml` is still read, with a warning saying where it belongs; its keys are the same as that file's.


# engine.yaml: mail and newsletter (/reference/configuration/engine-mail)

Every key of engine.yaml's mail section (the transactional mail driver for SMTP, Postmark, Amazon SES or Resend, bounce webhooks, templates, suppression and broadcast sending) and its newsletter section, with type, default and meaning.

The engine sends mail through a provider or relay you bring; it never runs mail infrastructure. Transactional mail (sign-in links, enquiry notifications, confirmations) uses the `mail` section. The Newsletter module's campaigns use the same driver with the `newsletter` section's sender and rules.

```yaml
mail:
  driver: postmark
  from: "Visit Example <hello@example.org>"
  reply_to: help@example.org
  postmark:
    server_token: ${POSTMARK_SERVER_TOKEN}
    webhook_token: ${POSTMARK_WEBHOOK_TOKEN}
```

Check a configuration with a real send:

```bash
engine-dmo mail status
engine-dmo mail test --to you@example.org            # sends the magic-link template by default
```

## mail [#mail]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.driver` | string | Empty (`log`) | `postmark`, `ses`, `resend`, `smtp`, or `log` (messages are written to the log, development only). `engine-dmo check` refuses `log` in production |
| `mail.from` | string | Empty | The sender, `hello@example.org` or `Visit Example <hello@example.org>`. Required in production |
| `mail.reply_to` | string | Empty | The `Reply-To` address |
| `mail.rate_limit_per_minute` | integer | `0` | The most messages a minute each process sends; `0` is no limit |
| `mail.delivery_record_retention` | retention | Empty (`13m`) | How long delivery records (what was sent to whom, and its outcome) are kept |

### mail.smtp [#mailsmtp]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.smtp.host` | string | Empty | The relay's host. Required for a send |
| `mail.smtp.port` | integer | `0` (meaning 587) | The relay's port |
| `mail.smtp.username` | string | Empty | The user, when the relay needs authentication |
| `mail.smtp.password` | secret | Empty | The password |
| `mail.smtp.tls` | string | Empty | `starttls`: require STARTTLS; `tls`: connect over TLS from the start (port 465); `none`: never encrypt. Empty uses STARTTLS when the relay offers it. TLS 1.2 or later |

Only Postmark, SES and Resend report bounces and complaints back through a webhook; an SMTP relay does not.

### mail.postmark [#mailpostmark]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.postmark.server_token` | secret | Empty | The Postmark server's API token |
| `mail.postmark.message_stream` | string | Empty | The transactional message stream; empty is Postmark's default stream |
| `mail.postmark.broadcast_stream` | string | Empty (`broadcast`) | The stream marketing mail (newsletters and broadcasts) goes out on, so its reputation stays apart |
| `mail.postmark.webhook_token` | secret | Empty | The token Postmark's bounce and complaint webhook must present. Required in production |

### mail.ses [#mailses]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.ses.region` | string | Empty | The AWS region, such as `eu-west-2` |
| `mail.ses.access_key_id` | string | Empty | The IAM access key |
| `mail.ses.secret_access_key` | secret | Empty | Its secret |
| `mail.ses.configuration_set` | string | Empty | The SES configuration set that publishes events |
| `mail.ses.notification_topic_arn` | string | Empty | The SNS topic bounces and complaints arrive from; notifications from another topic are refused |

### mail.resend [#mailresend]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.resend.api_key` | secret | Empty | The Resend API key. Required in production |
| `mail.resend.webhook_secret` | secret | Empty | The signing secret of the webhook endpoint the Resend dashboard shows (`whsec_...`). Required in production |

### mail.webhooks [#mailwebhooks]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.webhooks.path` | string | Empty (`/_mail/webhooks`) | Where the provider posts delivery events. Only the configured driver's route exists: `<path>/postmark`, `<path>/ses` or `<path>/resend`. Point the provider's webhook at `https://<your host><path>/<driver>` |

### mail.templates [#mailtemplates]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.templates.dir` | string | Empty (`emails`) | The subdirectory, in each of a site's template roots, that holds your mail templates (`templates/_shared/emails/`). A template there replaces the engine's of the same name |
| `mail.templates.plain_text` | string | Empty (`generate`) | `generate` makes the plain-text part from the HTML when a template has no `.txt` alternative; `require` makes a missing `.txt` an error |

`engine-dmo mail templates` lists every transactional template, which directory resolved it, and whether a plain-text alternative exists.

### mail.suppression [#mailsuppression]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.suppression.soft_bounce_threshold` | integer | `3` | Soft bounces within the window that suppress an address |
| `mail.suppression.soft_bounce_window` | retention | `30d` | The window soft bounces are counted over |
| `mail.suppression.notify_on_suppress` | boolean | `true` | When a CRM contact's address is suppressed after a hard bounce, notify staff, naming the contact's organisations (`engine-dmo`). The suppression is recorded on the contact's timeline either way |

### mail.broadcast [#mailbroadcast]

How the CRM's broadcasts to members are sent (`engine-dmo`).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mail.broadcast.batch_size` | integer | `50` | Messages queued at a time, 1 to 1000 |
| `mail.broadcast.batch_pause` | duration | `5s` | The pause between batches, `0s` to `1h`, on top of the mail rate limit |
| `mail.broadcast.unsubscribe_footer` | boolean | Unset (on) | Every broadcast carries an unsubscribe link. `false` is refused |
| `mail.broadcast.open_tracking` | boolean | `false` | Count opens with a tracking image |
| `mail.broadcast.per_recipient_tracking` | boolean | `false` | Record clicks and opens per recipient rather than per broadcast; the footer then says so |

## newsletter [#newsletter]

The Newsletter module's sender and rules. Double opt-in is always on.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `newsletter.from_name` | string | Empty | The sender name of campaigns. One line of plain text |
| `newsletter.from_address` | string | Empty | The sender address, a bare address such as `news@example.org` |
| `newsletter.reply_to` | string | Empty | The reply address, a bare address |
| `newsletter.double_opt_in` | boolean | Unset (on) | `false` is refused: a subscriber always confirms |
| `newsletter.pending_expiry` | retention | `14d` | An unconfirmed subscriber is deleted after this, `1d` to `90d` |
| `newsletter.preference_centre_path` | string | `/newsletter/preferences` | The preference centre's path on each site: starting with `/`, not `/_`, no trailing slash |
| `newsletter.open_tracking` | boolean | `false` | Count opens |
| `newsletter.click_tracking` | boolean | Unset (on) | Send links through a counted redirect; `false` turns it off |
| `newsletter.send_rate_per_minute` | integer | `600` | Campaign messages a minute, 1 to 100000 |
| `newsletter.dormant_after` | retention | `12m` | An active subscriber with no click in this long counts as dormant in the hygiene report. At least `30d` |
| `newsletter.require_domain_verification` | boolean | Unset (on) | A campaign is refused until the sending domain passes the SPF, DKIM and DMARC checks (`engine-dmo newsletter deliverability`) |
| `newsletter.topics` | list of strings | `[]` | The topics subscribers choose from, as lower case keys |
| `newsletter.dkim_selectors` | list of strings | `[]` | The DKIM selectors the deliverability check looks up for the sending domain |

See [Mail](/features/mail) and [Newsletters](/features/newsletters).


# engine.yaml (/reference/configuration/engine)

Every key of config/engine.yaml for the server, database, migrations, schema, templates, public files, logging, caches, storage, jobs, telemetry, retention, audit and extensions, with type, default and meaning; other sections are on their own pages.

`config/engine.yaml` configures the install: how the engine serves, what it connects to and how it runs. It is the one configuration file every project has. A key left out takes its default, and an unknown key is an error with a suggestion (`did you mean "max_connections"?`).

```yaml
engine:
  version: "1.x"
  environment: ${ENVIRONMENT:-development}
server:
  listen: ${LISTEN_ADDR:-127.0.0.1:8080}
  base_url: ${BASE_URL:-http://localhost:8080}
database:
  url: ${DATABASE_URL}
```

```bash
engine-dmo config render                 # every key with its resolved value, secrets redacted
engine-dmo config schema --file engine   # the JSON Schema of this file
```

This page covers the sections about running the engine. The rest of `engine.yaml` is on these pages:

| Sections | Page |
|---|---|
| `auth`, `mcp` | [engine.yaml: authentication and the MCP](/reference/configuration/engine-auth) |
| `content`, `media`, `events`, `tags`, `approvals`, `endpoints`, `forms`, `search`, `maps`, `admin`, `notifications` | [engine.yaml: content, media and search](/reference/configuration/engine-content) |
| `mail`, `newsletter` | [engine.yaml: mail and newsletter](/reference/configuration/engine-mail) |
| `analytics`, `ai`, `translation` | [engine.yaml: analytics and AI](/reference/configuration/engine-analytics-ai) |
| `claims`, `membership`, `portal` | [engine.yaml: DMO modules](/reference/configuration/engine-dmo) |

A section that belongs to a module the binary does not compile is refused by the module's name; `claims` and `membership` are `engine-dmo` only.

## Value formats [#value-formats]

| Format | Written as | Notes |
|---|---|---|
| Duration | `30s`, `15m`, `2h`, `720h` | Go duration syntax. Units `ns`, `us`, `ms`, `s`, `m`, `h`; no days |
| Retention period | `90d`, `2w`, `13m`, `7y` | Whole days, weeks, months of 30 days, or years of 365 days. Here `m` is months, never minutes. A Go duration such as `36h` is also accepted |
| Size | `25MB`, `256KB`, `1GB` | Binary units (`B`, `KB`, `MB`, `GB`, also `KiB`, `MiB`, `GiB`): 1MB is 1,048,576 bytes. A plain number is bytes |
| Rate limit | `60/minute/ip` | Count, window (`second`, `minute`, `hour`, `day`) and key |
| Cron schedule | `0 3 * * *` | Five fields: minute, hour, day of month, month, day of week. In UTC unless stated |
| Time of day | `03:30` | 24-hour `HH:MM` |
| Secret | `${VAR}` | A bare interpolation, never a literal. See [Configuration and secrets](/deploying/configuration-and-secrets) |

## engine [#engine]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `engine.version` | string | `"1.x"` | The engine major version the project targets, as `<major>.x`. A release binary from 1.0.0 on refuses a project whose major differs from its own |
| `engine.environment` | string | `development` | `development`, `staging` or `production`. Production enforces the rules in [Configuration and secrets](/deploying/configuration-and-secrets#what-production-refuses) |

## dev [#dev]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `dev.authoring` | boolean | `false` | Lets the authoring commands (`engine-dmo dev field add` and the rest, and `engine-dmo mcp` over standard input and output) run in `staging`. They always run in `development` and never in `production` |

## server [#server]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `server.listen` | string | `0.0.0.0:8080` | The `host:port` the public listener binds. A new project writes `${LISTEN_ADDR:-127.0.0.1:8080}` |
| `server.base_url` | string | Empty | The default site's public origin, such as `https://www.example.org`, for absolute URLs, sitemaps and hreflang. Required in production |
| `server.replicas` | integer | `1` | How many engine processes run against this database. With more than one, filesystem storage must be declared `shared` |
| `server.trusted_proxies` | list of strings | `[]` | IP addresses or CIDR ranges of the proxies and load balancers in front of the engine. Forwarded headers are believed only from these |
| `server.real_ip_header` | string | `X-Forwarded-For` | The header a trusted proxy puts the client address in. In production, a non-empty value with no `trusted_proxies` is an error; set `""` when nothing is in front |
| `server.read_timeout` | duration | `15s` | The longest the server waits to read a request |
| `server.write_timeout` | duration | `30s` | The longest a response may take to write |
| `server.shutdown_grace` | duration | `30s` | How long in-flight requests have to finish after a stop signal |
| `server.max_request_bytes` | size | `25MB` | The largest request body. A multipart upload may be up to `media.max_upload_bytes` plus 1MB |
| `server.compression` | list of strings | `[gzip]` | Response compression. Only `gzip` is built; `br` is accepted with a warning and ignored |
| `server.admin_host` | string | Empty | Where the admin lives: empty puts it on the default site's host; `*` on every site's host (a session per host); a host name such as `studio.example.org` on a host of its own (no scheme, no path) |
| `server.admin_path` | string | `/studio` | The admin's path. Must start with `/`. `/` needs an `admin_host` of its own; `/admin` is a warning |
| `server.portal_path` | string | `/members` | The member portal's path (`engine-dmo`) |
| `server.embed_path` | string | `/embed` | The path embeddable widgets are served under |
| `server.api.member.enabled` | boolean | `true` | Serve the member API the portal and member apps use (`engine-dmo`) |
| `server.api.content.enabled` | boolean | `false` | Serve the read-only content API a headless frontend reads |
| `server.api.content.public_reads` | boolean | `false` | Answer a published read that carries no API key, rate limited per address. Off, every request needs a key |
| `server.api.content.preview_ttl` | duration | `30m` | A headless preview token's life, at most `2h`; it also ends with the staff session it came from |
| `server.api.content.change_retention` | retention | `90d` | How far back the change feed reaches |
| `server.api.content.cache.s_maxage` | duration | `1m` | How long a shared cache may serve a published content API response |
| `server.api.content.cache.stale_while_revalidate` | duration | `10m` | How long past `s_maxage` a shared cache may serve it while fetching a fresh one |
| `server.api.content.cache.tag_header` | string | `Cache-Tag` | The header cache tags travel in: `Cache-Tag`, `Surrogate-Key`, or `none` |
| `server.security.signing_key` | secret | Empty | The install's master key: CSRF tokens, encryption of staff second-factor secrets at rest, hashed rate-limit keys and derived keys. At least 32 characters. Required in production; when it is empty outside production, a key is derived from the database URL, with a warning. Once the file names `${SIGNING_KEY}`, the variable must be set (empty is allowed outside production) for every command that loads the configuration. See [Setting them in development](/reference/environment-variables#setting-them-in-development) |
| `server.security.hsts.enabled` | boolean | `true` | Send `Strict-Transport-Security` |
| `server.security.hsts.max_age` | integer | `31536000` | Its `max-age`, in seconds |
| `server.security.hsts.include_subdomains` | boolean | `true` | Add `includeSubDomains` |
| `server.security.hsts.preload` | boolean | `false` | Add `preload` |
| `server.security.csp` | map | `{}` | The public sites' Content Security Policy: each key a directive with underscores for hyphens (`script_src`), each value a list of sources (or one string). Empty sources are dropped. `'unsafe-inline'` and `'unsafe-eval'` are refused in `script_src` and `default_src`. Empty sends no policy on public pages; the admin has its own fixed policy |
| `server.security.referrer_policy` | string | `strict-origin-when-cross-origin` | The `Referrer-Policy` header |
| `server.security.permissions_policy` | string | `geolocation=(self), camera=(), microphone=()` | The `Permissions-Policy` header |

```yaml
server:
  security:
    csp:
      default_src: ["'self'"]
      script_src: ["'self'"]
      style_src: ["'self'"]
      style_src_attr: ["'unsafe-inline'"]   # the dominant-colour image placeholders
      img_src: ["'self'", "data:"]
      connect_src: ["'self'"]
      object_src: ["'none'"]
      frame_ancestors: ["'self'"]
```

## database [#database]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `database.url` | secret | Required | The PostgreSQL connection string |
| `database.max_connections` | integer | `20` | The most connections one process holds. At least 1 |
| `database.min_connections` | integer | `2` | Connections kept open while idle. Not above `max_connections` |
| `database.max_conn_lifetime` | duration | `1h` | A connection is replaced after this long |
| `database.statement_timeout` | duration | `30s` | The session's `statement_timeout`. `0s` leaves the server's |

## migrate [#migrate]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `migrate.on_boot` | string | `refuse` | `refuse`: a pending migration stops the boot. `apply`: every boot applies pending migrations first |

## schema [#schema]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `schema.on_drift` | string | `refuse` | What the boot does when the configuration differs from the database: `refuse`, `apply` (approved destructive plans only) or `warn` (apply what is safe, start anyway). `warn` is refused in production |
| `schema.destructive_approval` | string | `config/schema/.destructive-approved` | The file, relative to the project, holding the digest of an approved destructive plan |

## template [#template]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `template.dir` | string | `templates` | The template directory, relative to the project |
| `template.contract` | integer | `1` | The template contract the templates are written against. `1` is the only one this engine supports |
| `template.strict` | boolean | `false` | An unknown variable path fails the page instead of rendering empty. `engine-dmo check` is always strict; `true` in production is a warning |
| `template.cache` | boolean | `true` | Keep compiled templates. `false` reads every template from disk at each render, for a host whose templates are edited in place |
| `template.error_template` | string | `errors/500.html` | The template for a server error page |
| `template.not_found_template` | string | `errors/404.html` | The template for a not-found page |

## public [#public]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `public.mounts` | list | `[]` | Directories outside `public/` served at a URL prefix on every site, after the site's own public files |
| `public.mounts[].path` | string | Required | The URL path prefix, such as `/video/` |
| `public.mounts[].dir` | string | Required | The directory, relative to the project |

## logging [#logging]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `logging.level` | string | `info` | `debug`, `info`, `warn` or `error` |
| `logging.format` | string | `json` | `json` or `text`. Lines go to standard error |
| `logging.redact_secrets` | boolean | `true` | Accepted. Secrets are redacted from printed configuration and stored errors whatever it says |

## cache [#cache]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `cache.max_entries` | integer | `10000` | The most entries in each process's in-memory cache (resolved lists, blocks and other derived data) |
| `cache.page_ttl` | duration | `5m` | How long a cached list or block lives. Above zero |
| `cache.invalidation_poll` | duration | `2s` | How often each process polls the database for invalidations, so a change reaches every replica |
| `cache.pages.enabled` | boolean | `false` | The page cache: whole public pages for anonymous visitors, served from memory |
| `cache.pages.fresh` | duration | `1m` | How long a cached page is served before it is rendered again; a publish ends it sooner |
| `cache.pages.stale` | duration | `24h` | How long past `fresh` a page is still served while one render replaces it |
| `cache.pages.max_memory` | size | `256MB` | The memory the page cache may hold, per process |
| `cache.pages.concurrency` | integer | `2` | Background renders at once. At least 1 |
| `cache.pages.warm.paths` | list of strings | `["/"]` | Paths each process renders into the cache at boot, on every site under its prefix. Each starts with `/` |
| `cache.pages.warm.top` | integer | `50` | Also warm each site's most visited pages of the last 30 days (the sitemap's first pages when there are no analytics) |
| `cache.pages.warm.deadline` | duration | `1m` | The longest the boot warm holds readiness back |

## storage [#storage]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `storage.driver` | string | `filesystem` | `filesystem` or `s3` |
| `storage.filesystem.root` | string | `./storage` | The directory, relative to the project or absolute. Must be writable |
| `storage.filesystem.shared` | boolean | `false` | The root is one filesystem every replica mounts. Required for `server.replicas` above 1 with this driver |
| `storage.s3.endpoint` | string | Empty | The service's base URL; empty for Amazon S3 |
| `storage.s3.region` | string | `eu-west-2` | Required with `s3`. `auto` for Cloudflare R2 |
| `storage.s3.bucket` | string | Empty | Required with `s3` |
| `storage.s3.access_key_id` | string | Empty | Required with `s3` |
| `storage.s3.secret_access_key` | secret | Empty | Required with `s3` |
| `storage.s3.path_style` | boolean | `false` | Path-style addressing, for MinIO and similar |
| `storage.s3.public_base_url` | string | Empty | The `https` origin of a CDN in front of `/media/`; media addresses are written on it |

[Storage and media](/deploying/storage-and-media) explains both drivers.

## jobs [#jobs]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `jobs.workers` | integer | `4` | The most jobs one process runs at once, across every queue. At least 1 |
| `jobs.queues.<queue>.workers` | integer | Unset | Caps one queue's jobs at once on each process. Not negative |

## telemetry [#telemetry]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `telemetry.metrics.enabled` | boolean | `true` | Serve Prometheus metrics on a listener of their own |
| `telemetry.metrics.bind` | string | `127.0.0.1:9090` | That listener's `host:port`. May not be `server.listen` |
| `telemetry.metrics.path` | string | `/_metrics` | Its path. Starts with `/` |
| `telemetry.metrics.export` | boolean | `false` | Also push the metrics to `telemetry.otlp` |
| `telemetry.metrics.interval` | duration | `1m` | How often they are pushed. At least `10s` |
| `telemetry.traces.enabled` | boolean | `false` | Export OpenTelemetry traces to `telemetry.otlp`. Needs `otlp.endpoint` |
| `telemetry.traces.sample_ratio` | number | `0.1` | The share of new traces recorded, 0 to 1 |
| `telemetry.traces.respect_parent_sampling` | boolean | `false` | Let an inbound `traceparent`'s sampled flag decide |
| `telemetry.otlp.endpoint` | string | Empty | The collector's OTLP/HTTP base URL; `/v1/traces` and `/v1/metrics` are appended. No query, fragment or credentials |
| `telemetry.otlp.headers` | map of strings | `{}` | Headers sent with every export. Every value is a secret. May not set `Content-Type`, `Content-Length` or `Host` |
| `telemetry.otlp.timeout` | duration | `10s` | Each export's timeout, at most `1m` |
| `telemetry.resource.service_name` | string | `meridian` | The `service.name` resource attribute. Not empty |
| `telemetry.resource.attributes` | map of strings | `{}` | More resource attributes, such as `deployment.environment`. Not `service.name` |
| `telemetry.errors.driver` | string | `none` | `none` or `sentry` |
| `telemetry.errors.dsn` | secret | Empty | The Sentry DSN, `https://<public key>@<host>/<project id>`. Required with `sentry` |
| `telemetry.errors.environment` | string | `engine.environment` | The environment reported with each event |
| `telemetry.errors.sample_rate` | number | `1` | The share of errors reported, above 0 and at most 1. A panic is always sent |

## i18n [#i18n]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `i18n.require_all` | boolean | Unset | How strictly `engine-dmo check` holds schema labels to the enabled locales. Unset: a label missing in the source locale is an error, in any other enabled locale a warning. `true`: missing in any enabled locale is an error. `false`: only the source locale is required |

## retention [#retention]

How long rows that carry personal data are kept after they stop being used. Each is a retention period of at least `1d`.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `retention.sessions` | retention | `90d` | Staff and member sessions, after expiry or revocation |
| `retention.login_tokens` | retention | `30d` | Sign-in, enrolment and magic-link tokens, after expiry or use |
| `retention.mail_events` | retention | `13m` | Mail delivery events, from the event. At least `mail.suppression.soft_bounce_window` |
| `retention.audit_log` | retention | `7y` | The audit log, from the entry. Under a year is a warning |
| `retention.ai_suggestions` | retention | `13m` | AI suggestions once decided, failed or answered |

## audit [#audit]

The audit log's [hash chain](/deploying/data-protection#the-audit-chain). Turn it on to make changes to the log detectable with `engine-dmo audit verify`.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `audit.hash_chain` | boolean | `false` | Chain every audit row to the one before it in its realm, under a per-realm lock that serialises the realm's writes. With it on, a daily `audit.anchor` task logs each realm's head |

## extensions [#extensions]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `extensions` | list of strings | `[]` | The extensions the engine loads at boot. A bare name (`vite`) is a first-party extension shipped beside the binary (`/app/extensions/vite.so` in the `-vips` image); a path, relative to the project, is your own `.so`. Only cgo builds load extensions; the pure Go image refuses with a message |

See [Extending](/extending) for building one.


# images.yaml (/reference/configuration/images)

Every key of config/images.yaml (breakpoints, image defaults and named transforms) and config/sites/<key>/images.yaml.

`config/images.yaml` holds the install's image breakpoints, defaults and named transforms. A site's `config/sites/<key>/images.yaml` adds transforms or replaces them by name. Image configuration is design, not deployment, so none of it is in `engine.yaml`.

```yaml
breakpoints:
  md: 48rem
  lg: 80rem
transforms:
  hero:
    aspect: "16:9"
    sizes: "100vw"
  card:
    aspect: "4:3"
    widths: [320, 480, 640, 960]
    sizes: "(min-width: md) 33vw, 100vw"
```

`engine-dmo media transforms` prints every resolved transform with its width ladder. See [Images](/templates/images).

## images.yaml [#imagesyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `breakpoints` | map of string | `{}` | Named min-widths as CSS lengths, such as `md: 48rem`, which `sizes` and `sources` name |
| `defaults.density` | integer | `2` | The highest pixel density a fixed-width transform serves |
| `defaults.formats` | list of avif, jpeg, png, webp | `[avif, webp, jpeg]` | The formats every transform generates unless it says otherwise |
| `defaults.placeholder` | blur, dominant, none | `dominant` | What paints an image's box before it loads: `dominant` (its dominant colour), `blur` or `none` |
| `defaults.quality` | map of integer | `{avif: 55, webp: 75, jpeg: 80}` | Quality per format |
| `defaults.widths` | object | `{min: 320, max: 2560, ratio: 1.25}` | The width range: each width is the previous times `ratio`, from `min` to `max` |
| `defaults.widths.max` | integer | `2560` | See `defaults.widths` |
| `defaults.widths.min` | integer | `320` | See `defaults.widths` |
| `defaults.widths.ratio` | number | `1.25` | See `defaults.widths` |
| `transforms` | map of objects | `{}` | Named transforms templates use, such as `hero` or `card` |
| `transforms.<key>.animated` | first, keep |  | For an animated source: `keep` the animation or take the `first` frame |
| `transforms.<key>.aspect` | string | The source's | The proportion, `width:height` such as `16:9` |
| `transforms.<key>.background` | string |  | The padding colour for `contain` |
| `transforms.<key>.fit` | contain, cover, inside | `cover` | `cover` crops to the box around the focal point; `contain` fits inside and pads with `background`; `inside` fits inside and keeps its own proportions |
| `transforms.<key>.formats` | list of avif, jpeg, png, webp | `defaults.formats` | The formats generated, best first: `avif`, `webp`, `jpeg`, `png` |
| `transforms.<key>.height` | integer |  | A fixed height in pixels |
| `transforms.<key>.quality` | map of integer | `defaults.quality` | Quality per format, such as `{ avif: 50 }` |
| `transforms.<key>.sizes` | string |  | The `sizes` attribute, using breakpoint names |
| `transforms.<key>.sources` | list of objects | `[]` | Art direction: another transform used below or from a breakpoint, in a `picture` |
| `transforms.<key>.sources[].below` | string |  | A breakpoint name: use `transform` below it |
| `transforms.<key>.sources[].from` | string |  | A breakpoint name: use `transform` from it up |
| `transforms.<key>.sources[].transform` | string | Required | The transform to use there |
| `transforms.<key>.width` | integer |  | A fixed display width in CSS pixels; served at each density up to `defaults.density` |
| `transforms.<key>.widths` | list of integer or object | `defaults.widths` | The widths generated: a list (`[480, 800, 1200]`) used as written, or a range `{ min, max, ratio }` whose missing keys come from the defaults. Each width 16 to 8192 |

## sites/&lt;key&gt;/images.yaml [#siteskeyimagesyaml]

The same `transforms` keys as above. A transform here with the same name as the install's replaces it on this site.


# Configuration (/reference/configuration)

Every configuration file a Meridian project can have, where it lives, what it holds and which page lists its keys, plus how files are loaded, checked, given ids and validated in an editor.

A project's configuration is YAML under `config/` (or the directory `--config` names). It is committed to git: secrets never appear in it, only `${VAR}` interpolations. Every file is checked as a whole, and every problem is reported together, each with its file, line and column, the source line and a caret.

```bash
engine-dmo check --no-db               # every file, with no database
engine-dmo config validate             # engine.yaml alone
engine-dmo config render               # engine.yaml resolved, defaults included, secrets redacted
engine-dmo config schema --file site   # one file's JSON Schema
```

## The files [#the-files]

| File | Holds | Reference |
|---|---|---|
| `engine.yaml` | The install: server, database, storage, mail, search, AI, telemetry and the rest. Required | [engine.yaml](/reference/configuration/engine) and the pages after it |
| `locales.yaml` | The install's locales and locale groups | [locales.yaml and strings](/reference/configuration/locales) |
| `strings/<locale>.yaml` | One locale's template strings | [locales.yaml and strings](/reference/configuration/locales) |
| `networks.yaml` | Sets of sites sharing organisations, people and partner accounts | [networks.yaml and memberships.yaml](/reference/configuration/networks-and-memberships) |
| `memberships.yaml` | Membership tiers, in rank order (`engine-dmo`) | [networks.yaml and memberships.yaml](/reference/configuration/networks-and-memberships) |
| `sites/<key>/site.yaml` | One site: name, hosts, locales, navigation, SEO, delivery | [site.yaml](/reference/configuration/site) |
| `sites/<key>/routes.yaml` | One site's routes, redirects, special pages and home page | [routes.yaml](/reference/configuration/routes) |
| `sites/<key>/endpoints.yaml` | One site's declared endpoints | [endpoints.yaml](/reference/configuration/endpoints) |
| `sites/<key>/plugins.yaml` | One site's process plugins (experimental) | [plugins.yaml](/reference/configuration/plugins) |
| `sites/<key>/promotions.yaml` | One site's promotion slots (`engine-dmo`) | [promotions.yaml](/reference/configuration/promotions) |
| `sites/<key>/portal.yaml` | One site's portal, screens and actions (`engine-dmo`) | [Portal files](/reference/configuration/portal) |
| `sites/<key>/images.yaml` | One site's image transforms | [images.yaml](/reference/configuration/images) |
| `sites/<key>/schema/<type>.yaml` | A type, or part of one, on that site only | [Schema files](/reference/configuration/schema) |
| `images.yaml` | Image breakpoints, defaults and named transforms | [images.yaml](/reference/configuration/images) |
| `schema/<type>.yaml` | A content type, or an extension of a core type | [Schema files](/reference/configuration/schema) |
| `schema/_shared.yaml` | Named field groups | [Schema files](/reference/configuration/schema) |
| `blocks/_index.yaml` | Shared block definitions | [Schema files](/reference/configuration/schema) |
| `crm/organisation.yaml`, `crm/person.yaml` | Custom fields on CRM records (`engine-dmo`) | [Schema files](/reference/configuration/schema) |
| `portal/enquiries.yaml` | Fields a partner keeps against an enquiry (`engine-dmo`) | [Schema files](/reference/configuration/schema) |
| `portal/portal.yaml` | The install's portal (`engine-dmo`) | [Portal files](/reference/configuration/portal) |
| `portal/roles.yaml` | Partner roles (`engine-dmo`) | [Portal files](/reference/configuration/portal) |
| `access/roles.yaml` | Staff roles | [access/roles.yaml and grants.yaml](/reference/configuration/access) |
| `access/grants.yaml` | Roles granted to staff groups under a scope | [access/roles.yaml and grants.yaml](/reference/configuration/access) |
| `analytics/reports.yaml` | Scheduled member and organisation reports | [analytics files](/reference/configuration/analytics) |
| `analytics/dashboards.yaml` | Organisation dashboards and entered figures | [analytics files](/reference/configuration/analytics) |
| `analytics/bots.txt` | Extra user-agent substrings analytics filters, one per line | [engine.yaml: analytics](/reference/configuration/engine-analytics-ai#analytics) |
| `accessibility.yaml` | The known accessibility issues register | [accessibility.yaml](/reference/configuration/accessibility) |
| `ai/prompts/<key>.yaml` | Overrides of the engine's AI prompts | [AI prompt overrides](/reference/configuration/ai-prompts) |
| `paidlistings.yaml` | The paid listings provider and prices (`engine-dmo`) | [paidlistings.yaml](/reference/configuration/paidlistings) |
| `search/synonyms.yaml` | Seed search synonyms | [Seed files](/reference/configuration/seed-files) |
| `tags/vocabulary.yaml` | The seed tag vocabulary | [Seed files](/reference/configuration/seed-files) |
| `tags/smartlists.yaml` | Seeded smart lists | [Seed files](/reference/configuration/seed-files) |

A new project from `engine-dmo init` has `engine.yaml`, `locales.yaml`, `access/grants.yaml` and one site's `site.yaml` and `routes.yaml`; every other file is optional. A file for a module the binary does not compile (such as `memberships.yaml` under `engine-cms`) is refused by the module's name.

## Stable ids [#stable-ids]

Elements that hold data (types, fields, groups, blocks, options, sites, locales, routes, endpoints, tiers, networks, screens, actions, roles, slots and landing families) carry an `id`, such as `fld_thsh2xa6nf`. The id is what stored data is keyed by, so renaming a handle keeps its data. Never write or change an id by hand:

```bash
engine-dmo check --fix --no-db    # writes every missing id in place, keeping comments, then checks
```

`check` without `--fix` reports a missing id as an error. The `engine-dmo dev` authoring verbs write ids as they add elements. See [Stable ids](/concepts/stable-ids).

## Shared value formats [#shared-value-formats]

| Format | Example |
|---|---|
| Text per locale | `label: { en-GB: Walk, fr-FR: Randonnée }`. The source locale is required; a missing locale falls back |
| Duration | `30s`, `15m`, `2h` |
| Retention period | `90d`, `2w`, `13m` (months), `7y` |
| Size | `25MB`, `256KB` |
| Tiers | A list of tier keys, or `{ min: <tier> }` for that tier and every tier above it |
| Secret | `${VAR}`: a bare interpolation, never a literal |

## Editor support [#editor-support]

`engine-dmo init` writes the JSON Schema of every file to `.meridian/schema/` and maps the file patterns to them in the project's VS Code and Zed settings. To refresh them after an engine upgrade:

```bash
engine-dmo config schema --write .meridian/schema --editors vscode,zed
```

Each schema is generated from the structures the loaders decode, so an editor's completion and validation match what `check` accepts.


# locales.yaml and strings (/reference/configuration/locales)

Every key of config/locales.yaml (the install's locales with their time zone, currency, fallbacks, direction, calendar and sorting) and of config/strings/<locale>.yaml.

`config/locales.yaml` declares every locale the install knows. Each site enables its own subset in its `site.yaml`. `config/strings/<locale>.yaml` holds the template string catalogue of one locale.

```yaml
locales:
  available:
    - code: en-GB
      label: English
      source: true
      default: true
      timezone: Europe/London
      currency: GBP
    - code: fr-FR
      label: Français
      fallback: [en-GB]
```

`engine-dmo dev locale add` declares a locale with its id and enables it on a site. See [Sites, locales and routes](/concepts/sites-locales-and-routes) and [Localisation](/content-modelling/localisation).

## locales.yaml [#localesyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `locales` | object |  | The install's locales and locale groups |
| `locales.available` | list of objects | Required | Every locale any site may enable, in order |
| `locales.available[].calendar` | buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-civil, islamic-rgsa, islamic-tbla, islamic-umalqura, iso8601, japanese, persian, roc | Derived from the region | The CLDR calendar dates are shown in |
| `locales.available[].code` | string | Required | The BCP 47 tag, such as `en-GB`, `fr-FR` or `zh-Hans`. It is the locale's handle in URLs, hreflang and every other file |
| `locales.available[].collation` | string | Derived from the tag | The ICU collation text is sorted with |
| `locales.available[].currency` | string | The source locale's | An ISO 4217 currency code, such as `GBP` |
| `locales.available[].default` | boolean | `false` | The install's default locale |
| `locales.available[].derived_from` | string |  | Another locale this one derives from. Must name a known locale |
| `locales.available[].direction` | ltr, rtl | Derived from the script | `ltr` or `rtl` |
| `locales.available[].fallback` | list of string | `[]` | Locales whose text shows, in order, where this one has none |
| `locales.available[].first_day_of_week` | integer | Derived from the region | 1 (Monday) to 7 (Sunday) |
| `locales.available[].fold_diacritics` | boolean | `true` | Search treats `é` as `e` |
| `locales.available[].hour_cycle` | h11, h12, h23, h24 | Derived from the region | `h23` or `h12` (also `h11`, `h24`) |
| `locales.available[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `locales.available[].label` | string |  | The name shown to staff and in a locale switcher, in its own language |
| `locales.available[].machine_translation` | assist, forbid |  | `assist` allows AI translation drafts for this locale; `forbid` never offers them |
| `locales.available[].numbering` | string | Derived from the locale | The CLDR numbering system, such as `latn` or `arab` |
| `locales.available[].slugs` | native, transliterate | Derived from the script | `transliterate` makes Latin-script slugs from other scripts; `native` keeps the script |
| `locales.available[].source` | boolean | `false` | The locale content is written in first. Exactly one; it must declare `timezone` and `currency` |
| `locales.available[].statutory` | boolean | `false` | A locale the law requires: publishing reports any statutory locale still waiting for its text |
| `locales.available[].timezone` | string | The source locale's | An IANA time zone, such as `Europe/London` |
| `locales.available[].translators` | string |  | Who translates this locale, shown in `engine-dmo locale list` |
| `locales.groups` | list of objects | `[]` | Sets of locales that share values of fields translated per group |
| `locales.groups[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `locales.groups[].key` | string | Required | The group's key |
| `locales.groups[].locales` | list of string | Required | The locale codes in the group |

## strings/&lt;locale&gt;.yaml [#stringslocaleyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `strings` | map | `{}` | The locale's template strings by key, nested maps allowed, read in templates with the translation function. A key missing in a locale falls back along the locale's fallbacks |


# networks.yaml and memberships.yaml (/reference/configuration/networks-and-memberships)

Every key of config/networks.yaml (sites sharing organisations, people and partner accounts) and config/memberships.yaml (the membership tiers, engine-dmo).

`config/networks.yaml` groups sites that share organisations, people and partner accounts. `config/memberships.yaml` (`engine-dmo`) lists the membership tiers organisations hold.

```yaml
networks:
  - key: county
    name: { en-GB: County network }
```

```yaml
tiers:
  - key: listed
    label: { en-GB: Listed }
  - key: partner
    label: { en-GB: Partner }
```

`engine-dmo dev network add` and `engine-dmo dev tier add` write these with their ids.

## networks.yaml [#networksyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `networks` | list of objects | `[]` | Sets of sites that share organisations, people and partner accounts. A site joins one with `site.network` |
| `networks[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `networks[].key` | string | Required | The network's key |
| `networks[].name` | map of string |  | Its name per locale |

## memberships.yaml [#membershipsyaml]

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

| Key | Type | Default | Meaning |
|---|---|---|---|
| `tiers` | list of objects | `[]` | The install's membership tiers, in rank order, lowest first. A rule written `{ min: <tier> }` means that tier and every tier above it |
| `tiers[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `tiers[].key` | string | Required | The tier's key, used in schema rules, reports, prices and the portal |
| `tiers[].label` | map of string |  | Its name per locale |

A site sells every tier unless its `site.yaml` lists `memberships.tiers`. Renewal reminders are in [engine.yaml: DMO modules](/reference/configuration/engine-dmo#membership).


# paidlistings.yaml (/reference/configuration/paidlistings)

Every key of config/paidlistings.yaml (engine-dmo), the paid listings payment provider (Stripe or none) with its secrets, and each site's tier prices and how promotions are paid.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

`config/paidlistings.yaml` sets how members pay: the payment provider, and per site the price of each membership tier on sale and whether promotion bookings are paid at checkout or invoiced. Without the file, there is no provider and orders are invoiced by staff.

```yaml
provider: stripe
stripe:
  secret_key: ${STRIPE_SECRET_KEY}
  webhook_secret: ${STRIPE_WEBHOOK_SECRET}
sites:
  main:
    promotions: checkout
    tiers:
      gold: { amount: "240.00", currency: GBP, months: 12 }
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `provider` | string | `none` | `stripe` (payment through Stripe Checkout) or `none` (orders are kept for staff to invoice) |
| `stripe.secret_key` | secret | Required with `stripe` | The Stripe secret key, as `${VAR}`. The variable is read at boot, so `engine-dmo check` needs no secret |
| `stripe.webhook_secret` | secret | Required with `stripe` | The signing secret of the Stripe webhook endpoint, as `${VAR}` |
| `stripe.api_base` | string | Stripe's API | Another base URL, `https` (or `http` on a loopback address, for a test double) |
| `sites.<site>.promotions` | string | `invoice` | `checkout` (a priced promotion request is paid in the portal; needs a provider) or `invoice` |
| `sites.<site>.tiers.<tier>.amount` | string | Required | The price as a quoted decimal, such as `"240.00"` |
| `sites.<site>.tiers.<tier>.currency` | string | The site's `default_currency` | ISO 4217 code |
| `sites.<site>.tiers.<tier>.months` | integer | `12` | The period the price buys, 1 to 36 |

A tier on sale must be declared in `memberships.yaml` and sold by the site (its `site.yaml` `memberships.tiers`). An unset Stripe variable stops the boot with a message naming it. See [Paid listings](/dmo/paid-listings).


# plugins.yaml (/reference/configuration/plugins)

Every key of config/sites/<key>/plugins.yaml: the process plugins an endpoint step calls, with their command, pinned digest, environment, granted handlers and containment.

`config/sites/<key>/plugins.yaml` declares process plugins: separate binaries the engine starts and calls from an endpoint's `plugin` step. The plugin protocol is version 0 and experimental. For extending the engine itself, see [Extending](/extending).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `plugins` | map of objects | `{}` | The site's plugins by key |
| `plugins.<key>.args` | list of string | `[]` | Arguments the binary is started with |
| `plugins.<key>.build` | string |  | The directory of the Go program `engine-dmo plugin build` compiles to `command` |
| `plugins.<key>.circuit_breaker.cooldown` | string |  | How long its steps fail at once before it is tried again |
| `plugins.<key>.circuit_breaker.failures` | integer |  | Failed calls within `window` that take the plugin out |
| `plugins.<key>.circuit_breaker.window` | string |  | The window failures are counted in |
| `plugins.<key>.command` | string | Required | The plugin binary, relative to the project or absolute |
| `plugins.<key>.concurrency` | integer |  | Calls in flight at once, 1 to 256 |
| `plugins.<key>.endpoints` | list of string | `[]` | The endpoint handlers granted: a `plugin` step may call only these, and the plugin must serve every one |
| `plugins.<key>.env` | map of string | `{}` | The environment the plugin gets. Nothing of the engine's own environment is passed; a credential-like name must be an interpolation |
| `plugins.<key>.memory` | string |  | The memory limit set on the process where the platform allows, such as `256MB` |
| `plugins.<key>.sha256` | string |  | The binary's SHA-256 in lower case hex; the engine refuses to start a binary whose digest differs |
| `plugins.<key>.timeout` | string |  | The time limit per call |


# Portal files (/reference/configuration/portal)

Every key of config/portal/portal.yaml (the member portal's install defaults, member report rules and invitation timings), config/sites/<key>/portal.yaml (a site's portal, screens and actions) and config/portal/roles.yaml (partner roles), all engine-dmo.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

The member portal is where the people behind partner businesses sign in to update their listings, see their report and manage their membership. Three files configure it. [Partners and the portal](/dmo/partners-and-portal) and [Portal screens and actions](/dmo/portal-screens-and-actions) explain the portal; this page lists every key.

## portal/portal.yaml [#portalportalyaml]

The install's portal. A `portal:` block in `engine.yaml` is still read, with a warning that it belongs here.

```yaml
portal:
  mode: both
  invitations:
    expiry: 30d
    reminder_after: 7d
  report:
    peer_comparison: true
    peer_min_cohort: 5
```

A project on `engine-dmo` has the portal on by default (`engine-dmo describe project` shows `portal /members, both`). A site with no partner businesses turns it off with one file:

```yaml
# config/portal/portal.yaml
portal:
  mode: "off"
```

Quote `"off"`, or YAML may read it as a boolean in other tools; the engine accepts either.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `portal.mode` | string | `both` | `templated` (the engine renders the portal through your templates), `api` (the member API only, for an app of your own), `both`, or `off` |
| `portal.templated.enabled` | boolean | `true` | Serve the templated portal |
| `portal.templated.template_dir` | string | `portal` | The portal's template directory in each template root |
| `portal.templated.routes` | map of strings | `{}` | A screen's path under `server.portal_path`, by screen key; a screen left out keeps its default path |
| `portal.invitations.expiry` | retention | `30d` | How long an invitation works. Whole days |
| `portal.invitations.reminder_after` | retention | `7d` | When an unanswered invitation is chased. Whole days, before the expiry |
| `portal.report.peer_comparison` | boolean | `true` | Compare a member's figures with similar businesses |
| `portal.report.peer_min_cohort` | integer | `5` | The fewest peers a comparison needs; below it the comparison is left out |
| `portal.report.improvement_prompts.enabled` | boolean | `true` | Show "make your listing work harder" prompts in the report |
| `portal.report.improvement_prompts.min_impressions` | integer | `100` | Impressions a listing needs before prompts are shown |
| `portal.report.improvement_prompts.uplift_min_cohort` | integer | `20` | The fewest listings an uplift claim is computed from |
| `portal.report.improvement_prompts.uplift_min_percent` | integer | `10` | The smallest uplift worth quoting |
| `portal.report.improvement_prompts.max_shown` | integer | `4` | The most prompts shown at once |
| `portal.report.improvement_prompts.filter_min_searches` | integer | `50` | Searches the window must hold before a filter's share is quoted as evidence |
| `portal.report.improvement_prompts.rules` | map | See below | The thresholds each prompt uses |
| `portal.report.email_digest.enabled` | boolean | `true` | Email members their monthly report |
| `portal.report.email_digest.report` | string | `member-monthly` | The report (from `analytics/reports.yaml`) the digest sends |
| `portal.report.email_digest.skip_when_no_data` | boolean | `true` | Send nothing for a period with no data |

The default `rules`:

```yaml
rules:
  accessibility: { required: true }
  booking_link: {}
  description_words: { min: 150 }
  opening_hours: { filter: open_now, required: true }
  photos: { min: 4, target: 8 }
  stale_after: 180d
  summary_words: { min: 40 }
  website: { required: true }
  zero_result_terms: { min_searches: 10, radius_km: 10 }
```

## sites/&lt;key&gt;/portal.yaml [#siteskeyportalyaml]

One site's portal, over the install's: its mode and path, the reference screens it hides, and its own screens and actions.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `mode` | string | `portal.mode` | `templated`, `api`, `both` or `off` for this site |
| `path` | string | `server.portal_path` | The portal's path on this site |
| `template_dir` | string | `portal.templated.template_dir` | The portal template directory for this site |
| `routes` | map of strings | | Screen paths for this site, by screen key |
| `hide` | list of strings | `[]` | Reference screens this site does not offer: `contact_details`, `contact_team`, `enquiries`, `events`, `hours`, `listing_edit`, `membership`, `people`, `photos`, `promotions`, `report` |
| `screens` | list | `[]` | The site's own screens |
| `screens[].key` | string | Required | The screen's key. A reference screen's key replaces that screen's template and takes only `template` |
| `screens[].id` | string | Written for you | Its stable id |
| `screens[].path` | string | `/organisations/{org}/<key>` | Its path under the portal path, with `{org}`, `{id}` or neither |
| `screens[].template` | string | `<key>.html` | Its template in the portal template directory |
| `screens[].title` | map of strings | | Its title per locale |
| `screens[].nav` | any | | Where it appears in the portal navigation |
| `screens[].can` | string | `screen.<key>` | The partner permission it needs |
| `screens[].tiers` | any | Every tier | The tiers whose organisations see it: a list or `{ min: <tier> }` |
| `screens[].data` | map | | Declared data the screen reads, scoped to the partner's organisation: each a name and a source (`documents`, `document`, `published`, `report`, `enquiries`, `pending`, `people`, `membership`, `organisation`, `promotions`, `first_session`) with its parameters |
| `actions` | list | `[]` | Forms the portal posts to, at `<portal path>/actions/<key>` |
| `actions[].key` | string | Required | `<subject>.<verb>`, such as `listing.update_offer` |
| `actions[].id` | string | Written for you | Its stable id |
| `actions[].label` | map of strings | The key | How a screen lists it |
| `actions[].target` | any | Required | What it writes: a document of the organisation, the organisation's custom fields, or the signed-in person's |
| `actions[].fields` | list of strings | | The fields it may write |
| `actions[].can` | string | `action.<key>` | The partner permission it needs |
| `actions[].tiers` | any | Every tier | The tiers whose organisations may use it |
| `actions[].approval` | string | | For a document target: `tier` (the tier's `member_editable` rule decides) or `required` (every change waits for staff) |
| `actions[].input`, `validation`, `steps`, `respond`, `rate_limit` | any | | As in an endpoint (see [endpoints.yaml](/reference/configuration/endpoints)) |

`engine-dmo dev portal screen add` and `dev portal action add` declare these with their ids. `engine-dmo portal check` checks the portal templates against the portal's context, and `portal scaffold` copies the reference portal into the project to restyle.

## portal/roles.yaml [#portalrolesyaml]

Partner roles: what a person can do for an organisation in the portal. The built-in `owner`, `manager`, `contact` and `billing` may be restated with new grants.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `roles[].key` | string | Required | The role's key; a built-in key restates that role |
| `roles[].id` | string | Written for you | Its stable id |
| `roles[].label` | map of strings | | Its name per locale |
| `roles[].can` | list of strings | | The partner permissions it grants, including `screen.<key>` and `action.<key>` permissions the sites declare |

`engine-dmo dev role add` declares one with its id.


# promotions.yaml (/reference/configuration/promotions)

Every key of config/sites/<key>/promotions.yaml (engine-dmo): paid promotion slots with their types, capacity, booking length, lead time, eligible tiers and prices, and the promoted label.

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

`config/sites/<key>/promotions.yaml` declares the paid promotion slots on a site and the label every promoted placement carries.

```yaml
label: { en-GB: Promoted }
slots:
  - key: home-feature
    name: { en-GB: Home page feature }
    types: [event, listing]
    capacity: 2
    days: { min: 7, max: 28 }
    lead_time: 3d
    tiers: { min: silver }
    price: { amount: "90.00", currency: GBP, per: week }
```

`engine-dmo dev slot add` declares a slot with its id. See [Promotions](/dmo/promotions).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `label` | map of string | Required | The label every promoted placement shows, per locale, such as `Promoted` |
| `slots` | list of objects | `[]` | Places on the site a promotion can appear |
| `slots[].capacity` | integer |  | How many promotions it shows at once |
| `slots[].days` | object |  | The shortest and longest booking, `{ min, max }`, in days |
| `slots[].days.max` | integer |  | See the row above |
| `slots[].days.min` | integer |  | See the row above |
| `slots[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `slots[].key` | string | Required | The slot's key, which templates name |
| `slots[].landings` | list of string |  | With `scope: landing`, the landing families it appears on |
| `slots[].lead_time` | string |  | How far ahead a booking must start, such as `3d` |
| `slots[].name` | map of string |  | Its name per locale, shown to staff and members |
| `slots[].price` | object |  | The price: `amount` (a quoted decimal), `currency` and `per` (`day`, `week` or `placement`) |
| `slots[].price.amount` | any |  | See the row above |
| `slots[].price.currency` | string | The site's currency | See the row above |
| `slots[].price.per` | day, placement, week |  | See the row above |
| `slots[].prices` | list of objects | `[]` | Prices that differ by landing place or category, each with `amount`, `places` and `categories` |
| `slots[].prices[].amount` | any |  | See the row above |
| `slots[].prices[].categories` | list of string |  | See the row above |
| `slots[].prices[].places` | list of string |  | See the row above |
| `slots[].scope` | landing, site | `site` | `site` (one slot for the site) or `landing` (a slot on each landing page) |
| `slots[].tiers` | any | Every tier | The membership tiers that may book it: a list of keys, or `{ min: <tier> }` |
| `slots[].types` | list of string | Required | The content types it can promote |


# routes.yaml (/reference/configuration/routes)

Every key of config/sites/<key>/routes.yaml: routes with their URI patterns per locale, index pages, nesting, pagination, facets, feeds, calendars and landing pages, the home page, configuration redirects and special pages.

`config/sites/<key>/routes.yaml` maps the site's content types to URLs, declares its home page, configuration redirects and special pages.

```yaml
home: { type: page, slug: home }
routes:
  - type: article
    uri: "/stories/{slug}"
    index: "/stories"
    paginate: 12
    facets: [theme]
    feed: { summary: standfirst }
  - type: page
    uri: "/{slug}"
    priority: 100
    nest: true
redirects:
  - { from: "/news/*", to: "/stories/{1}", status: 301 }
special:
  search: "/search"
```

`engine-dmo dev route add` routes a type with its id, and `engine-dmo describe route <path>` says which route answers a path. Redirects edited by staff live in the database and are managed with `engine-dmo redirects`. See [Sites, locales and routes](/concepts/sites-locales-and-routes) and [Redirects and URLs](/features/redirects-and-urls).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `home` | object |  | The home page: a `type` and a `slug`, or a singleton type alone |
| `home.slug` | string |  | Its slug; omitted for a singleton type |
| `home.type` | string | Required | The type of the home page's document |
| `redirects` | list of objects | `[]` | Redirects held in configuration. A `*` in `from` is captured as `{1}` |
| `redirects[].from` | string | Required | The path or pattern |
| `redirects[].locale` | string |  | Applies in one locale only |
| `redirects[].status` | integer | `301` | `301`, `302`, `307`, `308` or `410` |
| `redirects[].to` | string |  | The target; omit with status 410 |
| `routes` | list of objects | `[]` | The site's routes, one per routed type |
| `routes[].calendar` | object |  | An iCalendar feed of the route's events |
| `routes[].calendar.days` | integer |  | How many days ahead the calendar covers |
| `routes[].calendar.description` | string |  | The field used as each event's description |
| `routes[].calendar.field` | string |  | The occurrence field the calendar reads |
| `routes[].calendar.geo` | string |  | The field used as each event's coordinates |
| `routes[].calendar.limit` | integer |  | The most events in the calendar |
| `routes[].calendar.path` | map of string | The index path plus a tail | The calendar's path, one string or per locale |
| `routes[].calendar.place` | string |  | The field used as each event's location |
| `routes[].calendar.title` | map of string |  | The calendar title per locale |
| `routes[].facets` | list of string | `[]` | The fields an index page can be filtered by |
| `routes[].feed` | object |  | A syndication feed of the route's entries |
| `routes[].feed.body` | string |  | The field the full content is read from, with `content: full` |
| `routes[].feed.content` | string | `summary` | `summary` (items carry their summary) or `full` (items carry the body as HTML too) |
| `routes[].feed.formats` | list of string | `[rss, atom, json]` | The formats served: `rss`, `atom`, `json`. The path serves `.xml`, `.atom` and `.json` |
| `routes[].feed.limit` | integer | `20` | The most entries in the feed, 1 to 100 |
| `routes[].feed.path` | map of string | The index path plus a tail | The feed's path, one string or per locale |
| `routes[].feed.summary` | string | The type's summary field | The text field each item's summary is read from |
| `routes[].feed.title` | map of string | The site name and the type's plural | The feed title per locale |
| `routes[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `routes[].index` | any |  | The index (listing) page's path, one string or a map per locale |
| `routes[].landings` | list of objects | `[]` | Generated landing pages under the route (`engine-dmo`): one per place, category or month combination with enough results |
| `routes[].landings[].category` | string |  | The field giving the category |
| `routes[].landings[].content` | string |  | A content type whose document, matched to a landing, adds editorial text |
| `routes[].landings[].description` | any |  | The meta description pattern per locale, with `{count}`, `{examples}` and the rest |
| `routes[].landings[].id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `routes[].landings[].key` | string | Required | The landing family's key |
| `routes[].landings[].min_results` | integer |  | The fewest results a landing page needs to exist |
| `routes[].landings[].month` | string |  | The occurrence field giving the month, for events |
| `routes[].landings[].place` | string |  | The relation field giving the place |
| `routes[].landings[].slugs` | map of any |  | Per category value, its slug per locale |
| `routes[].landings[].title` | any |  | The title pattern per locale, with `{place}`, `{category}`, `{month}` |
| `routes[].landings[].uri` | any | Required | The landing path under the index, with `{place}`, `{category}` or `{month}` |
| `routes[].nest` | boolean | `false` | Entries nest under their parent entry's path |
| `routes[].paginate` | integer |  | Entries per index page |
| `routes[].parent` | object |  | Builds the entry path from a related document: `relation` (the relation field) and `uri` (the pattern) |
| `routes[].parent.relation` | string | Required | The relation field naming the parent document |
| `routes[].parent.uri` | any | Required | The pattern, such as `/{category}/{slug}` |
| `routes[].priority` | integer | `0` | Orders two patterns of one shape, lowest first, and settles `check`'s ambiguity error. A document is found by its stored address, so both routes keep answering for their own documents |
| `routes[].type` | string | Required | The content type the route serves |
| `routes[].uri` | any | Required | The entry URL pattern, one string or a map per locale, with placeholders such as `{slug}` |
| `special` | map of any |  | The paths of the engine's special pages, such as `search: /search` and `sitemap: /sitemap.xml`, one string or per locale |


# Schema files (/reference/configuration/schema)

Every key of a content type file (config/schema/<type>.yaml), of a field definition, and of the shared field groups (schema/_shared.yaml), shared blocks (blocks/_index.yaml) and CRM and enquiry custom field files that use the same field grammar.

Content types are YAML files under `config/schema/`, one type per file (a type may also be split across several files, and a site may add its own under `config/sites/<key>/schema/`). Every place that declares fields uses the same field grammar: types, shared field groups, blocks, and the CRM's custom fields. [Content modelling](/content-modelling) explains types and fields; this page lists every key.

```yaml
key: walk
label: { en-GB: Walk }
plural: { en-GB: Walks }
icon: footprints
searchable: true
fields:
  - name: title
    type: text
    required: true
  - name: slug
    type: slug
    required: true
  - name: distance
    type: number
    index: true
  - name: route
    type: geo
  - use: contact
groups:
  - key: details
    label: { en-GB: Details }
    fields: [distance, route]
```

Every type, field, group and block carries a stable `id`. Leave it out when you write the file and run `engine-dmo check --fix`, which writes each missing id in place and keeps your comments; `check` without `--fix` reports a missing id as an error. `engine-dmo dev type add`, `dev field add`, `dev field set`, `dev field rename` and `dev group add` change these files safely and write ids; `engine-dmo describe type <key>` shows a type as the engine resolved it; `engine-dmo describe fieldtypes` lists every field type with its parameters.

## The type file [#the-type-file]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `key` | string | Required | The type's key. Lower case; used in routes, templates and the API |
| `id` | string | Written for you | The type's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `extends` | string | | Instead of `key`: a core type (`page`, `article`, `event`, `guide`, `collection`, and in `engine-dmo` `listing` and `area`) this file adds fields to |
| `label` | map of strings | | The type's name per locale |
| `plural` | map of strings | | Its plural per locale |
| `icon` | string | | The admin icon name |
| `localisable` | boolean | `true` | Documents of this type have per-locale versions |
| `singleton` | boolean | `false` | The type has one document per site, such as site settings |
| `searchable` | boolean | `false` | Published documents are indexed for site search |
| `template` | string | `<type>/entry.html` | The template an entry renders with |
| `uri` | string or map | | A URI pattern the type carries itself, where it is not routed in `routes.yaml` |
| `sites` | list of strings | Every site | The sites the type is offered on |
| `ordering.field` | string | | The field index pages order by |
| `ordering.direction` | string | | `asc` or `desc` |
| `fields` | list | Required | The fields, in editor order (below) |
| `groups` | list | `[]` | Tabs or sections of the editor: `key`, `label`, the `fields` they hold and `collapsed` |
| `validation` | list | `[]` | Cross-field rules: `rule` (an expression), `message` per locale, `fields` the message shows against, `severity` (`error` or `warning`) and `on` (`save` or `publish`) |
| `member_editable` | object | | Which fields members may edit in the portal, by tier, and whether their changes need review (`engine-dmo`) |
| `structured_data` | map | | The schema.org type and property mapping for the type's JSON-LD |
| `embed` | any | | How the type is offered to embeddable widgets |
| `revisions` | any | `content.revisions` | The type's revision retention, overriding the install's key by key |
| `variants.default` | string | | The default entry variant |
| `variants.options` | list | | Entry variants: alternative editor and template layouts of the same type |

## A field [#a-field]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `name` | string | Required | The field's handle, used in templates and the API. Unique in its type |
| `id` | string | Written for you | The field's stable id, which keeps its values through a rename |
| `type` | string | Required | The field type: `address`, `asset`, `blocks`, `boolean`, `date`, `datetime`, `form`, `geo`, `geo_shape`, `link`, `money`, `number`, `opening_hours`, `phone`, `portable_text`, `recurrence`, `relation`, `repeater`, `select`, `seo`, `slug`, `text` or `video` |
| `use` | string | | Instead of `name` and `type`: include a field group from `_shared.yaml` |
| `aliases` | list of strings | `[]` | Old handles still answered after a rename. `engine-dmo schema alias` lists and retires them |
| `label` | map of strings | | The label per locale |
| `help` | map of strings | | Help text per locale |
| `required` | boolean | `false` | A value is needed to publish |
| `required_in` | string or list | `source` | Where `required` applies: `source`, `all`, or a list of locale codes |
| `required_when` | string | | An expression under which the field is required |
| `visible_when` | string | | An expression under which the editor shows the field |
| `recommended` | boolean | `false` | The editor flags an empty value without blocking publishing |
| `index` | boolean | `false` | Projected for listing, filtering and sorting |
| `unique` | boolean | `false` | No two documents of the type share a value |
| `protected` | boolean | `false` | Any change to the field's definition is a destructive schema change needing approval |
| `default` | any | | The value a new document starts with |
| `translate` | string | The field type's default (`text` and `link` are `locale`; `number`, `geo` and `phone` are `none`) | How values vary by locale: `locale` (each locale its own), `language` (shared across locales of one language), `group` (shared within a locale group) or `none` (one value for all) |
| `translatable` | boolean | | Shorthand: `true` is `translate: locale`, `false` is `translate: none` |
| `structure` | string | | For a container field: `shared` (one structure, per-locale text inside) or `per_locale` |
| `fallback` | string | | What shows where a locale has no value: `inherit` (the fallback locale's) or `empty` |
| `machine_translate` | string | `allow` | `allow` or `forbid` AI translation drafts for this field |
| `summary_of` | string | | The field this text field summarises, which offers AI summarisation |
| `site_overridable` | boolean | `false` | A site may set its own value of a shared document's field |
| `personal` | boolean | `false` | CRM person fields only: personal data, included in a subject access export and cleared by an erasure |
| `fields` | list | | Child fields, for a `repeater` |
| `blocks` | list | | The blocks a `blocks` field offers: each `key`, `label`, `description`, `item_label` and `fields`, or `use` of a shared block |
| `options` | list | | A `select` field's options: strings, or objects with their own ids |
| Any other key | | | A parameter of the field's type, such as `max`, `multiline`, `to` or `accept`, checked against that type's parameters |

The parameters of the asset, link and video types (`accept`, `alt`, `aspect`, `caption`, `focal`, `min_width`, `max_size`, `orientation`, `upload`, `upload_tags`, `tags`, `kinds`, `attributes`, `rel`, `styles`, `text`, `sources`, `hosts`, `poster`, `captions`, `transcript`) are listed with their field types in [Fields](/content-modelling/fields).

## schema/_shared.yaml [#schema_sharedyaml]

Named field groups any field list includes with `- use: <group>`.

```yaml
field_groups:
  contact:
    - name: phone
      type: phone
    - name: website
      type: link
```

| Key | Type | Meaning |
|---|---|---|
| `field_groups.<group>` | list of fields | The group's fields, with the field keys above |

## blocks/_index.yaml [#blocks_indexyaml]

Shared block definitions a `blocks` field includes with `- use: <block>`.

| Key | Type | Meaning |
|---|---|---|
| `blocks[].key` | string | The block's key; its template is `blocks/<key>.html` |
| `blocks[].id` | string | Its stable id, written for you |
| `blocks[].label` | map of strings | Its name per locale |
| `blocks[].description` | map of strings | What it is for, per locale |
| `blocks[].item_label` | string | The field whose value labels an item in the editor |
| `blocks[].fields` | list of fields | Its fields |

## crm/organisation.yaml, crm/person.yaml and portal/enquiries.yaml [#crmorganisationyaml-crmpersonyaml-and-portalenquiriesyaml]

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

Custom fields on CRM organisations and people, and the fields a partner keeps against an enquiry in the portal. Each file has one key, `fields`, a list of field definitions with the keys above, limited to the field types the CRM supports; `engine-dmo check` names the allowed types if you use another. `engine-dmo dev field add organisation <name>` adds one with its id.

| Key | Type | Meaning |
|---|---|---|
| `fields` | list of fields | The custom fields |


# Seed files (/reference/configuration/seed-files)

Every key of config/search/synonyms.yaml, config/tags/vocabulary.yaml and config/tags/smartlists.yaml, the files commands import into the database, and of the seed/organisations and seed/people records.

The first three files below seed data the database then owns. Each is read by a command, never reconciled at boot; after that, staff edit the data in the admin. `engine-dmo seed apply` also reads all three when they exist.

| File | Read by | Holds |
|---|---|---|
| `config/search/synonyms.yaml` | `engine-dmo search synonyms import` | Search synonyms. Rules already held are left alone |
| `config/tags/vocabulary.yaml` | `engine-dmo tags import` | The tag vocabulary. Existing keys are left alone. `engine-dmo tags export` writes the live vocabulary back |
| `config/tags/smartlists.yaml` | `engine-dmo seed apply` | Smart lists. `engine-dmo check` and `engine-dmo lists check` validate them against the schema and the vocabulary |

## search/synonyms.yaml [#searchsynonymsyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `synonyms` | list of objects | `[]` | Search synonym rules |
| `synonyms[].from` | string |  | A one-way rule: this word also finds `terms` |
| `synonyms[].locale` | string | Every locale | The locale it applies in |
| `synonyms[].sites` | list of string | Every site | The sites it applies on |
| `synonyms[].terms` | list of string | Required | Words that mean the same; with `from`, what it expands to |

## tags/vocabulary.yaml [#tagsvocabularyyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `tags` | list of objects | `[]` | The tag tree |
| `tags[].children` | list of objects | `[]` | Child tags, with the same keys, to any depth. Each child's `key` is the full dotted key under its parent (`stay.hotel` under `stay`) |
| `tags[].colour` | string |  | Its colour in the admin |
| `tags[].key` | string | Required | The tag's key |
| `tags[].kind` | string | `topic`; a child takes its parent's | `topic`, `audience`, `operational` or `internal` |
| `tags[].label` | map of string |  | Its label per locale |
| `tags[].public` | boolean | `true`; a child takes its parent's | Listed to the public, in the content API's tag list |

## tags/smartlists.yaml [#tagssmartlistsyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `smart_lists` | list of objects | `[]` | Seeded smart lists: saved queries over content or the CRM |
| `smart_lists[].key` | string | Required | The list's key |
| `smart_lists[].limit` | integer |  | The most rows |
| `smart_lists[].name` | map of string |  | Its name per locale |
| `smart_lists[].public` | boolean |  | Templates may read it |
| `smart_lists[].query` | map of any | Required | The query, by field |
| `smart_lists[].site` | string |  | The site it belongs to |
| `smart_lists[].sort` | object |  | Its order |
| `smart_lists[].sort.direction` | string |  | `asc` or `desc` |
| `smart_lists[].sort.field` | string |  | The field it sorts by |
| `smart_lists[].subject` | string | Required | What it lists |

## seed/organisations and seed/people [#seedorganisations-and-seedpeople]

`engine-dmo`: one YAML file per record, under `seed/`, read by `engine-dmo seed apply`. [Organisations and people](/content-modelling/seeding-and-importing#organisations-and-people) has an example of each.

### organisations/\<key\>.yaml [#organisationskeyyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `key` | string | The file name | The key a document's `organisation:` names |
| `name` | string | Required | The organisation's name |
| `legal_name` | string |  | Its legal name |
| `status` | string | `active` | `prospect`, `active`, `lapsed` or `archived` |
| `email`, `website` | string |  | Its own address and website |
| `phone`, `address` | map of any |  | Stored as given |
| `custom` | map of any |  | The fields of `config/crm/organisation.yaml`, by handle |
| `tags` | list of string |  | Vocabulary tag keys |
| `network` | string | The first membership's site's, else the default site's | The network's key |
| `trash` | boolean | `false` | Puts it in the trash once everything else is done |
| `contacts[].person` | string |  | A `people/` key or a contact's email. Each contact needs this or `name` |
| `contacts[].name`, `.email`, `.phone`, `.custom` | |  | The details of a person created for this contact |
| `contacts[].role` | string |  | The job title, free text |
| `contacts[].partner_role` | string | `contact` | The partner role's key |
| `contacts[].is_primary` | boolean | `false` | The primary contact |
| `contacts[].started_on`, `.ended_on` | date |  | `ended_on` makes a former contact |
| `memberships[].site` | string | The default site | The site's key |
| `memberships[].tier` | string |  | The tier's key |
| `memberships[].status` | string | `active` | `pending`, `active`, `lapsed` or `cancelled` |
| `memberships[].joined_on`, `.renews_on`, `.ended_on` | date |  | Its dates |
| `memberships[].amount`, `.currency`, `.external_ref`, `.notes` | string |  | The fee, its currency, your reference and staff notes |
| `memberships[].history[]` | list of objects |  | Later changes in order: `tier`, `status`, `renews_on`, `ended_on`, `amount`, `reason` |
| `invitations[].email`, `.name`, `.role`, `.partner_role` | string |  | Who is invited |
| `invitations[].site` | string | The default site | The site |
| `invitations[].by` | string | Required | A `people/` key or contact's email, holding `people.invite` |
| `invitations[].accepted` | boolean | `false` | Accept it at once |

### people/\<key\>.yaml [#peoplekeyyaml]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `key` | string | The file name | The key a contact's `person:` names |
| `name` | string | `given_name` and `family_name` | The display name |
| `given_name`, `family_name` | string |  | The parts of the name |
| `email` | string |  | Their address |
| `phone`, `custom` | map of any |  | Their phone, and the fields of `config/crm/person.yaml` by handle |
| `marketing_consent` | date |  | When they consented to marketing |
| `network` | string | The default site's | The network's key |
| `tags` | list of string |  | Vocabulary tag keys |
| `trash` | boolean | `false` | Puts them in the trash once everything else is done |


# site.yaml (/reference/configuration/site)

Every key of config/sites/<key>/site.yaml: the site name, hosts, country, time zone, locales and URL strategy, navigation slots, template roots, SEO and robots, accessibility statement, widgets, headless delivery, assets, mail sender and outbound links.

Each directory under `config/sites/` is a site, named by its key (lower case letters, digits and hyphens). Its `site.yaml` holds the site's identity, hosts, locales, navigation slots, SEO and delivery; its `routes.yaml` holds the URLs. A site may also have `endpoints.yaml`, `images.yaml`, `plugins.yaml`, `promotions.yaml`, `portal.yaml` and its own `schema/`.

```yaml
site:
  name: { en-GB: Wyndmouth }
  timezone: Europe/London
  country: GB
  default_currency: GBP
  domains: [www.wyndmouth.example]
  default: true

templates:
  roots: [wyndmouth, _shared]

locales:
  strategy: prefix
  enabled: [en-GB, fr-FR]
  default: en-GB

seo:
  title_template: "{{ title }} | {{ site.name }}"
  sitemap: { enabled: true }
  robots: { enabled: true, disallow: ["/studio"] }
```

`engine-dmo dev site add` writes a new site's directory with its id. See [Sites, locales and routes](/concepts/sites-locales-and-routes).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `accessibility.alt_fallback` | string | `warn` | What publishing does when an image's alt text would show from a fallback locale: `allow`, `warn` or `block` |
| `accessibility.alt_fallback_locales` | map of string |  | Per locale, the policy for alt text shown from a fallback locale |
| `accessibility.conformance` | string |  | The standard claimed, such as `WCAG 2.2 AA` |
| `accessibility.contact_email` | string |  | Where accessibility problems are reported |
| `accessibility.last_reviewed` | string |  | When the statement was last reviewed |
| `accessibility.statement_path` | string |  | The path of the site's accessibility statement |
| `assets.budgets` | map of string |  | Size budgets by kind (`css`, `js`, `legacy_css`, `legacy_js`), each the total across the site's bundles, such as `120KB` |
| `assets.bundles` | map of string | `main: src/entries/<site>.js` | The site's entries by bundle name, each a path relative to the project. Another name defaults to `src/entries/<site>-<name>.js` |
| `assets.external` | boolean | `false` | The site is built by a toolchain of its own: the Vite integration builds no entry for it and the asset helpers read `assets.manifest` |
| `assets.manifest` | string | `public/build/.vite/manifest.json` | A Vite manifest, relative to the project, for an external site |
| `delivery.frontend.origin` | string |  | For a headless site, the frontend's origin; every canonical and absolute URL is built on it. `https` in production |
| `delivery.frontend.preview_url` | string |  | The frontend's preview route, with `{token}`, and optionally `{path}`, `{document}` and `{locale}`. `https` in production |
| `delivery.frontend.webhooks` | list of objects | `[]` | Receivers told what changed, so the frontend can revalidate |
| `delivery.frontend.webhooks[].events` | list of string | Every event | The change events to send |
| `delivery.frontend.webhooks[].secret` | string | Required | A secret of at least 16 characters, as `${VAR}`, the deliveries are signed with |
| `delivery.frontend.webhooks[].url` | string | Required | The frontend's revalidation route; `https` in production |
| `delivery.mode` | string | `rendered` | `rendered` (the engine renders pages) or `headless` (a separate frontend reads the content API) |
| `embed.enabled` | boolean | `false` | Serve the embeddable widgets under `server.embed_path` |
| `embed.map.attribution` | string |  | The tile credit. Required with `tiles` |
| `embed.map.max_zoom` | integer | `16` | The map widget's highest zoom |
| `embed.map.tiles` | string |  | A tile URL template for the map widget, such as `https://tiles.example.org/{z}/{x}/{y}.png`. Without it the map is drawn from its markers alone |
| `embed.max_items` | integer |  | Caps every list widget, whatever a caller asks for |
| `embed.only` | boolean | `false` | Embed-only mode: every page the site serves carries `noindex`, because the content ranks on the website that embeds it |
| `embed.origins` | list of string | `[]` | The origins allowed to embed the widgets by script tag or frame |
| `embed.theme` | map of string | `{}` | CSS custom properties the widget shell sets, so a widget matches the page it sits on |
| `links.outbound.new_tab` | boolean | `false` | Open links to other websites in a new tab, announced as such, with `noopener` |
| `links.outbound.rel` | list of string | `[]` | `rel` tokens every link to another website carries, such as `nofollow` |
| `locales.default` | string | Required | The site's default locale |
| `locales.domains` | map of string |  | With `strategy: domain`, the host of each locale |
| `locales.enabled` | list of string | Required | The locale codes the site runs, from `locales.yaml` |
| `locales.fallback` | map of list of string | `{}` | Per locale, the locales whose text shows where it has none, overriding the install's fallbacks for this site |
| `locales.strategy` | domain, prefix, prefix-all | `prefix` | How a locale shows in URLs: `prefix` (every locale but the default under `/<code>/`), `prefix-all` (every locale prefixed) or `domain` (a host per locale) |
| `mail.from` | string | `mail.from` | The site's transactional sender |
| `mail.newsletter.dkim_selectors` | list of string | `newsletter.dkim_selectors` | The DKIM selectors checked for the site's sending domain |
| `mail.newsletter.from_address` | string | `newsletter.from_address` | The site's own newsletter sender address |
| `mail.newsletter.from_name` | string | `newsletter.from_name` | The site's own sender name |
| `mail.newsletter.reply_to` | string | `newsletter.reply_to` | The site's own reply address |
| `mail.reply_to` | string | `mail.reply_to` | The site's `Reply-To` |
| `memberships.tiers` | list of string | Every tier | The tiers this site sells (`engine-dmo`) |
| `nav` | map of any | `{}` | The navigation slots the templates print, by name, each `{ id, label, depth }`. The items are edited in the admin |
| `seo.default_image` | string |  | The social sharing image used when a page has none |
| `seo.robots.agents` | list of objects |  | Groups for named crawlers, written after the group for every crawler: a crawler that finds its name obeys only its own group |
| `seo.robots.agents[].allow` | list of string |  | Paths this crawler may fetch |
| `seo.robots.agents[].disallow` | list of string |  | Paths this crawler may not fetch |
| `seo.robots.agents[].user_agent` | string | Required | The crawler's name |
| `seo.robots.allow` | list of string |  | Paths reopened under a disallowed one, for every crawler |
| `seo.robots.disallow` | list of string |  | Paths no crawler may fetch |
| `seo.robots.enabled` | boolean |  | Serve `/robots.txt` from these rules |
| `seo.sitemap` | map of any |  | The sitemap: `enabled`, `max_urls_per_file` |
| `seo.structured_data.breadcrumbs` | boolean | `true` | Emit a BreadcrumbList from the real URL hierarchy |
| `seo.structured_data.organisation` | any | `true` | The destination as the publisher of the site: `true`, `false`, or a mapping with its `type`, `logo` and other properties |
| `seo.structured_data.search` | boolean | `true` | Emit the WebSite search action where the site routes search |
| `seo.title_template` | string |  | The page title pattern, such as `"{{ title }} \\| {{ site.name }}"` |
| `settings` | map of any | `{}` | Free values your templates read as `site.settings` |
| `site` | object | Required | The site itself |
| `site.country` | string |  | The site's ISO 3166 country code, which decides country conventions (address formats, the financial year) |
| `site.default` | boolean | `false` | The install's default site. Exactly one |
| `site.default_currency` | string |  | The site's ISO 4217 currency |
| `site.domains` | list of string | Required | The host names the site answers on, with a port where one is used (`localhost:8080`). `*.example.org` matches subdomains. A host belongs to one site |
| `site.id` | string | Written for you | The element's stable id. Written by `engine-dmo check --fix`; never write or change it by hand |
| `site.name` | map of string | Required | The site's name per locale |
| `site.network` | string | The default network | The network the site belongs to (`networks.yaml`) |
| `site.organisation` | string |  | The organisation that runs the site, for structured data and statements |
| `site.path_prefix` | string |  | A path the whole site lives under on its host |
| `site.position` | integer |  | The site's order in the admin |
| `site.short_name` | map of string |  | A shorter name per locale |
| `site.timezone` | string |  | The site's IANA time zone |
| `templates.allow_unescaped` | boolean | `false` | Allow `{% autoescape off %}` and the `safe` filter in this site's templates |
| `templates.roots` | list of string | `[<site>, _shared]` | The template directories searched, in order |


# Environment variables (/reference/environment-variables)

Which environment variables the engine reads directly (very few), the conventional names a project's engine.yaml interpolates, the variables commands read secrets from, and the variables the engine sets for child processes.

The engine reads almost nothing from the environment on its own. Configuration reaches it through the `${VAR}` interpolations in your configuration files, so the variable names are whatever your `engine.yaml` says. A new project's files, the examples and this handbook use the conventional names below; keep them unless you have a reason not to.

## Read directly by the engine [#read-directly-by-the-engine]

| Variable | Read by | Effect |
|---|---|---|
| `NO_COLOR` | Every command | When non-empty, no colour in terminal output (as `--no-colour`) |
| `TERM` | Every command | `dumb` turns colour off |

Nothing else changes the engine's behaviour unless your configuration names it. The engine does not read `.env` files.

## Conventional names in engine.yaml [#conventional-names-in-engineyaml]

These are the names `engine-dmo init` writes into a new project's `config/engine.yaml`, and the ones the deployment pages use. Each is only read because the file interpolates it.

| Variable | Interpolated at | Starter default | Notes |
|---|---|---|---|
| `ENVIRONMENT` | `engine.environment` | `development` | `development`, `staging` or `production` |
| `LISTEN_ADDR` | `server.listen` | `127.0.0.1:8080` | Set `0.0.0.0:8080` in a container |
| `BASE_URL` | `server.base_url` | `http://localhost:8080` | The default site's public origin; required in production |
| `DATABASE_URL` | `database.url` | None: must be set | A secret |
| `LOG_FORMAT` | `logging.format` | `text` | `json` in production |

Names the deployment pages and examples add:

| Variable | Interpolated at | Notes |
|---|---|---|
| `SIGNING_KEY` | `server.security.signing_key` | A secret, at least 32 characters. Required in production |
| `MEDIA_SIGNING_KEY` | `media.signing_key` | A secret; optional |
| `ADMIN_HOST` | `server.admin_host` | A host of the admin's own, or `*` for every site's host |
| `MIGRATE_ON_BOOT` | `migrate.on_boot` | `refuse` or `apply` |
| `LOG_LEVEL` | `logging.level` | `debug`, `info`, `warn` or `error` |
| `SEARCH_DRIVER` | `search.driver` | `meilisearch`, `elasticsearch`, `opensearch` or `none` |
| `MEILISEARCH_URL` | `search.meilisearch.url` | Such as `http://search:7700` |
| `MEILISEARCH_API_KEY` | `search.meilisearch.api_key` | A secret; set it empty for a server with no key |
| `MEILISEARCH_INDEX_PREFIX` | `search.meilisearch.index_prefix` | When several installs share one Meilisearch |
| `METRICS_BIND` | `telemetry.metrics.bind` | Such as `0.0.0.0:9090` on a private network |
| `PDF_RENDERER` | `analytics.pdf.renderer` | `auto`, `browser` or `builtin` |
| `SMTP_HOST`, `SMTP_USERNAME`, `SMTP_PASSWORD` | `mail.smtp.*` | The password is a secret |
| `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | `storage.s3.*` | The secret access key is a secret |
| `SENTRY_DSN` | `telemetry.errors.dsn` | A secret |
| `AI_ENABLED` | `ai.enabled` | `true` or `false`; `ai.enabled` is a string so it can be interpolated |
| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` | `stripe.secret_key`, `stripe.webhook_secret` in `config/paidlistings.yaml` | `engine-dmo` only. Secrets |

## Setting them in development [#setting-them-in-development]

Once a file names a variable with no default, every command that loads the configuration needs it set, on your laptop as much as in production. Which commands load what is in [Commands and the environment](/reference/cli#commands-and-the-environment). For local work without a database, and once `engine.yaml` names `${SIGNING_KEY}` for production:

```bash
export DATABASE_URL=postgres://localhost/placeholder   # any address; check --no-db and describe never connect
export SIGNING_KEY=""                                  # empty is a derived development key; or 32 or more random characters
```

`SIGNING_KEY` set to 1 to 31 characters is refused everywhere (`signing_key must be at least 32 characters`). With a real development database, set `DATABASE_URL` to it. The engine does not read `.env` files: export the variables in your shell, or load a file yourself (`set -a; . ./.env; set +a`).

Only string-typed settings can be interpolated; a boolean or number setting cannot come from a variable. [Configuration and secrets](/deploying/configuration-and-secrets) explains `${VAR}`, `${VAR:-default}` and the secret rule.

## Variables commands read secrets from [#variables-commands-read-secrets-from]

Some commands take a secret from a variable you name, so it never appears on the command line or in shell history:

| Command | Flag | Default variable |
|---|---|---|
| `engine-dmo mcp call` | `--token-env` | `MERIDIAN_TOKEN`: a personal access token for the remote content MCP |
| `engine-dmo site export` | `--signing-key-env` | None: the receiving install's signing key |
| `engine-dmo affiliates connect` | `--secret-env` | None: a network's reporting API secret; standard input when not given |

## Variables the engine sets for child processes [#variables-the-engine-sets-for-child-processes]

| Variable | Set for | Value |
|---|---|---|
| `MERIDIAN_ENGINE` | The frontend build `engine-dmo build` runs, and the Vite development server `serve --dev` starts through the Vite extension | The path of the running engine binary, which the Vite plugin calls for the asset manifest |
| `MERIDIAN_PROJECT` | The same | The absolute project directory |
| `MERIDIAN_VITE_ORIGIN` | The Vite development server | The origin Vite should serve on |
| `MERIDIAN_PLUGIN_*` | A plugin process declared in `plugins.yaml` | The socket, protocol version, plugin name and lifeline. A plugin's `env` may not declare these names |

Set `MERIDIAN_ENGINE` yourself in a container build stage that runs the Vite build, so the plugin uses the engine binary you copied in rather than looking for one (see [Container images](/deploying/container-images)).

A plugin process receives only `PATH`, `HOME`, `TMPDIR`, `USER`, `LANG`, `LC_ALL`, `SSL_CERT_FILE` and `SSL_CERT_DIR` from the engine's environment, plus what its `env` declares and `TZ=UTC`. It never sees the database URL or a key it was not given.


# Error codes (/reference/error-codes)

Every stable MRD error code the engine reports, with its cause and its fix.

{/* Generated from internal/errcode/catalogue.go by make errors.gen. Do not edit by hand. */}

Every operator-facing error the engine reports carries a stable `MRD-nnnn` code. A code is never renumbered or reused. It appears on the terminal (`engine-dmo check`, a refused boot), in the log line's `error_code` attribute, in `engine-dmo doctor --include-logs`, on the diagnostics screen, in an error report's `error_code` tag, and in the catalogue below with its cause and its fix. Search this handbook for a code to find it.

## Configuration [#configuration]

Codes MRD-1nnn.

### MRD-1001 A configuration file cannot be read [#mrd-1001-a-configuration-file-cannot-be-read]

**Cause.** The file named in the message is missing or the engine's user cannot read it. Every project has `config/engine.yaml`.

**Fix.** Check the path given to `--project`, the file's permissions, and that the container mounts the project's `config/` directory.

### MRD-1002 A configuration file is not valid YAML [#mrd-1002-a-configuration-file-is-not-valid-yaml]

**Cause.** A tab used for indentation, an unclosed quote or bracket, or a value that starts with a character YAML reserves (`@`, a backtick, `%`).

**Fix.** Fix the line the caret points at. Quote a value that starts with a reserved character.

### MRD-1003 A configuration key is not one the engine knows [#mrd-1003-a-configuration-key-is-not-one-the-engine-knows]

**Cause.** A typo, or a key from a newer release. Unknown keys are refused rather than ignored, so a misspelt setting cannot silently do nothing.

**Fix.** Use the key the hint suggests, or remove it. `engine-dmo config schema` prints every key the binary knows.

### MRD-1004 A secret is written into the configuration as a literal [#mrd-1004-a-secret-is-written-into-the-configuration-as-a-literal]

**Cause.** Configuration is committed to version control and must never hold a secret. Every secret path (`config.SecretPaths`) and every `telemetry.otlp.headers` value must be a bare `${VAR}` interpolation.

**Fix.** Write the value as `${VAR}`, set the variable in the environment, and rotate the secret that was written down.

### MRD-1005 An environment variable the configuration names is not set [#mrd-1005-an-environment-variable-the-configuration-names-is-not-set]

**Cause.** The configuration interpolates `${VAR}` and the process environment has no such variable.

**Fix.** Set the variable, or for a value that is not a secret give it a default with `${VAR:-default}`.

### MRD-1006 A project file breaks a rule [#mrd-1006-a-project-file-breaks-a-rule]

**Cause.** A value in engine.yaml, a schema type, a route, a template or another project file breaks the rule the message states: a duration, size or schedule that cannot be read, a value outside its set, a name that does not resolve, or two settings that contradict each other. It is the code of every project diagnostic without a more specific one.

**Fix.** Change the value at the line and column given. `engine-dmo check` reports every problem in one run.

### MRD-1007 A key has moved out of engine.yaml [#mrd-1007-a-key-has-moved-out-of-engineyaml]

**Cause.** The setting now lives in a file of its own.

**Fix.** Move the value to the file the message names.

### MRD-1008 The project configuration is not valid [#mrd-1008-the-project-configuration-is-not-valid]

**Cause.** A site, route, schema type, role or template setting under `config/` breaks a rule; the diagnostics above this line name each one.

**Fix.** Run `engine-dmo check` and fix every error it lists.

## Migrations and schema [#migrations-and-schema]

Codes MRD-2nnn.

### MRD-2001 The database has migrations the binary has not applied [#mrd-2001-the-database-has-migrations-the-binary-has-not-applied]

**Cause.** A new release added migrations and `migrate.on_boot` is `refuse`, the production default, so the engine will not serve until they are applied.

**Fix.** Back up, then run `engine-dmo migrate up` (or set `migrate.on_boot: apply` outside production).

### MRD-2002 A migration failed to apply [#mrd-2002-a-migration-failed-to-apply]

**Cause.** A statement in the migration failed, usually against data the migration did not expect or a lock it could not take. Migrations run in a transaction, so nothing was half applied.

**Fix.** Read the statement and error in the message, fix the data or wait for the lock, and run `engine-dmo migrate up` again. Send the doctor bundle if the cause is not clear.

### MRD-2003 The database is newer than this binary [#mrd-2003-the-database-is-newer-than-this-binary]

**Cause.** The database has migrations this binary does not know: a newer release ran against it, or a rollback went to an older binary.

**Fix.** Run the release that migrated the database. Migrations are forward only; restoring the backup taken before the upgrade is the only way back.

### MRD-2004 The schema in the database differs from the configuration [#mrd-2004-the-schema-in-the-database-differs-from-the-configuration]

**Cause.** The content types in `config/schema/` changed and `schema.on_drift` is `refuse`, so the engine will not serve a model the database was not reconciled to.

**Fix.** Run `engine-dmo schema plan`, review it, then `engine-dmo schema apply`.

### MRD-2005 Applying the schema plan failed [#mrd-2005-applying-the-schema-plan-failed]

**Cause.** A step of the reconciliation plan was refused, typically a destructive change without its confirmation or data that breaks a new constraint.

**Fix.** Run `engine-dmo schema plan` to see the step and its reason, and follow the hint it prints.

## Boot and runtime [#boot-and-runtime]

Codes MRD-3nnn.

### MRD-3001 The engine cannot reach the database [#mrd-3001-the-engine-cannot-reach-the-database]

**Cause.** The database is down, the URL is wrong, a firewall drops the connection, or the credentials are refused.

**Fix.** Check `database.url` and that PostgreSQL is answering. `engine-dmo doctor` prints the host, the database and the error.

### MRD-3002 The database server is older than the engine supports [#mrd-3002-the-database-server-is-older-than-the-engine-supports]

**Cause.** The PostgreSQL server is older than 14, the oldest the engine supports.

**Fix.** Upgrade PostgreSQL to 14 or later.

### MRD-3003 The engine cannot listen on its address [#mrd-3003-the-engine-cannot-listen-on-its-address]

**Cause.** Another process holds the port, or the engine's user may not bind a port below 1024.

**Fix.** Change `server.listen` or stop the other process. `telemetry.metrics.bind` must be a different address.

### MRD-3004 The templates failed the linter at boot [#mrd-3004-the-templates-failed-the-linter-at-boot]

**Cause.** A template has a security finding, which refuses a production boot whatever `template.strict` says, or an unknown variable under `template.strict: true`.

**Fix.** Run `engine-dmo check` for the findings with their lines, and fix each one.

### MRD-3005 A request panicked [#mrd-3005-a-request-panicked]

**Cause.** A bug: a handler reached a state it did not expect. The visitor got a 500, the stack was logged and reported, and the engine kept serving.

**Fix.** Send the doctor bundle with `--include-logs 20` and the request id from the error. If an error reporter is configured, the report holds the stack.

### MRD-3006 A job used its last attempt [#mrd-3006-a-job-used-its-last-attempt]

**Cause.** The job's handler failed on every attempt, or no handler is registered for its kind. The job is kept as dead with its last error.

**Fix.** `engine-dmo jobs list --failed` shows the error and the request that queued it. Fix the cause, then `engine-dmo jobs retry <id>`.

### MRD-3007 A job panicked [#mrd-3007-a-job-panicked]

**Cause.** A bug in the job's handler. The attempt counts as failed and the job is retried with back-off.

**Fix.** Send the doctor bundle with `--include-logs 20`; the report holds the stack.

### MRD-3008 A scheduled task failed [#mrd-3008-a-scheduled-task-failed]

**Cause.** A task on the scheduler's leader returned an error; it runs again at its next time.

**Fix.** The message names the task and the error. `engine-dmo schedule run <task>` runs it again once the cause is fixed.

### MRD-3009 A scheduled task panicked [#mrd-3009-a-scheduled-task-panicked]

**Cause.** A bug in the task. The run counts as a failure and the scheduler carries on.

**Fix.** Send the doctor bundle with `--include-logs 20`; the report holds the stack.

## Storage [#storage]

Codes MRD-4nnn.

### MRD-4001 The object storage bucket failed the boot probe [#mrd-4001-the-object-storage-bucket-failed-the-boot-probe]

**Cause.** At boot the engine writes, reads back and deletes a small object. A wrong key, a policy that denies one of the three verbs, a missing bucket or an unreachable endpoint fails it.

**Fix.** Check `storage.s3` and the bucket policy: the engine needs put, get, head, delete and list.

### MRD-4002 The local storage directory cannot be written [#mrd-4002-the-local-storage-directory-cannot-be-written]

**Cause.** `storage.filesystem.root` cannot be created or written: it belongs to another user, or its volume is full or read only.

**Fix.** Create the directory, give the engine's user write access, and check free space.

### MRD-4003 The object store refused a request [#mrd-4003-the-object-store-refused-a-request]

**Cause.** S3 answered with a refusal such as AccessDenied or NoSuchBucket; refusals are not retried.

**Fix.** The message carries S3's own error code. Fix the credentials or the policy.

### MRD-4004 An upload was refused because its metadata could not be removed [#mrd-4004-an-upload-was-refused-because-its-metadata-could-not-be-removed]

**Cause.** The media pipeline strips location and camera metadata, and a file whose metadata it cannot strip is refused rather than stored.

**Fix.** Re-export the file without metadata and upload it again.

## Search [#search]

Codes MRD-5nnn.

### MRD-5001 The search backend did not answer [#mrd-5001-the-search-backend-did-not-answer]

**Cause.** The backend is down, the URL is wrong, or the credentials are refused. Public search falls back to browse mode.

**Fix.** Check the backend's health and `search.*` in engine.yaml.

### MRD-5002 The search circuit breaker is open [#mrd-5002-the-search-circuit-breaker-is-open]

**Cause.** Enough recent queries failed that the engine stopped asking the backend for a while.

**Fix.** Fix the backend; the breaker closes on its own once a probe succeeds.

### MRD-5003 Indexing a document failed [#mrd-5003-indexing-a-document-failed]

**Cause.** The backend refused a document, typically a mapping conflict after a schema change.

**Fix.** Run `engine-dmo search verify`, then `engine-dmo search rebuild` for the site.

## Mail [#mail]

Codes MRD-6nnn.

### MRD-6001 The mail provider failed [#mrd-6001-the-mail-provider-failed]

**Cause.** A transport failure, a 5xx or a 429 from the provider. The delivery is retried.

**Fix.** Check the provider's status page. Retries continue on their own.

### MRD-6002 The mail provider rejected a message [#mrd-6002-the-mail-provider-rejected-a-message]

**Cause.** A 4xx such as an unverified sender, an invalid recipient or refused credentials. Not retried.

**Fix.** Read the provider's message in the delivery record; a 401 is the credential.

## Telemetry and error reporting [#telemetry-and-error-reporting]

Codes MRD-7nnn.

### MRD-7001 Exporting traces or metrics failed [#mrd-7001-exporting-traces-or-metrics-failed]

**Cause.** The OTLP endpoint did not answer, refused the headers, or rejected the payload. Telemetry is dropped, never queued without bound, and serving is not affected.

**Fix.** Check `telemetry.otlp.endpoint` and its headers. The diagnostics screen and `engine-dmo doctor` show the last error.

### MRD-7002 Sending an error report failed [#mrd-7002-sending-an-error-report-failed]

**Cause.** The error reporter's endpoint did not answer or refused the report. Reports are dropped, never queued without bound.

**Fix.** Check `telemetry.errors.dsn`, then run `engine-dmo telemetry test`.

## Content API problem types [#content-api-problem-types]

Codes MRD-8nnn.

### MRD-8001 Content API: no such site [#mrd-8001-content-api-no-such-site]

**Cause.** The request names a site the install does not have, or one that is not headless.

**Fix.** Use a site key from `engine-dmo describe project`.

### MRD-8002 Content API: not found, or not visible [#mrd-8002-content-api-not-found-or-not-visible]

**Cause.** No published document matches, or the key may not read it.

**Fix.** Check the id or path, and that the document is published on the site.

### MRD-8003 Content API: the field is not indexed [#mrd-8003-content-api-the-field-is-not-indexed]

**Cause.** A filter or sort names a field that is not declared queryable.

**Fix.** Declare the field queryable in the schema, or filter on another field.

### MRD-8004 Content API: a parameter is not valid [#mrd-8004-content-api-a-parameter-is-not-valid]

**Cause.** A parameter could not be read; the `parameter` member names it.

**Fix.** Fix the parameter as the detail says.

### MRD-8005 Content API: a limit was exceeded [#mrd-8005-content-api-a-limit-was-exceeded]

**Cause.** A page size, expansion depth or filter count is above its limit.

**Fix.** Ask for less, or page through the result.

### MRD-8006 Content API: the engine could not answer [#mrd-8006-content-api-the-engine-could-not-answer]

**Cause.** An error inside the engine; it is logged with the request id.

**Fix.** Retry. If it persists, send the doctor bundle with the request id.

### MRD-8007 Content API: the key is missing, unknown, expired or revoked [#mrd-8007-content-api-the-key-is-missing-unknown-expired-or-revoked]

**Cause.** The `Authorization` header holds no key the install knows, or one past its expiry or revoked.

**Fix.** Issue a key under Settings, API keys, and send it as a bearer token.

### MRD-8008 Content API: a secret key was sent from a browser [#mrd-8008-content-api-a-secret-key-was-sent-from-a-browser]

**Cause.** A secret key arrived with an `Origin` header, so it is in front-end code. It is marked exposed and administrators are told.

**Fix.** Rotate the key, and use a publishable key in the browser.

### MRD-8009 Content API: the key does not read this site [#mrd-8009-content-api-the-key-does-not-read-this-site]

**Cause.** The key's sites do not include the one requested.

**Fix.** Add the site to the key, or use the site's own key.

### MRD-8010 Content API: the origin is not allowed for this key [#mrd-8010-content-api-the-origin-is-not-allowed-for-this-key]

**Cause.** A publishable key was used from an origin it does not list.

**Fix.** Add the origin to the key.

### MRD-8011 Content API: the key does not hold the capability [#mrd-8011-content-api-the-key-does-not-hold-the-capability]

**Cause.** The operation needs a capability, such as preview, that the key was not given.

**Fix.** Issue a key with the capability.

### MRD-8012 Content API: the preview has expired [#mrd-8012-content-api-the-preview-has-expired]

**Cause.** Preview tokens end with the staff session that issued them.

**Fix.** Open the preview again from the editor.

### MRD-8013 Content API: the preview token is not valid [#mrd-8013-content-api-the-preview-token-is-not-valid]

**Cause.** The token was altered, or signed under a key the install no longer holds.

**Fix.** Open the preview again from the editor.

### MRD-8014 Content API: too many requests [#mrd-8014-content-api-too-many-requests]

**Cause.** The key or address used its quota; `Retry-After` says when to try again.

**Fix.** Back off as `Retry-After` says, or cache responses on the frontend.

### MRD-8015 Content API: a form submission was not valid [#mrd-8015-content-api-a-form-submission-was-not-valid]

**Cause.** A post to a form through the content API failed the form's own validation; `field_errors` names each field and why.

**Fix.** Show the field errors to the visitor and let them correct the form.


# Exit codes (/reference/exit-codes)

The five exit codes every engine-dmo and engine-cms command uses (0 success, 1 error, 2 pending or unconfirmed, 3 invalid configuration, 4 degraded), and which commands return 2 and 4 and why.

Every command exits with one of five codes, so a script or CI step can act on the result without parsing output. Under `--json` the code is also in the output (the envelope's `exit`).

| Code | Name | Meaning |
|---|---|---|
| `0` | Success | The command did what it was asked, or there was nothing to do |
| `1` | Error | It failed: a database it could not reach, a file it could not write, a refusal that is not about confirmation |
| `2` | Pending | Changes are pending, or the command refused for want of confirmation |
| `3` | Invalid | The configuration is invalid, or a flag's value cannot be used |
| `4` | Degraded | It ran, and something it depends on is not answering |

```bash
engine-dmo migrate status
case $? in
  0) echo "up to date" ;;
  2) engine-dmo migrate up ;;
  *) exit 1 ;;
esac
```

## Exit 2: pending or unconfirmed [#exit-2-pending-or-unconfirmed]

| Command | Exits 2 when |
|---|---|
| `migrate status` | Any migration is pending |
| `schema plan` | The configuration differs from the database |
| `schema apply` | The plan is destructive and not approved; an id in the files replaces a stored one not named by `--replace`; the plan holds a change this engine cannot apply yet; or a destructive plan was not confirmed on the terminal |
| `serve` | Migrations are pending (and `migrate.on_boot` is `refuse`), or the configuration has drifted (and `schema.on_drift` is `refuse`) |
| `dev` authoring verbs with `--apply` | The resulting plan is destructive: review it and run `schema apply` |
| `search rebuild` | A rebuild, purge or check is already running, or held by another worker |
| `search verify` | The index has drifted from what is published |
| `ai test`, `crm dedupe` | The AI budget is spent |
| `seed reset`, `user reset-mfa`, `mail suppression remove`, `content purge`, `site retire`, `crm erase`, `newsletter send`, `broadcast send` and similar | The confirming flag (`--confirm` or `--yes`) is missing |

## Exit 3: invalid [#exit-3-invalid]

`check`, `config validate`, `serve` and every command that loads the project exit 3 when the configuration or a template is invalid, after printing every problem with its file, line and column. Several commands also exit 3 for a flag value they cannot use (an address that is not loopback for `docs serve`, an AI command with no provider configured, a `sar` address or `--out` it cannot use). `audit verify` exits 3 when nothing is chained, and 1 on a break in the chain.

<Callout type="warn" title="Unknown commands and flags exit 1">
`help --json` describes exit 3 as "configuration invalid, or a bad invocation", but an unknown command, an unknown flag or a missing required flag exits 1 in this release. Treat any non-zero code other than 2 and 4 as a failure.
</Callout>

## Exit 4: degraded [#exit-4-degraded]

| Command | Exits 4 when |
|---|---|
| `health` | The server did not answer 200 (within `--wait`, when given) |
| `jobs list`, `jobs retry` | The database does not answer |
| `search status`, `search test`, `search verify` | The search backend does not answer |
| `ai status`, `ai test` | The AI provider does not answer; the AI features are unavailable and nothing else is affected |
| `analytics report --format pdf` | The PDF could not be rendered |
| `crm dedupe` | The AI provider behind duplicate detection is not answering (exit 2 when the AI budget is spent) |

## Related [#related]

- [CLI](/reference/cli): every command.
- [Error codes](/reference/error-codes): the `MRD-nnnn` code a refusal carries.


# Reference (/reference)

Where to find every command and flag, every configuration file and key, the template API for your project, environment variables, exit codes and error codes, and how to get the same from the binary.

The reference lists everything exactly: every command, every configuration key, every exit and error code. The other sections explain how and why; come here for the precise name, type, default or limit.

<Cards>
<Card title="CLI" href="/reference/cli" />
<Card title="Configuration" href="/reference/configuration" />
<Card title="Template API" href="/reference/template-api" />
<Card title="Environment variables" href="/reference/environment-variables" />
<Card title="Exit codes" href="/reference/exit-codes" />
<Card title="Error codes" href="/reference/error-codes" />
</Cards>

## From the binary [#from-the-binary]

The binary describes itself, and what it prints always matches the version you run:

| To get | Run |
|---|---|
| Every command, argument and flag, as JSON | `engine-dmo help --json` |
| One command's flags | `engine-dmo <command> --help` |
| The JSON Schema of every configuration file | `engine-dmo config schema --json` |
| The resolved `engine.yaml` with every default | `engine-dmo config render` |
| Every field type and its parameters | `engine-dmo describe fieldtypes --json` |
| The template surface of your project | `engine-dmo template api --json` |
| Your project's sites, types, routes and the rest, with ids | `engine-dmo describe project --json` |
| Version, bundle, modules and capabilities | `engine-dmo version --json` |
| This handbook as Markdown | https://docs.cherwell.studio/llms.txt, https://docs.cherwell.studio/llms-full.txt |


# Template API (/reference/template-api)

How to get the complete, generated template surface for your own project (every global, filter, tag, field type, your types and fields, routes and components) from engine-dmo template api, docs serve, describe and guide.

The template surface depends on two things: the engine version (its globals, filters, tags and field types) and your project (its types, fields, routes and components). So the complete reference is generated from both, by the binary you run, for the project you are in. The [Templates](/templates) section explains the language and each part; this page is how you get the exact list.

## In the terminal [#in-the-terminal]

```bash
engine-dmo template api                 # the default site's surface, as text
engine-dmo template api --site wyndwold # another site
engine-dmo template api --json          # all of it, as JSON
```

```text
site main, template contract 1

globals (76)
  aiDisclosure  aiDisclosure(entry): the disclosure sentence when the entry carries AI-assisted text, else empty
  analytics  analytics(): the cookieless client that records impressions and in-page interactions
  ancestors  ancestors(doc): a nesting document's published ancestors on the site, root first
  ...
filters (94)
  ...
tags (37)
  ...
types (8)
  ...
components (0)
```

It needs no database and no secrets, so it runs in CI and in an agent's sandbox.

### The JSON document [#the-json-document]

`template api --json` prints one object for the site:

| Key | Holds |
|---|---|
| `contract` | The template contract version the surface belongs to |
| `site` | The site key |
| `production` | Whether `engine.environment` is `production` (development-only helpers such as `dump` are absent there) |
| `globals` | Every global variable and function: `name`, `doc` |
| `filters` | Every filter: `name`, `doc` |
| `tags` | Every tag: `name`, `doc` |
| `field_types` | Every field type with the properties and helpers its values have in a template: `key`, `properties`, `helpers` |
| `types` | Your content types (core types included) with their `key`, `label`, the `template` that renders an entry, the configuration `file` and `line`, and their `fields` (`name`, `type`, `required`, `index` and nested fields) |
| `routes` | The site's routes: `id`, `type`, the `uri` and `index` pattern per locale, the `template`, and the configuration `file` |
| `components` | Your components with their props and where they are called |
| `undocumented` | How many entries carry no documentation (zero for a release) |

## In a browser [#in-a-browser]

```bash
engine-dmo docs serve
```

```text
this project's template API is at http://127.0.0.1:6061/
```

It needs a project, and serves:

| Address | What it is |
|---|---|
| `http://127.0.0.1:6061/` | An index of the project's sites, with counts of globals, filters, tags, types, routes and components |
| `http://127.0.0.1:6061/<site>/` | One page per site: every global, function, filter, tag, field type, document type with its fields, route, and component with its props and call sites |
| `http://127.0.0.1:6061/<site>.json` | The same as `template api --json` |

The project is read again on every request, so a saved change shows on reload; a project that does not load shows its diagnostics there instead. `--site` limits it to one site and `--listen` changes the loopback address (it must be loopback). `docs serve` is refused when `engine.environment` is `production`.

## One thing at a time [#one-thing-at-a-time]

| Question | Command |
|---|---|
| Which fields does a type have, with their ids, types and parameters? | `engine-dmo describe type <type>` |
| What does each field type store and accept? | `engine-dmo describe fieldtypes` |
| Which route answers a path, and which template renders it? | `engine-dmo describe route <path>` |
| What does a template extend and include, and what does it render? | `engine-dmo describe template <file>` |
| What does the whole project declare? | `engine-dmo describe project` |
| What does a page actually render, with its errors and queries? | `engine-dmo render <path> --json` |

Each takes `--json`.

## For an agent [#for-an-agent]

`engine-dmo guide` writes working guidance for the project (its types, routes and the template contract, generated) for a person or a coding agent:

```bash
engine-dmo guide --out AGENTS.md
engine-dmo guide --skill --out .claude/skills/meridian/SKILL.md
```

An agent without a browser reads this handbook as Markdown from https://docs.cherwell.studio/llms.txt, and the template API with `template api --json`. See [For agents](/agents).

## Editors [#editors]

`engine-dmo lsp` is the template language server: `check`'s diagnostics as you type, completion, hover and go to definition, from the same generated surface. `engine-dmo config schema --write .meridian/schema` writes the JSON Schema of every configuration file for editor completion. See [The development loop](/getting-started/development-loop).


# Caching (/templates/caching)

How the page cache and the cache tag for template fragments work, what a template does that makes a page or a block uncacheable, how cached output is invalidated on publish, and the configuration keys that bound it.

Two caches hold rendered output, and both are invalidated by content changes without any code of yours:

- **The page cache** keeps whole public pages for anonymous visitors, serving a stale copy while one background render replaces it. It is off until `engine.yaml` turns it on.
- **The `{% cache %}` tag** keeps one region of a template, keyed by what you name and registered against every document it read, so publishing one of them clears it.

Static files, built assets and image derivatives are cached by the browser and any CDN through their headers ([Frontend build](/templates/frontend-build#static-files), [Images](/templates/images#how-derivatives-are-made-and-served)).

## The page cache [#the-page-cache]

```yaml
# config/engine.yaml
cache:
  pages:
    enabled: true
    fresh: 60s
    stale: 24h
    max_memory: 256MB
    concurrency: 2
    warm:
      paths: ["/"]
      top: 50
      deadline: 60s
```

| Key | Default | Meaning |
|---|---|---|
| `cache.pages.enabled` | `false` | Turn the page cache on |
| `cache.pages.fresh` | `60s` | How long a page is served before it is rendered again; a publish ends it sooner |
| `cache.pages.stale` | `24h` | How long past `fresh` a page may still be served while one background render replaces it |
| `cache.pages.max_memory` | `256MB` | The bodies held in each process; the least recently read go first |
| `cache.pages.concurrency` | `2` | Background renders at once |
| `cache.pages.warm.paths` | `["/"]` | Paths rendered into the cache at boot, on every site, before the process reports ready |
| `cache.pages.warm.top` | `50` | Each site's most visited pages of the last 30 days to warm as well (the sitemap's first pages without analytics) |
| `cache.pages.warm.deadline` | `60s` | The longest warming holds readiness back |

The cache is per process. A publish, unpublish, trash, navigation change or tag change on any replica moves every replica's cache generation within one invalidation poll (`cache.invalidation_poll`, 2 seconds by default); every page stored before is then stale, and pages read in the last 15 minutes are re-rendered in the background without waiting for a visitor. A body over 4 MB is not stored.

Responses carry `X-Cache: hit`, `stale` or `miss`.

### Which pages are cached [#which-pages-are-cached]

A request is answered from the cache, and its response stored, only when **all** of these hold:

- It is a `GET` or `HEAD` for a whole page: not a fragment or sigmx request, not a preview (`?preview`, `?token`), not the profiler (`?_profile`), with no `Authorization` header.
- No staff member and no member is signed in.
- The response is `200`, `404`, `410`, `301` or `308`, is HTML, sets no cookie, has no `Cache-Control` saying `private` or `no-store`, and varies on nothing but `Accept-Encoding`.
- The render printed nothing that belongs to one request.

The cache key is the host and the full address with its query string, so each page of results and each filtered list is a page of its own.

### What a template does that stops a page being stored [#what-a-template-does-that-stops-a-page-being-stored]

| In the template | Why |
|---|---|
| A CSRF token printed for a signed-in visitor (`csrfInput()`, `csrfToken()`, `csrf`, a drawn form) | The token is that visitor's alone. For an anonymous visitor the helpers print nothing and a drawn form's `_csrf` field is empty, so the page stays cacheable |
| The search route's page | Each search is logged |
| A form for a members-only endpoint | The page is sent `Cache-Control: private, no-store` |
| `{% requireMember %}` | The page depends on who is signed in, and is sent as private |

Keep them out of pages that should be fast for everyone: a site-wide newsletter form works for anonymous visitors without breaking the cache, because its token is empty for them.

## The cache tag [#the-cache-tag]

```jinja
{% cache 'news-card' key=article.id version=article.updatedAt ttl='1h' %}
  {% component 'teaser' doc=article %}
{% endcache %}

{% cache 'latest-news' ttl='10m' %}
  {% for a in query('article').orderBy('publishedAt', 'desc').limit(6).all() %}
    {% component 'teaser' doc=a %}
  {% endfor %}
{% endcache %}

{% cache 'results' vary=['query'] %}
  {% for item in items %}{% component 'teaser' doc=item %}{% endfor %}
{% endcache %}
```

```jinja
{% cache 'name' key=... version=... ttl='...' vary=[...] %}...{% endcache %}
```

| Part | Meaning |
|---|---|
| `'name'` | Required, a quoted literal: lower-case letters, digits and hyphens, starting with a letter. It is what the admin's cache screen groups by and what a named purge clears |
| `key=` | Any expression, a list included (`key=[locale.code, request.path]`); its value is part of the key |
| `version=` | Any expression; its value is part of the key, so a new version is a new entry |
| `ttl=` | `'90s'`, `'10m'`, `'1h'` or `'1d'`; at most seven days. Without it, `cache.page_ttl` (300 seconds by default) |
| `vary=` | A list of `'locale'`, `'path'` (the request path) and `'query'` (the query string, parameters sorted) |

Every option is optional and written at most once.

### What is always in the key [#what-is-always-in-the-key]

You cannot get these wrong, because the engine adds them: the site, the locale, the formatting locale, the template file and the line the block starts on (two blocks that share a name never collide), the route the page was served by, the block's name, and the `key`, `version` and `vary` values. `vary=['locale']` is accepted and adds nothing.

A block's life, from the first render to the publish that clears it:

```mermaid
flowchart TD
  R["Render reaches cache block"] --> P{"A public page<br/>for a visitor?"}
  P -- no --> BODY["Render the body, store nothing"]
  P -- yes --> K["Key: site, locale, file, line,<br/>route, name, key, version, vary"]
  K --> H{"Stored and<br/>not invalidated?"}
  H -- hit --> OUT["Print the stored output"]
  H -- miss --> RB["Render the body"]
  RB --> PR{"Printed per-request output?<br/>token, member, focus, preload"}
  PR -- yes --> NS["Print it, do not store"]
  PR -- no --> ST["Store it against the documents<br/>and lists it read"]
  ST -.->|"a publish of one of them"| H
```

### When a block is used [#when-a-block-is-used]

Only in a public page rendered for a visitor: an entry, an index, a landing page, search and the error pages. A preview, a fragment request, the admin, the member portal and mail render the body every time, so a draft or one member's view is never stored. Outside those pages the tag simply renders its body.

### Invalidation [#invalidation]

A stored block is registered against cache scopes found by the render, not written by you, and is a miss once any of them changes:

| What the block read | Cleared by |
|---|---|
| A document: an entry, a relation's target, a link's document, a list item, a component's document prop | That document's publish, unpublish, scheduled publish, trash, restore or tagging change |
| An index page's `items`, `pagination` or `facets` | Any change to a document of that type, which can add a result |
| `smartList(...)` | The list's own scopes |
| `search(...)` | Any change to the site's live content |
| Anything | A purge of the block's name, its route or the site from the admin's cache screen; a tag change (tags are printed everywhere) |

The scopes come from the variables the body names (including `{% set %}` inside the block), followed four levels deep. A body that includes another template sees the whole context, so every document in it is registered; a component sees only its props. A block nested in another passes its scopes up.

A change the engine cannot see, such as an organisation's details shown on a listing or an asset's alt text, is bounded only by the block's `ttl`. Set a `ttl` that is acceptable for those.

A block that read a document while a publish of it was in flight is not stored, so a block is never stamped with a revision it did not read.

### What is never stored [#what-is-never-stored]

A block whose render printed a CSRF token, read or required the signed-in member, emitted `{% announce %}` or `{% focus %}`, added an image preload (`priority=true`) or a video, is rendered and not stored. In development the engine logs which block and why.

`engine-dmo check` reports the obvious cases from the source as errors: `csrfInput`, `csrfToken`, `csrf`, `now`, `enquiryForm`, `subscribeForm` and `{% requireMember %}` inside a cache block.

```text
_shared/article/index.html:12:1: error: cache block bad holds csrfInput, which emits per-request output: csrfInput() prints this visitor's CSRF token
      = move it outside the {% cache %} block, or leave the block uncached
```

It also refuses, at parse, a name that breaks the naming rule, a `ttl` over seven days or that is not a duration, an unknown `vary` value, and an unknown option.

### Choosing what to cache [#choosing-what-to-cache]

- Cache regions that run queries: a `query()` strip, a smart list, a facet panel, a card grid. A single field print is not worth a block.
- Give the block a `key` that names what makes it differ (the document's id for a card), and a `version` that changes when it should be rebuilt (`updatedAt`).
- Leave forms, the signed-in member and the current time outside the block.
- Prefer the page cache for whole pages. Blocks help most on pages the page cache cannot keep: pages for signed-in members, and pages with query strings that vary widely.

## Seeing it work [#seeing-it-work]

- The admin's cache screen shows, per block name, the hit rate, entries, size, age, scopes and the last invalidation, and purges by block name, route, document or site.
- Under `engine-dmo serve --dev`, the profiler (open a page with `?_profile`) shows each block's hit, miss or skip with the reason.
- In development (`serve --dev`) and with `template.cache: false` in `engine.yaml`, templates are parsed afresh on every render, so an edited template counts at once. In production, templates are compiled at boot and a template added or removed counts from the next restart.
- `engine-dmo warm` requests each site's warm paths, indexes and most visited pages from a running release after a deploy, and reports whether the page cache answered each and how long it took.

## Related [#related]

- [Configuration reference: engine.yaml](/reference/configuration/engine): `cache.*`.
- [Forms in templates](/templates/forms#the-csrf-token): tokens and anonymous visitors.


# Components (/templates/components)

How to write, call and override a template component with a declared contract of props, slots and attributes that engine-dmo check enforces at every call site.

A component is a reusable piece of markup with a contract. The contract, `component.yaml`, declares the props the component takes, the slots a caller may fill and whether the caller may add attributes. `engine-dmo check` holds every call to the contract, on every site, and the engine holds it again at render, so a wrong prop is an error with a file, line and column rather than a page that renders wrong.

Use a component for anything you would otherwise copy between templates: a card, a page header, a notice, a pager, an icon. Use `{% include %}` only for a fragment of one layout that needs the caller's whole context.

## A first component [#a-first-component]

<Steps>
<Step>

Scaffold it. `engine-dmo new component` writes the contract, the markup and a co-located stylesheet into the shared template root:

```bash
engine-dmo new component teaser
```

```text
created templates/_shared/components/teaser/component.yaml
created templates/_shared/components/teaser/teaser.html
created templates/_shared/components/teaser/teaser.css
```

Add `--site <key>` to write it into one site's own root instead, and `--force` to replace files that are already there.

</Step>
<Step>

Declare its inputs in `component.yaml`:

```yaml
# templates/_shared/components/teaser/component.yaml
name: teaser
description: A news story as a card for a grid, its title the one link.
props:
  doc:     { type: article, required: true, description: "The story the card shows" }
  heading: { type: enum, values: [h2, h3], default: h3, description: "The title's level" }
  tone:    { type: enum, values: [plain, feature], default: plain }
  note:    { type: string, description: "A line in place of the summary" }
slots:
  meta: { required: false, description: "Below the title, in place of the date" }
attrs: root
```

</Step>
<Step>

Write the markup. Every declared prop is a variable, `slots` holds the filled slots, and `attrs` holds the caller's attributes:

```jinja
{# templates/_shared/components/teaser/teaser.html #}
<article class="teaser teaser--{{ tone }}" {{ attrs }}>
  {% if doc.heroImage %}
    {{ doc.heroImage.img("card", class="teaser__img") }}
    {% if doc.heroImage.credit %}<p class="teaser__credit">{{ doc.heroImage.credit }}</p>{% endif %}
  {% endif %}
  <{{ heading }} class="teaser__title"><a href="{{ doc.uri|url }}">{{ doc.title }}</a></{{ heading }}>
  {% if slots.meta %}<p class="teaser__meta">{% slot 'meta' %}{% endslot %}</p>{% endif %}
  {% if note %}<p>{{ note }}</p>{% elif doc.summary %}<p>{{ doc.summary }}</p>{% endif %}
</article>
```

</Step>
<Step>

Call it from any template on the site:

```jinja
{% for article in items %}
  {% component 'teaser' doc=article heading='h2' %}
{% endfor %}

{% component 'teaser' doc=entry tone='feature' %}
  {% slot 'meta' %}<time datetime="{{ entry.publishedAt|iso }}">{{ entry.publishedAt|date:"medium" }}</time>{% endslot %}
{% endcomponent %}
```

</Step>
<Step>

Run `engine-dmo check`. It validates the contract, the markup and every call.

</Step>
</Steps>

## Where a component lives [#where-a-component-lives]

A component is a directory under `components/` in a template root:

<Files>
  <Folder name="templates" defaultOpen>
    <Folder name="_shared" defaultOpen>
      <Folder name="components" defaultOpen>
        <Folder name="teaser" defaultOpen>
          <File name="component.yaml" />
          <File name="teaser.html" />
          <File name="teaser.css" />
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

| File | Required | Purpose |
|---|---|---|
| `components/<name>/component.yaml` | Yes, somewhere on the site's chain | The contract |
| `components/<name>/<name>.html` | Yes | The markup; its file name repeats the directory name |
| `components/<name>/<name>.css`, `<name>.js` | No | Co-located styles and script, collected into each site's bundle by the Vite plugin ([Frontend build](/templates/frontend-build)) |

The name is the directory name: lower case letters, digits, `-` and `_`. Both files resolve along the site's template chain, so a site root can override a shared component ([Overriding a component](#overriding-a-component-on-one-site)).

## The contract [#the-contract]

`component.yaml` is decoded strictly: an unknown key is an error, so a misspelt `requried` cannot quietly make a prop optional.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `name` | string | the directory name | Must equal the directory name when given |
| `description` | string | none | One sentence; shown on hover in the language server and in the generated template API |
| `props` | map of name to prop | none | The inputs a call passes as `name=value` |
| `slots` | map of name to slot | none | The regions of markup a call may fill |
| `attrs` | `root`, `none` or `named` | `none` | Whether a call may pass `attrs=` |

### Props [#props]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `type` | string | none (required) | One of the prop types below |
| `required` | boolean | `false` | A call without it is an error |
| `default` | any | none | The value when a call leaves the prop out; must suit the type |
| `values` | list | none | The accepted values; only and always for `type: enum` |
| `description` | string | none | Shown in hints, hover and the template API |

`required` and `default` are exclusive. `attrs` and `slots` are reserved and cannot be prop names.

| Prop type | Accepts |
|---|---|
| `string` | A string, or any value that prints as one |
| `number` | An integer or a decimal |
| `boolean` | `true` or `false` |
| `enum` | One of `values`, compared as text |
| `list` | A list |
| `map` | A map, or an engine value with properties (an entry, an image) |
| `html` | Markup. Only markup the engine produced (such as `ptext` output) prints unescaped; a plain string is escaped where it is printed |
| `attrs` | An attribute string the engine built, or a map |
| `document` | Any document (an entry, a relation's target, a list item) |
| `any` | Anything |
| a type key of your project, such as `article` or `listing` | A document of that type; a document of another type is an error |

A prop the call leaves out takes its default, or is empty when it has none, so the markup can test any declared prop with `{% if note %}` without an error.

### Slots [#slots]

| Key | Type | Default | Meaning |
|---|---|---|---|
| `required` | boolean | `false` | A call that does not fill it is an error |
| `description` | string | none | Shown in hints and the template API |

### attrs [#attrs]

| Value | Meaning |
|---|---|
| `none` | The default. A call that passes `attrs=` is an error, since the attributes would be dropped |
| `root` | A call may pass `attrs=`. The markup must print `{{ attrs }}`, normally on its root element; `engine-dmo check` reports a component that declares `root` and never prints it |
| `named` | A call may pass `attrs=`, and the markup decides where to print them. Nothing checks where |

## Calling a component [#calling-a-component]

```jinja
{% component 'name' prop=expression prop2=expression %}
```

- The name is a quoted string literal, so `engine-dmo check` can find the contract. A variable name is a parse error.
- Props are `name=expression` pairs separated by spaces. A prop passed twice is an error.
- `attrs=` is not a prop. It passes the call site's attributes: a value an engine helper built, such as `sigmx.fragment(...)`, or a map. The template language has no map literal, so in practice `attrs=` takes a helper's value:

```jinja
{% component 'teaser' doc=article attrs=sigmx.fragment('results', on='click') %}
```

A map passed as `attrs` prints as escaped `name="value"` pairs in key order; `true` prints the bare name, and `false` or an empty value leaves the attribute out.

### A call with slots [#a-call-with-slots]

A call has a body, closed by `{% endcomponent %}`, exactly when the first thing after the tag (whitespace aside) is a `{% slot %}`:

```jinja
{% component 'notice' tone='warning' %}
  {% slot 'body' %}<p>{{ t("closures.notice") }}</p>{% endslot %}
{% endcomponent %}
```

- Every region of the body is a named slot. Text or markup outside a slot is an error, both at check and at render. There is no unnamed default slot.
- A slot filled twice in one call is an error.
- A slot's content renders in the caller's scope, so it can use the caller's loop variables and `{% set %}` names.

### Inside the markup [#inside-the-markup]

The markup sees:

- the page's globals (`site`, `locale`, `page`, `t()`, `path()`, `url()`, `assets`, `images` and the rest of the [globals](/templates/globals));
- each declared prop: the value passed, else its default, else empty;
- `attrs`, the call's attributes, ready to print;
- `slots`, the filled slots by name.

It never sees the caller's own variables (a loop variable, a `{% set %}`), so a component cannot come to depend on the page that happens to call it. Pass what it needs as a prop.

Print a slot with a fallback, or test whether it was filled:

```jinja
{% slot 'meta' %}<span>{{ t("teaser.no_date") }}</span>{% endslot %}
{% if slots.meta %}<p class="teaser__meta">{% slot 'meta' %}{% endslot %}</p>{% endif %}
```

`{% slot 'name' %}fallback{% endslot %}` in the markup prints what the call filled, or the fallback when it filled nothing. A `{% slot %}` the markup prints must be declared in the contract.

Components can call other components.

## What is checked [#what-is-checked]

`engine-dmo check` (and the [language server](/templates/testing#the-language-server) as you type) reports each of these at its line and column, every site along its own chain. The engine refuses the same mistakes at render, so a value the check could not see (a prop computed from a variable) still fails loudly.

| Mistake | Example message |
|---|---|
| Unknown prop | `teaser has no prop "colour"`, with the declared props or a "did you mean" |
| Missing required prop | `required prop doc is missing from the call to teaser` |
| Enum value not in `values` | `prop heading of teaser: "h4" is not one of h2, h3` |
| Literal of the wrong type | `prop size of icon: a string was passed where a number is expected` |
| Document of the wrong type | `prop doc of teaser is a article, and a event is passed` |
| Unknown slot | `unknown slot "footer"`, with the declared slots |
| Required slot left empty | `required slot body is not filled`. The check reports it for a call with a body; a call with no body at all is refused at render only |
| Content outside a slot | `component notice has content outside a {% slot %} in its call` |
| `attrs=` on an `attrs: none` component | `attrs passed to teaser, whose contract says attrs: none, so they would be dropped` |
| `attrs: root` and no `{{ attrs }}` in the markup | `component teaser declares attrs: root and its markup never prints {{ attrs }}` |
| A slot printed in the markup and not declared | `slot "summary" is not declared in this component's contract` |
| A variable in the markup that is neither a prop nor a global | `"tone" is not in the template context` |
| A contract key that does not exist, a bad prop type, an enum without values, `required` with a `default`, a default of the wrong type | Reported at the key in `component.yaml` |
| A directory with no contract, or a contract with no markup | Reported at the directory |

All of these are errors (`MRD-1006`, invalid configuration), and `engine-dmo check` exits 3.

### What is not checked [#what-is-not-checked]

A prop typed with one of your types (`doc: { type: article }`) is held to that type at the call, but **fields read on it inside the markup are not**. `{{ doc.photo }}` on a type with no `photo` field passes `engine-dmo check` and prints nothing at render, with no warning, even with `template.strict: true`. The same holds for a field read on a loop variable or a `query()` result. Take field names from `engine-dmo describe type <type>`, and read the rendered page (`engine-dmo render <path>`) to see each one print.

Dates have no properties: write `{{ entry.publishedAt|iso }}` and `{{ entry.publishedAt|date:"medium" }}`. A property such as `entry.publishedAt.iso` is not reported and prints nothing.

## Overriding a component on one site [#overriding-a-component-on-one-site]

A site whose template chain puts its own root before `_shared` can override a component by adding the same directory to its root ([Multisite templates](/templates/multisite)):

```text
templates/
  _shared/components/teaser/component.yaml
  _shared/components/teaser/teaser.html
  town/components/teaser/teaser.html        the town's own markup
```

- An override may carry markup alone. It then inherits the contract it overrides.
- An override may carry its own `component.yaml`, which must take the same inputs: the same props with the same types, requiredness and enum values, the same slots with the same requiredness, and the same `attrs`. Descriptions and defaults may differ. Anything else is an error at the override's contract (`component teaser on site town overrides _shared/components/teaser/component.yaml and takes different inputs: ...`). A component with different inputs needs a name of its own.
- The override's markup may extend the shared markup and replace blocks of it: `{% extends "components/teaser/teaser.html" %}` inside the override resolves to the next file of that name along the chain, never to itself.

Every call site, on every page and in every shared template, then renders the site's version, unchanged.

## Components and the frontend build [#components-and-the-frontend-build]

The co-located `<name>.css` and `<name>.js` files are not linked by the engine. With the `meridian()` Vite plugin, each site's main bundle imports the CSS and JS of every component that resolves for that site, so a site's override brings its own styles and not the shared ones. `engine-dmo assets manifest` lists which component directory each site resolves. See [Frontend build](/templates/frontend-build).

Component styles are not scoped or class-prefixed by the build. Prefix your class names (the scaffold uses `c-<name>`).

## Caching and components [#caching-and-components]

A component inside a `{% cache %}` block registers the documents passed to it as props, so publishing one of them clears the block. See [Caching](/templates/caching).


# The page context (/templates/context)

Exactly what each kind of page template receives (a document's entry and its common fields, an index page's items, pagination and facets, the search page's results, error pages, block and rich text templates) and how to print the real context of any URL.

A template's context is the set of variables it can read. Every page template receives the [globals](/templates/globals) (`site`, `locale`, `page`, `request`, `now` and the rest) and the [functions](/templates/functions) (`path()`, `query()`, `t()` and the rest). Each kind of page then adds its own variables, described here.

To see the context of a real page with its values, run:

```bash
engine-dmo describe route /places/the-red-lion --json
```

`context` in the output is every variable the template receives, with its value; `template` is the file the site's chain resolved. It needs the project's database. `engine-dmo template api --json` lists the same surface without a database, with your own types' fields.

Every template starts from the same globals and functions; the kind of page decides what is added on top:

```mermaid
flowchart TD
  G["Globals and functions<br/>site, locale, page, request, t(), path(), query() ..."] --> D["A document's page<br/>entry, its type's key"]
  G --> I["An index page<br/>items, pagination, facets"]
  I --> L["A landing page (engine-dmo)<br/>plus landing"]
  G --> S["The search page<br/>results, pagination"]
  G --> E["Error pages<br/>page only, no entry"]
  D --> B["Block and rich text templates<br/>block or node, plus entry and page"]
```

## Every page [#every-page]

| Variable | What it is |
|---|---|
| `page` | The page itself: always `uri`, `canonical`, `title`, `type` and `isPreview`; the other keys depend on the kind of page, below |
| The globals | `site`, `locale`, `locales`, `request`, `now`, `today`, `tomorrow`, `yesterday`, `settings`, `singletons`, `nav`, `csrf`, `assets`, `devMode`, and `sites` on a project with more than one site. See [Globals](/templates/globals) |
| The functions | `path()`, `url()`, `t()`, `query()` and every other function. See [Functions](/templates/functions) |

## A document's page [#a-documents-page]

Rendered with `<type>/entry.html` (or the type's or variant's `template:`). The document is `entry`, and the same value is also available under the type's key, so `listing/entry.html` can write `{{ listing.title }}` or `{{ entry.title }}`:

```jinja title="templates/_shared/listing/entry.html"
{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ entry.title }}</h1>
  <p>{{ entry.summary }}</p>
  {% if entry.publishedAt %}<p><time datetime="{{ entry.publishedAt|iso }}">{{ entry.publishedAt|date:"long" }}</time></p>{% endif %}
  {{ entry.description|ptext }}
  {% for tag in entry.tags %}<span class="tag">{{ tag.label }}</span>{% endfor %}
</article>
{% endblock %}
```

### page on a document [#page-on-a-document]

| Key | Value |
|---|---|
| `page.uri` | The path of this page, with its locale prefix |
| `page.canonical` | The absolute canonical URL, on the site's configured domain. For a document shared from another site, its address on the site that owns it |
| `page.title` | The document's title |
| `page.type` | The type key |
| `page.isPreview` | `false` on a public page |
| `page.alternates` | The locales the document is published in on this site: each `locale`, `hreflang`, `path` and `url` |

### Fields every document has [#fields-every-document-has]

| Path | Value |
|---|---|
| `entry.id` | The document's id |
| `entry.type` | The type key |
| `entry.uri` | The document's path on this site in the request locale, with the locale prefix. Print it in an `href` with `\|url` |
| `entry.url` | The same as an absolute URL on the site's configured domain |
| `entry.slug` | The slug in the request locale |
| `entry.title` | The title in the request locale |
| `entry.status` | `published` on a public page |
| `entry.locale` | The request locale's code |
| `entry.createdAt`, `entry.updatedAt`, `entry.publishedAt` | Dates in the site's time zone. `publishedAt` is the locale's first publication, `updatedAt` its latest published revision. A type that declares a field of the same name keeps its own value |
| `entry.translations` | A map from every enabled locale's code to `locale`, `exists` (published with a live path on this site), `stale` (it trails its source), `path` and `url` (empty when it does not exist) |
| `entry.tags` | The document's public tags, each `key`, `label` (in the request locale), `kind`, `parent`, `depth`, `colour`, `description` |
| `entry.seo` | `title` (the site's `seo.title_template` applied), `description` (the `summary` as plain text), `image` (the site's `seo.default_image`, absolute), `noindex` and `canonical`. A type that declares its own `seo` field keeps it |
| `entry.overridden` | The names of the fields whose value on this page is this site's own override rather than the shared document's, sorted; empty otherwise. Every field value is already the resolved one |
| `entry.aiAssisted` | Whether the revisions shown carry AI-assisted text the site's disclosure policy discloses; `aiDisclosure(entry)` prints the sentence |
| `entry.variant` | The entry variant's key, on a type that declares variants only |
| `entry.parent` | On a type whose route nests: the parent document, one level deep; empty at a root |
| `entry.ancestors` | On a nesting type: the ancestors, root first; empty at a root or on a flat type |
| `entry.children` | On a nesting type: the published children in the request locale, title order |
| `entry.siblings` | On a nesting type: the parent's other children, title order |
| `entry.<field>` | Every field the type declares, as its field type renders it |

`engine-dmo check` holds `entry.<field>` and `<type key>.<field>` to the schema, so `{{ entry.photo }}` on a type without a `photo` field is an error. It does not follow a document reached any other way: a loop variable over `items`, `query()` results or a relation (`{% for w in entry.relatedWalks %}{{ w.photo }}`), or a component prop. A field those do not have prints nothing, with no error or warning at check or at render, even with `template.strict: true`. Check those names against `engine-dmo describe type <type>` and read the output of `engine-dmo render`.

There is no `entry.author`. A byline is a field you declare, such as a relation to a person or a text field.

With `engine-dmo`, the modules add properties: `entry.organisation` (the organisation that owns a listing, from the CRM module, when it has one) and `entry.landings` (the live landing pages a place has, or that a document is a result of). See the [DMO section](/dmo).

### Field values [#field-values]

Each field prints sensibly on its own and has properties and helpers for everything else:

| Field type | In a template |
|---|---|
| `text`, `slug` | A string |
| `number`, `boolean` | A number or a boolean. Format numbers with `\|number` or `\|currency` |
| `date`, `datetime` | A date value for the date filters: `\|date`, `\|datetime`, `\|time`, `\|iso`, `\|relative` |
| `select` | An option, `value` and `label`, or a list of them |
| `portable_text` | Rich text: print it with `\|ptext`, as plain text with `\|plain`, its headings with `\|toc` |
| `relation` | The related document as an entry (or a list), resolved one level deep. A target that is not published in the locale or not shown on this site is left out |
| `asset` | A media value: `url`, `alt`, `width`, `height` and the rest, and `img()`, `picture()`, `figure()`, `link()`. See [Images](/templates/images) |
| `link` | A link value: `url`, `text` and the rest, and `link()`, `attributes()`. See [Links](/templates/links) |
| `geo`, `address`, `phone`, `opening_hours`, `video`, `form`, `repeater`, `blocks`, `recurrence`, `geo_shape` | See [Fields](/content-modelling/fields) |

`engine-dmo describe fieldtypes` lists every field type's properties and helpers, with the keywords each helper takes. `engine-dmo check` refuses a property or helper a field's type does not have.

### Guides and collections [#guides-and-collections]

A `guide` or `collection` document's entry also has:

| Path | Value |
|---|---|
| `entry.list` | The list as entries, in order: a guide's live items' documents, or a collection's page of documents |
| `entry.listTotal` | How many documents the list holds in all |
| `entry.items` | Guides: the live items, each `document` (an entry) and `note` (plain text) |
| `entry.pagination` | Collections: the page of the list that `?page=` asked for, shaped as an index page's `pagination`. A page past the last answers 404 |
| `entry.jsonld` | The page's `CollectionPage` and `ItemList` structured data, which `jsonld()` merges into the page graph |

On a collection's page `pagination` is also set at the top level of the context.

## An index page [#an-index-page]

Rendered with `<type>/index.html` at the route's `index:` address. The route's `paginate:` sets the page size.

```jinja title="templates/_shared/listing/index.html"
{% extends "base.html" %}
{% block body %}
<h1>{{ t('places.title') }}</h1>
<p>{{ t('index.count', pagination.total) }}</p>
<ul>
  {% for item in items %}<li><a href="{{ item.uri|url }}">{{ item.title }}</a></li>{% endfor %}
</ul>
{% if pagination.pages > 1 %}
<nav aria-label="{{ t('pager.label') }}">
  {% if pagination.prev %}<a rel="prev" href="{{ pagination.prev|url }}">{{ t('pager.previous') }}</a>{% endif %}
  <span>{{ t('pager.page_of', 'page', pagination.page, 'pages', pagination.pages) }}</span>
  {% if pagination.next %}<a rel="next" href="{{ pagination.next|url }}">{{ t('pager.next') }}</a>{% endif %}
</nav>
{% endif %}
{% endblock %}
```

| Variable | Value |
|---|---|
| `items` | The page of published documents of the type on this site in the request locale, in the type's `ordering` (title order without one). Each is an entry with its relations resolved |
| `pagination.page` | The current page, from `?page=`, from 1 |
| `pagination.pages` | How many pages |
| `pagination.total` | How many documents match, exactly |
| `pagination.per` | The page size, the route's `paginate:` |
| `pagination.next`, `pagination.prev` | The path of the next and previous page, keeping the selected facets; empty at the ends |
| `pagination.range` | The page numbers from 1 to `pages`, as plain numbers with no address |
| `facets` | One per field in the route's `facets:` list |
| `page.index` | `true` |
| `page.title` | The type's plural label, an admin word that also becomes the page's `<title>`. Take the `h1` from `t()` rather than printing this. An index has no title or description of its own |
| `page.noindex` | `true` on a filtered page |
| `page.canonical` | The unfiltered index (or, with `engine-dmo`, the most specific landing page the filters match) |
| `page.alternates` | The index in each locale |

The response also carries `Link` headers with `rel="prev"` and `rel="next"`.

Only `pagination.prev` and `pagination.next` are addresses. They keep the selected facets (`/walks?difficulty=easy&page=2`). There is no address for an arbitrary page number, and a link written as `href="?page={{ n }}"` drops every selected facet, which `engine-dmo check` does not report. Build the pager from `prev` and `next`, as above, or print numbered links only on an unfiltered index (`{% if not page.noindex %}`). The strings `pager.label`, `pager.previous`, `pager.next` and `pager.page_of` are your own, in `config/strings/<locale>.yaml`.

Each facet is `field`, `label` (the field's label), `selected` (whether a value is chosen), `clearUrl` (the index without this facet) and `values`. Each value is `value`, `label` (an option's or tag's label in the request locale), `count`, `selected` and `url` (the index with the value chosen, or removed when it is the chosen one). A facet is selected by the query string `?<field>=<value>`.

Facet values are links, not form controls, so draw them as lists of links under a heading inside one navigation landmark, not as a `<fieldset>` and not as one landmark per facet:

```jinja
{% if facets %}
<nav aria-label="{{ t('facets.label') }}">
  {% for facet in facets %}
  <h2>{{ facet.label }}</h2>
  <ul>
    {% for v in facet.values %}<li><a href="{{ v.url|url }}"{% if v.selected %} aria-current="true"{% endif %}>{{ v.label }} ({{ v.count }})</a></li>{% endfor %}
  </ul>
  {% if facet.selected %}<p><a href="{{ facet.clearUrl|url }}">{{ t('facets.clear') }}</a></p>{% endif %}
  {% endfor %}
</nav>
{% endif %}
```

A `select` facet's value labels are the option labels, which must be written as a map per locale (`label: { en: Easy, cy: Hawdd }`); a plain-string option label prints the value instead.

## A landing page [#a-landing-page]

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

A landing page is an index filtered to a place and a category at a clean path. It renders `<type>/landing.html` where the chain has one, else `<type>/index.html`, with everything an index page has, plus `landing` (`key`, `place`, `category`, `title`, `heading`, `description`, `content`, `faq`, `count`, `siblings`, `parents`, `breadcrumbs`, `jsonld` and more) and `page.landing` set to `true`. See [Landing pages](/dmo/landing-pages).

## The search page [#the-search-page]

Rendered with `search.html` at the site's `special.search` route, for the request's `q`, `type`, `tag`, `sort`, `lat`, `lon`, `km` and `page` parameters. The page is never cached.

| Variable | Value |
|---|---|
| `results` | The search results, as `search()` returns them: `items`, `total`, `facets`, `degraded`, `backend`, `query`, `sort`, `page`, `pages`, `hasMore`, `pagination`, `didYouMean`. See [Search in templates](/templates/queries#search) |
| `pagination` | `results.pagination` |
| `page` | `uri`, `canonical`, `title` (`Search`), `type` (`search`), `isPreview` |

## Error pages [#error-pages]

`errors/404.html` and `errors/500.html` receive the globals and the functions, with `page` set to `uri` (the requested path), `title` (`Not found` or `Error`), `type` (`error`) and `isPreview`. They receive no `entry`. Keep them simple: an error template that itself fails falls back to a plain-text response.

## Block templates [#block-templates]

`{% blocks entry.body %}` renders each item of a blocks field through `blocks/<block key>.html` on the site's chain. The block template receives the page's globals and functions, the page's `entry` and `page`, and:

| Variable | Value |
|---|---|
| `block` | The item: its `_type` (the block key), `_key`, and every field of the block by name, rendered as on an entry |
| `blockIndex` | The item's position, from 0 |
| `blockCount` | How many items the field holds |

```jinja title="templates/_shared/blocks/callout.html"
<aside class="callout callout--{{ block.tone.value }}">
  {% if block.title %}<p class="callout__title">{{ block.title }}</p>{% endif %}
  {{ block.content|ptext }}
</aside>
```

`engine-dmo check` refuses a project that declares a block with no `blocks/<key>.html` anywhere on a site's chain. `engine-dmo new block <key>` scaffolds one.

## Rich text serialisers [#rich-text-serialisers]

`|ptext` renders an object block inside rich text through `ptext/<set>/<block key>.html`, where the set is the filter's argument (`default` when none: `|ptext` or `|ptext:"compact"`). The serialiser receives the page's globals and functions, and:

| Variable | Value |
|---|---|
| `node` | The object block, with its fields by name |
| `index` | Its position in the rich text, from 0 |

An object block with no serialiser renders nothing on a public page; under `serve --dev` it shows a notice naming the template to add, and `engine-dmo check` warns about it. Naming a set that has no templates at all is an error at render.

## Endpoint and module templates [#endpoint-and-module-templates]

Declared endpoints (forms and their responses) and some modules render templates with context of their own, such as `form`, `values`, `errors`, `submission`, `signals` and `endpoint`. Those are described with the features: [Forms](/templates/forms), and, with `engine-dmo`, the [member portal](/dmo/partners-and-portal#the-portal).


# Filters (/templates/filters)

Every filter a Meridian template can use, grouped (text, locale-aware formatting of numbers, dates and money, rich text, URLs and encoding, lists, and the Pongo2 built-ins), with its argument, default, output and example.

A filter transforms the value to its left: `{{ value|filter }}`, or with its one argument `{{ value|filter:arg }}`. Filters chain left to right. This page lists every filter a site's templates can use, in both bundles; `engine-dmo template api` prints the same list from the engine itself.

```jinja
{{ entry.title|upper }}
{{ entry.summary|truncate:120 }}
{{ entry.publishedAt|date:"long" }}
{{ entry.description|plain|excerpt:160 }}
{{ listing.website|url }}
```

Two things hold for every filter:

- **The output is escaped** unless the filter says it returns markup. A filter that returns markup returns one of the engine's safe values, which prints as it is.
- **Locale-aware filters read the request locale.** You never pass a locale: the same template prints `14 September 2026` on an English page and `2026年9月14日` on a Japanese one, with the locale's numerals, calendar and hour cycle, and times in the site's time zone unless the value carries its own.

A filter that does not recognise its input (a date filter given text that is not a date, say) returns the input unchanged.

## Dates and times [#dates-and-times]

| Filter | Argument | Output |
|---|---|---|
| `date` | A style or skeleton; `medium` by default | The date in the locale's words and order |
| `datetime` | `"<date style> <time style>"`; `"medium short"` by default, or `"relative"` | The date and time joined as the locale joins them |
| `time` | `short` (default) or `medium` (with seconds) | The time of day in the locale's hour cycle |
| `iso` | none | RFC 3339 with the value's own offset, the same in every locale, for a `datetime` attribute |
| `relative` | none | Relative to now: `in 3 days`, `yesterday`, `2 hours ago` |
| `daterange` | An end date, or a style (`short`, `medium`, `long`, `full`) | Two dates with their shared parts collapsed: `2–3 Nov 2026`, `14 Aug – 2 Nov 2026` |
| `duration` | `long` (default), `short` or `narrow` | A length of time in words: `2 hours, 30 minutes` |

`date` styles are `short`, `medium`, `long` and `full`; the skeletons `yMd`, `yMMMd`, `yMMMMd`, `yMMMEd`, `yMMMMEEEEd`, `Md`, `MMMd`, `MMMMd`, `MMMEd`, `yMMM`, `yMMMM`, `y` and `Ed`; `relative`; and `zone`, which prints the IANA name of the zone the value is shown in. Each renders in the locale's own order. An unknown style renders as `medium`.

```jinja
{{ a.publishedAt|date }}  {# 14 Aug 2026 #}
{{ a.publishedAt|date:"short" }}  {# 14/08/2026 #}
{{ a.publishedAt|date:"full" }}  {# Friday, 14 August 2026 #}
{{ a.publishedAt|date:"yMMMM" }}  {# August 2026 #}
{{ a.publishedAt|date:"MMMEd" }}  {# Fri 14 Aug #}
{{ a.publishedAt|datetime:"long short" }}  {# 14 August 2026 at 10:00 #}
{{ a.publishedAt|time }}  {# 10:00 #}
<time datetime="{{ a.publishedAt|iso }}">{{ a.publishedAt|date:"long" }}</time>
{{ event.startsAt|relative }}  {# in 3 days #}
{{ today|daterange:tomorrow }}  {# 2–3 Nov 2026 #}
{{ "PT2H30M"|duration }}  {# 2 hours, 30 minutes #}
{{ 5400|duration:"short" }}  {# 1 hr, 30 mins #}
```

The date filters accept a date or datetime field's value, `now`, `today`, `tomorrow`, `yesterday`, the engine's dates (`entry.publishedAt`), and text in RFC 3339 or `YYYY-MM-DD` form. A wall-clock time that carries its own zone (an event in Paris on a London site) keeps it; any other instant is shown in the site's time zone.

`daterange` takes either a start with the end as the argument (`start|daterange:end`), or one value holding both: a list of two dates, or a map with `start` and `end`, `from` and `to`, `startsAt` and `endsAt`, or `local` and `localEnd`.

`duration` reads an ISO 8601 duration (`PT2H30M`, days allowed), a Go duration (`2h30m`) or a number of seconds.

A Go reference layout (`|date:"2 Jan 2006"`) still renders, the same way in every locale, and `engine-dmo check` warns about it (`date-layout`) with the named format to use instead.

## Numbers and money [#numbers-and-money]

| Filter | Argument | Output |
|---|---|---|
| `number` | Fixed decimal places; without it, up to three as needed | The locale's grouping, decimal separator and digits: `1,234.5`, `1 234,5`, `١٬٢٣٤٫٥` |
| `currency` | An ISO 4217 code | An amount in that currency for the locale, with the currency's own minor units: `£12.50`, `JP¥1,500` |
| `money` | none | A money value, which carries its own currency, formatted as `currency` |
| `percentage` | Most decimal places; 0 by default | A fraction as a percentage: `0.125` is `13%` |
| `ordinal` | none | An ordinal by the locale's rules: `3rd`, `3.`, `第3` |
| `unit` | `"<unit> <width>"`, width `short` (default), `long` or `narrow` | A quantity of a unit: `12.3 kilometres` |
| `distance` | none | Metres in the viewer's measurement system: `7.5 mi` in `en-GB` and `en-US`, `12,1 km` in `de` |
| `filesize` | none | Bytes as a size in decimal units: `1.6 MB` |
| `list` | `and` (default), `or`, `unit`, `unit-narrow`, `and-short` | A list joined as the locale writes it: `A, B and C`, `A, B or C` |

```jinja
{{ 1234.567|number }}  {# 1,234.567 in en-GB, 1.234,567 in de #}
{{ walk.lengthKm|number:1 }} km  {# 12.3 km #}
{{ 12.5|currency:"GBP" }}  {# £12.50 #}
{{ listing.fee|money }}
{{ 0.1234|percentage:2 }}  {# 12.34% #}
{{ 22|ordinal }}  {# 22nd #}
{{ 20|unit:"celsius long" }}  {# 20 degrees Celsius #}
{{ walk.metres|distance }}  {# 4.7 mi #}
{{ asset.bytes|filesize }}  {# 1.6 MB #}
{{ ["Banbury", "Bicester"]|list:"or" }}  {# Banbury or Bicester #}
```

`currency` accepts a number, a decimal written as text, or a money value; with no code and no currency in the value it returns the input unchanged. The units `unit` knows are `year`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond`, `kilometer`, `meter`, `centimeter`, `millimeter`, `mile`, `yard`, `foot`, `inch`, `hectare`, `acre`, `kilogram`, `gram`, `pound`, `ounce`, `liter`, `milliliter`, `celsius`, `fahrenheit`, `kilometer-per-hour`, `mile-per-hour`, `byte`, `kilobyte`, `megabyte`, `gigabyte`, `terabyte` and `percent`.

## Text [#text]

| Filter | Argument | Output |
|---|---|---|
| `upper`, `lower` | none | Upper or lower case by the locale's rules (Turkish `i` upper-cases to `İ`) |
| `title` | none | Title case by the locale's rules |
| `capfirst`, `ucfirst` | none | The first character upper-cased by the locale's rules |
| `ucwords` | none | The first letter of each word upper-cased |
| `camel`, `pascal`, `kebab`, `snake` | none | `openingHours`, `OpeningHours`, `opening-hours`, `opening_hours`. Words split on anything that is not a letter or digit and on a change from lower to upper case |
| `truncate` | Length in grapheme clusters; 80 by default | Cut to that length with an ellipsis, only when longer |
| `words` | Number of words | The first n words, with an ellipsis when cut |
| `excerpt` | Length in grapheme clusters; 160 by default | Plain text, markup and Markdown removed, whitespace collapsed, cut at a word with an ellipsis |
| `trim` | none | Leading and trailing whitespace removed |
| `length` | none | A string's length in grapheme clusters (what a reader counts as characters), or a list's or map's length |
| `wordcount` | none | The number of words |
| `striptags` | none | HTML tags removed, entities decoded (the result is escaped again when printed) |
| `replace` | `"from=>to"`, or a map of replacements | Every occurrence replaced. Any other argument is an error |
| `mask` | Characters to keep; 4 by default | All but the last n characters as bullets: `••••••7890` |
| `ascii` | none | Accents folded, anything with no ASCII form dropped: `Café Ætna` becomes `Cafe tna` |
| `transliterate` | A language code | Each word romanised, with the language's rules: `Straße` becomes `Strasse` with `de` |
| `slugify` | `mixed` (default), `transliterate` or `native` | A URL slug: `cafe-strasse`; `native` keeps scripts such as `東京-tower` |
| `contains`, `startsWith`, `endsWith` | The text to look for | `true` or `false` |
| `nl2br` | none | Newlines as `<br>`, the text escaped. Returns markup |
| `widont` | none | The last two words joined with a no-break space, the text escaped. Returns markup |
| `markdown` | none | A safe subset of Markdown as HTML. Returns markup |
| `stripMarkdown` | none | Markdown as plain text |

```jinja
{{ entry.title|truncate:40 }}
{{ entry.summary|excerpt:155 }}
<h2>{{ entry.title|widont }}</h2>
{{ entry.notes|nl2br }}
{{ entry.title|replace:"&=>and" }}
{{ entry.reference|mask:4 }}
```

`markdown` renders ATX headings, paragraphs and hard breaks, emphasis and strong, inline code and fenced code blocks, block quotes, bullet and numbered lists one level deep, and links whose scheme `url` accepts. Every character of the input is escaped first, raw HTML stays text, and a link to `javascript:` keeps its text and loses its link.

There is no translation filter: interface text comes from `t()`, which knows the request locale (see [Functions](/templates/functions#t)).

## Rich text [#rich-text]

| Filter | Argument | Output |
|---|---|---|
| `ptext` | A serialiser set; `default` by default | A `portable_text` value as HTML. Headings get `id` anchors from their text (`getting-here`, then `getting-here-2`). Object blocks render through `ptext/<set>/<block key>.html`. Returns markup |
| `plain` | none | Portable Text or Markdown as plain text |
| `toc` | none | A `<nav>` of nested lists linking to the rich text's headings, the same ids `ptext` gives them; empty when there are none. Returns markup |

```jinja
<nav>{{ entry.body|toc }}</nav>
{{ entry.body|ptext }}
{{ entry.body|ptext:"compact" }}
<meta name="description" content="{{ entry.body|plain|excerpt:155 }}">
```

`ptext` renders every span escaped. An object block with no serialiser template renders nothing on a public page. A serialiser template receives the block as `node`, its position as `index`, and the page's globals; naming a set that has no templates at all is an error. See [Rich text serialisers](/templates/context#rich-text-serialisers).

## URLs, JSON and attributes [#urls-json-and-attributes]

| Filter | Argument | Output |
|---|---|---|
| `url` | none | The URL when its scheme is safe (relative, `#`, `?`, `http`, `https`, `mailto`, `tel`, `sms`, `otpauth`), otherwise `#`. A protocol-relative `//host` becomes `#`. Escaped for an attribute. Required on a variable in `href`, `src` and the other URL attributes |
| `json` | none | The value as JSON with `<`, `>`, `&` and the JavaScript line separators escaped, safe inside a `<script>` element. Required on a variable inside `<script>` |
| `attr` | none | A map as escaped HTML attributes: `true` prints the bare name, `false` and nothing leave it out, a list is joined with spaces |
| `urlencode` | none | Percent-encoded for a query string (spaces as `+`) |
| `iriencode` | none | An IRI encoded for use in a URL |
| `escapejs` | none | Escaped for a JavaScript string. Prefer `json` |
| `icsUrl` | none | An event entry's `.ics` address when its route has a calendar, otherwise empty |

```jinja
<a href="{{ listing.website|url }}">{{ t('listing.website') }}</a>
<script>window.page = {{ entry.title|json }};</script>
<a href="{{ entry|icsUrl }}">{{ t('event.add_to_calendar') }}</a>
```

`json` fails the render on a value that holds helper functions, such as a `geo` value or a document from a list; print its plain parts instead (`{{ entry.location.lat|json }}`). The page's own `entry`, tags, addresses, strings and numbers encode.

A template has no map literal, so `attr` is for a map that comes from the context, such as part of `settings`.

## Escaping [#escaping]

| Filter | Output |
|---|---|
| `escape` | The value escaped for HTML. Escaping is automatic; this is for an explicit call |
| `raw` | Prints an engine-produced safe value as it is. On anything else it is an error: `raw requires a Safe value` |

`safe`, `safeseq`, `e`, `escapeseq` and `json_script` are not available. See [Autoescaping](/templates/language#autoescaping).

## Lists and values [#lists-and-values]

| Filter | Argument | Output |
|---|---|---|
| `default` | A fallback | The argument when the value is empty, zero or false |
| `default_if_none` | A fallback | The argument only when the value is nothing |
| `first`, `last` | none | The first or last item of a list, or character of a string |
| `join` | A separator | A list joined with it |
| `split` | A separator | A string split into a list |
| `slice` | `"start:end"`, either side optional, negative from the end | A slice of a list or string |
| `make_list` | none | A string as a list of characters |
| `length_is` | A number | Whether the length equals it |
| `random` | none | A random item of a list |
| `add` | A number, string or list | Adds to a number, appends to a string or list |
| `divisibleby` | A number | Whether the value divides by it |
| `yesno` | `"yes,no,maybe"` | One of the words for true, false and nothing |
| `pluralize` | `"suffix"` or `"singular,plural"`; `s` by default | The plural suffix by count. Prefer `t(id, count)`, which follows the locale's plural rules |
| `integer`, `float` | none | The value as an integer or a float |
| `floatformat` | Decimal places; negative to drop trailing zeros | A float rounded. Prefer `number` for display |
| `stringformat` | A Go format verb, such as `"%05d"` | The value formatted with it |
| `get_digit` | A position from the right | That digit |

## Pongo2 text built-ins [#pongo2-text-built-ins]

These come from Pongo2 and are available unchanged. They do not know the locale.

| Filter | Argument | Output |
|---|---|---|
| `addslashes` | none | Quotes escaped with backslashes |
| `center`, `ljust`, `rjust` | A width | Padded with spaces to the width |
| `cut` | Text | Every occurrence removed |
| `truncatechars` | A length | Cut to that many characters, with an ellipsis |
| `truncatewords` | A number | Cut to that many words, with ` ...` |
| `wordwrap` | A width in words | Wrapped onto new lines |
| `linenumbers` | none | Each line numbered |
| `phone2numeric` | none | Letters on a phone keypad as digits |
| `linebreaks`, `linebreaksbr`, `urlize`, `urlizetrunc`, `removetags` | | These produce HTML, which is then escaped and prints as visible tags. Use `nl2br` and `markdown` instead |
| `truncatechars_html`, `truncatewords_html` | A length | Cut HTML and close its tags. **They print their input as markup without escaping it**, so never apply them to content; use `truncate`, `words` or `excerpt` |

## Development only [#development-only]

`dump` prints a value as a navigable tree. It is not registered when `engine.environment` is `production`, so a stray `|dump` fails to compile there rather than leaking data.

## Not available [#not-available]

`timesince`, `timeuntil`, `filesizeformat`, `dictsort`, `dictsortreversed` and `unordered_list` are removed: use `relative`, `filesize`, `orderBy()` in a query, and a loop or `{% nav %}`. A filter that does not exist is a compile error naming it: `Filter 'frobnicate' does not exist.`


# Forms in templates (/templates/forms)

How a template draws a form that posts to a declared endpoint (form field render(), enquiryForm(), subscribeForm() or hand-built markup), carries the CSRF token and abuse controls, and renders the success and error responses.

A public form posts to a **declared endpoint**: an entry in `config/sites/<key>/endpoints.yaml` that names its path, its inputs and their rules, its spam defences and what it does with a submission. No Go is written. The template's job is to draw the form from that declaration and to render the endpoint's answer. Because the form is drawn from the declaration, an input added to `endpoints.yaml` appears in the form with its label, its rules and its error, in the visitor's language.

This page is the template side. Declaring endpoints, their steps (store, mail, subscribe and the rest) and their spam defences is in [Forms and submissions](/features/forms-and-submissions) and the [endpoints reference](/reference/configuration/endpoints).

## From page to answer [#from-page-to-answer]

The page that shows a form and the endpoint that takes it are separate: the page is a document at its own address, and the form posts to the endpoint's `path`. One post runs like this:

```mermaid
sequenceDiagram
  participant B as Browser
  participant E as Engine
  B->>E: GET the page (/contact)
  E-->>B: Page with the drawn form, action="/contact"
  B->>E: GET /_e/forms.js, then the signed challenge
  B->>E: POST /contact (inputs, _csrf, hidden fields)
  E->>E: Cross-site check, rate limit, spam defences
  E->>E: Validate the inputs against endpoints.yaml
  alt invalid
    E-->>B: 422 with on_error (or the form redrawn with errors)
  else valid
    E->>E: Steps in order: store, mail, subscribe ...
    E-->>B: respond.fragment
  end
```

A form posted in place gets the answer as a patch; a plain post gets it inside your layout ([Rendering the answer](#rendering-the-answer)).

### The form's address and locale [#the-forms-address-and-locale]

`action` is the endpoint's `path` with the site's path prefix and the **request locale's** prefix, and nothing else. An endpoint has one path for every locale, so on a Welsh page at `/cy/cysylltu` the form posts to `/cy/contact`, not to the page's own address. The locale prefix tells the endpoint which language to answer in, and that is the locale its labels, messages, response templates and mail are rendered in.

A page and an endpoint may share an address: a page at `/contact` (a `GET`) and an endpoint with `path: /contact` and `methods: [post]` do not collide, because declared endpoints are matched before content only for the methods they declare. Give the endpoint its own path (`/contact/send`) if you prefer the two to differ.

## Three ways to draw a form [#three-ways-to-draw-a-form]

| Way | Use it when |
|---|---|
| A `form` field's `render()` | Editors choose which form a page shows. The engine draws the whole accessible form |
| `enquiryForm('key')` or `subscribeForm('key')` printed as it is | A template always shows one form. The engine draws the whole form |
| Your own markup from the description `enquiryForm()` returns | You need markup the drawn form does not give |

### A form field [#a-form-field]

Give the type a field of type `form` ([the form field](/content-modelling/fields/form)). Editors pick one of the site's form endpoints, and the template renders it:

```jinja
{% if entry.contactForm %}
  <section aria-labelledby="contact-heading">
    <h2 id="contact-heading">{{ t("form.contact.title") }}</h2>
    {{ entry.contactForm.render(submit=t("form.contact.send"), class="panel") }}
  </section>
{% endif %}
```

`render()` options:

| Option | Default | Effect |
|---|---|---|
| `submit` | The string `form.<key>.submit`, else `form.submit`, else the endpoint's key as words | The button's text |
| `enhance` | `true` | `false` leaves out the in-place post, so the form is a plain post with or without JavaScript |
| any other keyword | | An attribute of the `<form>` element (`class=`, `aria-labelledby=`, `data-*`) |

`id`, `action`, `method`, `enctype` and `data-on:submit` belong to the form and are refused. `render()` takes keywords only.

The value also has the description's properties (`id`, `key`, `action`, `method`, `inputs`, `hidden`, `honeypot`, `honeypotName`, `member`). An empty field, or one naming an endpoint the site no longer declares, is false and prints nothing.

An endpoint a form field can name must take a post from the public or a signed-in member, answer with a page (not JSON or a stream), declare at least one input from the form, and take nothing from its path.

### enquiryForm() and subscribeForm() [#enquiryform-and-subscribeform]

```jinja
{{ enquiryForm('contact') }}
{{ enquiryForm('contact-listing', listing) }}
{{ subscribeForm('newsletter') }}
```

Printed as it is, the value draws the same accessible form as a form field's `render()`, as a plain post (no in-place enhancement). The second argument is the subject an endpoint's path parameters are filled from: for `path: /enquire/{listing}` with an input `listing: { type: relation, from: path }`, `enquiryForm('contact-listing', listing)` posts to `/enquire/<the listing's id>`.

Two things `engine-dmo check` does not catch, so render the page to confirm the form is there:

- **An unknown key prints nothing.** `{{ enquiryForm('contcat') }}` passes the check and renders an empty string.
- **There is no `render()` on it.** Only a `form` field's value has `render()`. `{{ enquiryForm('contact').render() }}` passes the check and prints nothing. Print `enquiryForm()` as it is, or build markup from it.

### Your own markup [#your-own-markup]

`enquiryForm()` and `subscribeForm()` return the endpoint's description. Build the form from it:

```jinja
{% with form = enquiryForm('contact') %}
<form method="post" action="{{ form.action|url }}" id="form-contact"
      data-on:submit="@post(el.getAttribute('action'), {contentType: 'form'})"
      {% if form.challenge %}data-mrd-challenge="{{ form.challenge }}"{% endif %}>
  {{ csrfInput() }}
  {% for k, v in form.hidden %}<input type="hidden" name="{{ k }}" value="{{ v }}">{% endfor %}
  {% if form.honeypot %}
    <p hidden aria-hidden="true"><label for="hp">{{ t("form.leave.blank") }}</label>
    <input id="hp" type="text" name="{{ form.honeypotName }}" tabindex="-1" autocomplete="off"></p>
  {% endif %}

  {% if errors %}{% focus '#form-contact-errors' %}
  <div role="alert" id="form-contact-errors" tabindex="-1">
    <h2>{{ t("form.problems", errors._count) }}</h2>
    <ul>{% for e in errors._summary %}<li><a href="#f-{{ e.path }}">{{ e.message }}</a></li>{% endfor %}</ul>
  </div>
  {% endif %}

  {% for fld in form.inputs %}
  <p>
    <label for="f-{{ fld.name }}">{{ fld.label }}{% if fld.required %} <span aria-hidden="true">*</span>{% endif %}</label>
    {% for issue in errors[fld.name] %}<span id="f-{{ fld.name }}-error">{{ issue.message }}</span>{% endfor %}
    {% if fld.multiline %}
      <textarea id="f-{{ fld.name }}" name="{{ fld.name }}"{% if fld.max %} maxlength="{{ fld.max }}"{% endif %}>{{ values[fld.name] }}</textarea>
    {% else %}
      <input id="f-{{ fld.name }}" name="{{ fld.name }}" value="{{ values[fld.name] }}"
             type="{% if fld.format == 'email' %}email{% else %}text{% endif %}"
             {% if fld.autocomplete %}autocomplete="{{ fld.autocomplete }}"{% endif %}
             {% if errors[fld.name] %}aria-invalid="true" aria-describedby="f-{{ fld.name }}-error"{% endif %}>
    {% endif %}
  </p>
  {% endfor %}
  <button type="submit">{{ t("form.contact.send") }}</button>
</form>{{ form.challengeScript }}
{% endwith %}
```

| Property | Value |
|---|---|
| `key` | The endpoint's key |
| `action` | The address to post to, with the site's path prefix and the locale prefix |
| `method` | `POST` |
| `inputs` | The declared inputs in order, each `name`, `type`, `label`, `help`, `required`, `autocomplete`, `multiline`, `max`, `format`, `options` and `visible_when` where declared. Inputs taken from the path are left out |
| `hidden` | The hidden fields the spam defences need, name to value |
| `honeypot`, `honeypotName` | Whether the endpoint has a honeypot, and its field's name |
| `challenge` | The endpoint's key when it uses the form challenge, else empty; print it as `data-mrd-challenge` |
| `challengeScript` | The `<script>` that fetches the challenge once the page has loaded, or nothing |
| `csrf` | Whether the endpoint checks the CSRF token |

An input with `options` has them in `options`, but the drawn form does not draw a `<select>` or radio buttons from them. An endpoint with a choice input needs your own markup for that input.

A label not declared in the endpoint is its input's name as words (`contactName` reads "Contact name").

## The CSRF token [#the-csrf-token]

Every unsafe request (a post) is checked against cross-site request forgery, in one of two ways:

- **An anonymous visitor** has no session for a token to bind to, so the post is checked by where it comes from: the browser's `Sec-Fetch-Site` must say same-origin (or none), else the `Origin` header's host must be the request's host. A cross-site post is refused with 403, "the form was posted from another site". The token helpers print nothing for an anonymous visitor and set no cookie, so a public page is the same for every visitor and can be page-cached.
- **A signed-in visitor** (a member, or staff) carries a token bound to their session in a field named `_csrf` (or the `X-CSRF-Token` header). A post without a valid token is refused with 403, "the form has expired, reload the page and try again".

So a public page served to an anonymous visitor has an empty `_csrf` and sets no cookie on a running server as well as under `render`, and that is correct, not a fault. Print the token in every form you write yourself, so both cases work:

| Helper | Prints |
|---|---|
| `csrfInput()` | `<input type="hidden" name="_csrf" value="...">`, or nothing for an anonymous visitor |
| `csrfToken()`, `csrf` | The token alone, or empty |

Drawn forms carry it already: for an anonymous visitor the drawn form holds an empty `_csrf` field, which is harmless. A page that printed a token is never stored in the page cache, and a `{% cache %}` block that names a token helper is an error ([Caching](/templates/caching)).

`engine-dmo render` has no visitor and no session, so under it `csrfInput()`, `csrfToken()` and `csrf` print nothing and a drawn form's `_csrf` is empty. That is expected; check the token on a running server, signed in.

## Spam defences in the markup [#spam-defences-in-the-markup]

The defences are declared on the endpoint (`spam: { honeypot, min_fill_time, proof_of_work }`, plus `rate_limit`). A drawn form carries what they need; markup of your own must carry:

- every field of `hidden`;
- the honeypot field, hidden from people and from assistive technology, when `honeypot` is true;
- `data-mrd-challenge` and `challengeScript` when `challenge` is set. The script (`/_e/forms.js`, served by the engine, so allowed by `script-src 'self'`) fetches a signed challenge that dates the form and, for a browser that can compute it, a small proof of work. A browser without JavaScript can still post; the challenge is a cost at volume, never a gate. There is no CAPTCHA.

A script posts as that browser does. With `min_fill_time` set, a post with no challenge answers 422 and draws the form again, so fetch one first: `GET /_e/challenge/<key>` answers `field`, `token`, `minFill`, `proofField` and `proofBits` ([the steps](/agents/recipes/enquiry-form#post-it-from-a-script)). The proof of work is optional.

## Rendering the answer [#rendering-the-answer]

The endpoint's `respond` block names the templates:

```yaml
respond:
  fragment: partials/contact-sent.html      # after a successful post
  on_error: partials/contact-form.html      # after a failed one
```

```jinja
{# templates/_shared/partials/contact-sent.html #}
<div id="form-contact" role="status">
  <h2>{{ t("form.contact.sent.title") }}</h2>
  <p>{{ t("form.contact.sent.body") }}</p>
</div>
```

How the answer arrives depends on the request:

| Request | Answer |
|---|---|
| The in-place post (sigmx, from `data-on:submit`) | The rendered fragment as a patch the page applies by element id, so give the fragment's root the form's `id`. A failure is sent the same way |
| A plain post (no JavaScript) | The fragment inside your `base.html`, as its `{% block body %}`, so your layout must have that block. The status is the endpoint's own (422 for a validation failure) |
| A GET to a fragment endpoint, or a project with no `base.html` | The fragment alone |

A form endpoint, one that takes nothing from its path, with no `on_error` draws its own form again with the errors, as a form field's `render()` draws it, and that is usually what you want. `on_error` is for a hand-built form: it is rendered with the errors and the values posted.

The root element of a response template must have the id `form-<endpoint key>`, the id the drawn form has, since an in-place post replaces the element by that id. `<div id="form-{{ endpoint.key }}">` lets one template serve several endpoints. A response template has the base page context and the variables below, and no `entry`, no `page` values and no type variable such as `listing`.

An endpoint that takes a value from its path (`/enquire/{listing}`) must have an `on_error`. It is not treated as a form, so without one a failed post answers 422 with the success `fragment`. Print `{{ enquiryForm(endpoint.key) }}` in the partial: with no subject it takes the address from the post that failed, so it posts to the same listing again, with the errors and a fresh challenge. The same partial serves any form endpoint.

### What the answer templates see [#what-the-answer-templates-see]

| Variable | Value |
|---|---|
| `errors` | After a failure: each input's issues by name (a list of `code`, `message`, `hint`), `_form` for issues of the whole form, `_summary` (one `path` and `message` per input, in form order) and `_count` (the number of inputs with a problem). Empty after a success |
| `values` | The values posted, by input name, to fill the form again |
| `submission` | After a success: the stored submission |
| `signals` | The values a `signal` step set |
| `endpoint` | The endpoint that answered (`key` and the rest of the description). A layout that also carries the same form, such as a footer sign-up, can leave its own copy out with `{% if endpoint.key != "newsletter" %}` |
| `subscriber` | After a subscription endpoint: the subscriber |

Answer templates can compose a richer in-place response with `{% patchelements %}`, `{% patchsignals %}`, `{% removeelements %}`, `{% focus %}`, `{% announce %}`, `{% location %}` and `{% replaceurl %}` ([Tags](/templates/tags)).

## The drawn form's markup [#the-drawn-forms-markup]

A form drawn by `render()` or by printing `enquiryForm()` has fixed ids, so CSS and a response fragment can target them:

| Element | id or class |
|---|---|
| The `<form>` | `id="form-<key>"`, `class="mrd-form"` |
| Each input | `id="f-<key>-<name>"`, its label `for` it; help in `f-<key>-<name>-help`, the error in `f-<key>-<name>-error`, both wired with `aria-describedby`; `aria-invalid="true"` on a failed input |
| The error summary | `id="form-<key>-errors"`, `role="alert"`, focused after a failed in-place post; each item links to its input |
| The submit button | `id="form-<key>-submit"` |
| The honeypot | `class="mrd-hp"`, hidden |

Inputs are drawn as a text input (`type="email"`, `type="url"` or `type="tel"` for the input's `format` `email`, `url` or `phone`), a `<textarea>` for `multiline`, or a checkbox for a boolean. Nothing else is drawn: an input's `options` never become a `<select>` or radio buttons. Required inputs carry `required` and a visual asterisk hidden from screen readers.

### Strings the drawn form reads [#strings-the-drawn-form-reads]

| String | Used for |
|---|---|
| `form.<key>.submit`, `form.submit` | The button's text |
| `form.problems` | The error summary's heading, plural-aware with `{count}` |
| `form.leave.blank` | The honeypot's label, in the drawn form and in a hand-built one. Without the string the label prints as its id, `form.leave.blank`. The field is hidden, but its label is still in the markup |

Add them to every locale's `config/strings/<locale>.yaml`. Labels, help and validation messages come from the endpoint's own `label`, `help` and rule `message` keys, per locale: give each input's `label` a value for every locale the site enables. `engine-dmo check` warns about a schema field label with no translation, but not about an endpoint input's label, which falls back to the source locale's.

## Email templates [#email-templates]

A `mail` step renders `templates/<root>/emails/<name>.html` on the site's chain (`templates/_shared/emails/` in a single-site project; the check's message says `templates/emails/`, meaning that folder in any root). The template extends `emails/_layout.html`, the engine's layout, and fills its `subject` and `body` blocks. The full list of blocks and the engine's own templates are in [Mail](/features/mail).

```jinja
{# templates/_shared/emails/contact-to-staff.html #}
{% extends "emails/_layout.html" %}
{% block subject %}New enquiry from {{ name }}{% endblock %}
{% block body %}
<p>{{ name }} ({{ email }}) wrote:</p>
<blockquote>{{ message }}</blockquote>
{% endblock %}
```

An email template is not a page template. It sees:

| Name | Value |
|---|---|
| each input, by name | What the visitor posted (`name`, `email`, `message`) |
| `submission` | The stored submission, when a `store` step ran first |
| `replyTo` | The address the step's `reply_to` resolved to, for the template to print. It does not set the message's `Reply-To` header |
| `site.name`, `site.url` | The site's name in the mail's locale, and its address |
| `recipient.email`, `recipient.displayName`, `recipient.locale` | Who it is for |
| `locale` | The mail's locale **as a code string** (`cy`), not the page's `locale` object: write `{{ locale }}` or `{% if locale == "cy" %}`, never `locale.code` |
| `now` | The time of rendering |

Every mail a step sends, the staff copy included, is rendered in the locale of the post: the locale prefix of the form's `action`.

<Callout type="warn" title="No t() in email templates">
The string catalogue is not available to email templates: `t()` prints nothing there, and `engine-dmo check` does not report it. On a site with more than one locale, write each language's text in the template and branch on `locale`:

```jinja
{% block subject %}{% if locale == "cy" %}Diolch am eich neges{% else %}Thank you for your message{% endif %}{% endblock %}
```
</Callout>

`engine-dmo check` compiles each email template, but it does not catch a field read on a plain value (`locale.code`) or an empty subject. Send one to the log before you rely on it: in development the `log` driver writes the message to the output instead of sending it.

```bash
engine-dmo mail test --to you@example.org --template contact-to-staff --locale cy
```

A send that fails reports the template's line and column, such as `not sent: _shared/emails/contact-to-staff.html:3:34: can't access a field by name on type string (variable locale.code)`. The sample context `mail test` uses has no form inputs, so they print empty there.

## In-place posts need sigmx on the page [#in-place-posts-need-sigmx-on-the-page]

`data-on:submit` is a sigmx attribute. The drawn form posts in place only when your bundle loads the sigmx client, which the example projects do from their Vite entry ([Frontend build](/templates/frontend-build)). Without it, the form is a plain post and still works.

## Member forms [#member-forms]

An endpoint with `access: member` is drawn only for a signed-in member, and a page that renders one is sent `Cache-Control: private, no-store`, since what it shows depends on who asked.

## Site search [#site-search]

`searchForm()` prints a GET form to the site's search route in the request locale, labelled from the strings `search.field` and `search.go`, working without JavaScript. It prints nothing when the site routes no search. See [Search](/features/search).

## Related [#related]

- [Forms and submissions](/features/forms-and-submissions): declaring endpoints, steps, storage and retention.
- [Caching](/templates/caching): why a page with a form is not page-cached.
- [Tags](/templates/tags): the response tags.


# Frontend build (/templates/frontend-build)

How stylesheets, scripts and static files reach a page through the assets helpers, with or without a Vite build, how the vite extension reads the build manifest and runs the dev server, and how to stay inside the content security policy with no inline script.

The engine does not own your frontend build. It serves what is in `public/`, and its asset helpers print the right `<link>` and `<script>` tags for a site's bundle: plain files when you have no build step, or the content-hashed files a Vite build wrote when the project uses the `vite` extension. No Node runs in production.

## The helpers [#the-helpers]

```jinja
<head>
  {{ head() }}
  {{ preload() }}
  {{ assets.css('main') }}
  {{ assets.js('main') }}
  <link rel="icon" href="{{ assets.url('favicon.svg') }}" type="image/svg+xml">
</head>
```

| Helper | Prints |
|---|---|
| `assets.css('main')` | The stylesheet links of the site's bundle `main` |
| `assets.js('main')` | Its script as `<script type="module">` |
| `assets.js('legacy', false)` | A classic `<script defer>`, for code that expects globals and order |
| `preload()`, `preload('legacy')` | With the vite extension: `<link rel="modulepreload">` for the bundle's entry and the chunks it imports, and `<link rel="preload" as="style">` for its stylesheets. `main` when no name is given |
| `assets.url('img/logo.svg')` | A file's path with `?v=` and a version from its modification time |

Each site's bundle is its own: the same `assets.css('main')` in a shared layout prints each site's build.

## Without a build step [#without-a-build-step]

With no extension, a bundle name maps to files under `public/`:

| Call | Prints |
|---|---|
| `assets.css('main')` | `<link rel="stylesheet" href="/css/main.css?v=...">` |
| `assets.js('main')` | `<script type="module" src="/js/main.js?v=..."></script>` |
| `assets.js('main', false)` | `<script src="/js/main.js?v=..." defer></script>` |

```text
public/
  css/main.css
  js/main.js
  favicon.svg
```

This is how the bare starter project works, and how a project with a build of its own (any bundler that writes plain file names) can work.

## Static files [#static-files]

Files under `public/` are served at their path when no content route matches. They resolve along a chain per site, first match wins:

1. `public/<site key>/`
2. `public/_shared/`
3. `public/`

So `public/town/favicon.svg` is the town's icon and `public/favicon.svg` everyone else's. Only regular files are served, never directory listings.

| File | `Cache-Control` |
|---|---|
| Requested with `?v=` (as `assets.url` writes it), or under `public/build/` | `public, max-age=31536000, immutable` |
| Anything else | `public, max-age=3600` |

To serve another directory, such as uploads from a legacy site, at a URL prefix after the chain, add a mount to `engine.yaml`:

```yaml
public:
  mounts:
    - { path: /legacy/, dir: ../legacy-site/files }
```

`path` starts and ends with `/`; `dir` is relative to the project.

## With Vite [#with-vite]

The first-party `vite` extension connects a Vite build to the helpers. Vite writes the files and a manifest; the engine reads the manifest and prints the tags:

```mermaid
flowchart LR
  SRC["src/entries/main.js<br/>CSS and JS"] --> V["vite build"]
  M["engine-dmo assets manifest<br/>(read by meridian(), optional)"] -.-> V
  V --> OUT["public/build/<br/>hashed files"]
  V --> MAN["public/build/.vite/manifest.json"]
  MAN --> EXT["vite extension"]
  EXT --> H["assets.css('main')<br/>assets.js('main'), preload()"]
  H --> P["link and script tags<br/>under /build/"]
  OUT --> P
```

- `assets.css()`, `assets.js()` and `preload()` read the build's manifest and print the content-hashed files, under `/build/`;
- `engine-dmo serve --dev` starts the project's Vite dev server as a child process and points the helpers at it, with hot module replacement;
- `engine-dmo assets budget` and `engine-dmo assets unused` report on the build.

<Steps>
<Step>

Name the extension in `engine.yaml`:

```yaml
# config/engine.yaml
extensions:
  - vite
```

The extension ships beside the binary (`extensions/vite.so`; `/app/extensions/vite.so` in the `-vips` container image). Extensions load only in a binary built with cgo, on Linux, macOS or FreeBSD; the `-vips` image is one. A binary built without cgo refuses a project that names one: `this engine is a pure Go build, which cannot load extensions: run the -vips image, a cgo build`. The `extensions:` line of `engine-dmo version` names `cgo` when the binary can load them.

</Step>
<Step>

Write one entry per site at `src/entries/<site key>.js`. It imports the site's stylesheet and script:

```js
// src/entries/main.js
import '../css/site.css';
import '../js/site.js';
```

A site's other bundles are `src/entries/<site key>-<name>.js` (`main-legacy.js` is the bundle `legacy`), or the paths its `site.yaml` names (below).

</Step>
<Step>

Configure Vite to write `public/build/` with a manifest, served under `/build/`.

<Callout title="Which configuration you can use">
The `meridian()` Vite plugin (`vite-plugin-meridian`) is not published to npm. The binary carries it, but writes it only when `engine-dmo init --from` copies a project whose `package.json` names it, which in practice means an example project in a Meridian source checkout. `engine-dmo init` with no flag writes no `package.json` and no plugin. Without a checkout, use the plain Vite configuration below: it works with the `vite` extension, and you list each site's entry yourself. `sigmx`, the client for in-place updates, is published to npm.
</Callout>

With the plugin, the configuration is:

```js
// vite.config.js
import { defineConfig } from 'vite';
import { meridian } from 'vite-plugin-meridian';

export default defineConfig({
  plugins: [meridian()],
  build: { target: 'es2022', cssMinify: true, sourcemap: false },
});
```

`meridian()` asks the engine for each site's bundles (`engine-dmo assets manifest --json`), builds one entry per site bundle, adds to each site's main entry the CSS and JS of every component that resolves for that site, writes `public/build` with a manifest under base `/build/`, and in development reloads the page when a template or a component contract changes.

Without the plugin, the same layout in plain Vite configuration. Add one `input` per site bundle; component CSS and JS are not collected for you, so import them from the entry:

```js
// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/build/',
  build: {
    outDir: 'public/build',
    emptyOutDir: true,
    manifest: true,
    rollupOptions: { input: { 'main/main': 'src/entries/main.js' } },
  },
  server: process.env.MERIDIAN_VITE_ORIGIN
    ? { origin: process.env.MERIDIAN_VITE_ORIGIN, strictPort: true }
    : {},
});
```

The helpers look the bundle up in `public/build/.vite/manifest.json` by its source path (`src/entries/main.js`), so the input's key may be anything. A `package.json` with `"build": "vite build"` and `vite` as a development dependency is all `engine-dmo build` needs.

</Step>
<Step>

Build and check:

```bash
npm install
engine-dmo build
```

`engine-dmo build` runs the `build` script of `package.json` through npm (or `--command "..."`) with `MERIDIAN_ENGINE` set to the running binary, then runs `engine-dmo check`. A failed build exits 1 before the check.

| Flag | Effect |
|---|---|
| `--command string` | The build command, instead of the `package.json` build script |
| `--no-check` | Build only |
| `--no-db` | Check without the database checks |
| `--strict` | Check with warnings as errors |

</Step>
</Steps>

### What the helpers print from the build [#what-the-helpers-print-from-the-build]

| Call | Prints |
|---|---|
| `assets.css('main')` | A `<link rel="stylesheet">` for the entry's CSS and the CSS of every chunk it imports statically, each under `/build/` |
| `assets.js('main')` | `<script type="module" src="/build/...">` for the entry; `assets.js('main', false)` a classic deferred script |
| `preload()` | `modulepreload` for the entry and its imported chunks, `preload as=style` for its stylesheets |

A bundle the manifest does not know falls back to `css/<name>.css` and `js/<name>.js` along the public chain. The manifest is read again when the file changes, so a rebuild needs no restart. The manifest itself is not served.

### Development [#development]

`engine-dmo serve --dev` looks for `vite.config.js` (or `.mjs`, `.ts`, `.mts`, `.cjs`, `.cts`) in the project. With one, and Vite installed in `node_modules/.bin/vite`, it:

- starts Vite on a free loopback port with `--strictPort`, passing `MERIDIAN_VITE_ORIGIN`, `MERIDIAN_PROJECT` and `MERIDIAN_ENGINE` in its environment;
- writes Vite's output into the engine's log and stops Vite on Ctrl+C;
- prints the Vite client once per page and each entry's source URL in place of the built files; `preload()` prints nothing, and `assets.css()` prints nothing for a script entry, whose CSS the dev server injects;
- widens the development content security policy to admit the dev server's origin and inline styles (the dev server injects each stylesheet as a `<style>` element). Only in development.

With a config and no installed Vite, it says so and serves `public/` as it is. CSS changes reach the page through Vite's hot module replacement; with the `meridian()` plugin, saving a template reloads the whole page.

### site.yaml assets [#siteyaml-assets]

```yaml
# config/sites/<key>/site.yaml
assets:
  bundles:
    main: src/entries/town.js
    legacy: src/legacy/town-legacy.js
  budgets:
    css: 60KB
    js: 120KB
    legacy_js: 200KB
  external: false
  manifest: ""
```

| Key | Default | Meaning |
|---|---|---|
| `bundles` | `main` is `src/entries/<site>.js`, any other name `src/entries/<site>-<name>.js` | Each bundle's entry, relative to the project |
| `budgets` | none | Size limits by kind (`css`, `js`, `legacy_css`, `legacy_js`), each the total of that kind across the site's bundles, in bytes or with a unit (`120KB`, `1.5MB`, `64KiB`); `legacy_` counts the bundle named `legacy` apart |
| `external` | `false` | The site is built by a toolchain of its own: the `meridian()` plugin builds no entry for it, and the helpers read `manifest` |
| `manifest` | `public/build/.vite/manifest.json` | A Vite manifest for an external site, relative to the project |

### Reports [#reports]

| Command | Reports |
|---|---|
| `engine-dmo assets manifest [--site key] [--json]` | Each site's template chain, the component directory each component resolves to, co-located component files, blocks, template globs and bundle entries: what a bundler needs. The engine's own, with or without the extension |
| `engine-dmo assets budget [--site key] [--strict]` | Each site's CSS and JS sizes, raw and gzipped, against its budgets and the previous build (remembered in `.meridian/assets-sizes.json`); `--strict` exits 1 over a budget |
| `engine-dmo assets unused [--site key] [--bundle name]` | CSS selectors in a site's bundles that match nothing in that site's templates. Report only |

`engine-dmo render <path> --json` lists the assets the rendered page references.

## Content security policy [#content-security-policy]

The public site's policy is `server.security.csp` in `engine.yaml`. Each key is a directive, with underscores for hyphens, and each value a list of sources. With no `csp` block, no policy header is sent.

```yaml
# config/engine.yaml
server:
  security:
    csp:
      default_src: ["'self'"]
      script_src: ["'self'"]
      style_src: ["'self'"]
      style_src_attr: ["'unsafe-inline'"]
      img_src: ["'self'", "data:", "${MEDIA_CDN_ORIGIN:-}"]
      font_src: ["'self'"]
      connect_src: ["'self'"]
      object_src: ["'none'"]
      base_uri: ["'self'"]
      form_action: ["'self'"]
      frame_ancestors: ["'self'"]
```

- `'unsafe-inline'` and `'unsafe-eval'` are refused in `script_src` and `default_src`: the engine's scripts need neither.
- An empty source is dropped, so an unset `${MEDIA_CDN_ORIGIN:-}` leaves nothing behind.
- `style_src_attr: ["'unsafe-inline'"]` lets image placeholders paint ([Images](/templates/images#placeholders)); no script can be injected through a style attribute, and templates cannot write one.
- A page that renders a video or a third-party embed widens the policy for that response alone, to let the player's host frame it.

The engine's own scripts are files on the site's origin, added only when a page needs them: the form challenge (`/_e/forms.js`), the impressions reporter (`/_e.js`), the video facade (`/_mrd-video.js`) and the embed facade (`/_mrd-embed.js`).

### No inline script [#no-inline-script]

Write behaviour in your bundle, not in the page. `engine-dmo check` enforces the template side:

| In a template | Result |
|---|---|
| A variable inside `<script>` without the `json` filter | Error: `a variable inside <script> must go through \|json` |
| A variable in an inline event handler (`onclick="..."`) | Error; use a sigmx `data-on` attribute with a static expression |
| A variable in a `style` attribute or a `<style>` element | Error; use a class, or a custom property set from a data attribute |
| A variable inside a `<template>` element | Error |
| `style=` or `on...=` passed to a helper | Refused |
| The `safe` filter | Refused unless the site sets `templates.allow_unescaped: true` |

Pass data to your script through `data-*` attributes, or a JSON block, which is data and not executed:

```jinja
<div id="map" data-lat="{{ entry.location.lat }}" data-lon="{{ entry.location.lon }}"></div>
<script type="application/json" id="map-data">{{ entry.title|json }}</script>
```

### sigmx [#sigmx]

The engine's in-place updates (forms posted in place, fragments, the `sigmx.fragment()` helper) use sigmx attributes such as `data-on:submit`. The client is a module your bundle loads. The example projects use the `sigmx` npm package with its Vite plugins, which scan the templates at build time, bundle only the plugins used and precompile every expression, so the policy can refuse `eval`:

```js
// vite.config.js
import { sigmxAuto, sigmxPrecompile } from 'sigmx/vite';
const scan = { root: here, include: ['templates', 'src'] };
// plugins: [meridian(), sigmxAuto(scan), sigmxPrecompile(scan)]
```

```js
// src/js/site.js
import { createSigmx, precompiled } from 'sigmx';
import { plugins } from 'virtual:sigmx-plugins';
import { table } from 'virtual:sigmx-expressions';
import { handlers } from 'vite-plugin-meridian/sigmx';

window.sigmx = createSigmx({
  plugins: [...plugins, ...handlers],
  expressions: precompiled(table, () => () => undefined, (src) => console.warn('not precompiled', src)),
});
```

`vite-plugin-meridian/sigmx` carries the handlers the engine's fragment responses use, so it comes with the plugin and has the same availability. They act on four events the engine sends after a response's patches: `sigmx-focus` (`{% focus %}`, and the error summary of a failed post), `sigmx-announce` (`{% announce %}`), `sigmx-location` (`{% location %}`) and `sigmx-history` (`{% replaceurl %}` and a facet's new address). Without the handlers those four do nothing on the page; the patches themselves still apply. Every form and link works without sigmx; it is enhancement.

## Related [#related]

- [Multisite templates](/templates/multisite): per-site bundles and component overrides.
- [Extensions](/extending/first-party-extensions): what first-party extensions are and how they load.
- [Container images](/deploying/container-images): which image carries extensions.


# Functions (/templates/functions)

Every function a Meridian template can call (links and URLs, interface strings and locale helpers, content queries, head and structured data, feeds, forms and security, analytics, assets and images, embeds, sigmx, upstream sources, and the DMO functions) with arguments, keywords, return values and examples.

Functions are globals called with parentheses: `{{ path('/places') }}`. Some take keyword arguments (`name=value`, see [Keyword arguments](/templates/language#functions-and-keyword-arguments)); `engine-dmo check` refuses a keyword a function does not take, and any keyword to a function that takes none. A function that returns markup returns a safe value that prints as it is.

This page is the complete list. Field values have functions of their own (an image's `picture()`, a link's `link()`, opening hours' `isOpenAt()`), listed per field type by `engine-dmo describe fieldtypes`.

## Summary [#summary]

| Function | Returns |
|---|---|
| [`path()`](#path), [`url()`](#url), [`siteUrl()`](#siteurl) | A path or URL on this or another site |
| [`localeUrl()`](#localeurl), [`localeSwitcher()`](#localeswitcher) | The current page in another locale; a language switcher |
| [`t()`](#t), [`plural()`](#plural), [`dir()`](#dir), [`bidi()`](#bidi) | Interface strings and locale helpers |
| [`query()`](#content), [`nearby()`](#content), [`children()`](#content), [`ancestors()`](#content), [`smartList()`](#content), [`search()`](#content) | Content |
| [`head()`](#head), [`jsonld()`](#jsonld) | The head metadata and structured data |
| [`feedUrl()`](#feedurl), [`feedLinks()`](#feedlinks), [`calendarUrl()`](#calendarurl) | Feeds and calendars |
| [`searchForm()`](#searchform) | The search form |
| [`csrfToken()`](#csrftoken-and-csrfinput), [`csrfInput()`](#csrftoken-and-csrfinput) | The form token |
| [`enquiryForm()`](#enquiryform-and-subscribeform), [`subscribeForm()`](#enquiryform-and-subscribeform) | A declared endpoint's form |
| [`track()`](#track), [`reveal()`](#reveal), [`impressions()`](#impressions), [`analytics()`](#analytics) | Measured links and the analytics script |
| [`assets.*`](#assets-and-preload), [`preload()`](#assets-and-preload), [`images.file()`](#imagesfile) | Static files, bundles and images |
| [`embed()`](#embed) | A privacy-preserving embed |
| [`sigmx.fragment()`](#sigmxfragment) | Attributes for in-place updates |
| [`source()`](#source) | An upstream data source |
| [`aiDisclosure()`](#aidisclosure) | The AI-assistance disclosure |
| [`dump()`](#dump) | A debugging view (development only) |
| [`promoted()`](#promoted-and-promotionlabel), [`promotionLabel()`](#promoted-and-promotionlabel), [`memberTier()`](#membertier), [`hasAffiliateLinks()`](#hasaffiliatelinks) | DMO bundle only |

## Links [#links]

### path [#path]

```text
path('/literal')            a path on this site, with the request locale's prefix
path('type')                the type's index page in the request locale
path('type', entry)         the entry's path (any document value)
path()                      the home page in the request locale
path(..., locale='code')    the same in another locale
path(locale='code')         the current page in that locale
```

```jinja
<a href="{{ path('/') }}">{{ site.name }}</a>
<a href="{{ path('listing') }}">{{ t('nav.places') }}</a>
<a href="{{ path('/about', locale='ja-JP') }}">日本語</a>
```

`path('listing')` gives the index's segment in each locale (`/places`, `/ja/spots`), so a template links to an index without knowing it. A literal path is prefixed and not translated: `path('/places', locale='ja-JP')` is `/ja/places`. `locale=` returns empty for a locale the site does not enable. With no `locale=`, an argument that is neither a path nor a type with an index is returned unchanged. Keywords: `locale`.

### url [#url]

`url(...)` takes what `path()` takes and returns an absolute URL on the origin the visitor is on, port included, so a page served on `localhost:8080` links to `localhost:8080`. The canonical URL and structured data use the site's configured domain instead. Keywords: `locale`.

```jinja
<link rel="alternate" hreflang="ja-jp" href="{{ url(locale='ja-JP') }}">
```

### siteUrl [#siteurl]

`siteUrl(path or type, site=, locale=)` is an absolute URL on a site of the project, on that site's configured domain. The argument is a path starting with `/` (prefixed for the locale) or a type key (the type's index page there). `site=` is the other site's key, this site when not given; `locale=` the locale to link to where that site enables it, its default locale otherwise. When the request came in on a port and the other site lists its domain without one, the link keeps the port.

```jinja
<a href="{{ siteUrl('/events', site='towns') }}">{{ t('nav.events') }}</a>
<a href="{{ siteUrl('event', site='towns', locale=locale.code) }}">{{ t('nav.events') }}</a>
```

### localeUrl [#localeurl]

`localeUrl('cy-GB')` is the current page's path in another locale, or empty where the page has no translation published on this site. A page with no alternates of its own (the search page, an endpoint's response) exists in every locale at the same path.

### localeSwitcher [#localeswitcher]

`localeSwitcher()` prints a `<nav>` listing the locales the current page exists in, the current one marked with `aria-current="page"`, each link with `hreflang` and `lang`. It is labelled from the string `nav.language` when the catalogue has it, and prints nothing when the page exists in one locale only.

```html
<nav class="mrd-locales" aria-label="Language"><ul><li><span aria-current="page" lang="en-GB">English</span></li><li><a href="/ja/access" hreflang="ja-jp" lang="ja-JP">日本語</a></li></ul></nav>
```

## Interface strings and locale [#interface-strings-and-locale]

### t [#t]

Every piece of interface text a template prints comes from the string catalogue, `config/strings/<locale>.yaml`, so a template carries no literal English and a new locale is a file:

```yaml title="config/strings/en-GB.yaml"
strings:
  nav.places: Places
  index.count:
    one: "{count} place"
    other: "{count} places"
  pager.page_of: "Page {page} of {pages}"
```

```jinja
{{ t('nav.places') }}
{{ t('index.count', pagination.total) }}
{{ t('pager.page_of', 'page', pagination.page, 'pages', pagination.pages) }}
```

| Call | Result |
|---|---|
| `t(id)` | The string in the request locale |
| `t(id, count)` | When the second argument is a number: the plural form for it by the locale's CLDR rules (`zero`, `one`, `two`, `few`, `many`, `other`), with `{count}` filled |
| `t(id, name, value, ...)` | `{name}` filled with each value. After a count, the pairs follow it |

The lookup walks the request locale, its fallback chain and the source locale. An id defined nowhere prints as the id itself, and `engine-dmo check` warns at the line (`unknown-string`). `t()` takes no keyword arguments.

### plural [#plural]

`plural(n)` is the CLDR plural category of `n` in the request locale (`one`, `few`, `other` and so on), for the rare branch `t(id, n)` cannot express.

### dir [#dir]

`dir()` is the request locale's direction, `ltr` or `rtl`, the same as `locale.direction`.

### bidi [#bidi]

`bidi(text)` wraps text in `<bdi>`, so a name in another script does not disturb the order of the text around it. Returns markup.

## Content [#content]

These are described in full on [Querying content](/templates/queries):

| Function | Returns |
|---|---|
| `query('type')` | A query over one type: `.where()`, `.tag()`, `.near()`, `.orderBy()`, `.limit()`, `.offset()`, `.exclude()`, `.organisation()`, `.onePer()`, `.with()`, then `.all()`, `.first()`, `.count()`, `.exists()` or `.ids()` |
| `nearby(entry, km, type)` | Up to 12 documents near the entry, nearest first |
| `children(doc)`, `ancestors(doc)` | A nesting document's children (title order) or ancestors (root first) |
| `smartList('key')` | A public smart list: `.limit(n)`, `.all()`, `.first()`, `.count()` |
| `search(q)` | The search service: `.types()`, `.tags()`, `.near()`, `.sort()`, `.facets()`, then `.paginate(n)` or `.limit(n)` |

## Head and structured data [#head-and-structured-data]

### head [#head]

`head()` prints the page's `<title>`, meta description, canonical link, `hreflang` alternates with `x-default`, the robots directive, Open Graph and Twitter card tags, and `rel=prev` and `rel=next` on a paged page, all from what the page context already holds. Print it once, in `<head>`. See [SEO and structured data](/templates/seo-and-structured-data).

### jsonld [#jsonld]

`jsonld()` prints the page's structured data as one JSON-LD `@graph`, cross-referenced by `@id`, built from the types' `structured_data` mappings and the site's settings; `jsonld(entry)` prints one document's entity alone. See [SEO and structured data](/templates/seo-and-structured-data).

```jinja
<head>
  <meta charset="utf-8">
  {{ head() }}
  {{ jsonld() }}
</head>
```

## Feeds and calendars [#feeds-and-calendars]

### feedUrl [#feedurl]

`feedUrl(type, format=)` is the path of a type's feed in the request locale, empty when its route has none. `format=` is `rss` (the default), `atom` or `json`.

### feedLinks [#feedlinks]

`feedLinks()` prints a `<link rel="alternate">` for each of the site's feeds in the request locale; `feedLinks(type)` for one type's. Put it in `<head>`.

### calendarUrl [#calendarurl]

`calendarUrl(type)` is the path of a type's calendar feed in the request locale, empty when its route has none. For one event's `.ics`, use the `icsUrl` filter: `{{ entry|icsUrl }}`.

Feeds and calendars are declared on a route; see the [routes reference](/reference/configuration/routes).

## Forms and security [#forms-and-security]

### searchForm [#searchform]

`searchForm()` prints a GET form to the site's search route that works without JavaScript, with a labelled search input named `q`. It prints nothing when the site routes no search.

```html
<form class="mrd-search" role="search" method="get" action="/search"><label for="mrd-q">What are you looking for?</label> <input id="mrd-q" type="search" name="q" value="" autocomplete="off"> <button type="submit">Search</button></form>
```

### csrfToken and csrfInput [#csrftoken-and-csrfinput]

`csrfToken()` is the token a form posting back to the engine must carry, the same value the `csrf` global prints. `csrfInput()` prints the hidden input that carries it. For an anonymous visitor both print nothing and set no cookie, since an anonymous post is checked by its origin; for a signed-in visitor they print a token bound to the session, and such a page is not stored in the page cache. A `{% cache %}` block that names either is an error. Under `engine-dmo render` both are always empty. See [The CSRF token](/templates/forms#the-csrf-token).

### enquiryForm and subscribeForm [#enquiryform-and-subscribeform]

`enquiryForm('endpoint')` describes a declared endpoint's form: its `action`, its inputs with labels, rules and errors, and its hidden fields. Printed as it is, `{{ enquiryForm('contact') }}`, it draws the complete accessible form. It has no `render()` method (only a `form` field's value has one), and an unknown key prints nothing; `engine-dmo check` reports neither. `subscribeForm('endpoint')` does the same for a subscription endpoint. Both come from the forms module, in both bundles. See [Forms](/templates/forms).

## Measured links and analytics [#measured-links-and-analytics]

### track [#track]

`track(entry, kind, url)` returns a tracked outbound URL (`/r/v1/...`) that records the click against the document, then redirects to the destination. `kind` is one of `website`, `booking`, `phone`, `email`, `directions`, `social`, `event`, `download` or `share` (anything else counts as `website`). `url` is a string, a link value or a phone value. An empty destination returns empty. On a staff preview it returns the destination itself. In an `href`, put it through `|url` as any variable there must be.

```jinja
<a href="{{ track(entry, 'website', entry.website)|url }}" rel="noopener">{{ t('listing.website') }}</a>
```

### reveal [#reveal]

`reveal(entry, kind, value)` is `track()` for a contact detail: with `phone` the value becomes a `tel:` link, with `email` a `mailto:` link, and the returned tracked URL records the interaction before handing over to it. It works without JavaScript.

```jinja
<a href="{{ reveal(entry, 'phone', entry.phone)|url }}">{{ entry.phone.display }}</a>
```

### impressions [#impressions]

`impressions()` prints the script that reports which cards marked `data-mrd-impression` a visitor actually saw (in the viewport for half a second, once per session per page). With no JavaScript nothing is recorded.

### analytics [#analytics]

`analytics()` prints the cookieless analytics client that records impressions and in-page interactions. Print it once, before `</body>`. See [Analytics](/features/analytics).

## Assets and images [#assets-and-images]

### assets and preload [#assets-and-preload]

`assets.url(path)`, `assets.css(bundle)` and `assets.js(bundle, module)` print files and bundles from `public/` (see [Globals](/templates/globals#assets)). `preload(bundle, ...)` prints the preload hints of the named bundles (`main` when none is named) from the build manifest, and nothing without a build integration or under the dev server. See [The frontend build](/templates/frontend-build).

### images.file [#imagesfile]

`images.file('img/team.jpg')` turns a file under `public/` into an image value, with the same `img()`, `picture()` and `figure()` a media asset has, through the same image pipeline. A path with no image under `public/` fails the render. See [Images](/templates/images).

```jinja
{{ images.file('img/team.jpg').img('card') }}
```

## embed [#embed]

`embed(url, title=)` prints a third party's player, map or post as a facade: a notice, a button that loads it, and a plain link to it. Nothing loads from the provider until the visitor presses the button. `title=` names what is embedded, for the button and the announcement; the provider's name when not given. YouTube embeds use the privacy domain.

```jinja
{{ embed('https://www.youtube.com/watch?v=dQw4w9WgXcQ', title='A walk along the canal') }}
```

## sigmx.fragment [#sigmxfragment]

`sigmx.fragment(names, on=, debounce=, history=, focus=)` prints the attributes that make a form or link ask the server for the named fragments of the page and swap them in place, the address bar following:

| Keyword | Value |
|---|---|
| `on` | The event that asks: `change` (the default), `input`, `submit`, or `click` on a link |
| `debounce` | Wait this long after the last event, such as `'300ms'` |
| `history` | `push` (the default), `replace` or `none` |
| `focus` | `new`: move focus to the first item an append added |

```jinja
<form method="get" action="{{ path('listing') }}" {{ sigmx.fragment('results', on='input', debounce='300ms') }}>
```

Every name must be a fragment some template on the site declares with `{% fragment %}`; `engine-dmo check` refuses one that none does. See [Forms](/templates/forms) for fragments and in-place updates.

## source [#source]

`source('name')` reads an upstream declared in `sources.yaml`, cached and behind its circuit breaker. It is empty when the source is not declared or cannot answer, so a template must handle the empty case. See [Integrating](/integrating).

## aiDisclosure [#aidisclosure]

`aiDisclosure(entry)` prints the disclosure sentence when the entry carries AI-assisted text that the site's policy discloses (`entry.aiAssisted`), and nothing otherwise. The sentence is the catalogue's `ai.disclosure` string in the request locale, or the engine's English sentence when the catalogue has none.

```jinja
{% if entry.aiAssisted %}<p class="disclosure">{{ aiDisclosure(entry) }}</p>{% endif %}
```

## dump [#dump]

Development only. `dump(value)` prints a value as a navigable tree, and `dump()` the whole context. It is not registered when `engine.environment` is `production`, so a stray call fails to compile there.

## DMO functions [#dmo-functions]

<Callout title="engine-dmo">These functions are part of the DMO bundle (engine-dmo). In `engine-cms` a template that uses one fails the check with the name of the module it belongs to.</Callout>

### promoted and promotionLabel [#promoted-and-promotionlabel]

`promoted('slot')` is the documents of a promotion slot's live promotions, oldest start first, each an entry with `promotion` (`id`, `slot`, `label`, `startsAt`, `endsAt`) and `organisationId`. For a slot sold per landing page, `promoted('slot', landing)` names the page; on a landing page `promoted('slot')` reads it. `promotionLabel(item)` prints the site's promotion label as visible text, to put inside each placement's link. A slot must be declared in the site's `promotions.yaml`, and a template that renders `promoted()` without printing `promotionLabel()` fails the check (`promoted-unlabelled`).

```jinja
{% set items = promoted('home-feature') %}
{% if items %}<ul class="cards">
  {% for item in items %}<li data-mrd-promotion="{{ item.promotion.id }}"><a href="{{ item.uri|url }}">{{ promotionLabel(item) }} {{ item.title }}</a></li>{% endfor %}
</ul>{% endif %}
```

See [Promotions](/dmo/promotions).

### memberTier [#membertier]

`memberTier(entry)` is the tier key of the active membership the entry's organisation holds on the page's site, or empty when it holds none or the document has no organisation. See [Memberships](/dmo/partners-and-portal#memberships).

### hasAffiliateLinks [#hasaffiliatelinks]

`hasAffiliateLinks(value)` is whether a value (an entry, its relations included) holds a link through an affiliate programme, so the page can print the disclosure:

```jinja
{% if hasAffiliateLinks(entry) %}<p class="affiliate-disclosure">{{ t('affiliate.disclosure') }}</p>{% endif %}
```

See [Affiliates](/dmo/affiliates).


# Globals (/templates/globals)

The variables every public template can read (site, sites, locale, locales, page, request, now, today, settings, singletons, nav, csrf, assets, devMode) with every key each one holds.

Globals are the variables every public page template receives, whatever the page is: entry pages, index pages, the search page, error pages, block and rich text templates, components and partials. The callable globals (`path()`, `query()`, `t()` and the rest) are on [Functions](/templates/functions); what each kind of page adds is on [The page context](/templates/context).

```jinja
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<title>{{ page.title }} | {{ site.name }}</title>
<p>{{ settings.contact.phone }}</p>
<footer>&copy; {{ now|date:"y" }} {{ site.organisation }}</footer>
```

## site [#site]

The site the request is for.

| Key | Value |
|---|---|
| `site.key` | The site's key, its folder name under `config/sites/` |
| `site.name` | The site's name in the request locale |
| `site.shortName` | `short_name` in the request locale, empty when not set |
| `site.organisation` | `organisation` from `site.yaml` |
| `site.baseUrl` | The site's absolute base URL, on its configured domain |
| `site.domains` | The site's `domains` list |
| `site.country` | `country`, an ISO 3166 code |
| `site.timezone` | `timezone`, an IANA zone name |
| `site.defaultCurrency` | `default_currency`, an ISO 4217 code. `site.currency` is the same value |
| `site.embedOnly` | Whether the site runs in embed-only mode |
| `site.robots` | `noindex, follow` in embed-only mode (the engine also sends it as an `X-Robots-Tag` header), else empty |

## sites [#sites]

On a project with more than one site, every site, each `key`, `name` (in the request locale) and `baseUrl`. Not set on a single-site project. Use `siteUrl()` to link to a page on another site.

```jinja
{% if sites %}<nav aria-label="{{ t('nav.sites') }}">{% for s in sites %}<a href="{{ s.baseUrl|url }}"{% if s.key == site.key %} aria-current="true"{% endif %}>{{ s.name }}</a>{% endfor %}</nav>{% endif %}
```

## locale and locales [#locale-and-locales]

`locale` is the request locale:

| Key | Value |
|---|---|
| `locale.code` | The locale code, such as `en-GB` |
| `locale.label` | Its name in its own language, such as `English` or `日本語` |
| `locale.isDefault` | Whether it is the site's default locale |
| `locale.direction` | `ltr` or `rtl` |
| `locale.language` | The language subtag, such as `en` |
| `locale.currency` | The locale's currency code |
| `locale.firstDayOfWeek` | `0` for Sunday to `6` for Saturday |
| `locale.calendar` | The calendar the formatting filters use, such as `gregory` |
| `locale.numbering` | The numbering system, such as `latn` |

`locales` is the site's enabled locales, each with the same keys. For a language switcher that lists only the locales the current page is published in, use `localeSwitcher()` or `page.alternates`; `locales` lists them all.

## page [#page]

The page being rendered: always `uri`, `canonical`, `title`, `type` and `isPreview`, and more on some pages (`alternates`, `index`, `noindex`, `description`, `landing`). The keys of each kind of page are on [The page context](/templates/context).

## request [#request]

What a template may know about the request. It is deliberately small: no headers, no cookies, no IP address, so a page stays cacheable and private.

| Key | Value |
|---|---|
| `request.path` | The request path, with the locale prefix |
| `request.query` | The query string, as a map from name to value: `request.query.q` |
| `request.isSecure` | Whether the request came over HTTPS (directly, or with `X-Forwarded-Proto: https`) |

Reading a query parameter outside the canonical set makes the page uncacheable, and `engine-dmo check` warns at the read (`uncacheable-query`). The canonical set is `page`, `sort`, `q`, `type`, `tag`, `lat`, `lon`, `km`, and every field a route of the site lists in `facets:`.

## now, today, tomorrow, yesterday [#now-today-tomorrow-yesterday]

| Variable | Value |
|---|---|
| `now` | The time of the request, in the site's time zone |
| `today` | Midnight at the start of the request's date, in the site's time zone |
| `tomorrow`, `yesterday` | Midnight of the day after and the day before |

They are never in the server's zone or in UTC, so a site in summer time does not see today begin at one in the morning. Format them with the date filters: `{{ today|date:"full" }}`. Compare them with dates directly: `{% if entry.endsAt < now %}`.

## settings [#settings]

The site's `settings:` block from `site.yaml`, nested maps and lists as written. It is the place for values a template needs that are not content, such as a contact email or a social profile URL.

```yaml title="config/sites/main/site.yaml"
settings:
  contact:
    email: hello@example.test
  social:
    instagram: https://www.instagram.com/example
```

```jinja
<a href="mailto:{{ settings.contact.email }}">{{ settings.contact.email }}</a>
<a href="{{ settings.social.instagram|url }}">Instagram</a>
```

Secrets never belong here: configuration files may not hold secrets, which come from environment variables.

## singletons [#singletons]

The site's singleton documents by type key. `singletons.<type>` is that type's one document on the site, published in the request locale, shaped as `entry` is, or empty when nothing is published. It is read only when a template reaches it, so listing singletons costs nothing on a page that does not use them.

```jinja
{% with footer = singletons.siteFooter %}
  {% if footer %}{{ footer.text|ptext }}{% endif %}
{% endwith %}
```

`engine-dmo check` reports a key that is not a singleton type on the site (`unknown-singleton`). Singletons are declared in the schema; see [Content types](/content-modelling/types).

## nav [#nav]

The site's navigation by slot. Each slot is declared under `nav:` in `site.yaml` and filled in the admin:

```yaml title="config/sites/main/site.yaml"
nav:
  main: { id: nav_q69bmrm00d, label: { en-GB: Header }, depth: 1 }
  footer: { id: nav_fw01bn2kgg, label: { en-GB: Footer columns }, depth: 2 }
```

`nav.main` is a list of items, resolved for the site and the request locale, with targets that are not available left out. Each item is:

| Key | Value |
|---|---|
| `label` | The label in the request locale |
| `url` | The address: a document's live path, an asset's URL, a site path, an external URL or a type's index page; empty for a heading |
| `kind` | What the item points at |
| `isExternal` | Whether it leaves the site |
| `isCurrent` | Whether it links to the page being rendered |
| `isActive` | Whether it or one of its descendants is current |
| `depth` | Its level, from 1 |
| `children` | Its child items |

Render a tree with the `nav` tag (see [Tags](/templates/tags#nav-children-and-ifchildren)):

```jinja
<nav aria-label="{{ t('nav.main') }}"><ul>
{% nav item in nav.main %}
  <li><a href="{{ item.url|url }}"{% if item.isCurrent %} aria-current="page"{% endif %}>{{ item.label }}</a>
  {% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}</li>
{% endnav %}
</ul></nav>
```

## csrf [#csrf]

The token a form posting back to the engine must carry. It is minted when a template prints it, which sets the binding cookie, so a page that never prints it stays free of cookies. `csrfToken()` returns the same token and `csrfInput()` the hidden input that carries it.

```jinja
<form method="post" action="{{ path('/enquiry') }}">
  {{ csrfInput() }}
  ...
</form>
```

## assets [#assets]

Files and bundles from `public/`:

| Call | Prints |
|---|---|
| `assets.url('css/site.css')` | The file's path with a version from its modification time (`/css/site.css?v=tnuoz7`), so a changed file is fetched again |
| `assets.css('main')` | A `<link rel="stylesheet">` for the bundle `main` |
| `assets.js('main')` | A `<script type="module">` for the bundle `main` |
| `assets.js('legacy', false)` | A classic `<script defer>` |

Files resolve along the site's public chain: `public/<site key>/`, then `public/_shared/`, then `public/`. Without a build integration, bundle `main` is `css/main.css` and `js/main.js`. With the Vite extension, a bundle resolves to the built, content-hashed files, and to the Vite dev server under `serve --dev`. See [The frontend build](/templates/frontend-build).

## devMode [#devmode]

`true` when the engine runs with `engine-dmo serve --dev`, otherwise `false`. Use it for development-only markup; never to hide content.


# Images (/templates/images)

How to print responsive images from asset fields and theme files with img(), picture() and figure(), configure named transforms, breakpoints and art direction in config/images.yaml, and check what a page downloads.

Every image a template prints goes through named **transforms**: a shape (an aspect ratio and a fit), a ladder of widths, a list of formats and a default `sizes`. You declare the transforms once in `config/images.yaml`, and a template asks for one by name. The engine writes the `srcset`, `sizes`, `width`, `height`, `alt` and loading attributes, generates each derivative the first time it is requested, and never upscales.

## A minimal example [#a-minimal-example]

```yaml
# config/images.yaml
breakpoints:
  md: 48rem
  lg: 64rem

transforms:
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
    sizes: "100vw"
```

```jinja
{# templates/_shared/article/entry.html #}
{% if article.heroImage %}
  {{ article.heroImage.figure("hero", priority=true, class="article__hero") }}
{% endif %}

{% for related in article.related %}
  {% if related.heroImage %}{{ related.heroImage.img("card") }}{% endif %}
{% endfor %}
```

`figure("hero", priority=true)` prints a `<figure>` holding a `<picture>` with a `<source>` per format, the `<img>` with its whole `srcset`, and the caption and credit in a `<figcaption>`. Because it is the page's main image, it loads eagerly with `fetchpriority="high"`, and the engine adds a preload for it to the `<head>`.

Run `engine-dmo media transforms` to see each transform resolved, with its ladder of widths and the formats this build serves.

## Where image values come from [#where-image-values-come-from]

An image value is what each of these gives a template:

| Source | Example |
|---|---|
| An `asset` field holding an image | `entry.heroImage`; with `multiple: true`, a list to loop over |
| A video's poster | `entry.film.poster` |
| A relation's target, a promoted item, a list item | `item.heroImage` |
| A file under the project's `public/` directory | `images.file("img/team.jpg")` |

An empty asset field is false, and its methods print nothing, so `{% if entry.heroImage %}` is only needed when you wrap the image in markup of your own. Printing the value itself, `{{ entry.heroImage }}`, prints the original file's URL.

The field's own configuration (which kinds of file an editor may choose, minimum dimensions, required alt text, per-use focal points and captions) is described in [the asset field](/content-modelling/fields/asset).

## Methods [#methods]

| Method | Prints |
|---|---|
| `img(transform, ...)` | An `<img>` with `src`, `srcset`, `sizes`, `width`, `height`, `alt`, `loading` and `decoding="async"` |
| `picture(transform, ...)` | A `<picture>` with one `<source>` per format (and per art-direction source), then the `<img>` |
| `figure(transform, ...)` | The `picture` inside a `<figure>`, with the caption and the credit line in a `<figcaption>` |
| `transform(name, width=)` | A transform object, for markup you build by hand (below) |
| `url(transform, width=, format=, absolute=)` | The address of one derivative; `url` read as a property is the original |
| `link(text=, ...)` | Any asset: a download link announcing the type and size, such as "Annual report (PDF, 2.1 MB)" |
| `audio(...)` | An audio asset: `<audio controls>` with a download link inside for a browser without audio |

### Options of img, picture and figure [#options-of-img-picture-and-figure]

| Option | Values | Default | Effect |
|---|---|---|---|
| `sizes` | A shorthand such as `"lg:33vw md:50vw 100vw"`, a full media list, or `"auto"` | The transform's `sizes` | The `sizes` attribute |
| `priority` | `true` or `false` | `false` | Marks the page's main image: `loading="eager"`, `fetchpriority="high"` and a `<link rel="preload" as="image">` with `imagesrcset` and `imagesizes` added to the head |
| `loading` | `lazy` or `eager` | `lazy` | The loading attribute, when `priority` is not set |
| `fetchpriority` | `high`, `low` or `auto` | none | The fetchpriority attribute |
| `placeholder` | `dominant`, `blur` or `none` | `defaults.placeholder` in `images.yaml`, else `dominant` | What paints the box before the image arrives |
| `alt` | A string | The value's alt text | Alt text for this call only; `alt=""` marks it decorative here |

Any other keyword becomes an attribute of the `<img>` (of the `<figure>`'s image for `figure`). Keywords may contain hyphens:

```jinja
{{ entry.heroImage.picture("card", class="card__img", data-role="lead", aria-describedby="credit") }}
```

`class` is merged with the engine's own classes. `src`, `srcset`, `width`, `height` and `style` belong to the helper and are refused, as are inline event handlers (`onload=`). A keyword one or two letters away from an option (`sizez=`) is reported as a misspelling.

### The url method [#the-url-method]

| Option | Default | Meaning |
|---|---|---|
| first argument | none | The transform; with none, the original |
| `width` | the largest step | The narrowest derivative at least this wide |
| `format` | the transform's fallback format | `jpeg`, `png`, `webp` or `avif` |
| `absolute` | `false` | `true` for an address on the site's origin, which an Open Graph tag needs |

```jinja
<link rel="preload" as="image" href="{{ entry.heroImage.url('hero', width=1600) }}">
<meta property="og:image" content="{{ entry.heroImage.url('social', absolute=true) }}">
```

You rarely need the second line: [`head()`](/templates/seo-and-structured-data) writes the Open Graph image itself.

### The transform object [#the-transform-object]

`transform(name, width=)` returns the parts, for an `<img>` you write yourself:

| Property or method | Value |
|---|---|
| `src` | The fallback format's derivative at the ladder's middle width (with `width=`, the narrowest step at least that wide) |
| `srcset` | The fallback format's `srcset` |
| `srcsetFor(format)` | One format's `srcset` |
| `sizes` | The transform's sizes, expanded from the shorthand |
| `width`, `height`, `aspect` | The output's proportions for `src` |
| `sources` | Each `<source>` a `picture` would print: `type`, `media`, `srcset`, `sizes` |
| `placeholder` | The blurred preview as a data URI |
| `dominant` | The dominant colour, `#rrggbb` |
| `attributes(...)` | `src`, `srcset`, `sizes`, `width` and `height` as one attribute string, plus any keywords you pass |

```jinja
{% set t = entry.heroImage.transform("card") %}
<img {{ t.attributes(class="card__img") }} alt="{{ entry.heroImage.alt }}">
```

Prefer `attributes()`. A variable printed into `src` or `srcset` by hand must go through the `url` filter, and `engine-dmo check` warns about a hand-built `<img>` whose `srcset` has width descriptors and no `sizes`.

## Properties [#properties]

| Property | Value |
|---|---|
| `url` | The original file's URL |
| `id` | The asset's id (empty for a theme file) |
| `kind` | `image`, `document`, `audio` or `video` |
| `mime`, `extension`, `type`, `filename`, `title` | The media type, the lower-case extension, the type as a reader names it (`JPG`), the file name, the title (else the file name) |
| `bytes`, `size` | The size in bytes, and formatted for the request locale (`2.1 MB`) |
| `width`, `height`, `aspect`, `orientation` | The image's dimensions after its crop, its width over its height, and `landscape`, `portrait` or `square` |
| `alt`, `altLang`, `decorative` | The per-use alt text, else the asset's for this site and locale; the locale it came from when it is a fallback; whether an empty alt is intended |
| `caption`, `captionLang` | The same for the caption |
| `credit`, `creditRequired` | The rights credit line, and whether the licence requires it to be shown |
| `focal` | `{x, y}`: the per-use focal point, else the asset's |
| `hotspot`, `crop` | `{x, y, w, h}` in fractions of the whole image, the per-use one else the asset's, else empty |
| `dominant` | The dominant colour, `#rrggbb` |

When the alt text or caption came from a fallback locale, `img`, `picture` and `figure` write it with a `lang` attribute, so a screen reader pronounces it correctly.

### Credits [#credits]

An image whose licence requires a credit (`creditRequired`) must show it. `figure()` always writes the credit. When you print an image with `img()` or `picture()`, `engine-dmo check` warns unless the same template prints the image's `credit`:

```jinja
{{ entry.heroImage.img("card") }}
{% if entry.heroImage.credit %}<p class="credit">{{ entry.heroImage.credit }}</p>{% endif %}
```

## config/images.yaml [#configimagesyaml]

The install's breakpoints, defaults and transforms. Without the file there are no transforms, and every image method needs one. A site may add or replace transforms in `config/sites/<key>/images.yaml`.

```yaml
# config/images.yaml
breakpoints:                 # named min-widths, used by sizes shorthands and art direction
  md: 48rem
  lg: 64rem

defaults:
  formats: [avif, webp, jpeg]               # sources in this order; JPEG is the <img> fallback
  quality: { avif: 55, webp: 75, jpeg: 80 }
  widths: { min: 320, max: 2560, ratio: 1.25 }
  density: 2
  placeholder: dominant

transforms:
  thumb:
    width: 200                              # a fixed display width: 1x and 2x
    aspect: "1:1"
  card:
    aspect: "3:2"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
  hero:
    aspect: "16:9"
    widths: { min: 640, max: 2560 }
    sizes: "100vw"
  square:
    aspect: "1:1"
    widths: [480, 800, 1200]                # an explicit ladder
  hero-art:                                 # art direction: a square crop on narrow screens
    sources:
      - { below: md, transform: square }
      - { transform: hero }
  logo:
    width: 200
    fit: contain
    background: transparent
  social:
    width: 1200
    aspect: "1.91:1"
    formats: [jpeg]
```

### breakpoints [#breakpoints]

A map of name to a positive CSS length in `rem`, `em` or `px`. Each is a min-width. `from: lg` in an art-direction source means `(min-width: 64rem)`; `below: md` means `(max-width: 47.99rem)` (0.02 under for `px`).

### defaults [#defaults]

| Key | Type | Built-in default | Meaning |
|---|---|---|---|
| `formats` | list of `avif`, `webp`, `jpeg`, `png` | `[avif, webp, jpeg]` | The formats each transform produces. A `picture` lists them as sources best first (AVIF, WebP, then the rest); the `<img>` fallback is JPEG when the list has it, else PNG, else the last format listed |
| `quality` | map of format to integer | `{ avif: 55, webp: 75, jpeg: 80 }` | Per format; PNG is lossless |
| `widths` | `{ min, max, ratio }` | `{ min: 320, max: 2560, ratio: 1.25 }` | The generated ladder |
| `density` | integer | `2` | The highest pixel density a fixed-width transform serves |
| `placeholder` | `dominant`, `blur` or `none` | `dominant` | The placeholder every image paints unless a call says otherwise |

`density` and `placeholder` are defaults only; a transform cannot set them.

### A transform [#a-transform]

| Key | Type | Meaning |
|---|---|---|
| `aspect` | string `"W:H"` | The output's proportions, such as `"3:2"` or `"1.91:1"`; without it, the source's own |
| `fit` | `cover`, `contain` or `inside` | `cover` (the default) crops to the aspect around the hotspot and focal point; `contain` fits inside the box and pads with `background`; `inside` fits inside and keeps the source's proportions |
| `background` | `#rrggbb` or `transparent` | The padding colour for `fit: contain`; transparent padding becomes white in JPEG. With any other fit it is a warning |
| `width` | integer | A fixed display width, served at 1x up to `density`x with `x` descriptors; such a transform writes no `sizes` |
| `height` | integer | Only with `width` and no `aspect`; sets the aspect to `width:height` |
| `widths` | `{ min, max, ratio }` or a list of integers | The ladder, as a range or used as written |
| `formats` | list | Replaces the default formats |
| `quality` | map of format to integer | Over the default qualities |
| `sizes` | string | The default `sizes`, as a shorthand or a full media list |
| `animated` | `first` or `keep` | An animated GIF keeps its first frame (`first`, the default) or is served as the original GIF (`keep`) |
| `sources` | list of `{ below or from, transform }` | Art direction (below). A transform with `sources` takes only `sources` and `sizes` |

A transform has exactly one of `width`, `widths` (a list) or a range (`widths: { ... }`, else the default range). Widths are between 16 and 8,192 pixels. Names are lower-case letters, digits, hyphens and underscores; names starting with an underscore are reserved for the engine's own transforms.

### The width ladder [#the-width-ladder]

- A range generates widths from `min` to `max`, each `ratio` times the last, rounded to a multiple of 8. A step within half a step of `max` is dropped in favour of `max`.
- A list is used as written.
- **Nothing is upscaled.** Widths above the widest box the source can fill are dropped, and that width joins the ladder as its top step, so a 1,000 pixel photograph in a 2,560 ladder serves at most 1,000 pixels.
- A fixed-width transform serves its width at 1x, 2x and so on up to `density`.

`engine-dmo media transforms --source-width 1000` shows each ladder for a source of that width.

### The sizes shorthand [#the-sizes-shorthand]

`"lg:33vw md:50vw 100vw"` names breakpoints from the largest down and ends with the default. It expands to `(min-width: 64rem) 33vw, (min-width: 48rem) 50vw, 100vw`. A string that is already a full media list is used as written. `sizes="auto"` on a lazy image writes `sizes="auto, <the transform's sizes>"`, which browsers that support it size from the layout.

### Art direction [#art-direction]

A transform with `sources` renders a different crop per breakpoint:

```yaml
transforms:
  hero-art:
    sources:
      - { below: md, transform: square }
      - { transform: hero }
```

`picture("hero-art")` prints a `<source media="(max-width: 47.99rem)">` per format with the `square` crop, then the `hero` crop as the `<img>`. Only the last source may have no breakpoint; a source may not name another art-direction transform or the same breakpoint twice. With `priority=true`, the preload is the `<img>`'s own crop.

### Per-site transforms [#per-site-transforms]

```yaml
# config/sites/town/images.yaml
transforms:
  card:
    aspect: "4:3"
    widths: { min: 320, max: 1200 }
    sizes: "lg:33vw md:50vw 100vw"
```

A site's transform **replaces** the install's transform of the same name whole, not key by key: restate every key you need. Breakpoints and defaults are the install's.

### What check reports [#what-check-reports]

`engine-dmo check` reports every problem in `images.yaml` together, each at its line and column: an unknown key, a breakpoint that is not a length, a breakpoint used and not declared, a ratio at or below 1, a `min` above `max`, an aspect that does not parse, an art-direction source naming an unknown transform or a breakpoint twice, a reserved name, and a transform whose largest output exceeds `media.max_pixels`. In templates it reports a literal transform name or `sizes` breakpoint that the site does not define (with a "did you mean"), an attribute the helper owns, an unknown keyword, and a second `priority=true` on the same page as a warning.

## Formats and the build you run [#formats-and-the-build-you-run]

What a build can encode depends on its image processor. The `image pipeline` line of `engine-dmo version` names it and what it encodes:

| Build | Encodes | Notes |
|---|---|---|
| The `-vips` image (libvips) | AVIF, WebP, JPEG, PNG | Converts to sRGB, strips metadata, sharpens lightly after downscaling |
| A build with the Go image processor (`pure-go`) | JPEG, PNG | Configured AVIF and WebP are left out of the markup, never failed; `engine-dmo check` prints a note naming them |

The note reads `note: the image transforms name avif and webp, which this build cannot encode; it serves the rest, and the vips image serves all of them`. It is not a warning and changes nothing: the page serves JPEG and PNG. A transform without `formats` inherits the default `[avif, webp, jpeg]`, so every such transform names AVIF and WebP. To silence the note on a build that will only ever serve JPEG, set `defaults: { formats: [jpeg] }` (or `formats: [jpeg]` on each transform); leave the default if production runs the `-vips` image.

An SVG asset is never rasterised: its methods serve the original with no `srcset` or sources.

## Placeholders [#placeholders]

`dominant` sets the image's background colour to its dominant colour; `blur` sets a 16 pixel blurred preview as the background image. Both are written as a `style` attribute by the engine, so a content security policy must allow inline style attributes (`style_src_attr: ["'unsafe-inline'"]`) for them to show. Templates themselves can never write a `style` attribute. `none` writes nothing.

## Theme images [#theme-images]

Images that belong to the design rather than to content (a team photograph, a background illustration) live under `public/` and go through the same pipeline:

```jinja
{% set team = images.file("img/team.jpg") %}
{{ team.figure("card", alt=t("about.team_alt")) }}
```

`images.file(path)` reads a file under the project's `public/` directory (refusing a path that leaves it) and returns an image value with every method above. It has no alt text of its own, so pass `alt=`. Its derivatives are cached by the file's content hash.

`images.breakpoints` lists the breakpoints (`name`, `value`, `from`, `below`) and `images.transforms` the site's transforms (`name`, `aspect`, `fit`, `sizes`, `formats`, `width` or `widths`, `artDirected`), for a template that needs them.

## How derivatives are made and served [#how-derivatives-are-made-and-served]

- A derivative is generated the first time it is requested, once even under concurrent requests and across replicas, then stored. If generation fails, the request is redirected to the original (not cached), and the next request tries again.
- Its address is named by what it is (the asset, its version, its framing and the transform's resolved definition), not by the transform's name. Renaming a transform reuses every derivative; changing one produces new addresses on the next render, with no purge.
- Derivatives and originals are served with `Cache-Control: public, max-age=31536000, immutable`.
- Publishing a document renders its pages and generates the derivatives they reference in the background. `engine-dmo media warm` does the same on demand, and `engine-dmo warm --media` queues it for every published page after a deploy.
- Derivatives not served for `media.derivatives.keep_unused` (90 days by default) are pruned nightly; `engine-dmo media prune` runs it by hand.

## Checking what a page downloads [#checking-what-a-page-downloads]

- `engine-dmo render <path> --json` adds an `images` report: each image on the page with its transform, the `sizes` written, the ladder, the formats, and each derivative's bytes and whether it is stored yet. Without `--json` it prints a short table on standard error. It needs a database ([Testing](/templates/testing)).
- Under `engine-dmo serve --dev`, a development script compares each image's drawn width with the candidate the browser chose and reports an image that downloads far more pixels than it shows, with a suggested `sizes`, in the browser console and in `engine-dmo dev status`.

## Related [#related]

- [The asset field](/content-modelling/fields/asset): what editors can choose, alt text and framing.
- [Media](/features/media): the library, uploads, rights and the commands.
- [Images configuration reference](/reference/configuration/images).


# Templates (/templates)

How a request becomes a page, which template file renders each kind of page, how the template chain resolves names, and the commands that show what a template receives.

Meridian renders every public page on the server from HTML templates in your project's `templates/` directory. A template is plain HTML with Pongo2 template syntax (Django and Jinja style) for printing values, looping and inheriting layouts. The engine decides which template to render from the URL, builds the template's context (the variables it can read), renders it, and sends the result.

This page explains that path end to end. The rest of the section is the reference:

<Cards>
  <Card title="The template language" href="/templates/language" />
  <Card title="The page context" href="/templates/context" />
  <Card title="Globals" href="/templates/globals" />
  <Card title="Querying content" href="/templates/queries" />
  <Card title="Filters" href="/templates/filters" />
  <Card title="Tags" href="/templates/tags" />
  <Card title="Functions" href="/templates/functions" />
</Cards>

Everything here applies to both bundles: `engine-cms` and `engine-dmo` render templates the same way. The commands below use `engine-dmo`; replace it with `engine-cms` on a CMS project.

## A minimal page [#a-minimal-page]

A new project has a layout, one type template and two error pages:

<Files>
  <Folder name="templates" defaultOpen>
    <Folder name="_shared" defaultOpen>
      <File name="base.html" />
      <Folder name="page" defaultOpen>
        <File name="entry.html" />
      </Folder>
      <Folder name="errors" defaultOpen>
        <File name="404.html" />
        <File name="500.html" />
      </Folder>
    </Folder>
  </Folder>
</Files>

```jinja title="templates/_shared/base.html"
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
</head>
<body>
  <main id="main">{% block body %}{% endblock %}</main>
</body>
</html>
```

```jinja title="templates/_shared/page/entry.html"
{% extends "base.html" %}
{% block body %}
<h1>{{ entry.title }}</h1>
{% endblock %}
```

A request for `/about` finds the published `page` document whose slug is `about`, renders `page/entry.html` with that document as `entry`, and `base.html` supplies the surrounding layout. `head()` writes the title, description, canonical link and the rest of the head metadata (see [SEO and structured data](/templates/seo-and-structured-data)).

<Callout title="The starter layout is a placeholder">
The `base.html` that `engine-dmo init` writes is smaller than the one above: it prints its own `<title>` and canonical link and has no `head()`. `engine-dmo check` therefore prints `warning: this head has no head() and its own tags miss a meta description` on a brand-new project, and still exits 0 with `0 errors, 0 warnings`, because template warnings are not counted ([Testing](/templates/testing#engine-dmo-check)). Replace the starter's `<title>` and `<link rel="canonical">` with `{{ head() }}`, as above, before you build on it. The core `page` type has only `title` and `slug`, so `head()` has no description for a page until you add a `summary` or `seo` field to it ([SEO](/templates/seo-and-structured-data#titles)).
</Callout>

## How a request becomes a page [#how-a-request-becomes-a-page]

The engine answers a request in this order. The first step that claims the path answers it.

```mermaid
flowchart TD
  R["Request"] --> SL["Pick the site (host)<br/>and the locale (prefix or host)"]
  SL --> EP{"An engine path?<br/>endpoint, feed, search, sitemap ..."}
  EP -- yes --> EPA["The engine or module answers"]
  EP -- no --> C{"A route matches?"}
  C -- "a document" --> DOC["type/entry.html"]
  C -- "an index" --> IDX["type/index.html"]
  C -- "a landing page" --> LND["type/landing.html"]
  C -- no --> F{"A file under public/?"}
  F -- yes --> FILE["The file"]
  F -- no --> RD{"A redirect rule?"}
  RD -- yes --> RED["The redirect, or 410"]
  RD -- no --> NF["errors/404.html, 404"]
```

<Steps>
<Step>
**Site and locale.** The request's host picks the site (a site lists its `domains` in `site.yaml`), and the path's locale prefix, or the host under the domain strategy, picks the locale. The rest of the path is what the site resolves.
</Step>
<Step>
**Engine paths.** `/robots.txt` and the sitemap, the embed widgets, a staff member's preview, declared endpoints (form posts and fragments), a route's feeds and calendars, the search route, tracked outbound redirects (`/r/v1/...`) and any path a module serves are handled before content. Only `GET` and `HEAD` go further.
</Step>
<Step>
**Content.** The path is resolved against the site's routes:
- a document's address renders the document with its type's entry template;
- a route's `index:` address renders the type's index page;
- with `engine-dmo`, a landing page (a category in a place) renders the type's landing template.
</Step>
<Step>
**A miss.** A path no document or index answers is tried as a file under `public/` (along the site's public chain), then against the redirect rules, and otherwise renders the not-found template with status 404.
</Step>
</Steps>

Every page is rendered completely in memory first. If the render fails, nothing of it is sent: the visitor gets the error template with status 500, and the error is logged with the file, line and column.

## Which template renders what [#which-template-renders-what]

| Page | Template | Status | What the template adds to the context |
|---|---|---|---|
| A document | `<type>/entry.html`, or the file the type's `template:` names | 200 | `entry`, the same value under the type's key, `page` |
| A document in an entry variant with its own `template:` | that file, by convention `<type>/<variant>.html` | 200 | as above, with `entry.variant` |
| The home page | the entry template of the home document's type (`home:` in `routes.yaml`) | 200 | as a document |
| A type's index (`index:` on its route) | `<type>/index.html` | 200 | `items`, `pagination`, `facets`, `page` with `page.index` true |
| A landing page (`engine-dmo`) | `<type>/landing.html`, else `<type>/index.html` | 200 | as an index, plus `landing` |
| The search route (`special.search`) | `search.html` | 200 | `results`, `pagination`, `page` |
| Not found | `errors/404.html` (`template.not_found_template`) | 404 | `page` with `type` `error` |
| A render error | `errors/500.html` (`template.error_template`) | 500 | `page` with `type` `error` |
| An item of a blocks field | `blocks/<block key>.html` | | `block`, `blockIndex`, `blockCount` |
| A rich text object block | `ptext/<set>/<block key>.html` | | `node`, `index` |

When the not-found or error template is missing from the chain the engine answers with a plain-text response instead. The search route answers 404 when the chain has no `search.html`. The full context of each kind of page is on [The page context](/templates/context).

There is no fallback to a flat `<type>.html`: a project that still has one gets a `missing-type-template` finding from `engine-dmo check`, naming the file it expects.

## The template chain [#the-template-chain]

Each site has an ordered list of template roots, its chain. A name such as `page/entry.html` is looked up in each root in turn and the first file that exists wins. The default chain is the site's key, then `_shared`:

```yaml title="config/sites/main/site.yaml"
templates:
  roots: [main, _shared]   # the default; list your own to change it
```

So `templates/main/page/entry.html` overrides `templates/_shared/page/entry.html` for the site `main` alone.

Three resolution rules matter:

1. **Extending your own name reaches the next root.** A file that extends or includes the name it is itself resolved as skips its own root and continues along the chain. `templates/main/page/entry.html` can write `{% extends "page/entry.html" %}` and replace one block of the shared file, with no special keyword.
2. **Relative first.** An include or extends name is tried relative to the including file's directory first, then from the top of each root.
3. **Never outside the directory.** Names are relative to the templates directory. `..` and absolute paths are refused.

A root-qualified name, such as `_shared/page/entry.html`, resolves to exactly that file. Multisite projects use the chain heavily; see [Multisite templates](/templates/multisite).

## Template configuration [#template-configuration]

The `template:` block of `config/engine.yaml`:

| Key | Default | Meaning |
|---|---|---|
| `dir` | `templates` | The templates directory, relative to the project |
| `contract` | `1` | The template contract version the project is written against |
| `cache` | `true` | Keep parsed templates in memory. `false` rereads every template on each render, as `serve --dev` does |
| `strict` | `false` | Refuse to boot when a template reads a variable or field that does not exist. Without it such a read is a warning and renders empty |
| `not_found_template` | `errors/404.html` | The template for a 404 |
| `error_template` | `errors/500.html` | The template for a 500 |

And per site, in `site.yaml`:

| Key | Default | Meaning |
|---|---|---|
| `templates.roots` | `[<site key>, _shared]` | The site's template chain |
| `templates.allow_unescaped` | `false` | Allow `{% autoescape off %}` and the `safe` filter in this site's templates. See [Autoescaping](/templates/language#autoescaping) |

At boot the engine parses every template on every site's chain and runs the template check. A template that does not parse stops the boot. Other findings refuse a production boot and are warnings in development; an unknown variable or field refuses a boot only with `template.strict: true`.

## Seeing what a template receives [#seeing-what-a-template-receives]

You never have to guess what a page's context holds. These commands read the project and, where they say so, the database:

| Command | What it tells you | Needs a database |
|---|---|---|
| `engine-dmo describe route /places/the-red-lion --json` | Which route and template answer the path, and the whole context with real values | Yes |
| `engine-dmo render /places/the-red-lion` | The rendered page through the real pipeline, in process, with no server. `--json` adds errors, queries, assets and accessibility findings | Yes |
| `engine-dmo describe template listing/entry.html` | The file the name resolves to on the site's chain, what it extends and includes, and the type it renders | No, but every `${VAR}` the configuration uses must be set |
| `engine-dmo template api --json` | Every global, filter, tag and field type the site's templates can use, with your own types and fields | No |
| `engine-dmo check` | Every template parsed and checked against the context, the schema and the security rules | Use `--no-db` to skip database checks |

`render` and `describe route` take `--site`, `--locale` and `--host` to pick what the request would carry. A render made by these commands is not counted as a visit. Without a database there is no way to render a page: `render`, `describe route` and `engine-dmo a11y audit` all stop with `MRD-3001` when they cannot connect. Create a local database for them ([Install](/getting-started/install)).

In development, `engine-dmo serve --dev` rereads a template and everything it extends or includes on every request, and a template that fails shows a development error page with the file, line, column and the source line marked, in place of the site's error template. That page is never shown without `--dev`.

## Add a template for a type [#add-a-template-for-a-type]

<Steps>
<Step>
Scaffold it: `engine-dmo new template listing` writes `listing/entry.html` in the shared root (`--site main` writes into the site's own root). For an existing template, `engine-dmo new template listing/entry.html --from-shared --site main` copies the shared one into the site's root so you can change it there.
</Step>
<Step>
Look at what the page will receive: `engine-dmo describe route <a listing's path> --json`.
</Step>
<Step>
Write the template, then run `engine-dmo check`. Fix every error it reports at its file, line and column.
</Step>
<Step>
Render it: `engine-dmo render <the path>`, or open it under `engine-dmo serve --dev`.
</Step>
</Steps>


# The template language (/templates/language)

The Pongo2 syntax Meridian templates use (printing, expressions, filters, keyword arguments, inheritance, includes, macros, loops, whitespace) and the escaping and security rules the engine enforces on every template.

Meridian templates are written in [Pongo2](https://github.com/flosch/pongo2), a Go implementation of Django's template language. If you know Django, Jinja or Twig, most of it reads the same. This page covers the syntax as Meridian uses it, including what Meridian adds (keyword arguments), what it removes, and the escaping rules every template is held to.

## Syntax at a glance [#syntax-at-a-glance]

```jinja
{% extends "base.html" %}

{% block body %}
  {# A comment, never rendered #}
  <h1>{{ entry.title }}</h1>

  {% if entry.summary %}
    <p>{{ entry.summary|truncate:160 }}</p>
  {% endif %}

  <ul>
  {% for place in query('listing').orderBy('title').limit(6).all() %}
    <li><a href="{{ place.uri|url }}">{{ place.title }}</a></li>
  {% empty %}
    <li>{{ t('places.none') }}</li>
  {% endfor %}
  </ul>
{% endblock %}
```

| Delimiter | Use |
|---|---|
| `{{ expression }}` | Print a value, escaped for HTML |
| `{% tag ... %}` | A tag: control flow, inheritance, includes, and the engine's own tags |
| `{# ... #}` | A comment on one line |
| `{% comment %}...{% endcomment %}` | A comment over several lines |

## Expressions [#expressions]

| Form | Example | Notes |
|---|---|---|
| Strings | `"text"`, `'text'` | Either quote |
| Numbers | `3`, `2.5` | |
| Booleans and nothing | `true`, `false`, `nil` | `nil` prints nothing |
| Lists | `["listing", "event"]` | A list literal. There is no map literal: `{"a": 1}` does not parse |
| Attributes | `entry.title`, `entry["title"]`, `locales.0.code` | A missing attribute is empty, and `engine-dmo check` reports it when it can know |
| Arithmetic | `+ - * / % ^` | `+` also joins two strings. `/` on two integers is integer division (`10 / 4` is `2`); `10.0 / 4` is `2.5`. `^` is power |
| Comparison | `== != < > <= >=` | |
| Logic | `and or not`, `&& \|\|` | Parentheses group |
| Membership | `"a" in "abc"`, `x in list` | For "not in", write `not (x in list)` |

A `{{ }}` or `{% %}` must be written on one line: a newline inside one is a parse error (`Newline not allowed within tag/variable`), so a long query chain stays on a single line.

Not supported: the `~` concatenation operator (use `+` or the `add` filter), `//` and `**`, and the inline `x if y else z` form (use `{% if %}`).

A boolean prints as `True` or `False`. Print a word from the string catalogue with `t()` or use the `yesno` filter instead.

## Filters [#filters]

A filter transforms the value to its left. Filters chain left to right, and a filter takes at most one argument, after a colon:

```jinja
{{ entry.title|upper }}
{{ entry.summary|truncate:120 }}
{{ entry.publishedAt|date:"long" }}
{{ entry.description|plain|truncate:160 }}
```

Every filter is listed on [Filters](/templates/filters). Anything that needs more than one option is a function or a value's helper with keyword arguments.

## Functions and keyword arguments [#functions-and-keyword-arguments]

Globals such as `path()`, `query()` and `t()` are called with parentheses. Meridian adds keyword arguments to Pongo2: inside the parentheses of a call, `name=value` passes an option by name.

```jinja
{{ path('/places', locale='ja-JP') }}
{{ siteUrl('/events', site='towns') }}
{{ entry.heroImage.picture('hero', sizes='100vw', priority=true, class='hero__img') }}
{{ entry.website.link(class='button', aria-describedby='booking-note') }}
```

The rules:

- Positional arguments come first. A positional argument after a keyword is an error.
- A keyword name may contain hyphens, so `aria-label=` and `data-track=` are keywords.
- Keywords work inside `{{ }}` and inside the expressions of `{% %}` tags, wherever a call has parentheses.
- Each function and helper declares the keywords it takes. `engine-dmo check` refuses, at the keyword's line and column, a keyword the callee does not take (with a "did you mean"), a keyword given twice, and any keyword passed to a function that takes none, such as `t()`. The same rule is enforced at render time.
- A tag's own `name=value` arguments outside parentheses belong to the tag, as in `{% component 'card' tone='stale' %}` and `{% with total=items|length %}`. Macros take positional arguments only.

The functions and their keywords are listed on [Functions](/templates/functions). A field value's helpers (`img()`, `link()`, `render()` and the rest) are listed per field type by `engine-dmo describe fieldtypes`.

## Inheritance [#inheritance]

A layout declares blocks; a child template extends it and replaces the blocks it needs. `{{ block.Super }}` prints the parent's content of the block being replaced.

```jinja title="templates/_shared/base.html"
<title>{% block title %}{{ page.title }} | {{ site.name }}{% endblock %}</title>
<main id="main">{% block body %}{% endblock %}</main>
```

```jinja title="templates/_shared/listing/entry.html"
{% extends "base.html" %}
{% block title %}{{ entry.title }}, {{ block.Super }}{% endblock %}
{% block body %}<h1>{{ entry.title }}</h1>{% endblock %}
```

Put `{% extends %}` first in the file; anything in a child template outside its blocks is not rendered. A file that extends the name it is itself resolved as reaches the same name further along the site's template chain, which is how a site overrides one block of a shared template (see [The template chain](/templates#the-template-chain)).

## Includes [#includes]

`{% include "partials/footer.html" %}` renders another template in place with the current context. `with name=value` adds variables for the included template, and `only` gives it those variables and nothing else, not even the globals:

```jinja
{% include "partials/footer.html" %}
{% include "partials/greeting.html" with name="Ana" %}
```

<Callout type="warn" title="Partials are checked on their own">
`engine-dmo check` checks every template file against the page context, without knowing what an include passed it. A partial that reads a variable only an `include ... with` provides is reported as `"name" is not in the template context`, which fails the check. Write a partial that needs arguments as a [macro](#macros) or a [component](/templates/components) instead, and keep included partials to what every page has (`site`, `t()`, `path()`, `entry` on an entry page and so on).
</Callout>

## Macros [#macros]

A macro is a reusable piece of markup with positional arguments and defaults. To use it from another file, mark it `export` and import it by name:

```jinja title="templates/_shared/partials/macros.html"
{% macro badge(text, tone="info") export %}<span class="badge badge--{{ tone }}">{{ text }}</span>{% endmacro %}
```

```jinja
{% import "partials/macros.html" badge %}
{{ badge(t('listing.new')) }}
{{ badge(t('listing.closed'), "warning") }}
```

For anything with named props, slots or attributes, use a [component](/templates/components): it is checked against a declared contract.

## Variables and scope [#variables-and-scope]

```jinja
{% set count = items|length %}
{% with total=pagination.total per=pagination.per %}{{ total }} / {{ per }}{% endwith %}
```

`{% set %}` binds a name for the rest of the current scope. `{% with %}` binds names for its body only. A block template, a rich text serialiser, a component's markup and an included partial with `only` do not see the page's `set` variables; they see the page's globals.

## Loops [#loops]

```jinja
{% for item in items %}
  <li class="{% cycle 'odd' 'even' %}">{{ forloop.Counter }}. {{ item.title }}</li>
{% empty %}
  <li>{{ t('index.empty') }}</li>
{% endfor %}

{% for key, value in settings %}{{ key }}: {{ value }}{% endfor %}
{% for code in ["en-GB", "cy-GB"] reversed %}{{ code }}{% endfor %}
{% for code in ["en-GB", "cy-GB"] sorted %}{{ code }}{% endfor %}
```

| Inside a loop | Value |
|---|---|
| `forloop.Counter` | Position from 1 |
| `forloop.Counter0` | Position from 0 |
| `forloop.Revcounter` | Items left, counting this one |
| `forloop.Revcounter0` | Items left after this one |
| `forloop.First`, `forloop.Last` | Whether this is the first or last pass |
| `forloop.Parentloop` | The enclosing loop's `forloop` |

Two loop variables (`key, value`) iterate a map. Over a list, use one.

## Whitespace [#whitespace]

A hyphen inside a delimiter trims the whitespace on that side, including newlines:

```jinja
<ul>
  {%- for x in items -%}
  <li>{{- x.title -}}</li>
  {%- endfor -%}
</ul>
```

`{% spaceless %}...{% endspaceless %}` removes whitespace between tags in its body.

## Autoescaping [#autoescaping]

Every value printed with `{{ }}` is escaped for HTML. This cannot be turned off from a template:

- `{% autoescape off %}`, the `safe` filter and the `safeseq` filter are not available. A template that uses them does not compile: `Usage of filter 'safe' is not allowed`.
- `raw` prints a value unescaped only when the engine produced it as markup. Values that are already safe are the output of the engine's own helpers and filters: `|ptext`, `|markdown`, `|nl2br`, `|widont`, `|json`, `|url`, `|attr`, an image's `picture()`, a link's `link()`, `head()`, `jsonld()` and the like. These print correctly without `raw`; `raw` exists so a template can say so. On any other value `raw` is an error: `|raw requires a Safe value`.

The engine's safe values are typed for the place they go: HTML, a URL, a JavaScript value, a CSS value or a set of attributes. Content an editor typed is never one of them, so content never becomes markup by accident.

Why `safe` is refused: a template that marks a stored value safe turns every editor, importer and integration that can write that value into someone who can put script on the public site. If a site has a genuine need, the site opts in explicitly in `site.yaml` and owns the consequence:

```yaml title="config/sites/main/site.yaml"
templates:
  allow_unescaped: true
```

<Callout type="error" title="Two Pongo2 filters print markup unescaped">
`truncatechars_html` and `truncatewords_html` return their input as markup without escaping it, even with `allow_unescaped` off, and `engine-dmo check` does not flag them. Never apply them to content. To shorten text use `truncate`, `words` or `excerpt`, which return plain text that is escaped.
</Callout>

## The security rules [#the-security-rules]

`engine-dmo check` reads every template with an HTML context tracker and refuses a value printed where escaping does not protect it:

| Where the value is printed | Rule | Finding |
|---|---|---|
| Inside `<script>` | Must go through `\|json`: `const data = {{ entry\|json }};` | `script-context` |
| `href`, `src`, `action`, `formaction`, `srcset`, `poster` | The first value in the attribute must go through `\|url`, or come from `path()`, `url()`, `siteUrl()`, `assets.*`, `feedUrl()`, `calendarUrl()` or `\|icsUrl`. `\|url` rejects `javascript:` and `data:` | `url-context` |
| An `on*` event handler attribute | Not allowed. Use a `data-on` attribute and pass values in `data-*` attributes | `event-handler` |
| A `style` attribute or a `<style>` element | Not allowed. Use a class, or a custom property set from a data attribute | `style-context` |
| An attribute value without quotes | Not allowed: write `name="{{ value }}"` | `unquoted-attr` |
| Inside a `<template>` element | Not allowed: its content is cloned by script after escaping | `template-element` |

```jinja
<a href="{{ entry.uri|url }}">{{ entry.title }}</a>
<a href="{{ path('listing') }}">{{ t('nav.places') }}</a>
<script type="application/json" id="map-data">{{ entry.address|json }}</script>
```

## What Meridian removes from Pongo2 [#what-meridian-removes-from-pongo2]

These Pongo2 built-ins are not available in site templates, because they ignore the request locale, duplicate an engine filter, or expose the server:

| Removed | Use instead |
|---|---|
| `{% now %}` | `now`, `today` and the date filters, which use the site's time zone and the visitor's locale |
| `{% ssi %}`, `{% autoescape %}` | `{% include %}`; see Autoescaping |
| `timesince`, `timeuntil` | `\|relative` |
| `filesizeformat` | `\|filesize` |
| `e`, `escapeseq` | Escaping is automatic |
| `safe`, `safeseq` | `\|raw` on an engine-produced value |
| `json_script` | `\|json` inside a script element |
| `dictsort`, `dictsortreversed` | Sort in the query: `orderBy()` |
| `unordered_list` | A loop, or `{% nav %}` for a tree |

## Development only [#development-only]

Outside production (`engine.environment` other than `production`), `dump(value)` and the `dump` filter print a value as a navigable tree, and `dump()` with no argument prints the whole context. In production they are not registered, so a stray one fails to compile rather than leaking data.

## Errors [#errors]

A template error always carries the file, the line, the column and the source line with a caret:

```text
_shared/page/entry.html:12:14: Filter 'frobnicate' does not exist.
   12 |   <p>{{ entry.title|frobnicate }}</p>
      |              ^
```

`engine-dmo check` reports every problem in every template together. Under `engine-dmo serve --dev` a failed render shows the same detail on a development error page.


# Links and URLs (/templates/links)

How a template builds links with path(), url(), siteUrl() and localeUrl(), prints an entry's address, renders link and asset fields, and why every variable in href or src goes through the url filter.

Templates never assemble an address from strings. A document's address comes from its route, so it is read from the entry; a literal path, a type's index and another site are built by helpers that add the site's path prefix and the locale prefix; and an editor's link comes from a link field that resolves its target, its text and its attributes. If a route or a locale prefix changes, every link follows.

## A minimal example [#a-minimal-example]

```jinja
<nav>
  <a href="{{ path('/') }}">{{ t("nav.home") }}</a>
  <a href="{{ path('event') }}">{{ t("nav.whats_on") }}</a>
  <a href="{{ path('/visit/accessibility') }}">{{ t("nav.access") }}</a>
</nav>

{% for article in items %}
  <a href="{{ article.uri|url }}">{{ article.title }}</a>
{% endfor %}

{% if entry.bookingUrl %}{{ entry.bookingUrl.link(text=t("event.book"), class="button") }}{% endif %}
```

- `path('/')` is the home page with the locale prefix the site's strategy needs.
- `path('event')` is the index page of the `event` type in the request's locale, whatever segment its route gives it in that locale.
- `article.uri` is the article's own path; a variable in `href` goes through `|url`.
- `bookingUrl.link()` prints the editor's link with the text, `rel`, new-tab announcement and class the editor chose.

## The url filter rule [#the-url-filter-rule]

`engine-dmo check` refuses a variable printed into `href`, `src`, `action`, `formaction`, `srcset` or `poster` unless it goes through the `url` filter:

```jinja
<a href="{{ entry.uri|url }}">          {# accepted #}
<a href="{{ entry.uri }}">              {# error: a variable inside href must go through |url #}
```

The filter validates the scheme. Relative paths, `#fragment`, `?query`, `http`, `https`, `mailto`, `tel`, `sms` and `otpauth` pass; anything else (`javascript:`, `data:`, a protocol-relative `//host`) becomes `#`. It also escapes the value for the attribute.

Values built by the engine's own helpers are already safe, so these need no filter: `path(...)`, `url(...)`, `siteUrl(...)`, `assets.url(...)`, `feedUrl(...)`, `calendarUrl(...)`, the `icsUrl` filter, and a field value's method called with parentheses, such as `entry.heroImage.url('hero')`. A property read without parentheses (`entry.uri`, `entry.url`, `item.url`, `pagination.next`, `localeUrl('fr')`) needs `|url`.

## Helpers [#helpers]

### path() [#path]

| Call | Returns |
|---|---|
| `path()` | The site's home in the request locale: `/`, or `/fr/` under a prefix strategy |
| `path('/visit')` | The literal path with the site's path prefix and the request locale's prefix |
| `path('event')` | The `event` type's index page in the request locale; the argument itself when the type has no index route on the site |
| `path('event', entry)` | The entry's own path (`entry.uri`); empty when the second argument is not an entry |
| `path('/visit', locale='fr')` | The path in another locale the site enables; empty when it does not enable it |
| `path(locale='fr')` | The current page in that locale, as `localeUrl('fr')` |

A path starts with `/`. Anything without a leading slash is read as a type key.

### url() [#url]

`url(...)` takes the same arguments as `path()` and returns an absolute URL on the origin the visitor is on (scheme, host and port of the request). Use it where an absolute address is needed and the visitor's own host is right, such as a share link. For an address search engines read (canonical, hreflang, sitemaps, structured data), the engine uses the site's configured domain itself; see [SEO and structured data](/templates/seo-and-structured-data).

### siteUrl() [#siteurl]

An absolute URL on any site of the project, for a link from one site to another:

```jinja
<a href="{{ siteUrl('/', site='county') }}">{{ t("nav.county_site") }}</a>
<a href="{{ siteUrl('listing', site='county', locale=locale.code) }}">{{ t("nav.places") }}</a>
```

| Argument | Default | Meaning |
|---|---|---|
| first | `/` | A path starting with `/`, or a type key for that type's index page on the target site |
| `site` | this site | Another site's key; an unknown key is an error at render |
| `locale` | the target site's default locale | A locale the target site enables; ignored when it does not enable it |

The host is the target site's domain. When the visitor came in on a port (in development, `town.localhost:8080`), the link keeps the port. An absolute URL as the first argument is an error.

### localeUrl() and the language switcher [#localeurl-and-the-language-switcher]

| Helper | Returns |
|---|---|
| `localeUrl('fr')` | The current page in another locale; empty where the page has no translation published on this site |
| `localeSwitcher()` | A ready-made `<nav>` of the locales this page exists in, the current one marked |
| `locales` | The site's enabled locales, for a switcher you build yourself |
| `entry.translations` | Each enabled locale's `{ locale, exists, stale, url, path }` for this document |

```jinja
<ul>
{% for code, tr in entry.translations %}
  {% if tr.exists %}<li><a href="{{ tr.path|url }}" hreflang="{{ code }}" lang="{{ code }}">{{ code }}</a></li>{% endif %}
{% endfor %}
</ul>
```

## An entry's address [#an-entrys-address]

| Property | Value |
|---|---|
| `entry.uri` | The path on this site, with the locale prefix (`/whats-on/film-club`) |
| `entry.url` | The same, absolute |
| `entry.translations.<code>.path` and `.url` | The document in another locale on this site; both empty when it does not exist there |
| `page.uri` | The current page's path |
| `page.canonical` | The page's canonical URL, absolute on the site's configured domain |
| `page.alternates` | The locales the page exists in on this site, each `locale`, `hreflang`, `url` (absolute) and `path` |

Use `uri` for a link on the page, `{{ item.uri|url }}`: it is a path, so the link stays on whatever host the visitor is on. Use `url` only where an absolute address is needed, such as a share link or an email. Both are correct in `href`; the examples in this handbook use `uri`.

A document with no route on the site has no `uri` or `url`. Relations, list items, children and ancestors are entries too, so `item.uri` works everywhere. Navigation items carry `url`, `isExternal`, `isCurrent` and `isActive` ([Navigation](/features/navigation)).

Index pages give `pagination.prev` and `pagination.next` as paths that keep the selected facets, and each facet value its own `url`:

```jinja
{% if pagination.next %}<a rel="next" href="{{ pagination.next|url }}">{{ t("pager.next") }}</a>{% endif %}
```

## Link fields [#link-fields]

A link field stores an editor's link to a document, an asset, a web address, an email address, a phone number, another site or an anchor. Its value resolves the target at render, so a link to a document follows the document when its address changes, and a link to a document that is not live in the locale is reported as broken. How kinds, styles and editor attributes are configured is in [the link field](/content-modelling/fields/link).

```jinja
{# the whole <a>, with everything the editor set #}
{{ entry.cta.link() }}
{{ entry.cta.link(text=t("more"), class="button button--primary", data-track="cta") }}

{# your own element around the editor's attributes #}
<a {{ entry.card.attributes(class="card__link") }}>
  <span class="card__title">{{ entry.card.text }}</span>
</a>

{# a list of links #}
{% for l in entry.links %}<li>{{ l.link() }}</li>{% endfor %}
```

### Helpers [#helpers-1]

| Helper | Prints |
|---|---|
| `link(text=, ...attributes)` | The `<a>` with `href`, the editor's title, accessible name, `rel`, `target`, the chosen style's class merged with `class=`, and the new-tab and file-type announcements. Nothing when the link is broken or empty |
| `attributes(...attributes)` | The same attributes alone, `href` included, for an element you write yourself |

`href` is the link's own and is refused as a keyword. `style=` and inline event handlers are refused. `engine-dmo check` warns when a literal `aria-label=` does not contain the literal `text=`, since the visible text must be part of the accessible name.

### Properties [#properties]

| Property | Value |
|---|---|
| `url` | The resolved address with the editor's suffix (query or fragment); empty when broken |
| `text` | The editor's text, else the target document's title, the asset's title, the URL's host and path, the address or the number |
| `kind` | The kind's key as the field declares it |
| `of` | The engine kind: `document`, `asset`, `url`, `email`, `phone`, `site` or `anchor` |
| `title`, `ariaLabel` | The editor's title and accessible name |
| `newTab`, `target` | Whether the editor asked for a new tab; `_blank` or empty |
| `rel` | The chosen rel tokens, with `noopener` for a new tab |
| `style`, `class` | The chosen style's key and class |
| `isExternal` | Whether the link leaves the site |
| `broken` | Whether the target is not live in the locale chain |
| `document` | The target document as an entry, one level deep |
| `asset` | The target asset: `url`, `title`, `filename`, `mime`, `extension`, `bytes`, `size`, `type` |
| `fields` | The link's sub-field values, by name |
| `isAffiliate`, `affiliate` | With the affiliates module (`engine-dmo`): whether the link is tracked through an affiliate programme, rewritten to the site's `/go/` redirect and marked `rel="sponsored"`, and the programme's names |

Printing the value itself, `{{ entry.cta }}`, prints its `url`. With `multiple: true` the value is a list.

### Links to other websites [#links-to-other-websites]

Every link to another website, in a link field or in rich text, takes the site's outbound rules on top of the editor's own choices:

```yaml
# config/sites/<key>/site.yaml
links:
  outbound:
    new_tab: true                 # open in a new tab, announced, with noopener
    rel: [noopener, noreferrer]   # tokens every outbound link carries
```

A link counts as outbound when its host is not one of the install's sites. The new-tab announcement text is the string `link.new_tab` in the [string catalogue](/templates/functions#t).

## Asset links [#asset-links]

Any asset value has `link()`, a download link that names the file's type and size in the request locale:

```jinja
{{ entry.report.link() }}                         {# Annual report (PDF, 2.1 MB) #}
{{ entry.report.link(text=t("download.report")) }}
```

`{{ entry.report }}` prints the original file's URL. For images, see [Images](/templates/images).

## Static files [#static-files]

`assets.url(path)` is a file under the site's public directories with a version query from its modification time, so a changed file is fetched again and an unchanged one stays cached for a year:

```jinja
<link rel="icon" href="{{ assets.url('favicon.svg') }}" type="image/svg+xml">
```

Files resolve along `public/<site>/`, `public/_shared/`, then `public/`. See [Frontend build](/templates/frontend-build).

## Feeds and calendars [#feeds-and-calendars]

| Helper | Returns |
|---|---|
| `feedLinks()` | The `<link rel="alternate">` tags of the site's feeds in this locale; `feedLinks('article')` one type's |
| `feedUrl('article', format='atom')` | A type's feed path in this locale (`rss`, the default, `atom` or `json`); empty when it has none |
| `calendarUrl('event')` | A type's calendar feed path in this locale; empty when it has none |
| `entry\|icsUrl` | An event's `.ics` address, when its route has a calendar |

Feeds and calendars are configured on the route ([routes reference](/reference/configuration/routes)).

## Related [#related]

- [Sites, locales and routes](/concepts/sites-locales-and-routes): how a route and a locale strategy make an address.
- [Redirects and URLs](/features/redirects-and-urls): what happens to an old address.
- [Multisite templates](/templates/multisite): linking between sister sites.


# Multisite templates (/templates/multisite)

How several sites in one project share templates through an ordered chain of template roots, override a component, a block or a whole file for one site, extend their own name across the chain, and detect copies that have drifted.

One project can serve several sites, each with its own domains, locales, routes and look. Their templates live side by side under `templates/` and resolve along an ordered **chain of roots** per site: the first root that holds a file wins. Shared templates go in `_shared/`, and a site overrides only what differs, as a component, a block or a whole file.

## A minimal example [#a-minimal-example]

Two sites, `county` and `town`. The town shares everything with the county except its page header block:

```text
templates/
  _shared/
    base.html
    page/entry.html
    components/teaser/
  town/
    page/entry.html
```

```jinja
{# templates/town/page/entry.html #}
{% extends "page/entry.html" %}

{% block hero %}
  <div class="harbour-banner">{{ t("town.banner") }}</div>
{% endblock %}
```

`{% extends "page/entry.html" %}` inside `town/page/entry.html` does not resolve to itself: it resolves to the next `page/entry.html` along the town's chain, here `_shared/page/entry.html`. The town's page is the shared page with one block replaced.

Check what a site resolves:

```bash
engine-dmo describe template page/entry.html --site town
```

```text
page/entry.html on site town resolves to town/page/entry.html (chain town, _shared)
  extends page/entry.html as _shared/page/entry.html
renders page (entry)
```

## The chain [#the-chain]

Each site's chain is `[<site key>, _shared]` unless its `site.yaml` sets one:

```yaml
# config/sites/chipping-norton/site.yaml
templates:
  roots: [chipping-norton, towns, _shared]
```

| Key | Default | Meaning |
|---|---|---|
| `templates.roots` | `[<site key>, _shared]` | Directories under the template directory, searched in order |
| `templates.allow_unescaped` | `false` | Allow the `safe` filter in this site's templates |

The template directory itself is `template.dir` in `engine.yaml` (default `templates`).

For three town sites that share a `towns/` root, a request on the town of Chipping Norton looks for a name in its own root, then in `towns/`, then in `_shared/`, and renders the first file it finds; a file that extends its own name continues down the same chain:

```mermaid
flowchart LR
  N["page/entry.html<br/>on site chipping-norton"] --> A{"templates/chipping-norton/<br/>has it?"}
  A -- yes --> UA["Render it"]
  A -- no --> B{"templates/towns/<br/>has it?"}
  B -- yes --> UB["Render it"]
  B -- no --> C{"templates/_shared/<br/>has it?"}
  C -- yes --> UC["Render it"]
  C -- no --> X["Not found: check reports<br/>the missing template"]
  UA -.->|"extends page/entry.html"| B
```

- **First match wins.** A name such as `listing/entry.html`, `base.html`, `partials/footer.html` or `components/teaser/teaser.html` is looked up in each root in turn.
- **`_shared` is a convention**, not a keyword. A site whose chain is `[business-site]` alone shares nothing.
- **An intermediate root** groups sites that resemble each other. Three town sites with `roots: [<town>, towns, _shared]` share `towns/` without copying a file. Inserting a root later changes nothing that already exists, because no file names the chain.
- Every root `templates.roots` names must be a directory under the template directory; `engine-dmo check` reports one that is not. With the default chain, a site needs no directory of its own until it overrides something.

`engine-dmo assets manifest` prints every site's chain:

```text
site town
  templates  town → towns → _shared
```

## Extending across the chain [#extending-across-the-chain]

A template that extends or includes **its own name** resolves to the next file of that name further along the chain, never to itself:

```jinja
{# templates/towns/base.html: every town wraps the shared layout #}
{% extends "base.html" %}
{% block body %}<div class="town-shell">{{ block.Super }}</div>{% endblock %}
```

`{{ block.Super }}` prints the parent's content of the block. To skip a layer deliberately, name the root: `{% extends "_shared/page/entry.html" %}`.

## The cheapest override that works [#the-cheapest-override-that-works]

Stop at the first rung that solves the problem.

| Rung | When | How |
|---|---|---|
| 1. Tokens | A different logo, colours, type or spacing | No template change. Each site's stylesheet sets its own CSS custom properties, and the shared templates and components read only the properties |
| 2. A component | One component looks different on one site | Add `components/<name>/` to the site's root, with markup and optionally a contract that takes the same inputs ([Components](/templates/components#overriding-a-component-on-one-site)) |
| 3. A block | One region of a page differs | Extend your own name and override the block, as above |
| 4. A whole file | The page is genuinely different | Copy it with `--from-shared` (below), so drift is reported |
| 5. A different chain | The site is genuinely different | Set `templates.roots` |

A site-only type (one declared under `config/sites/<key>/schema/`) has its templates in that site's root and nowhere else.

## Copies and divergence [#copies-and-divergence]

When a site needs its own copy of a whole template, make it with the scaffold, which records where it came from:

```bash
engine-dmo new template article/entry.html --site town --from-shared
```

The copy's first line names its source and the source's content hash:

```jinja
{# meridian:copied-from _shared/article/entry.html sha256=951fbf0b... on 2026-11-02 #}
```

When the shared original changes, or disappears, `engine-dmo check` warns at that line:

```text
town/article/entry.html:1:1: warning: copied from _shared/article/entry.html on 2026-11-02, which has changed since
      = review the copy against _shared/article/entry.html, or copy it again with: engine-dmo new template article/entry.html --site town --from-shared --force
```

It is a warning, never an error, since a copy that differs is sometimes right. Remove the header line once the copy is meant to stand alone. `engine-dmo check --strict` turns the warning into an error for a CI gate that should insist on review.

`--from-shared` copies the template the site resolves today. Without it, `engine-dmo new template <type>` writes a starter for a type, into the shared root, or into a site's root with `--site`.

## What resolves along the chain [#what-resolves-along-the-chain]

| Name | Resolved along the chain |
|---|---|
| Page templates (`<type>/entry.html`, `<type>/index.html`, `<type>/landing.html`) | Yes |
| `base.html` and every `{% extends %}`, `{% include %}` and `{% import %}` | Yes |
| Components (`components/<name>/`) and their contracts | Yes |
| Block templates (`blocks/<block>.html`, rendered by `{% blocks %}`) | Yes |
| Error pages (`errors/404.html`, `errors/500.html`) | Yes |
| Endpoint response templates (`respond.fragment`, `on_error`) | Yes |
| Static files under `public/` | Along a parallel chain: `public/<site>/`, `public/_shared/`, then `public/` |

Every check runs per site: a shared template is checked once for each site whose chain reaches it, against that site's types, fields, routes and components, so a shared template that uses a field one site lacks is reported for that site.

The same applies to anything a site declares. With `engine-dmo`, a shared template that calls `promoted('home-feature')` fails the check on every site sharing it that does not declare the slot `home-feature`; there is no way to mark the call optional. Declare the slot on every such site, or move the call into the template roots of the sites that have it.

A directory no site's chain names is never rendered. With `engine-dmo`, `engine-dmo portal scaffold` without `--site` writes `templates/portal/`, which is on no chain by default; pass `--site <key>` so the files land where the site's portal reads them.

## Site-specific values without a template [#site-specific-values-without-a-template]

Prefer configuration over a template fork for small differences:

- **`settings`** in `site.yaml` is free-form and read as `settings.<key>` in templates, for a phone number, a sister site's key or a feature switch.
- **`site`** gives the site's `key`, `name`, `shortName`, `organisation`, `baseUrl`, `country`, `timezone`, `defaultCurrency`, `domains`, `embedOnly` and `robots`.
- **`sites`** lists every site (`key`, `name`, `baseUrl`), present only when the project has more than one.
- **Strings** are per locale, not per site; a site-specific phrase belongs in `settings` or its own string id.
- **Image transforms** can be replaced per site in `config/sites/<key>/images.yaml` ([Images](/templates/images#per-site-transforms)).

```yaml
# config/sites/town/site.yaml
settings:
  sister: { key: county, name: "Visit the county" }
```

```jinja
<a href="{{ siteUrl('/', site=settings.sister.key, locale=locale.code) }}">{{ settings.sister.name }}</a>
```

`siteUrl()` keeps the visitor's language where the other site enables it, and that site's default otherwise ([Links and URLs](/templates/links#siteurl)). A type key in place of the path (`siteUrl('listing', site=...)`) lands on the equivalent section rather than the home page.

## Styles and scripts per site [#styles-and-scripts-per-site]

Each site has its own bundle. With the Vite extension, `assets.css('main')` and `assets.js('main')` print the site's own build: `src/entries/<site>.js` by convention, or what `assets.bundles` in its `site.yaml` names. The `meridian()` Vite plugin adds to each site's bundle the CSS and JS of the components that resolve for that site, so an overridden component's styles reach only its site. See [Frontend build](/templates/frontend-build).

## Related [#related]

- [Sites, locales and routes](/concepts/sites-locales-and-routes): adding a site with `engine-dmo dev site add`.
- [Components](/templates/components): contracts and overrides.
- [Site configuration reference](/reference/configuration/site).


# Querying content (/templates/queries)

How a template fetches published documents with query() (where, tag, near, orderBy, limit, offset, exclude, organisation, onePer, with, and the terminal methods), nearby(), children(), ancestors(), smartList() and search(), with every rule, limit and error.

A template reads content, never writes it. Besides the page's own `entry` and an index page's `items`, a template fetches documents with a small set of functions:

| Function | Use it for |
|---|---|
| `query('type')` | A list of published documents of one type, filtered and sorted |
| `nearby(entry, km, type)` | Documents near a document, nearest first |
| `children(doc)`, `ancestors(doc)` | A nesting document's tree |
| `smartList('key')` | A list an editor maintains in the admin |
| `search(q)` | The site's search service, with facets and paging |
| `singletons.<type>` | A singleton document (see [Globals](/templates/globals#singletons)) |

Every one of them returns only documents that are **published in the request locale and shown on the current site**. There is no way to read a draft or another site's hidden content from a template.

```jinja
{% set featured = query('listing').tag('eat-drink.*').where('dogFriendly', true).orderBy('title').limit(6).all() %}

<ul class="cards">
{% for place in featured %}
  <li><a href="{{ place.uri|url }}">{{ place.title }}</a></li>
{% empty %}
  <li>{{ t('places.none') }}</li>
{% endfor %}
</ul>
```

## query() [#query]

`query('listing')` starts a query over one type the current site serves. Each method returns a new query, so a partial query can be kept and reused:

```jinja
{% set places = query('listing').tag('eat-drink.*') %}
<p>{{ t('index.count', places.count()) }}</p>
{% for p in places.orderBy('title').limit(12).all() %}...{% endfor %}
```

A query covers one type. Passing several (`query(['listing', 'article'])` or `query('listing', 'article')`) returns nothing, with no error at check or render; run one query per type, or use [`search()`](#search), which searches every type, for a mixed list.

The query runs only when a terminal method (`all()`, `first()`, `count()`, `exists()` or `ids()`) is called. Each terminal call runs it again, so call `all()` once and keep the result with `{% set %}`.

### Filtering on fields: index: true [#filtering-on-fields-index-true]

A query can filter and sort only on fields declared `index: true` in the schema. `title` can always be filtered and sorted on, and the engine's own dates (`createdAt`, `updatedAt` and `publishedAt`, on a type that does not declare a field of that name) can be sorted on with `orderBy()` but not filtered with `where()`, which keeps nothing. This keeps every query a database index lookup however large the site grows.

```yaml title="config/schema/listing.yaml"
fields:
  - name: dogFriendly
    id: fld_ab12cd34ef
    type: boolean
    index: true
```

A query that filters or sorts on a field that is not indexed, or not a field of the type, fails the render with an error naming the field:

```text
query().where("website"): website is not declared index: true, so it cannot be queried
```

`engine-dmo check` does not catch this; render the page (`engine-dmo render <path>`) to be sure.

### Methods [#methods]

| Method | What it does |
|---|---|
| `where(field, value)` | Keep documents whose field equals the value |
| `where(field, op, value)` | Compare with an operator: `eq`, `ne`, `in` (the value is a list), `gt`, `gte`, `lt`, `lte`, `exists` (the value is `true` or `false`). Any other operator is an error |
| `tag(key, ...)` | Keep documents carrying every tag given. A key matches that tag only; `key.*` matches the tag and every tag below it (`eat-drink.*`). Only public vocabulary tags count |
| `near(point, km)` | Keep documents within `km` kilometres of a point, and order them nearest first unless `orderBy()` says otherwise. The point is anything with `lat` and `lon` (a geo value, an address's `geo`) or a document with a geo field. `km` defaults to 10 and is capped at 500. The type needs a `geo` field declared `index: true`. A point that is empty keeps nothing |
| `orderBy(field, dir)` | Sort by an indexed field, `title`, `createdAt`, `updatedAt` or `publishedAt`, or by `distance` after `near()`. `dir` is `asc` (the default) or `desc` |
| `limit(n)` | At most `n` documents, at most 500 |
| `offset(n)` | Skip the first `n` documents |
| `exclude(doc, ...)` | Leave documents out, given as entries or ids: `exclude(entry)` leaves the current page out |
| `organisation(x)` | Keep the documents one organisation owns. `x` is the organisation's id, an entry that has an organisation, or an organisation value |
| `onePer('organisation')` | Keep the first document of each organisation in the query's order (and every document no organisation owns), so a strip shows one item per business. `limit()` and `count()` count what is kept |
| `with(paths, ...)` | Read relations and tree paths for every result up front. See [Eager loading](#eager-loading) |

### Terminal methods [#terminal-methods]

| Method | Returns |
|---|---|
| `all()` | The documents as a list of entries. Without `limit()`, at most 100 |
| `first()` | The first document, or nothing |
| `count()` | How many documents match, exactly, ignoring `limit()` |
| `exists()` | Whether any document matches |
| `ids()` | The documents' ids |

### Values [#values]

Each document is an entry, the same shape as the page's `entry` (see [The page context](/templates/context#fields-every-document-has)): `title`, `uri`, `url`, `tags`, dates and every field. Relations are read lazily: the first time a template reads a relation on one entry of the list, it is read for all of them in one go, so a loop that prints each item's related document costs a query or two, not one per item. Each entry also carries `organisationId`, the id of the organisation that owns it, when one does.

### Ordering [#ordering]

Without `orderBy()`, a query uses the type's `ordering` from the schema, or title order when it has none; after `near()`, nearest first.

### Where value types matter [#where-value-types-matter]

`where()` compares as the field stores its value: a boolean as `true` or `false`, a number as written, a relation by the related document (pass the entry or its id), a select by its option value, a `date` or `datetime` field by a date written as text (`'2026-09-01'` or an RFC 3339 time), anything else as text.

A date value such as `today` or `now` is not accepted by `where()`: the query logs `is not a date or an RFC 3339 time` and keeps nothing. Pass it through `|iso` first.

```jinja
{{ query('listing').where('priceBand', 'in', ['£', '££']).count() }}
{% set next = query('article').where('publishedAt', 'gte', today|iso).orderBy('publishedAt').limit(5).all() %}
{% set inArea = query('listing').where('area', entry).all() %}
{{ query('listing').where('phone', 'exists', true).count() }}
```

### Errors [#errors]

A misuse the author can fix fails the render with a message naming it, and the page answers 500 (under `serve --dev`, the development error page):

| Message | Cause |
|---|---|
| `query("x"): "x" is not a type served on site main` | The type does not exist or is not on this site |
| `query().where("f"): f is not a field of listing` | No such field |
| `query().where("f"): f is not declared index: true, so it cannot be queried` | The field is not indexed (also for `orderBy()`) |
| `query().where(): "like" is not an operator: eq, ne, in, gt, gte, lt, lte or exists` | Unknown operator |
| `near() needs a geo field declared index: true on listing` | No indexed geo field |
| `query().onePer() takes 'organisation'` | Any other argument |

A database error does not fail the page: it is logged and the query returns an empty list.

### Paging [#paging]

`query()` has no paging of its own beyond `limit()` and `offset()`. For a paged list of a type, use the type's index page (a route with `index:` and `paginate:`), which gives `items` and `pagination` (see [An index page](/templates/context#an-index-page)). For a paged custom list, use `search()` with `paginate()`.

## Eager loading [#eager-loading]

`with()` names the relations and tree paths a template will read on every result, and reads each level for all results before the first renders:

```jinja
{% set regions = query('area').where('kind', 'region').with(['heroImage', 'children', 'children.heroImage']).all() %}

{% set areas = query('area').with('children', limit=6, orderBy='-title').all() %}
```

- A path is a field (a relation, or a field that holds one) or a tree relation (`children`, `ancestors`, `siblings`), with each deeper step after a dot.
- A call that names one path takes keywords that shape the list each entry ends up with at the path's last step: `limit=`, `orderBy=` (a field; a leading `-` sorts descending) and `desc=`.

Without `with()` the same values are still read efficiently, lazily, one group at a time. `with()` only says up front what the template needs.

## nearby() [#nearby]

`nearby(entry, km, type)` is the documents of a type within `km` kilometres of an entry's point, nearest first, with the entry itself left out. `type` defaults to the entry's own type and `km` to 10. It returns at most 12 documents, as a list (no `.all()`):

```jinja
{% for p in nearby(entry, 5) %}<a href="{{ p.uri|url }}">{{ p.title }}</a>{% endfor %}
{% for e in nearby(entry, 20, 'event') %}...{% endfor %}
```

The entry's point is its type's first indexed `geo` field, or a field named `location`, `centre` or `geo`. An entry without a point gives an empty list.

## children() and ancestors() [#children-and-ancestors]

On a type whose route nests (`nest: true`), the page's own `entry` already has `entry.children`, `entry.ancestors` and `entry.parent`. The functions give the same for any document value, such as a related one:

```jinja
{% for c in children(entry.parent) %}<a href="{{ c.uri|url }}">{{ c.title }}</a>{% endfor %}
{% for a in ancestors(entry) %}<a href="{{ a.uri|url }}">{{ a.title }}</a> / {% endfor %}
```

`children(doc)` is the published children in the request locale, in title order. `ancestors(doc)` is the ancestors, root first. Both are empty for a type that does not nest on the site. When a document came from a list, the first `children()` call reads the children of every document in that list at once, so a menu of regions listing each region's places costs the queries of one region.

## smartList() [#smartlist]

A smart list is a saved query an editor maintains in the admin. A project can seed one in `config/tags/smartlists.yaml`; from then on the admin owns it.

```jinja
{% set dogs = smartList('dog-friendly-places') %}
<h2>{{ t('lists.dogs') }} ({{ dogs.count() }})</h2>
{% for p in dogs.limit(12).all() %}<a href="{{ p.uri|url }}">{{ p.title }}</a>{% endfor %}
```

| Method | Returns |
|---|---|
| `.limit(n)` | The list limited to `n` documents |
| `.all()` | The documents in the list's own order. Without a limit, up to 500; a limit above 500 renders 500 and the engine logs it |
| `.first()` | The first document, or nothing |
| `.count()` | How many documents the list holds, exactly |

Only a list marked `public` and belonging to this site (or to no site) renders. Any other key renders as an empty list, never an error, so a template cannot reveal a list the admin keeps internal.

## search() [#search]

`search(q)` runs a query through the site's search service: the configured backend, its query log and, when the backend is unavailable, the browse fallback over published content.

```jinja
{% set results = search(request.query.q).types('listing', 'event').paginate(20) %}
{% if results.degraded %}<p>{{ t('search.degraded') }}</p>{% endif %}
<p>{{ t('search.count', results.total) }}</p>
{% for item in results.items %}
  <a href="{% if item.clickUrl %}{{ item.clickUrl|url }}{% else %}{{ item.uri|url }}{% endif %}">{{ item.title }}</a>
  {% if item.highlight %}<p>{{ item.highlight }}</p>{% endif %}
{% endfor %}
```

| Method | What it does |
|---|---|
| `.types(key, ...)` | Only these types |
| `.tags(key, ...)` | Only documents with these tags |
| `.near(point, km)` | Only documents within `km` (default 10) of a point; with no words, nearest first |
| `.sort(order)` | `relevance`, `name`, `distance` or `recent`. Without it, a search with words is by relevance |
| `.facets(name, ...)` | Return only these facets |
| `.paginate(n)` | Run it: the page `?page=` names, `n` per page |
| `.limit(n)` | Run it: page one, `n` results |

`n` defaults to 20 and is capped at 100. The result:

| Key | Value |
|---|---|
| `items` | The hits, each `id`, `type`, `title`, `summary`, `uri`, `url`, `tags`, `position`, `fields` (the document's indexed scalar fields), `image` (its main image as an image value, or empty), and where the backend gives them `highlight` (safe markup), `distance` and `clickUrl` (a link that records which result was chosen) |
| `total` | How many results |
| `facets` | Per facet name, a list of `value`, `count`, `label` |
| `degraded` | `true` when the answer came from the browse fallback rather than the search backend |
| `backend` | Which backend answered |
| `query`, `sort` | What was asked |
| `page`, `pages`, `hasMore` | The page, how many pages, whether there are more |
| `pagination` | As an index page's `pagination`, its links keeping the rest of the query string |
| `didYouMean` | Always empty at present |

A query shorter than the configured minimum length, the empty one included, is browse mode and is not logged. A search from a template is logged as the search route's is. The search route itself renders `search.html` with the same object as `results`; see [Search](/features/search).

## Performance [#performance]

- Every list's entries, their relations, tags, dates and translations are read in a few statements per list, however many entries it holds.
- Everything a response renders shares one cache for that response: the layout's menus, the page's lists and every entry's relations read each document once between them.
- To cache an expensive part of a page across requests, use `{% cache %}`; see [Caching](/templates/caching).
- `engine-dmo render <path> --json` lists the queries a page made.


# SEO and structured data (/templates/seo-and-structured-data)

What head() and jsonld() print, how titles, descriptions, canonical URLs, hreflang, robots and Open Graph are decided, how to map a content type to schema.org, and how the sitemap and robots.txt are configured.

You do not hand-write metadata or JSON-LD. Two calls in your layout print it, from the page, the document, the site's configuration and the type's schema.org mapping:

- `head()` prints the title, the meta description, the canonical link, hreflang alternates, the robots directive, `rel=prev` and `rel=next`, and the Open Graph and Twitter card tags.
- `jsonld()` prints the page's structured data as one JSON-LD `@graph` whose entities reference each other by `@id`.

The sitemap and `robots.txt` are generated from `site.yaml`.

## A minimal setup [#a-minimal-setup]

```jinja
{# templates/_shared/base.html #}
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head() }}
  {{ jsonld() }}
  {{ feedLinks() }}
  {{ assets.css('main') }}
</head>
<body>{% block body %}{% endblock %}</body>
</html>
```

```yaml
# config/sites/main/site.yaml
seo:
  title_template: "{{ title }} | {{ site.name }}"
  default_image: /img/share.jpg
  sitemap: { enabled: true }
  robots: { enabled: true }
  structured_data:
    organisation: { type: TouristInformationCenter, logo: /logo.svg }
```

```yaml
# config/schema/event.yaml (a type's mapping to schema.org)
structured_data:
  type: Event
  map:
    description: description
    image: heroImage
    offers: bookingUrl
    location: venue
    organizer: { value: "Riverside Arts Centre" }
```

`engine-dmo check` warns when a layout's `<head>` has no `head()` and its own tags have no meta description. The `base.html` that `engine-dmo init` writes has neither, so a new project prints this warning until you replace its `<title>` and canonical link with `{{ head() }}`. The warning is not counted in the check's summary line ([Testing](/templates/testing#engine-dmo-check)).

## head() [#head]

`head()` prints, in this order:

| Tag | Source |
|---|---|
| `<title>` | The document's `seo` field title where written; else the page title through `seo.title_template`; else the site's name |
| `<meta name="description">` | The page's description (an index or landing page's own); else the document's `seo` field description where written; else the document's `summary` field as plain text; left out when empty. Whitespace is collapsed |
| `<link rel="canonical">` | `page.canonical` |
| `<link rel="alternate" hreflang>` | `page.alternates`, plus `x-default`, only when the page exists in more than one locale on this site |
| `<meta name="robots">` | `index, follow, max-image-preview:large`, or `noindex, follow` (below) |
| `<link rel="prev">`, `<link rel="next">` | The pagination's neighbours, absolute |
| `og:type` | `article` when the type maps to a creative work (an `Article`, say), else `website` |
| `og:title`, `og:description` | The `seo` field's `og_title` and `og_description` where written, else the title and description above |
| `og:url`, `og:site_name`, `og:locale` | The canonical, the site's name, the locale with an underscore (`en_GB`) |
| `og:image`, `og:image:width`, `og:image:height`, `og:image:alt` | The image the type's `structured_data` maps as `image`, else `seo.default_image` (below) |
| `twitter:card` | `summary_large_image` with an image, else `summary`. Twitter reads the Open Graph tags, so no `twitter:title` is printed |

The response also carries `Content-Language` with the page's locale.

A type with no `summary` field and no `seo` field has no description. The core `page` type declares only `title` and `slug`, so extend it with a `summary` (`engine-dmo dev field add page summary --type text --param multiline=true --apply`) or an `seo` field before you rely on `head()` for the home, about and contact pages.

### Titles [#titles]

`seo.title_template` takes two placeholders, written exactly as `{{ title }}` and `{{ site.name }}` (with or without the inner spaces). Nothing else in it is evaluated. A page without a title gets the site's name.

To let editors write a search title and description per document, give the type a field of type `seo` ([the seo field](/content-modelling/fields/seo)). It stores `title`, `description`, `og_title` and `og_description`, and warns editors past 60 and 160 characters (`title_max`, `description_max`).

`entry.seo` gives the same decisions to a template that writes its own tags: `title` (the title template applied), `description` (the summary as plain text), `image` (the site's default image, absolute), `noindex` and `canonical`. A type that declares its own field named `seo` keeps its field's value there instead.

### The share image [#the-share-image]

The Open Graph image is the image field the type's `structured_data.map` names as `image`. When `config/images.yaml` defines a transform named `social`, the image is cut through it (its first width) and `og:image:width` and `og:image:height` are printed; otherwise the original is shared. A common definition:

```yaml
# config/images.yaml
transforms:
  social:
    width: 1200
    aspect: "1.91:1"
    formats: [jpeg]
```

Without a mapped image, `seo.default_image` (a path on the site) is shared, absolute.

`width: 1200` makes `social` a fixed-width transform, which is right for a share image of one known size. A transform written with `widths: { min, max }` instead is accepted too; the share image is then its first width. Both forms are described under [A transform](/templates/images#a-transform).

### Canonical URLs [#canonical-urls]

`page.canonical` is absolute, on the site's first configured domain with the scheme of `server.base_url`, never the host the request came in on.

| Page | Canonical |
|---|---|
| A document | Its own address |
| A document shared to a second site | Its address on the site that owns it, in the same locale, when it has a live page there |
| An index page | The unfiltered index (with its page number) |
| A filtered index page | The most specific landing page whose filters it holds, else the unfiltered index |
| A landing page | Itself |

### hreflang [#hreflang]

Alternates list only locales in which the page is published with a live address **on this site**, never another site's pages. `x-default` is the site's default locale when the page exists in it, else the first alternate. With one locale, no alternates are printed. Each item of `page.alternates` has `locale`, `hreflang` (the code in lower case), `url` and `path`.

### noindex [#noindex]

The robots directive is `noindex, follow` when any of these holds; none is configurable:

- the page is a filtered view of an index (any facet selected);
- the page is a preview;
- the site is in embed-only mode (`embed.only`), which also sends `X-Robots-Tag: noindex, follow`;
- `engine.environment` is `staging`.

`page.noindex` is true for a filtered index and a preview.

## jsonld() [#jsonld]

`jsonld()` prints one `<script type="application/ld+json">` holding the page's `@graph`:

| Node | `@id` | When |
|---|---|---|
| `WebSite` | `{root}/#website` | Every page; with a `SearchAction` where the site routes search, unless `structured_data.search: false` |
| The publisher | `{root}/#organization` | Every page, unless `structured_data.organisation: false` |
| `WebPage` (`CollectionPage` on an index, a guide, a collection or a landing page) | `{canonical}#webpage` | Every page; `isPartOf` the site and `about` the document's entity, with `datePublished` and `dateModified` |
| `BreadcrumbList` | `{canonical}#breadcrumb` | Home, the document's ancestors and the page, unless `structured_data.breadcrumbs: false` |
| The document's entity | `{canonical}#place`, `#event`, `#article`, `#organization` or `#thing` by its types | A document whose type has a `structured_data` mapping |
| Further event dates | `{canonical}#event-{local start}` | Up to twelve upcoming dates in all, each with its `eventStatus` |
| `ItemList` | | A guide's or a collection's items, and a landing page's results, each item referencing its entity where it has one |
| `FAQPage` | | A type that maps questions (`structured_data.faq`) |

Every URL in it is on the configured domain. `jsonld(entry)` prints one document's entity alone, for a card or a fragment. Under `engine-dmo serve --dev` the graph is checked against the vocabulary as it is printed, and an unknown type or property fails the render.

Guides and collections also carry the graph as `entry.jsonld`, and landing pages as `landing.jsonld`. Print either with the `json` filter inside a script element, if you build the head yourself:

```jinja
<script type="application/ld+json">{{ entry.jsonld|json }}</script>
```

### Site-wide nodes [#site-wide-nodes]

```yaml
# config/sites/<key>/site.yaml
seo:
  structured_data:
    organisation:
      type: TouristInformationCenter     # an Organization subtype; Organization when not given
      name: Visit Wyndmouth              # site.organisation, else the site's name, when not given
      logo: /logo.svg                    # a path on the site or an absolute URL
      same_as: ["https://example.org/wyndmouth"]
    breadcrumbs: true
    search: true
```

| Key | Values | Default |
|---|---|---|
| `organisation` | `true`, `false`, or a map of `type`, `name`, `logo`, `same_as` | `true` |
| `breadcrumbs` | boolean | `true` |
| `search` | boolean | `true` |

A `type` that is not an `Organization` is an error: `PerformingArtsTheater is not an Organization; the site's publisher is one, such as TouristInformationCenter`.

## Mapping a type to schema.org [#mapping-a-type-to-schemaorg]

A type's `structured_data` block in its schema file declares what its documents are:

```yaml
structured_data:
  type: TouristAttraction                 # a schema.org type, or a list
  subtype:                                # an extra type by a select field's value
    field: category
    values: { stay: LodgingBusiness, eat-drink: Restaurant, shop: Store }
  map:
    description: description
    image: heroImage
    geo: location
    address: address
    telephone: phone
    sameAs: website
    openingHoursSpecification: openingHours
    amenityFeature: accessibility
    isAccessibleForFree: true
    eventAttendanceMode: { value: "https://schema.org/OfflineEventAttendanceMode" }
  faq: { items: body.faq.items, question: question, answer: answer }
```

| Key | Meaning |
|---|---|
| `type` | A schema.org type or a list of them. A general type gives way to a more specific one: `[Place, Restaurant]` is `Restaurant` |
| `subtype.field`, `subtype.values` | A `select` field and a map of its values to extra types |
| `map` | Each line is a schema.org property and its source: a field name, `"@self"` for the canonical URL, `true`, `false`, a number, or `{ value: ... }` for any other literal |
| `faq` | Questions and answers: `items` is a dotted path through repeaters and blocks (a blocks field is followed by the block's key) to the items, `question` and `answer` the item fields. `engine-dmo check` resolves the path against the schema |

### Choosing a type [#choosing-a-type]

Pick the most specific schema.org type that describes what a visitor would go to, do or read. The entity's `@id` suffix follows from the type, so other nodes can reference it:

| What the document is | `type` | `@id` |
|---|---|---|
| A place to visit: an attraction, a viewpoint, a park, the start of a walk | `TouristAttraction` (or `Park`, `Museum`, `LandmarksOrHistoricalBuildings`) | `#place` |
| A business: somewhere to stay, eat or shop | `LodgingBusiness`, `Restaurant`, `Store`, or `LocalBusiness` with a `subtype` | `#place` |
| A walk, trail or itinerary described as a journey | `TouristTrip` | `#thing` |
| Something on at a time | `Event` | `#event` |
| A story, guide text or blog post | `Article` (`NewsArticle`, `BlogPosting`) | `#article` |
| An organisation's own page | `Organization` or a subtype | `#organization` |

A walking route can reasonably be either: `TouristAttraction` with `geo` mapped to its start point puts it on the map as a place, and `TouristTrip` describes the journey. Choose one; a list of both (`[TouristAttraction, TouristTrip]`) gives one node both types, with the `#place` id.

```yaml
# config/schema/walk.yaml
structured_data:
  type: TouristAttraction
  map:
    description: summary
    image: heroImage
    geo: startPoint
```

Without a line of its own the engine fills `name` from the title and `url` from the canonical address; on a creative work `headline`, `datePublished`, `dateModified` and `inLanguage`; on a place `containedInPlace`, the place above it in the hierarchy; on an event its dates and status from its occurrences.

### What each field type gives [#what-each-field-type-gives]

| Field type | Value in the graph |
|---|---|
| `text`, `slug` | The text. For a property whose value is a node (`organizer`, `author`, `location` and the like) a node of the property's first type named by it; for `address` a `PostalAddress` with it as the street |
| `portable_text` | Its words as plain text |
| `select` | Its label in the page's locale (labels for a multiple select); for `amenityFeature`, a `LocationFeatureSpecification` each |
| `number`, `boolean` | As it is |
| `date`, `datetime` | The date, or the local time with its offset |
| `phone` | E.164 |
| `money` | An `Offer` with `price` and `priceCurrency` |
| `asset` | The image's absolute URL, or a list |
| `link` | The URL; for `offers`, an `Offer` with it as `url` |
| `geo` | `GeoCoordinates`; for `location`, a `Place` with them |
| `address` | A `PostalAddress`; for `geo`, its point; for `location`, a `Place` with both |
| `opening_hours` | The `OpeningHoursSpecification` list for the coming week, seasons and exceptions resolved |
| `relation` | A reference (`{"@id": ...}`) to the related document's entity when its type fits the property, else a node with its name and URL |

A repeater, blocks, form, seo, video or geo shape field cannot be a source. A property the document's own types do not take is left out of its entity.

### Validation [#validation]

`engine-dmo check` validates every mapping against the schema.org vocabulary the engine ships:

| Problem | Severity | Example |
|---|---|---|
| Unknown type or property | Error | `"headlin" is not a schema.org property in the vocabulary the engine validates against (2026-10.1)`, with a "did you mean" |
| Property on a type that does not take it | Error | `starRating is not a property of Article; it applies to FoodEstablishment, LodgingBusiness` |
| A field that can never fill the property | Error | A `date` mapped to `organizer` |
| A missing field, or an `faq` path step that does not exist | Error | At its line |
| A property a rich result requires or recommends is not mapped | Warning | `the structured_data mapping of event has no organizer, which the event rich result recommends` |

The rich-result warnings are guidance from a dataset versioned with the engine, never a guarantee.

## The sitemap [#the-sitemap]

```yaml
seo:
  sitemap:
    enabled: true
    max_urls_per_file: 10000
```

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `false` | Serve the sitemap |
| `max_urls_per_file` | 50,000 | Above this many URLs, the sitemap becomes a sitemap index of numbered files (`/sitemap.xml?page=2`); at most 50,000 |

It is served at `/sitemap.xml`, or at the path `special.sitemap` gives in `routes.yaml`, with `Cache-Control: public, max-age=3600`. It lists every document with a live page on the site in each enabled locale (`lastmod` the later of its locale's and its shared revision), each type's index page in every enabled locale, and the live landing pages. A page in more than one locale lists its alternates on this site as `xhtml:link`. A site in embed-only mode lists nothing. The sitemap lists pages only: it has no image or video entries. A filtered index page (any facet selected) is never listed, since it is `noindex`; to keep a whole path out of search engines, use `robots.disallow`.

## robots.txt [#robotstxt]

```yaml
seo:
  robots:
    enabled: true
    disallow: ["/search"]
    allow: ["/search/help"]
    agents:
      - { user_agent: GPTBot, disallow: ["/"] }
```

| Key | Meaning |
|---|---|
| `enabled` | Generate `robots.txt`; without it, a `robots.txt` file in `public/` is served as it is |
| `disallow`, `allow` | Paths for every crawler |
| `agents` | A group of its own for each named crawler (`user_agent`, `disallow`, `allow`), written after the group for every crawler |

The admin, the member portal (with the portal module) and the tracked-redirect paths are always disallowed, and repeated in every named group, since a crawler that finds its name reads only its own group. The sitemap is declared when it is enabled. A staging environment serves a blanket `Disallow: /`. `engine-dmo check` refuses a rule that is not a path, a group for `*`, a crawler named twice and a group that says nothing.

## Feeds [#feeds]

`feedLinks()` in the head prints the `<link rel="alternate">` tags of the site's feeds in the request locale, for feed readers to discover. Feeds are configured on a route ([routes reference](/reference/configuration/routes)); see [Links and URLs](/templates/links#feeds-and-calendars) for `feedUrl()`.

## Checking the output [#checking-the-output]

- `engine-dmo render /whats-on/film-club --json` returns the page's HTML with the head and graph as printed ([Testing](/templates/testing)).
- A template test can assert on the graph: `jsonld: { "@type": "Event", "name": "Film Club" }` passes when some object in the page's JSON-LD holds those values.

## Related [#related]

- [Site configuration reference](/reference/configuration/site): every `seo` key.
- [Landing pages](/dmo/landing-pages): their own titles, descriptions and graphs (`engine-dmo`).
- [Images](/templates/images): the `social` transform.


# Tags (/templates/tags)

Every tag a Meridian template can use (Pongo2's control flow, inheritance and include tags, and the engine's blocks, nav, component, slot, fragment, cache, announce, focus, patch, location and requireMember tags) with syntax, options and errors.

A tag is written `{% name ... %}`; most have a closing `{% endname %}`. This page lists every tag a site's templates can use. `engine-dmo template api` prints the same list from the engine. A tag that does not exist, or one Meridian removes, is a compile error naming it.

## Inheritance and reuse [#inheritance-and-reuse]

### extends and block [#extends-and-block]

```jinja
{% extends "base.html" %}
{% block title %}{{ entry.title }} | {{ block.Super }}{% endblock %}
```

`{% extends "name" %}` inherits a layout. `{% block name %}...{% endblock %}` declares a region in a layout and replaces it in a child; `{{ block.Super }}` prints the parent's content of the block. Extending the name a file is itself resolved as reaches the next root on the site's chain. See [Inheritance](/templates/language#inheritance).

### include [#include]

```jinja
{% include "partials/footer.html" %}
{% include "partials/card.html" with title=entry.title %}
{% include "partials/card.html" with title=entry.title only %}
```

Renders another template in place with the current context; `with` adds variables and `only` passes those alone, without the globals. `engine-dmo check` checks an included file on its own and reports a variable only `with` provides as unknown, so write a partial that needs arguments as a macro or a component.

### macro and import [#macro-and-import]

```jinja
{% macro badge(text, tone="info") export %}<span class="badge badge--{{ tone }}">{{ text }}</span>{% endmacro %}

{% import "partials/macros.html" badge %}
{{ badge("New") }}
```

A macro is reusable markup with positional arguments and defaults. `export` makes it importable; `{% import "file" name, other %}` brings named macros into a template.

### component and slot [#component-and-slot]

```jinja
{% component 'listing-card' listing=item size='large' %}

{% component 'listing-card' listing=item %}
  {% slot 'footer' %}<a href="{{ item.uri|url }}">{{ t('card.visit') }}</a>{% endslot %}
{% endcomponent %}
```

Calls the component `components/<name>/<name>.html`, held to its contract in `components/<name>/component.yaml` by `engine-dmo check` and at render. Props are `name=value` pairs. The call has a body, closed by `{% endcomponent %}`, exactly when the first thing after the tag is a `{% slot %}`. Inside a component's markup, `{% slot 'name' %}fallback{% endslot %}` prints a filled slot. A component's markup sees the page's globals, its props, `attrs` and `slots`, never the caller's own variables. See [Components](/templates/components).

## Control flow [#control-flow]

### if [#if]

```jinja
{% if items|length > 2 and not devMode %}many{% elif items %}some{% else %}none{% endif %}
```

`elif` and `else` are optional. A value is false when it is empty, zero, `false` or nothing, and an empty field value is false.

### ifequal, ifnotequal [#ifequal-ifnotequal]

```jinja
{% ifequal entry.type "event" %}...{% else %}...{% endifequal %}
```

Equivalent to `{% if a == b %}` and `{% if a != b %}`.

### for [#for]

```jinja
{% for item in items %}...{% empty %}...{% endfor %}
{% for key, value in settings %}...{% endfor %}
{% for x in list reversed %}...{% endfor %}
{% for x in list sorted %}...{% endfor %}
```

`{% empty %}` renders when there is nothing to loop over. Inside the loop, `forloop.Counter`, `Counter0`, `Revcounter`, `Revcounter0`, `First`, `Last` and `Parentloop`. See [Loops](/templates/language#loops).

### cycle [#cycle]

```jinja
<tr class="{% cycle 'odd' 'even' %}">
```

Prints the next of its values on each pass of a loop.

### ifchanged [#ifchanged]

```jinja
{% for l in items %}{% ifchanged l.primaryTag.key %}<h2>{{ l.primaryTag.label }}</h2>{% endifchanged %}...{% endfor %}
```

Renders its body only when the value differs from the previous pass, for group headings in a sorted list.

### firstof [#firstof]

```jinja
{% firstof entry.subtitle entry.summary "" %}
```

Prints the first value that is not empty.

## Variables [#variables]

### set [#set]

```jinja
{% set places = query('listing').limit(6).all() %}
```

Binds a name for the rest of the current scope.

### with [#with]

```jinja
{% with total=pagination.total per=pagination.per %}{{ total }} / {{ per }}{% endwith %}
{% with form = enquiryForm('contact', entry) %}...{% endwith %}
```

Binds names for its body only.

## Output [#output]

### filter [#filter]

```jinja
{% filter upper %}shout{% endfilter %}
```

Applies filters to the body's output.

### spaceless [#spaceless]

```jinja
{% spaceless %}<p> <b>x</b> </p>{% endspaceless %}
```

Removes whitespace between tags in the body: `<p><b>x</b></p>`.

### templatetag [#templatetag]

```jinja
{% templatetag openvariable %} name {% templatetag closevariable %}
```

Prints a delimiter literally: `openblock`, `closeblock`, `openvariable`, `closevariable`, `openbrace`, `closebrace`, `opencomment`, `closecomment`.

### widthratio [#widthratio]

```jinja
<div class="bar" data-width="{% widthratio score 100 300 %}"></div>
```

Scales a value to a whole number: `value / max * width`.

### lorem [#lorem]

```jinja
{% lorem 2 p %}
```

Placeholder text for a layout in progress: a count, then `w` (words), `p` (paragraphs) or `b` (plain blocks).

### comment [#comment]

```jinja
{% comment %}Several lines that never render.{% endcomment %}
```

## Content [#content]

### blocks [#blocks]

```jinja
{% blocks entry.body %}
```

Renders each item of a `blocks` field through `blocks/<block key>.html` on the site's chain, with the item as `block`, its position as `blockIndex` and the number of items as `blockCount`, beside every global and the page's `entry`. It takes one argument, the field value. A block declared in the schema with no template anywhere on a site's chain fails `engine-dmo check`. See [Block templates](/templates/context#block-templates).

### nav, children and ifchildren [#nav-children-and-ifchildren]

```jinja
<nav aria-label="{{ t('nav.main') }}"><ul>
{% nav item in nav.main %}
  <li{% if item.isActive %} class="active"{% endif %}>
    <a href="{{ item.url|url }}"{% if item.isCurrent %} aria-current="page"{% endif %}>{{ item.label }}</a>
    {% ifchildren %}<ul>{% children %}</ul>{% endifchildren %}
  </li>
{% endnav %}
</ul></nav>
```

`{% nav item in list %}` renders its body once per item, with the item bound to the name given. Inside the body, `{% children %}` renders the same body again for the current item's children, one level deeper, and `{% ifchildren %}...{% endifchildren %}` renders only when the current item has children. It works over any list of maps with a `children` list: a navigation slot (`nav.main`), or your own tree. A tree deeper than 32 levels is an error.

### requireMember [#requiremember]

<Callout title="engine-dmo">This feature is part of the DMO bundle (engine-dmo).</Callout>

```jinja
{% requireMember %}
<p>{{ member.name }}</p>
```

Everything after the tag is for a signed-in member, who is then readable as `member` (`id`, `name`). A visitor who is not signed in is redirected (303) to the portal's sign-in (`/members/login` unless the portal's path is configured otherwise) with `next=` set to return to the page. A member's response is sent with `Cache-Control: private, no-store`. The tag takes no arguments. In `engine-cms`, using it is a check error naming the portal module. See [The member portal](/dmo/partners-and-portal#the-portal).

## Caching [#caching]

### cache [#cache]

```jinja
{% cache 'listing-card' key=listing.id ttl='1h' %}...{% endcache %}
{% cache 'facet-counts' key=[locale.code, page.uri] ttl='10m' vary=['query'] %}...{% endcache %}
```

Caches its rendered body across requests on public pages. The name is a quoted literal of lower case letters, digits and hyphens, starting with a letter. The options:

| Option | Value |
|---|---|
| `key` | An expression, or a list of them, that distinguishes one copy from another |
| `version` | An expression; a new value starts a new copy |
| `ttl` | How long a copy lives: a duration such as `'90s'`, `'10m'`, `'1h'`, or `'1d'` for days. At most seven days |
| `vary` | `'locale'`, `'path'` or `'query'`, or a list of them. The locale is always part of the key |

A copy is cleared when the content its body read is published, without any invalidation code. Outside a public page (a preview, a fragment request, mail) the body renders every time. See [Caching](/templates/caching).

## Interactive pages [#interactive-pages]

These tags work with the engine's fragment requests and sigmx, the small attribute-driven script the engine uses for in-place updates. They are introduced on [Forms](/templates/forms).

### fragment [#fragment]

```jinja
{% fragment 'results' %}...{% endfragment %}
{% fragment 'results-list' tag='ol' class='cards' aria-label=t('results.list') %}...{% endfragment %}
```

Names a region of a page. It renders in place inside a wrapper element with `id="f-<name>"` and `data-fragment="<name>"` (a `div`, or the element `tag=` names; any other option is an attribute of the wrapper). A request that names fragments in its `Meridian-Fragment` header gets those regions alone, rendered with the page's full context. The name is a quoted literal of lower case letters, digits and hyphens, at most 64 characters; a name may render only once per page, and `engine-dmo check` refuses one declared twice (`duplicate-fragment`). `engine-dmo render <path> --fragment results` renders only that fragment.

### announce and focus [#announce-and-focus]

```jinja
{% announce 'Saved' %}
{% announce t('form.errors', errors._count) assertive %}
{% focus '#form-errors' %}
```

`announce` tells screen readers about a change: in a response to an in-place update it is an event the page's live region reads out; on a full page load it prints a status message where it stands (`role="status"`, or `role="alert"` with `assertive`). `focus` moves focus to a selector after an in-place update, and prints nothing on a full page.

### Patch tags [#patch-tags]

Only in a declared endpoint's response template, which composes its own update of the page:

| Tag | What it does |
|---|---|
| `{% patchelements selector='#results' mode='inner' %}...{% endpatchelements %}` | Patch the elements: by the body's ids, or those `selector=` matches, with `mode=` `outer` (the default), `inner`, `replace`, `prepend`, `append`, `before` or `after` |
| `{% patchsignals searching=false count=results.total %}` | Merge values into the page's signals, as `name=value` pairs (a name may be dotted, `form.error=nil`), or one expression whose value is a map |
| `{% removeelements '#empty-state' %}` | Remove the elements a selector matches |
| `{% removesignals 'form.draft', 'form.error' %}` | Remove signals by path |

A template that contains a patch tag anywhere other than an endpoint's response is a check error (`patch-in-page`), as is content outside a `{% patchelements %}` in one (`patch-outside`). To an ordinary request, `patchelements` prints its body where it stands and the others print nothing.

### location and replaceurl [#location-and-replaceurl]

```jinja
{% location path('listing') replace=true delay=900 %}
{% replaceurl path('/search') %}
```

`location` navigates after an in-place update: to a local path, or to another origin only with `external=true` (a literal URL on another origin without it is a check error, `location-external`). `replace=true` replaces the history entry and `delay=` waits that many milliseconds. `replaceurl` changes the address bar to a local path with no navigation.

## Removed [#removed]

`{% now %}`, `{% ssi %}` and, unless the site opts in with `templates.allow_unescaped`, `{% autoescape %}` are not available: `Usage of tag 'now' is not allowed`. Use `now` and the date filters for the time.


# Testing templates (/templates/testing)

How to verify templates with engine-dmo check, the language server in your editor, describe template and describe route, render --json, and template tests in tests/templates/*.test.yaml with selector, JSON-LD and snapshot assertions.

Templates are checked at four levels, from cheapest to fullest. Each catches what the one before cannot see:

```mermaid
flowchart LR
  A["engine-dmo lsp<br/>as you type"] --> B["engine-dmo check<br/>every template, every site"]
  B --> C["engine-dmo render<br/>one real page"]
  C --> D["engine-dmo template test<br/>many pages, in CI"]
```

| Tool | Needs a database | Catches |
|---|---|---|
| [`engine-dmo lsp`](#the-language-server) in your editor | No | The check's diagnostics as you type, with completion and hover |
| [`engine-dmo check`](#engine-dmo-check) | No, with `--no-db` | Every template on every site against the project's types, fields, routes, components, image transforms and the security rules |
| [`engine-dmo render`](#render-a-page) | Yes | One real page through the whole pipeline, with its errors, queries, assets, accessibility findings and images |
| [`engine-dmo template test`](#template-tests) | Yes, seeded | Assertions on many pages' output, for CI and upgrades |

## engine-dmo check [#engine-dmo-check]

The gate. It validates configuration, schema, templates and the deployment together, and reports every problem at once, each with its file, line, column, the source line and a hint.

```bash
engine-dmo check            # everything, including database checks
engine-dmo check --no-db    # skip checks that need a database (CI, image builds)
engine-dmo check --strict   # configuration warnings are errors
engine-dmo check --json     # { diagnostics, errors, warnings, strict, valid }
```

| Flag | Effect |
|---|---|
| `--no-db` | Skip checks that need a database |
| `--strict` | Promote configuration warnings to errors (not template warnings; see below) |
| `--fix` | Write a stable id for every configuration element without one, keeping comments, then check |
| `--contract-report` | List template usage the next template contract version removes, each with its replacement |
| `--json` | Machine-readable diagnostics |

It exits 0 when valid and 3 when the configuration (templates included) is invalid. Configuration still needs its environment variables set; `--no-db` only skips connecting.

<Callout type="warn" title="Read every line, not the summary">
Template **errors** are counted and fail the check, but template **warnings** are not. A warning about a template (a head without `head()`, a missing string, an uncredited image) is printed above the summary, and the summary still says `0 errors, 0 warnings. Configuration is valid.` `--strict` does not turn a template warning into an error, and `--json` leaves template warnings out of `diagnostics` altogether. A fresh project from `engine-dmo init` shows this at once: its `base.html` has no `head()`, so `check` prints that warning and exits 0. Read the whole output, and in CI search it for `warning:` if template warnings must fail the build.
</Callout>

A template error is printed twice: once in the template checker's short form (`_shared/walk/entry.html:4:4: error: ...`) and once in the configuration form with its error code (`templates/_shared/walk/entry.html:4:4: ...` and `= error code MRD-1006`). They are the same problem.

For templates it reports, among the rest:

- a template that does not compile;
- a variable, field, filter, tag or function that is not in the template contract for that file, with a "did you mean" (`"tone" is not in the template context (contract 1)`);
- a field the template's type does not have, read on `entry` or on the type's own key (`entry.sumary`, `walk.sumary`);
- component calls against their contracts ([Components](/templates/components#what-is-checked));
- image transforms and breakpoints the site does not define, and helper keywords that are refused ([Images](/templates/images#what-check-reports));
- the security rules: a variable in `href` or `src` without `|url`, in `<script>` without `|json`, in a style or an inline handler, the `safe` filter ([Frontend build](/templates/frontend-build#no-inline-script));
- per-request output inside `{% cache %}` ([Caching](/templates/caching));
- a `sigmx.fragment()` naming a fragment no template declares;
- a site copy whose shared original has changed ([Multisite](/templates/multisite#copies-and-divergence));
- advisory warnings: a head without `head()` or a description, an image whose credit is printed nowhere, two `priority=true` images on one page.

A shared template is checked once for every site whose chain reaches it, against that site.

What it does **not** report, so that only `render` shows it:

| Not checked | What happens at render |
|---|---|
| A field read on a loop variable, a `query()` result, a relation's item or a component prop (`{% for w in items %}{{ w.photo }}`) | Prints nothing, with no error or warning, even with `template.strict: true` |
| A property a value does not have, such as `entry.publishedAt.iso` | Prints nothing |
| A `query()` misuse: an unknown type, a field that is not `index: true`, an unknown operator ([Errors](/templates/queries#errors)) | The page answers 500 |
| An unknown endpoint key in `enquiryForm()` or `subscribeForm()`, or `.render()` on either | Prints nothing |
| A required component slot when the call has no body at all | The render is refused |
| `t()` in an email template | Prints nothing ([Email templates](/templates/forms#email-templates)) |

So render each kind of page once it has content, and read the output.

## The language server [#the-language-server]

`engine-dmo lsp` is a Language Server Protocol server in the binary, so it always matches the engine that renders the templates. It needs no database and no secrets, and refuses a project whose `engine.environment` is `production`. Use `engine-cms lsp` for a project on `engine-cms`.

| Feature | What it gives |
|---|---|
| Diagnostics | On open and on every change, from the unsaved text: the compile, the security rules and the contract check of `engine-dmo check`, merged across every site whose chain holds the file. Each carries the check's code and hint, narrowed to what it names |
| Completion | Globals with their keywords, the template's type's fields (`entry.`), a field value's properties and helpers (`entry.heroImage.`), `singletons.`, `nav.`, filters after `\|`, tags after `{%`, template files in `include` and `extends`, component names and their remaining props |
| Hover | A global's or filter's documentation, a field's type, label, help and declaring file and line, a component's contract |
| Go to definition | `include`, `extends` and `import` to the file the site's chain resolves; a component call to its contract and markup; `entry.<field>`, `singletons.<key>` and `nav.<key>` to the configuration line that declares them |

It reloads the project when a configuration file or a component contract changes, so a field added to a schema file completes on the next keystroke. A configuration that fails to load keeps the last good project and publishes the loader's errors on the configuration files.

The server speaks over standard input and output (`--stdio`, the default and only transport). It finds the project from `--project`, else the workspace root the editor sends, else the working directory. Give it your templates as HTML files.

<Tabs items={['Neovim', 'VS Code', 'Zed']}>
<Tab value="Neovim">

Neovim 0.11 or later, in the project's `.nvim.lua` or your configuration:

```lua
vim.lsp.config('meridian', {
  cmd = { 'engine-dmo', 'lsp' },
  filetypes = { 'html', 'htmldjango' },
  root_markers = { 'config/engine.yaml' },
})
vim.lsp.enable('meridian')
```

</Tab>
<Tab value="VS Code">

VS Code starts a language server only through an extension. Use a generic language server client extension and point it at the command `engine-dmo lsp` for the `html` language. The server needs nothing else from the client.

</Tab>
<Tab value="Zed">

Zed registers a language server only through an extension, and there is no Meridian extension for Zed, so Zed has no diagnostics from the server. For highlighting, `engine-dmo config schema --write --editors zed` (and `engine-dmo init`) map `templates/**/*.html` to Zed's Twig language in `.zed/settings.json`; install the Twig extension once.

</Tab>
</Tabs>

## Look before you render [#look-before-you-render]

These need no database. `describe template` loads the configuration, so every `${VAR}` it uses without a default must be set, even to a placeholder (`DATABASE_URL=postgres://localhost/none`); `template api` needs none:

```bash
engine-dmo describe template listing/entry.html --site town
engine-dmo template api --site town --json
```

`describe template` says which file a name resolves to along the site's chain, what it extends and includes (and which file each resolves to), and which type it renders. `template api` is the complete template surface of a site: globals, filters, tags, field types with their properties and helpers, the project's types and fields, routes and components. `engine-dmo docs serve` shows the same in a browser.

With a database, `describe route` renders a path and prints what the template received:

```bash
engine-dmo describe route /whats-on/film-club --json
```

It reports the route that answered, the template the site's chain resolved, and the whole template context with real values: the variables, functions, filters and components available. Write a template against it.

## Render a page [#render-a-page]

```bash
engine-dmo render /whats-on/film-club              # the HTML on stdout, an image table on stderr
engine-dmo render /whats-on/film-club --json       # the report below
engine-dmo render /en/whats-on --locale fr --json  # the same page in another locale
engine-dmo render / --fragment results             # only the named fragments, as a script's request gets them
```

`render` boots the engine against the configured database, read-only, and renders the path through the real middleware and pipeline in process, with no server. A traced render records no page view and no search log entry.

| Flag | Meaning |
|---|---|
| `--site key` | The site (default: the default site) |
| `--locale code` | The locale; the path is then the unprefixed address, and the locale's prefix or domain is added |
| `--host host` | The `Host` the request carries (default: the site's first domain, or the locale's under the domain strategy) |
| `--fragment a,b` | Render only these fragments; a fragment the page did not render is a failure |
| `--json` | The report |

The `--json` report:

| Key | Value |
|---|---|
| `status`, `site`, `locale`, `request`, `kind`, `template` | The response status, what answered and the template file |
| `html` | The page |
| `errors`, `warnings` | Render problems, such as a template error with its file and line, or a second `priority=true` |
| `queries` | The database statements the page ran |
| `assets` | The stylesheets, scripts and other files the page references |
| `a11y` | Page-level accessibility findings (one `h1`, a title, the language) |
| `images` | Each image: transform, `sizes`, ladder, formats, each derivative's bytes and whether it is stored |

It exits 1 when the status is 400 or above or the render failed. Log lines (the engine starting, the signing key warning, the request) go to standard error before the page or the failure, so read standard output for the page and the exit status for the result; a failure to reach the database prints those lines and then `MRD-3001`.

`render` has no visitor and no session: `csrfInput()`, `csrfToken()` and `csrf` print nothing, and a drawn form's `_csrf` field is empty. Check token handling on a running server.

## Template tests [#template-tests]

Template tests render pages through the real pipeline against the seeded database and assert on the output. Put them in `tests/templates/*.test.yaml` (or one directory below):

```yaml
# tests/templates/site.test.yaml
- name: the home page lists what is on
  path: /
  template: page/entry.html
  expect:
    contains: ["Coming up", "Thursday Film Club"]
    selector: { "h1": "Riverside Arts", "#form-newsletter": { count: 1 } }
    lang: en-GB
    headers: { Content-Type: text/html }

- name: a news story renders its title and hero
  fixture: seed:article/new-season
  template: article/entry.html
  expect:
    selector: { "article h1": { count: 1 }, "article picture img": { count: 1 } }
    jsonld: { "@type": "Article" }
    not_contains: ["undefined", "%!s("]

- name: a weekly event links its calendar file
  fixture: seed:event/thursday-film-club
  expect:
    selector: { "a[download]": { attr: { href: /whats-on/thursday-film-club.ics } } }

- name: the events index is unchanged
  path: /whats-on
  locale: en-GB
  snapshot: true

- name: an address with no page is not found
  path: /no-such-page
  expect:
    status: 404
```

```bash
engine-dmo seed apply
engine-dmo template test
```

### A test [#a-test]

| Key | Meaning |
|---|---|
| `name` | Required; what the test is called in the output |
| `path` | The page's address, starting with `/`, without the locale prefix when `locale` is given |
| `fixture` | `seed:<type>/<slug>`: the seeded document's address through its type's route on the site. Use `path` for a nested or parented address |
| `site` | The site's key; the default site otherwise |
| `locale` | The locale |
| `fragment` | Fragments to request, as the `Meridian-Fragment` header names them |
| `template` | The template the page must render with |
| `snapshot` | `true` records the page's markup and compares later runs with it |
| `expect` | The assertions |

A test has exactly one of `path` and `fixture`.

### Assertions [#assertions]

| Key | Passes when |
|---|---|
| `status` | The response status is this (200 when not given) |
| `contains`, `not_contains` | The page contains, or does not contain, each string |
| `selector` | Each CSS selector's first match has the given text; or, as a map, `count` matches, its `text` equals, its text `contains`, its `attr` values equal |
| `jsonld` | Some object in the page's JSON-LD (inside `@graph` and nested objects too) holds these values |
| `lang` | The `html` element's `lang` |
| `headers` | Each header's value contains the given text |

Every failing assertion is reported, not only the first.

Selectors support type selectors, `#id`, `.class`, `[attr]`, `[attr=value]`, `[attr~=value]`, `[attr^=value]`, `[attr*=value]`, `*`, the descendant combinator (a space), the child combinator (`>`) and groups separated by commas.

### Snapshots [#snapshots]

A test with `snapshot: true`, or every test under `--snapshots`, records the page's markup in `tests/templates/__snapshots__/<file>/<name>.html` on its first run and compares later runs with it, reporting the first line that differs. The CSRF token's value and asset version queries are blanked first, since they change between runs. Commit the snapshots; `--update` records them again after an intended change.

### Running [#running]

```bash
engine-dmo template test                     # every test
engine-dmo template test --filter "news"     # tests whose name or file contains "news"
engine-dmo template test --snapshots         # snapshot every test
engine-dmo template test --update            # record snapshots again
engine-dmo template test --json              # { passed, failed, tests: [{ name, file, line, passed, failures, snapshot }] }
```

It prints one line per test with its file and line, the failures beneath, and a count. A failing test exits 1. A problem in a test file (a test with no name, with neither or both of `path` and `fixture`, a malformed fixture, a selector it cannot read) is reported at its line and column together with the rest, nothing renders, and the run exits 3:

```text
tests/templates/bad.test.yaml:5:12: test "both" names both a path and a fixture; give one
```

The tests read the database `engine-dmo seed apply` wrote. A test of content that is not there fails on its status.

## In development [#in-development]

Under `engine-dmo serve --dev`:

- a template error renders a development error page with the file, the line and the source, instead of the site's error template;
- `dump(value)` and the `dump` filter render a navigable tree of a value, and `dump()` the whole context; both are development only;
- `devMode` is true, for markup you want only while developing;
- `?_profile` on a page links to its profile: the render's spans, queries and each cache block's hit, miss or skip;
- templates are read afresh on every render.

## In CI [#in-ci]

```bash
engine-dmo check --no-db --strict > check.log 2>&1 || { cat check.log; exit 1; }
cat check.log; ! grep -q 'warning:' check.log      # fail on template warnings too
engine-dmo build --no-db --strict                  # with a frontend build
engine-dmo migrate up && engine-dmo schema apply && engine-dmo seed apply
engine-dmo template test --json
```

The first lines need no database, but they still load the configuration, so set `DATABASE_URL` and every other `${VAR}` without a default to a placeholder; a `signing_key` read from a variable must be at least 32 characters even then. The last three need a disposable database with `DATABASE_URL` pointing at it.

## Related [#related]

- [CLI reference](/reference/cli): every command and flag.
- [Template API reference](/reference/template-api): the generated surface.
- [Error codes](/reference/error-codes).