domma-cms 1.6.60 → 1.7.1

package/docs/configuration.md

@@ -0,0 +1,1811 @@
+# Configuration
+
+All runtime configuration lives in the `config/` directory as plain JSON files. Secrets (JWT_SECRET, NODE_ENV) belong exclusively in `.env` - nothing else should be placed there.
+
+Configuration files are loaded at startup via `server/config.js` and cached in memory. Admin-editable configs (`site`, `navigation`, `presets`, `plugins`) can be updated through the API at runtime and are written back to disk immediately.
+
+---
+
+## `config/server.json`
+
+Controls the HTTP server.
+
+```json
+{
+  "port": 4096,
+  "host": "0.0.0.0",
+  "cors": { "origin": false, "publicPrefixes": [] },
+  "uploads": { "maxFileSize": 10485760 },
+  "logging": { "level": "info" }
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `port` | number | `4096` | TCP port the Fastify server binds to |
+| `host` | string | `"0.0.0.0"` | Network interface to listen on. Use `"127.0.0.1"` to restrict to localhost |
+| `cors.origin` | boolean / string / string[] | `false` | Passed directly to `@fastify/cors`. `false` disables CORS. Set to `"*"` or a domain to allow cross-origin requests |
+| `cors.publicPrefixes` | string[] | `[]` | Absolute path prefixes whose **GET and HEAD** responses carry `Access-Control-Allow-Origin: *`, so other origins can hot-link those assets. A module script is fetched in CORS mode, so this is what makes e.g. `/public/demos/` importable from elsewhere. `@fastify/cors` decides per origin and cannot express a path, hence the separate key. Reads only - it never widens a write, and it applies to listed prefixes only. A value that is not an absolute path is ignored |
+| `csp.connectHosts` | string[] | `[]` | Other sites a public page may read from in the browser (`fetch`), added to the Content-Security-Policy's `connect-src` as `https://<host>`. The site itself and cdn.jsdelivr.net are always allowed. Bare hostnames only (`dcm.dommajs.org`); a scheme, path, port or wildcard is ignored. Read at boot, so restart after changing it |
+| `uploads.maxFileSize` | number | `10485760` (10 MB) | Maximum allowed upload size in bytes |
+| `logging.level` | string | Log verbosity: `fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`. Defaults to `info` in development, `warn` otherwise. `warn` hides 4xx responses and plugin `log.info` output, so a failed admin action leaves no trace - raise it to `info` if you need to diagnose one. Overridden by the `LOG_LEVEL` env var. |
+| `restartOnPluginToggle` | boolean | `true` | Restart the server automatically when an admin enables or disables a plugin. See **Plugin toggles restart the server** below |
+| `requireSignedPlugins` | boolean | `false` | When `true`, only signed `.dcmsplugin` bundles can be installed - an unsigned bundle (e.g. one exported from another site) is refused even if the installer confirms it. A bundle with a signature that does not verify is always refused, whatever this is set to |
+
+### Plugin toggles restart the server
+
+A plugin's routes, hooks and admin views only register at boot, so enabling or
+disabling one does nothing until the process restarts. The CMS does that for you:
+after the toggle is saved the process exits cleanly and its supervisor brings it
+back on the new plugin set. The admin UI waits for the server and reports when it
+is live again.
+
+Two guards keep this safe:
+
+- **Only when supervised.** A restart happens only if something will start the
+  process again - pm2 (`pm_id` / `PM2_HOME`) or the fleet manager, which forks
+  each site with an IPC channel. Under a bare `node server/server.js` the toggle
+  is saved and the response says `restartRequired: true, supervised: false`, and
+  the admin is told to restart manually rather than losing the site.
+- **Only on a real change.** Saving a plugin's *settings*, or re-sending the
+  `enabled` value it already had, never restarts anything. Several toggles in
+  quick succession are debounced into a single restart.
+
+Set `restartOnPluginToggle: false` to keep the old behaviour, where the admin is
+told a restart is needed and performs it themselves.
+
+---
+
+## `config/auth.json`
+
+Controls JWT token lifetimes and password hashing cost. Does **not** store roles or permissions - those live in the `roles` collection.
+
+```json
+{
+  "accessTokenExpiry": "15m",
+  "refreshTokenExpiry": "7d",
+  "resetTokenExpiry": "1h",
+  "bcryptRounds": 10
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `accessTokenExpiry` | string | `"15m"` | Access token lifetime. Accepts `Nm` (minutes), `Nh` (hours), `Nd` (days) |
+| `refreshTokenExpiry` | string | `"7d"` | Refresh token lifetime |
+| `resetTokenExpiry` | string | `"1h"` | Password reset link lifetime - `30m`, `1h`, `2d`; the email and the login screen say it in words |
+| `bcryptRounds` | number | `10` | bcrypt cost factor. Higher = slower hashing, more secure. 10-12 is typical |
+
+---
+
+## `config/content.json`
+
+Tells the CMS where to find its content directories and what defaults to apply to new pages.
+
+```json
+{
+  "contentDir": "./content",
+  "mediaDir": "./content/media",
+  "usersDir": "./content/users",
+  "collectionsDir": "./content/collections",
+  "pageDefaults": {
+    "layout": "default",
+    "status": "draft",
+    "sortOrder": 99
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `contentDir` | string | Root content directory - pages live at `{contentDir}/pages/` |
+| `mediaDir` | string | Where uploaded media files are stored |
+| `usersDir` | string | Where user account JSON files are stored |
+| `collectionsDir` | string | Root directory for all collection data and schemas |
+| `pageDefaults.layout` | string | Layout preset applied to new pages |
+| `pageDefaults.status` | string | Initial publish status for new pages (`"draft"` or `"published"`) |
+| `pageDefaults.sortOrder` | number | Default sort order for new pages |
+
+---
+
+## `config/site.json`
+
+The main site-wide configuration. This file is editable from the **Settings** admin panel.
+
+```json
+{
+  "title": "My Site",
+  "tagline": "A site built with Domma CMS",
+  "fontFamily": "Roboto",
+  "fontSize": 16,
+  "theme": "silver-dark",
+  "adminTheme": "charcoal-dark",
+  "layoutOptions": {
+    "spacerSize": 40
+  },
+  "seo": {
+    "defaultTitle": "My Site",
+    "titleSeparator": " | ",
+    "defaultDescription": "A site built with Domma CMS",
+    "defaultImage": "/media/og-default.png",
+    "robotsExtra": ""
+  },
+  "footer": {
+    "copyright": "© 2026 My Company",
+    "layout": "auto",
+    "blurb": "",
+    "showMotionToggle": true,
+    "links": [
+      { "text": "Privacy Policy", "url": "/privacy" }
+    ]
+  },
+  "social": {
+    "twitter": "",
+    "facebook": "",
+    "instagram": "",
+    "linkedin": "",
+    "github": "",
+    "youtube": ""
+  },
+  "smtp": {
+    "host": "localhost",
+    "port": 1025,
+    "user": "",
+    "pass": "",
+    "secure": false,
+    "fromAddress": "noreply@example.com",
+    "fromName": "My Site"
+  },
+  "backToTop": {
+    "enabled": true,
+    "scrollThreshold": 180,
+    "position": "bottom-right",
+    "offset": 16,
+    "bottomOffset": 16,
+    "label": "",
+    "smooth": true
+  },
+  "cookieConsent": {
+    "enabled": true,
+    "message": "We use cookies...",
+    "position": "bottom",
+    "layout": "bar",
+    "theme": "dark"
+  },
+  "breadcrumbs": {
+    "enabled": true,
+    "homeLabel": "Home",
+    "position": "TL",
+    "offsetX": 24,
+    "offsetY": 64
+  }
+}
+```
+
+### Key fields
+
+| Field | Description |
+|---|---|
+| `title` | Site name injected into `<title>` and the navbar brand |
+| `tagline` | Short strapline displayed in the navbar brand |
+| `adminHome` | The admin route `#/` (Dashboard) opens - `/plugins/site-manager/dashboard`, say. Absent or `/` = the built-in dashboard. Set at System > Site Settings. Ignored for a user without the permission guarding that screen, or when the sidebar no longer knows it (its plugin disabled); a confined role's own home wins. See `server/services/adminHome.js`. |
+| `theme`, `adminTheme`, `fontFamily`, `fontSize`, `autoTheme`, `baseTheme` | **Mirror only.** These moved to `config/theme.json` (see below) and are rewritten here on every theme save so plugins and fleet tooling that read them keep working. Editing them here has no effect. |
+| `smtp` | SMTP connection details for outgoing email (password is stripped from GET responses) - see **Outgoing email** below |
+| `social` | Social profile URLs; empty strings are ignored by the frontend |
+| `footer` | Footer copyright, legacy link list, and the "Reduce motion" switch - see below |
+| `backToTop` | Scroll-to-top button configuration |
+| `cookieConsent` | Cookie consent banner configuration |
+| `breadcrumbs` | Breadcrumb navigation configuration |
+| `bodyClass` | Your own CSS classes on the `<body>` of every public page (Site Settings > General > Body CSS classes) |
+| `baseUrl` | **Optional override.** Absolute origin (e.g. `https://example.com`). By default the CMS derives the origin from the incoming request (`request.protocol` + `request.host`), so sitemap URLs and canonical tags automatically match whatever domain you serve from - set this only if you sit behind infrastructure that doesn't forward `Host` correctly. Password reset links always use it when it is set; without it they go only to an address someone has signed in at, never to whatever host a reset request claims. Editable as **Site URL** in Settings › General. |
+| `seo` | SEO defaults applied when a page has no overrides - see below |
+
+### Outgoing email
+
+A new site ships with a complete `smtp` block, so the fields are visible in **Settings → Email** from
+the first boot and the site never starts out with nowhere to send mail.
+
+**Why it is seeded rather than left blank.** An empty `smtp.host` is not an error - the CMS falls
+back to a throwaway [Ethereal](https://ethereal.email) test account, which accepts the message and
+reports success. Password resets and form notifications all appear to send, the Health panel's "Last
+email send" goes green, and nothing arrives. That fallback is useful in development and is still
+there, but it is no longer silent.
+
+**What a new site gets.**
+
+- Created by the **CLI** (`npx domma-cms my-site`): `bin/lib/smtp-defaults.js` reads the environment
+  and falls back to a local MTA.
+
+  | Variable      | Default                                   |
+  |---------------|-------------------------------------------|
+  | `SMTP_HOST`   | `localhost`                               |
+  | `SMTP_PORT`   | `587` with a host set, `25` without       |
+  | `SMTP_SECURE` | `false` (`1`/`true`/`yes`/`on` to enable) |
+  | `SMTP_USER`   | empty                                     |
+  | `SMTP_PASS`   | empty                                     |
+  | `SMTP_FROM`   | empty                                     |
+
+  `fromName` is seeded from the site title, and `npm run setup` renames it along with the site - but
+  only while the two still agree, so a From name you chose yourself is never overwritten.
+
+- Created by the **fleet manager**: `composeSmtp` in
+  `plugins/site-manager/services/siteScaffolder.js` inherits the manager's own relay host, port and
+  TLS setting (never its credentials) and defaults `fromAddress` to `noreply@<primary domain>`.
+
+**Credentials.** They are read from the environment at scaffold time rather than compiled in, but
+they are written into `config/site.json`, which is where this CMS keeps them. That file is yours and
+the updater never merges it, but it is not a secret store - treat a site directory holding a relay
+password accordingly.
+
+**When a site has no host.** Existing sites are not migrated, so they keep whatever they have. If
+the host is empty you get, in order of how likely you are to see it:
+
+1. A warning banner on **Settings → Email**.
+2. An `SMTP host: not configured` warning in **Health**, alongside - and deliberately separate from -
+   the `Last email send` check, which reports green on an Ethereal send because nodemailer really did
+   accept the message. The two together are the whole story; neither tells it alone.
+3. A `console.warn` at startup of the first send.
+
+### Footer
+
+| `footer` field | Type | Description |
+|---|---|---|
+| `copyright` | string | Copyright line - above the footer navigation in the one-row layout, at the left of the bottom bar in the columns layout |
+| `layout` | string | `auto` (default), `columns` or `row`. **Columns**: the brand (the navbar's text, logo or icon), the blurb and the social links beside one column per group of the `footer-primary` menu (a top-level item with sub-items; its text is the heading, a link only if it has a URL), over a bottom bar of copyright, the `footer-legal` menu and the motion control. **Row**: everything on one wrapped row, as before. **Auto**: columns when the footer menu has groups, else a row. Site Settings > Footer > Layout. |
+| `blurb` | string | A sentence or two under the brand in the columns layout. Plain text. |
+| `showMotionToggle` | boolean | Whether the footer shows the "Reduce motion" accessibility switch. **Defaults to `true`** - omit the key and the switch appears, so sites that predate this setting are unchanged. Editable from Site Settings > Footer. |
+| `class` | string | Your own CSS classes on the site footer (`#site-footer`). Site Settings > Footer. |
+| `socialClass` | string | Your own CSS classes on every social media icon link in the footer. |
+| `links` | array | Legacy single footer link list. Migrated to `config/menus/` on first boot (see [Multi-menu system](#multi-menu-system)); kept only so the migration can read it. |
+
+Setting `showMotionToggle: false` hides the control, not the capability. A visitor who already
+flipped the switch keeps their stored `domma:reduced_motion` preference, and anyone whose browser
+sends `prefers-reduced-motion: reduce` still gets the calmer site - they just lose the ability to
+override it from the footer.
+
+### SEO and indexing
+
+The `seo` block on `site.json` provides site-wide defaults. Individual pages can override any of these via the `seo` block in their frontmatter.
+
+| `seo` field | Description |
+|---|---|
+| `defaultTitle` | Used in the title fallback chain and as `<title>` for pages without one |
+| `titleSeparator` | Separator between page title and site title (default ` | `) |
+| `defaultDescription` | Falls back into `<meta name="description">` and Open Graph / Twitter description |
+| `defaultImage` | Falls back into `og:image` / `twitter:image` |
+| `robotsExtra` | Extra lines appended to the end of `/robots.txt` (e.g. additional `Disallow` rules) |
+
+**Page-level frontmatter overrides:**
+
+```yaml
+---
+title: My Page
+seo:
+  title: Custom <title> override
+  description: Custom meta description override
+  image: /media/my-page-og.png
+  ogType: website        # default 'article' for content pages
+  noindex: true          # emits <meta name="robots" content="noindex, nofollow"> and excludes from sitemap
+---
+```
+
+**Generated tags on every page:**
+
+- `<title>` and `<meta name="description">`
+- `<link rel="canonical">` (requires `baseUrl`)
+- Open Graph: `og:title`, `og:description`, `og:type`, `og:site_name`, `og:url`, `og:image`
+- Twitter Card: `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`, `twitter:site`
+- JSON-LD `WebPage` schema block
+
+**Sitemap and robots.txt:**
+
+- `/sitemap.xml` is generated automatically from the published page list. The absolute URLs (`<loc>`) are derived from the incoming request's `Host` and protocol, so the same CMS serves correct URLs whether you visit it at `localhost`, a staging domain, or production - no config required.
+- `/robots.txt` is generated the same way and references the sitemap at the matching origin.
+- When the CMS sits behind a reverse proxy (nginx, Apache, the fleet manager, etc.), set the `TRUST_PROXY` environment variable so Fastify honours `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-For` from the proxy. Use `TRUST_PROXY=loopback` when the proxy is on the same machine (the default for sites the manager creates), or a comma-separated list of the proxy's addresses/CIDRs, or a hop count. Avoid `TRUST_PROXY=true` (or `1`): it trusts every hop, so Fastify takes the left-most `X-Forwarded-For` entry - which the visitor controls - letting anyone spoof their IP address and dodge rate limits and sign-in lockouts.
+- The cache is keyed per-origin, so a multi-domain deployment returns the right URLs for each host without cross-contamination.
+- The sitemap is cached and invalidated whenever a page is created, updated, renamed, or deleted.
+- Indexability rules (which pages enter the sitemap) live in `server/services/sitemap.js` → `shouldIncludeInSitemap()`. The default behaviour follows the `status`, `visibility`, and `seo.noindex` fields above.
+
+---
+
+## `config/theme.json`
+
+Everything that decides how the site and the admin look. Editable from **Content > Theme** in the admin.
+Created on first boot by a one-shot migration out of `config/site.json`.
+
+```json
+{
+  "version": 1,
+  "theme": "silver-dark",
+  "adminTheme": "charcoal-dark",
+  "baseTheme": null,
+  "autoTheme": {
+    "enabled": false,
+    "dayTheme": "charcoal-light",
+    "nightTheme": "charcoal-dark",
+    "dayStart": "07:00",
+    "nightStart": "19:00"
+  },
+  "font": {"family": "Nunito", "size": 18},
+  "overrides": [
+    {
+      "id": "ov-1789805000000-a1b2c3",
+      "label": "Navbar island",
+      "enabled": true,
+      "scope": "#site-navbar",
+      "theme": "ocean-light",
+      "tokens": {"--dm-primary": "#0096c7"},
+      "css": ""
+    }
+  ]
+}
+```
+
+| Field | Description |
+|---|---|
+| `theme` | Public site theme id |
+| `adminTheme` | Admin panel theme id (admin-chrome themes are only offered here) |
+| `baseTheme` | Set by the Theme Roller plugin when a generated theme is active. `theme` then names the custom theme and `baseTheme` the built-in one Domma's engine is given; the picker is disabled while it is set. |
+| `autoTheme` | Day/night pair, switched on each visitor's local time. Ignored when a page pins its own theme, and unavailable with a Theme Roller theme. |
+| `font.family` / `font.size` | Public site body font and root size |
+| `overrides[]` | Per-element theme overrides - see below |
+
+### Override fields
+
+| Field | Description |
+|---|---|
+| `id` | Generated; stable across saves |
+| `label` | Name shown in the admin. Emitted as a comment in the generated CSS. |
+| `enabled` | `false` keeps the record but compiles nothing |
+| `scope` | CSS selector for the region. `*`, `:root` and `html` are refused. |
+| `theme` | Optional theme id whose tokens are copied onto the scope |
+| `tokens` | `--dm-*` values applied after the adopted theme, so they win |
+| `css` | Verbatim CSS appended after the generated rule. `@import`, `javascript:` and `expression()` are refused, and `</style>` is neutralised. |
+
+The compiled stylesheet is injected into every public page as `<style id="dm-theme-overrides">`, **before**
+`content/custom.css`. See [Theming](theming.md#element-overrides) for the mechanism and its one known limit.
+
+### API
+
+| Method | Path | Permission |
+|---|---|---|
+| `GET` | `/api/theme` | `theme.read` |
+| `PUT` | `/api/theme` | `theme.update` |
+| `GET` | `/api/theme/catalog` | `theme.read` - theme ids and `--dm-*` token names the installed stylesheet defines |
+| `POST` | `/api/theme/compile` | `theme.read` - compile a candidate config to CSS without saving |
+
+---
+
+## `config/search.json`
+
+The public site's own search: what the overlay says, how it is opened, and where its trigger sits. Editable from
+**System > Search** in the admin. The file is optional - a site without one uses the defaults below - and it is
+written on first boot by the migration that retired the old `site-search` plugin.
+
+```json
+{
+  "enabled": true,
+  "placeholder": "Search pages...",
+  "keyboardShortcut": true,
+  "maxResults": 10,
+  "minQueryLength": 2,
+  "debounceMs": 300,
+  "displayMode": "floating",
+  "position": "right-center",
+  "offsetX": 32,
+  "offsetY": 32,
+  "iconOnly": true,
+  "iconSize": 52,
+  "iconRadius": 26
+}
+```
+
+| Field | Type | Default | Purpose |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Off adds no trigger, stylesheet or script to public pages at all |
+| `placeholder` | string | `Search pages...` | Placeholder text inside the search input |
+| `keyboardShortcut` | boolean | `true` | `Ctrl+K` / `⌘K` opens and closes the overlay |
+| `maxResults` | number | `10` | Results returned per query (1-50) |
+| `minQueryLength` | number | `2` | Characters required before a query runs (1-5) |
+| `debounceMs` | number | `300` | Pause after typing stops before the query fires (100-1000) |
+| `displayMode` | `navbar` \| `floating` | `floating` | Search icon in the navbar, or a fixed button on every page |
+| `position` | `top-left` \| `top-right` \| `left-center` \| `right-center` \| `bottom-left` \| `bottom-right` | `right-center` | Floating button placement (ignored in navbar mode) |
+| `offsetX` / `offsetY` | number | `32` | Floating button distance from the screen edge, in pixels (0-500) |
+| `iconOnly` | boolean | `true` | Off puts a "Search" label beside the floating icon |
+| `iconSize` | number | `52` | Width and height of the floating icon button, in pixels (32-96). The search glyph scales with it, keeping the 20/52 proportion the button shipped with. Icon mode only |
+| `iconRadius` | number | `26` | Corner radius of the floating icon button, in pixels. `0` is a square; **half of `iconSize` is a circle**, and that is the ceiling - a larger value is clamped on save, since at half its width a square is already round. Applies in icon mode only: the navbar trigger has no surface to round, and the labelled variant is a pill |
+
+Unknown keys are dropped on save and out-of-range numbers are clamped: the whole object is embedded in the source of
+every public page as `window.__CMS_SEARCH__`, so nothing private belongs in it.
+
+### API
+
+| Method | Endpoint | Auth |
+|---|---|---|
+| `GET` | `/api/search?q=…` | Public - scored results across published pages |
+| `GET` | `/api/search/settings` | Public - the same object the page already carries |
+| `PUT` | `/api/search/settings` | Admin |
+
+### What gets searched
+
+`listPages()` on every query - there is no index, so cost is linear in the number of pages. Drafts and pages with
+`visibility: private` are skipped. Scoring is weighted by field (title, then tags, then description, then body); the
+body is reduced to plain prose first (`stripMarkdown` in `server/services/search.js`), which drops fenced code,
+`<pre>`/`<code>`, shortcode tags and `[dconfig]` while keeping readable shortcode attributes such as
+`[card title="…"]`.
+
+---
+
+## `config/menus/<slug>.json`
+
+**Site menus** - the menus built in the admin (**Content → Site menus**) - each live in their own file under `config/menus/`. (They are not the **page contents**: the list a layout with a sidebar builds from a page's own headings, set up in Layouts and with `[contents]`.) The filename (minus extension) is the menu slug. A menu is a tree of items with per-menu style/behaviour overrides - sites can have any number of menus and map them to named slots (see `config/menu-locations.json` below).
+
+```json
+{
+  "slug":        "main",
+  "name":        "Main navigation",
+  "description": "Top-level site nav",
+  "variant":     "transparent",
+  "position":    "floating",
+  "style": {
+    "fontFamily":    "Inter",
+    "fontSize":      "14px",
+    "fontWeight":    "500",
+    "letterSpacing": "0.01em",
+    "iconSize":      "15px"
+  },
+  "items": [
+    {
+      "text":       "Home",
+      "url":        "/",
+      "icon":       "home",
+      "hidden":     false,
+      "bundled":    false,
+      "visibility": "public",
+      "items":      []
+    },
+    {
+      "text": "Resources",
+      "url":  "/resources",
+      "icon": "book-open",
+      "items": [
+        {
+          "text": "Guides",
+          "url":  "/resources/guides",
+          "items": [
+            { "text": "Beginner", "url": "/resources/guides/beginner" },
+            { "text": "Advanced", "url": "/resources/guides/advanced" }
+          ]
+        }
+      ]
+    }
+  ],
+  "meta": {
+    "createdAt":   "2026-05-24T10:00:00Z",
+    "updatedAt":   "2026-05-24T10:00:00Z",
+    "bundled":     false,
+    "presetOwner": null
+  }
+}
+```
+
+### Menu fields
+
+| Field         | Required | Type   | Description                                                                                |
+|---------------|----------|--------|--------------------------------------------------------------------------------------------|
+| `slug`        | yes      | string | URL-safe identifier; matches filename                                                      |
+| `name`        | yes      | string | Human-readable label shown in admin                                                        |
+| `description` | no       | string | Free text                                                                                  |
+| `variant`     | no       | string | Domma navbar variant - only meaningful in the navbar location                              |
+| `position`    | no       | string | `sticky | fixed | static | floating` - honoured by the navbar, the admin sidebar, and `[menu]` |
+| `orientation` | no       | string | `horizontal` (default) or `vertical` - see **Orientation** below                           |
+| `align`       | no       | string | `left | centre | right | spread` - where items sit along a horizontal menu; see **Alignment** below |
+| `side`        | no       | string | `left` (default) or `right` - which edge a vertical navbar docks to                        |
+| `float`       | no       | object | Pinning + panel surface for `position: floating` - see **Floating menus** below            |
+| `highlight`   | no       | object | Hover + current-page item effects - see **Item highlighting** below                        |
+| `entrance`    | no       | object | Staggered entrance of the items when the menu is drawn - see **Staggered entrance** below  |
+| `class`       | no       | string | Your own CSS classes on the menu's outer element - see **Designer classes** below          |
+| `style`       | no       | object | Font/spacing overrides; applied as CSS custom properties on the menu root                  |
+| `binding`     | no       | object | Slot takeover for one project or a set of pages - see **Menu bindings** below              |
+| `items`       | yes      | array  | Items tree (depth-unbounded)                                                               |
+| `meta`        | no       | object | Audit / lifecycle metadata (`createdAt`, `updatedAt`, `bundled`, `presetOwner`)            |
+
+### Item fields
+
+| Field        | Required | Type               | Description                                                                       |
+|--------------|----------|--------------------|-----------------------------------------------------------------------------------|
+| `text`       | yes      | string             | Label                                                                             |
+| `url`        | yes      | string             | href                                                                              |
+| `icon`       | no       | string             | Domma icon name                                                                   |
+| `hidden`     | no       | boolean            | Hard off-switch - never rendered                                                  |
+| `bundled`    | no       | boolean            | Preset/plugin-seeded marker                                                       |
+| `visibility` | no       | string \| string[] | `public | private | <role> | =<role> | [<role>, ...]` (page-style; `=<role>` = that role only). Defaults to `public`. |
+| `permission` | no       | string             | Resource key from `permissionRegistry` (e.g. `pages`, `menus`, `projects`). Renderer hides items the user can't act on. Missing = always visible (subject to `visibility`). |
+| `highlight`  | no       | object             | Per-item override of the menu's `highlight` - same `{hover, active, accent}` shape. See **Item highlighting** below |
+| `class`      | no       | string             | Your own CSS classes on the item's `<li>` - see **Designer classes** below        |
+| `items`      | no       | array              | Nested children                                                                   |
+
+`visibility` is checked at render time by `checkVisibility(userRole, visibility)` from `server/middleware/auth.js` - items the requesting user can't see are removed from the output server-side.
+
+#### Structural items
+
+Three item types carry no `text` and no `url` - they shape the list rather than link anywhere.
+All are positional like any other item, so they move, indent and drag the same way, and none can
+take children.
+
+| `type`           | Renders as                                   | Extra fields |
+|------------------|----------------------------------------------|--------------|
+| `separator`      | A dividing line                              | -            |
+| `spacer`         | Blank room, no line                          | `size`       |
+| `theme-switcher` | The site's theme dots, among the links       | -            |
+
+`size` is `xs | sm | md | lg | xl` (default `md`), mapped to the theme's `--dm-space-*` tokens so a
+spacer scales with the rest of the UI - or `flex`, which claims all the leftover room instead of a
+fixed amount:
+
+```json
+"items": [
+  { "text": "Home",    "url": "/" },
+  { "text": "Docs",    "url": "/docs" },
+  { "type": "spacer",  "size": "flex" },
+  { "text": "Log in",  "url": "/login" }
+]
+```
+
+A `flex` spacer is how you push what follows it to the far end: the right of a horizontal navbar,
+the foot of a vertical rail or the admin sidebar. It needs a flex container to claim room from, so
+the renderers stamp `dm-menu--has-flex-spacer` (or `dm-admin-sidebar--has-flex-spacer`) on a menu
+that actually contains one, rather than making every menu list flex.
+
+The axis follows the menu: in a vertical list a spacer is height, in a horizontal one it is width.
+Spacers are `aria-hidden`, so they never read as empty items.
+
+Two rendering notes:
+
+- **Public navbar** - Domma has no spacer or top-level divider concept, so both are removed before
+  the navbar is built. Spacers are then re-inserted into the rendered `<ul>`; top-level separators
+  stay dropped, since a dividing line across a horizontal bar has nothing to divide.
+- **Floating panels** - a panel sized to its content has no leftover room, so a `flex` spacer there
+  falls back to a fixed minimum gap.
+
+A `theme-switcher` item shows the themes chosen in `config/theme.json`'s `switcher.themes`
+(all of them when the list is empty), whether or not the floating switcher (`switcher.enabled`)
+is on - so a site can turn the floating disc off and keep the switcher in its menu. The disc is
+drawn inline and its panel drops down from it. In the public navbar it works at the top level
+only; one inside a dropdown is left out, as a dropdown has no room for the panel. The Menus editor
+adds one with **Add theme switcher** (not offered for the admin sidebar, where it means nothing).
+
+### Docked menus
+
+The menu in the navbar slot, when it is docked (any position but `floating`), takes a `dock` block:
+
+```json
+"dock": { "width": 280, "collapsible": true, "collapsed": false, "autohide": false, "hideOnScroll": false }
+```
+
+| Key | For | Does |
+|-----|-----|------|
+| `width` | vertical rail | Its width in px, 160-480 (240 when unset). The page's gutter follows it. |
+| `collapsible` | vertical rail | A toggle shrinks the rail to its icons (labels become tooltips; an item with no icon shows its initial; sub-menus fly out beside it). Each visitor's choice is remembered in their browser. |
+| `collapsed` | vertical rail | Starts collapsed until the visitor chooses (implies `collapsible`). |
+| `autohide` | vertical rail | The rail slides off its edge, leaving a 10px strip; it comes back on hover, on a tap, or when focus moves into it. The page takes the full width. Wins over `collapsible`. |
+| `hideOnScroll` | horizontal bar | The bar slides away while scrolling down and returns on the way up - never while a dropdown is open or focus is inside it. Best with `position: sticky`. |
+
+Width and autohide are drawn from the first paint (body classes and a `--dm-vnav-width` token); a
+visitor's collapsed or hidden choice is applied by a small script straight after `<body>`, so the
+gutter never jumps. Visitors can right-click the rail for **Collapse to icons / Expand menu**,
+**Hide when not in use / Keep on screen** and **Reset to the site's setting**. All of it is desktop only
+(993px and up) - below that the menu is the usual drawer. Set it in **Menus → (menu) → Behaviour**.
+
+A page can change any of this - and any other Behaviour setting - for itself with the `[navbar]` tag
+(see `docs/markdown-shortcodes.md`).
+
+### Floating menus
+
+`position: "floating"` detaches a menu from the document flow and pins it to a viewport corner or
+edge - the same shape as `site.json`'s `breadcrumbs` block. The `float` object tunes the placement:
+
+| Field     | Required | Type   | Default | Description                                                                 |
+|-----------|----------|--------|---------|-----------------------------------------------------------------------------|
+| `anchor`  | no       | string | `TL`    | `TL | TR | BL | BR | L | R`. `L`/`R` pin to the middle of that edge         |
+| `offsetX` | no       | number | `16`    | Distance in px from the anchored left/right edge (clamped 0-4000)           |
+| `offsetY` | no       | number | `16`    | Distance in px from the anchored top/bottom edge; ignored for `L`/`R`       |
+| `width`   | no       | number | -       | Panel width in px (clamped 120-600). Omit for content width                 |
+| `zIndex`  | no       | number | `150`   | Stacking order against the rest of the page                                 |
+| `radius`  | no       | number | theme   | Corner rounding in px (clamped 0-48). Omit to inherit the theme radius      |
+| `shadow`  | no       | string | theme   | `none | sm | md | lg | xl` - maps to the `--dm-shadow-*` tokens            |
+| `accent`  | no       | string | -       | Preset colour key or `#rrggbb`. Tints the border and draws a stripe down the panel's leading edge |
+| `opacity` | no       | number | `100`   | Panel translucency in percent (clamped 20-100). Below 100 the surface is tinted and blurred; text stays opaque |
+| `title`       | no   | string | menu name | Text shown in the panel's bar, next to the drag handle and hamburger |
+| `collapsible` | no   | bool   | `false` | Adds a hamburger that folds the panel down to just that button                |
+| `collapsed`   | no   | bool   | `false` | Start collapsed. Needs `collapsible`; a visitor's own last state wins over it |
+| `movable`     | no   | bool   | `false` | Visitors drag the panel by its bar                                           |
+| `resizable`   | no   | bool   | `false` | Visitors drag the panel's bottom-right corner to resize it                   |
+
+```json
+{
+  "slug": "quick-links",
+  "name": "Quick Links",
+  "position": "floating",
+  "float": {
+    "anchor": "BR", "offsetX": 24, "offsetY": 40, "width": 240,
+    "radius": 14, "shadow": "xl", "accent": "primary", "opacity": 92
+  },
+  "items": [{ "text": "Contact", "url": "/contact" }]
+}
+```
+
+The surface fields resolve to theme tokens rather than literal colours, so a floating panel still
+tracks the active theme. Omitting one leaves the `.dm-menu-floating` default in `site.css` in
+charge rather than freezing today's value into the file.
+
+Applies in three places:
+
+- **Public navbar** - the menu mapped to the `navbar` slot floats instead of docking.
+- **`[menu]` shortcode** - floats wherever the shortcode is placed. Pass `float="no"` on an
+  individual shortcode to render that one inline while the menu still floats in its slot.
+- **Admin sidebar** - the `admin-sidebar` menu pins itself and the shell opens a matching gutter,
+  so the view never sits underneath it.
+
+A floating menu is capped to the viewport height and scrolls internally rather than overflowing.
+Below 768px floating is dropped and the menu returns to the flow, so it can't cover the content it
+belongs to on a phone.
+
+#### Collapse, move and resize
+
+`collapsible`, `movable` and `resizable` turn a pinned panel into something the visitor can handle.
+Any of them makes the server draw a bar across the top of the panel - a drag grip, the `title` (or
+the menu's name), and the hamburger - and `public/js/menu-float.js` wires the behaviour.
+
+```json
+{
+  "slug": "quick-links",
+  "name": "Quick Links",
+  "position": "floating",
+  "float": {
+    "anchor": "BR", "offsetX": 24, "offsetY": 24,
+    "collapsible": true, "collapsed": true, "movable": true, "resizable": true
+  },
+  "items": [{ "text": "Contact", "url": "/contact" }]
+}
+```
+
+Collapsed, the panel is nothing but a round hamburger button sitting on its anchor; clicking it
+brings the menu back.
+
+**The config is only ever a starting point.** Where a visitor drags a panel to, what size they
+leave it, and whether they collapsed it are stored in *their* browser under
+`dm_menu_float_<slug>`, and they win over `float` on the next page load. Double-clicking the bar
+throws that away and puts the panel back where you configured it. Nothing about a visitor's own
+layout reaches the server or any other visitor.
+
+Two consequences worth knowing:
+
+- `collapsed` is a **default**, not a state. Once a visitor has used the toggle, their choice
+  sticks and this field stops applying to them.
+- A panel only stops tracking its `anchor` once the visitor actually moves or resizes it. Until
+  then it keeps re-pinning to the corner as the viewport changes size. Once freed, it is clamped
+  to stay on screen when the window shrinks.
+
+Below 768px floating is dropped, so moving and resizing do nothing there - only collapsing still
+applies, which is exactly the hamburger behaviour a phone wants anyway.
+
+### Orientation
+
+`orientation` decides how a menu flows wherever it renders. `horizontal` is the default and the
+historic behaviour; `vertical` stacks the items into a column.
+
+| Where                | `horizontal`                                   | `vertical`                                                             |
+|----------------------|------------------------------------------------|------------------------------------------------------------------------|
+| Public navbar        | The usual bar across the top                   | A fixed side rail (`side: left | right`); the page body gains a matching gutter |
+| `[menu]` shortcode   | Top-level items in a row, submenus drop on hover| Indented stack with hover highlights                                   |
+| Floating menu        | Row inside the pinned panel                     | Stack inside the pinned panel                                          |
+| Admin sidebar        | n/a - always vertical                           | n/a                                                                    |
+
+The vertical navbar only applies from 993px up; below that the existing hamburger drawer is already
+a vertical list, so nothing changes there. A menu that sets no `orientation` at all emits no
+orientation class from the `[menu]` shortcode and keeps its plain nested-list rendering, so existing
+pages look exactly as they did.
+
+Individual placements can override the menu: `[menu slug="main" orientation="horizontal" /]`.
+
+### Alignment
+
+`align` decides where the items sit along a **horizontal** menu. A vertical rail and the mobile
+drawer ignore it - there is nothing to align along.
+
+| Value     | Effect                                                     |
+|-----------|-------------------------------------------------------------|
+| `left`    | Items pack against the start of the bar, after the brand    |
+| `centre`  | Items sit on the centre line of the bar itself              |
+| `right`   | Items pack against the end of the bar                       |
+| `spread`  | Items spread evenly across the available width              |
+
+**The default differs by render path, deliberately.**
+
+- The **public navbar** centres when `align` is unset. Domma already intends this - its stylesheet
+  says `justify-content: center` - but it centres the list inside the space *left over* once the
+  brand and the actions block have taken theirs, so a wide brand shunts the items right by half its
+  width and a search icon pulls them back left by half of its own. They are only ever truly centred
+  when those two happen to be the same width. Setting `align` (or leaving it unset, which means
+  centre) switches the bar to a three-track grid whose outer tracks are equal, so the items land on
+  the bar's real centre line whatever flanks them.
+- A **`[menu]` shortcode** in the page body emits no alignment class when `align` is unset and keeps
+  packing left, because silently re-flowing body content on upgrade is not wanted.
+
+Where the brand and the items together need more room than the bar has, the outer tracks stop
+shrinking rather than squeezing the brand into a wrap - the layout gives up exact centring before it
+gives up legibility.
+
+### Staggered entrance
+
+`entrance` brings a menu's items in one after another when the menu is drawn, the way `[row reveal]`
+brings in a row of cards. Set it on the menu's **Behaviour** tab; it applies on every public path -
+navbar, footer, `[menu]` and floating overlays (not the admin sidebar).
+
+```json
+"entrance": {"enabled": true, "animation": "slide-up", "stagger": 60, "duration": 400}
+```
+
+| Key         | Values                                                                                     |
+|-------------|--------------------------------------------------------------------------------------------|
+| `enabled`   | `true` plays it. `false` keeps the choices below without playing them                      |
+| `animation` | `fade` (default), `slide-up`, `slide-down`, `slide-left`, `slide-right`, `zoom`, `pop`, `flip`, `blur` |
+| `stagger`   | ms between one item and the next, 0-1000 (default 60)                                      |
+| `duration`  | ms each item's animation takes, 50-3000 (default 400)                                      |
+
+Items are numbered per list, so a dropdown or footer column staggers in on its own when it opens;
+items past the twentieth share its delay. Visitors who asked for less motion (the OS setting or the
+footer's motion switch) see the items at once.
+
+### Item highlighting
+
+`highlight` decides what a menu item does under the pointer and how the item for the page you are
+on is marked out. Both halves are optional: a menu with no `highlight` block keeps the theme's own
+look, exactly as before.
+
+```json
+{
+  "slug": "main",
+  "name": "Main navigation",
+  "highlight": {
+    "hover":  "underline",
+    "active": "pill",
+    "accent": "#ff8800"
+  },
+  "items": []
+}
+```
+
+| Field    | Type   | Description                                                              |
+|----------|--------|--------------------------------------------------------------------------|
+| `hover`  | string | What an item does under the pointer - see the table below                |
+| `active` | string | How the item for the current page is marked                              |
+| `accent` | string | Preset key (`primary`, `success`, `danger`, `warning`, `info`, `neutral`) or `#rrggbb`. Defaults to the theme primary |
+
+**`hover`**
+
+| Value        | Effect                                                                    |
+|--------------|---------------------------------------------------------------------------|
+| *(unset)*    | The theme's own hover - colour shift plus a tinted background              |
+| `none`       | Nothing at all. Rest and hover are identical                              |
+| `colour`     | Text takes the accent colour                                              |
+| `underline`  | Accent-coloured underline appears                                         |
+| `overline`   | Accent-coloured line above the text                                      |
+| `background` | Accent-tinted chip behind the item                                        |
+| `darken`     | Darkened chip, lighter than the selected one - works on a light and a dark bar alike |
+| `uppercase`  | Text switches to uppercase. The item gets wider as it does, so neighbours shift slightly |
+| `grow`       | Item scales up                                                            |
+| `breathe`    | Item pulses slowly for as long as the pointer rests on it                 |
+| `glow`       | Accent-coloured halo around the text                                      |
+
+**`active`**
+
+| Value        | Effect                                                                    |
+|--------------|---------------------------------------------------------------------------|
+| *(unset)*    | The theme's own current-page marker - a primary underline plus a weight bump |
+| `none`       | The current page is not marked at all                                     |
+| `bold`       | Bold text                                                                 |
+| `underline`  | Accent-coloured underline                                                 |
+| `overline`   | Accent-coloured line above the text                                       |
+| `background` | Accent-tinted chip                                                        |
+| `darken`     | Darkened chip - works on a light and a dark bar alike                     |
+| `pill`       | Filled accent pill with white text                                        |
+
+The effects apply wherever the menu is drawn: the public navbar, the footer columns, a `[menu]`
+shortcode, an overlay panel, and the admin sidebar. `grow` and `breathe` are motion, so they are
+dropped for visitors whose browser asks for reduced motion; the rest still apply.
+
+**Marking the current page.** "The item for the page you are on" means an exact URL match, ignoring
+a query string, a fragment and a trailing slash. A parent item is not marked because you are
+somewhere beneath it, and an item pointing at `/` is only marked on the home page. Marked items
+carry `aria-current="page"`, so the current page is announced whether or not a visual effect is set.
+
+**Deprecated spelling.** An earlier cut of this feature put the two effects on the `style` block as
+`style.hover` / `style.active`, with `transform` for uppercase and `background-color` for the tint.
+Those are still read and translated, so a menu saved that way keeps working, but `style` is
+otherwise a block of CSS declarations written straight into a `<style>` tag - behaviour keys do not
+belong in it. Use `highlight`; it wins per half when both are present.
+
+**Precedence.** A highlight sets the colour for the states it controls, so on a menu whose items
+carry their own `colour` overrides the highlight wins for those states and the item colour owns
+every other one. Pick `hover: none` and `active: none` to hand every state back to the item colours.
+
+**Per-item overrides.** Any single item can carry its own `highlight` block, in the same shape and
+with the same values. Each half is resolved independently: an item that sets only `hover` keeps the
+menu's `active`, and vice versa.
+
+```json
+{
+  "slug": "main",
+  "highlight": { "hover": "colour", "active": "underline", "accent": "primary" },
+  "items": [
+    { "text": "Home",    "url": "/" },
+    { "text": "Contact", "url": "/contact",
+      "highlight": { "hover": "glow", "active": "pill", "accent": "#ff8800" } }
+  ]
+}
+```
+
+Here every item gets a colour shift on hover and an underline when it is the current page, except
+Contact, which glows in orange and becomes an orange pill instead.
+
+An item override **replaces** the menu's effect for that half rather than adding to it: in the
+example above, hovering Contact glows and does *not* also take the menu's hover colour. Leaving a
+half blank in the admin means "inherit"; choosing `none` means "switch this off for this item while
+the rest of the menu keeps it". They are different things.
+
+The accent is resolved per item too, so one item can highlight in a different colour from the menu
+without any other item changing.
+
+### Designer classes
+
+`class` takes your own class names, separated by spaces, so a designer can style a menu or a single
+item from Custom CSS without the editor offering a setting for it. Set it under **Behaviour > CSS
+classes** for the whole menu, or **Styling > CSS classes** in an item's editor.
+
+- A menu's classes go on its outer element: the navbar (`#site-navbar`), the footer column's
+  `<nav class="footer-nav">`, or the `[menu]` shortcode's `<nav class="dm-menu">` (before any
+  `class=` the shortcode itself passes).
+- An item's classes go on its `<li>` on every render path, so they can lay the item out as well as
+  style it. Target the link with `.your-class > a`.
+
+```json
+{ "slug": "main", "class": "site-nav",
+  "items": [ { "text": "Get a quote", "url": "/quote", "class": "nav-cta push-right" } ] }
+```
+
+```css
+.site-nav .nav-cta > a { border: 1px solid currentColor; border-radius: 999px; }
+.site-nav .push-right { margin-left: auto; }
+```
+
+Names are letters, digits, hyphens and underscores, not starting with a digit; a leading dot is
+dropped, and at most 20 are kept. Anything else is refused on save. Navbar links carry Domma's own
+high-specificity hover rules, so a navbar hover style may need `#site-navbar` in its selector.
+
+### Menu bindings
+
+A binding lets one menu **take a slot over for part of the site** rather than being mapped to it
+everywhere. It is the answer to "the shop section needs its own navbar" without touching
+`menu-locations.json`.
+
+```json
+{
+  "slug": "shop-nav",
+  "name": "Shop navigation",
+  "binding": {
+    "slot": "navbar",
+    "projects": ["shop"],
+    "pages": ["/pricing", "/docs/*"]
+  },
+  "items": [{ "text": "Catalogue", "url": "/shop" }]
+}
+```
+
+| Field      | Required | Type     | Description                                                                       |
+|------------|----------|----------|-----------------------------------------------------------------------------------|
+| `slot`     | yes      | string   | The slot this menu claims (`navbar`, `footer-primary`, … - any registered slot)   |
+| `projects` | no       | string[] | Project slugs; applies on every page resolving to one of them                      |
+| `pages`    | no       | string[] | URL paths. A trailing `/*` matches that path and everything under it; `/*` matches the whole site |
+
+Resolution order for a slot on a given page, most specific first:
+
+1. A menu bound to that **exact page URL**
+2. A menu bound to a **page wildcard** that matches (longest pattern wins)
+3. A menu bound to the **project** the page resolves to (see **Page URL inheritance** below)
+4. The menu mapped to the slot in `config/menu-locations.json`
+
+Ties break on the longest pattern and then the slug, so resolution never depends on directory order.
+A binding with a slot but no projects or pages never matches; the admin's Binding tab says so
+explicitly. Bindings are not copied when a menu is duplicated - two menus claiming the same slot on
+the same pages would be a conflict nobody asked for.
+
+Bindings are honoured everywhere a slot is resolved with page context: the public navbar and footer
+columns, the overlay slot, and `[menu location="…" /]` inside a page body. `[menu slug="…" /]` names
+a menu directly and is unaffected. Rendering the whole set is cheap - menu files are read once and
+cached in process, invalidated on every write.
+
+### The overlay slot
+
+`navbar`, `footer-primary` and `footer-legal` are fixed regions: one menu wins each. The `overlay`
+slot is the "put a menu anywhere" placement. A menu bound to it renders on matching pages positioned
+by its own `float` config - no navbar, no footer, and no shortcode in the page body.
+
+```json
+{
+  "slug": "docs-rail",
+  "name": "Docs rail",
+  "position": "floating",
+  "orientation": "vertical",
+  "float": { "anchor": "L", "offsetX": 16, "radius": 8, "shadow": "md", "accent": "primary" },
+  "binding": { "slot": "overlay", "pages": ["/docs/*"] },
+  "items": [{ "text": "Getting started", "url": "/docs/start" }]
+}
+```
+
+That pins a vertical rail to the left edge on every page under `/docs`, and nowhere else.
+
+It differs from the other slots in three ways:
+
+- **Every match renders**, not just the most specific one - a page can carry a left rail and a
+  corner widget at once. (Precedence still applies *within* the other slots.)
+- **Mapping it in `menu-locations.json` makes it site-wide.** A menu mapped to `overlay` appears on
+  every page without needing page rules; a menu that is both mapped and bound appears once.
+- **An overlay with no visible items is dropped**, so a fully role-gated overlay leaves no empty box
+  floating over the page.
+
+Overlays are injected at the end of `<body>`, so a menu with `position: floating` pins itself
+anywhere on the viewport, while one left `static` simply renders after the page content. They are
+drawn by the same builder as the `[menu]` shortcode - the same menu looks identical either way - and
+items are filtered per visitor exactly as elsewhere.
+
+### Admin sidebar slot
+
+`admin-sidebar` is a built-in slot registered by core alongside `navbar`, `footer-primary`, and `footer-legal`. It drives the admin SPA's left sidebar - rendered from menu data rather than hardcoded config. The mapped menu is filtered per-request by each item's optional `permission` field, so users only see entries they can act on.
+
+`config/menus/admin-sidebar.json` is **auto-seeded** on first boot with the standard tree (Overview, Projects, Content, Data, System, Documentation). Seeding is idempotent - guarded by file existence - so subsequent boots leave admin edits intact. Delete the file to re-seed on the next boot.
+
+---
+
+## `config/menu-locations.json`
+
+Maps registered slot names to menu slugs. Built-in slots are `navbar`, `footer-primary`, and `footer-legal`; plugins register additional slots via `hooks.registerMenuLocation()` (see `docs/plugin-development.md`).
+
+```json
+{
+  "navbar":         "main",
+  "footer-primary": "footer",
+  "footer-legal":   "legal"
+}
+```
+
+Keys are slot names (must exist in the registry). Values are menu slugs (must resolve to a file in `config/menus/`). Unmapped slots render empty. Mappings to non-existent menus log a warning at request time and render empty.
+
+### Built-in slot registry
+
+| Slot             | Where it renders                                      | Default `maxDepth` |
+|------------------|-------------------------------------------------------|--------------------|
+| `navbar`         | `server/templates/page.html` navbar                   | unbounded          |
+| `footer-primary` | Primary footer column rendered by `public/js/site.js` | 1                  |
+| `footer-legal`   | Legal/secondary footer column                         | 1                  |
+| `admin-sidebar`  | Admin SPA left sidebar (`admin/js/lib/sidebar-renderer.js`) | unbounded     |
+| `overlay`        | Anywhere on the page - see **The overlay slot** below | unbounded          |
+
+`maxDepth` is advisory - the admin Locations UI surfaces a depth-overflow warning when the mapped menu exceeds the cap, but rendering still attempts to flatten beyond it.
+
+### Backwards compatibility
+
+The CMS auto-migrates from the legacy `config/navigation.json` (single navbar) and `site.json.footer.links` (single footer link list) to the multi-menu system on first boot. The originals are renamed to `.bak`; a one-release read-fallback restores the navbar from `navigation.json.bak` if the navbar slot is unmapped. The migration also populates a new top-level `brand` field on `site.json` (parallel to `adminBrand`) from the legacy `navigation.json.brand` - the public renderer reads `site.json.brand` when composing the navbar.
+
+---
+
+## Projects
+
+A **Project** is a named grouping of related artefacts (Pages, Collections, Forms, Actions, Menus, Blocks, Views, Roles, Users). It produces a sidebar section, an access-scope boundary for users, and a tag that the scaffolder stamps on recipe-produced artefacts.
+
+Projects are stored as a **preset collection** at `content/collections/projects/` - the same pattern as `user-types` and `roles`. CRUD UI, validation, and permission integration are inherited from the collection machinery.
+
+### The core project
+
+Every site has a built-in **core** project representing the core site itself. It is seeded at boot (create-if-absent, so existing sites gain it on their first start after updating) and owns **every artefact not claimed by another project** - by resolution fallback, not by tagging. Nothing is ever stamped `meta.project: 'core'`; "no tag" *is* core membership.
+
+- `slug: 'core'`, seeded as `name: 'Core'`, `icon: 'home'`, `rootUrl: '/'`, `sortOrder: -1`, `protected: true`.
+- **Not removable.** `DELETE /api/projects/core` and `POST /api/projects/core/untag-all` return 403; the admin UI hides the delete button and danger zone.
+- **`rootUrl` and `protected` are locked**; name, description, icon and sortOrder remain editable.
+- **Never an access boundary.** Core artefacts are visible to all authenticated users regardless of their `projects: []` scope - scoped users always keep the core site's pages, menus, and blocks.
+- If a site already had a user-created project with the slug `core`, boot seeding adopts it (sets `protected: true`, leaves every other field untouched).
+
+### Project record
+
+```json
+{
+  "slug":        "members",
+  "name":        "Members Area",
+  "description": "Curated members-only zone with profile, billing, and content.",
+  "icon":        "users",
+  "rootUrl":     "/members",
+  "sortOrder":   10,
+  "createdAt":   "2026-05-25T10:00:00Z",
+  "updatedAt":   "2026-05-25T10:00:00Z"
+}
+```
+
+| Field         | Required | Type   | Description                                                                                                |
+|---------------|----------|--------|------------------------------------------------------------------------------------------------------------|
+| `slug`        | yes      | string | URL-safe identifier; matches `^[a-z0-9][a-z0-9-]*$`; immutable after create; used as the `meta.project` tag |
+| `name`        | yes      | string | Human-readable; sidebar label                                                                              |
+| `description` | no       | string | Free text                                                                                                  |
+| `icon`        | no       | string | Sidebar icon (Domma icon name); defaults to `folder`                                                       |
+| `rootUrl`     | no       | string | URL prefix (must start with `/`; exactly `/` is reserved for the core project); enables page auto-inheritance |
+| `sortOrder`   | no       | number | Sidebar order; default = creation order                                                                    |
+| `protected`   | system   | bool   | Built-in marker (core project only) - locks `rootUrl`, blocks delete/untag-all; not user-settable          |
+
+### `meta.project` on artefacts
+
+Nine artefact types accept an optional `meta.project: '<slug>'` field. It declares "this artefact lives in this Project" for sidebar grouping and permission scoping. Artefacts without the field belong to the **core** project (and continue to appear under the standard Content/Data/Structure sections).
+
+| Type            | Where `meta.project` lives                                            |
+|-----------------|-----------------------------------------------------------------------|
+| **Pages**       | YAML frontmatter `project:` (with URL inheritance - see below)         |
+| **Collections** | `schema.json` top-level `meta.project`                                |
+| **Forms**       | Form JSON top-level `meta.project`                                    |
+| **Actions**     | Mongo doc `meta.project`                                              |
+| **Menus**       | `meta.project` alongside existing `meta.bundled` / `meta.presetOwner` |
+| **Blocks**      | Block JSON top-level `meta.project`                                   |
+| **Views**       | View JSON top-level `meta.project`                                    |
+| **Roles**       | Role entry `data.meta.project`                                        |
+| **Users**       | User JSON `meta.project` (administrative ownership - sidebar location) |
+
+### Page URL inheritance
+
+When a page is loaded the project is resolved in this order:
+
+1. Frontmatter has `project: '<slug>'` → use it (explicit override).
+2. Frontmatter has `project: null` → resolves to `core` (legacy opt-out, deprecated - "untagged" no longer exists as a state).
+3. Frontmatter `project:` field is missing → look up the project whose `rootUrl` is the longest prefix match of the page's URL → use that.
+4. No match → page belongs to the **core** project.
+
+The core project does not participate in prefix matching - it is the fallback when nothing else claims the page.
+
+Example: project `members` has `rootUrl: '/members'`. A page at `/members/profile.md` with no `project:` frontmatter is implicitly in `members`. A page at `/about.md` belongs to `core`. A page at `/members/admin.md` with explicit `project: 'staff'` overrides the auto-match.
+
+Where multiple `rootUrl` values match, longest wins; ties broken alphabetically by slug.
+
+### User access scope - `projects: []`
+
+Users gain a new optional field `projects: ['<slug>', ...]` - the **access scope**. Distinct from `meta.project` on the user record (the **administrative ownership** that tells the sidebar where to file the user).
+
+| Field            | Purpose                                                                                  |
+|------------------|------------------------------------------------------------------------------------------|
+| `meta.project`   | Administrative ownership - where the user appears in the sidebar's Projects section      |
+| `projects: []`   | Access scope - which projects' artefacts the user can see/edit                           |
+
+Most users have both fields set to the same single project; a recruiter user owned by `members` might be granted access to `members` + `intranet`.
+
+**Access rule** (enforced in API route guards, sidebar render, list/get endpoints):
+
+- Super-admins bypass entirely - they see all projects regardless of `projects`.
+- Core artefacts (no `meta.project`, or tagged `core`) are always visible (subject to role permission) - the core project is organisational, never an access boundary.
+- **Empty `projects: []` = no restriction** - a user with no scope set sees everything (subject to role).
+- A non-empty `projects` array restricts the user to artefacts whose `meta.project` is in their list, plus core artefacts. The core project always appears in their project list.
+
+### Permissions
+
+A new permission family `projects.{read, create, update, delete}` is added to `permissionRegistry`. The base `super-admin` and `admin` roles receive it through the boot self-heal (see below); **custom roles are not back-filled** - an admin grants `projects.read` to them in the role editor (**System > Roles**).
+
+---
+
+## API tokens & the external API
+
+API tokens are project-scoped machine credentials for the external collections API
+(`/api/v1/<collection>` - see `docs/api-reference.md`). They are stored as a **preset collection**
+at `content/collections/api-tokens/` (always file-based, like the other presets) and managed in
+the admin under **System → API Tokens**. Only a SHA-256 hash of each token is stored - the
+plaintext (`dcms_` + 64 hex) is shown once, at creation.
+
+### Per-verb collection API config - `schema.api`
+
+Each collection's `schema.json` carries an `api` block with one entry per verb:
+
+```json
+"api": {
+  "read":   { "enabled": true,  "access": "token", "fields": ["title", "price"] },
+  "create": { "enabled": true,  "access": "token" },
+  "update": { "enabled": false, "access": "admin" },
+  "delete": { "enabled": false, "access": "admin" }
+}
+```
+
+- `access` - `"public"` (no credentials), `"token"` (project-scoped API token), or a role name
+  (JWT at that role level or higher). A token is **only** accepted in token mode; a JWT is never
+  accepted in token mode.
+- `fields` (read only) - optional allowlist of `data` fields returned by the public/external read
+  endpoints. Absent or empty = all fields. Admin endpoints are unaffected.
+
+### Public export config - `schema.export`
+
+Each collection's `schema.json` may also carry an `export` block, controlling the "Export…" entry
+in the public right-click menu on collection displays (see `docs/markdown-shortcodes.md`) - separate
+from `schema.api`, which governs the external `/api/v1` API.
+
+```json
+"export": {
+  "enabled": true,
+  "access": "admin",
+  "formats": ["csv", "json"]
+}
+```
+
+| Key       | Default                        | Meaning                                                                 |
+|-----------|---------------------------------|--------------------------------------------------------------------------|
+| `enabled` | `true`                          | `false` disables export entirely, overriding `exportable="true"` on the shortcode |
+| `access`  | least-privileged role           | `"public"`, or a role name. Never `"token"` - token mode is for the external API only |
+| `formats` | `["csv", "json"]`               | Offered download formats; unrecognised values are filtered out           |
+
+Resolution is first-match-wins, in this order:
+
+1. `export.enabled === false` - export is never offered, and `exportable="true"` on the shortcode is
+   ignored
+2. `exportable="true"` on the `[collection]`/`[view]` shortcode - offered to everyone. This is
+   grandfathered: `exportable` has always meant "public CSV button", so existing pages do not regress
+3. `export.access` - as configured
+4. otherwise - the least-privileged role (i.e. signed-in users only)
+
+> **This gate is a convenience affordance, not an enforcement boundary.** Collection entries are
+> already embedded in the rendered page's `data-ctx` attribute so the browser can filter and sort
+> them without a round trip. Restricting `access` stops a visitor being handed a download button;
+> it does not stop a determined one reading the page source. A collection whose contents must not
+> reach a visitor at all should not be rendered on a page that visitor can load - use
+> `page.visibility`, or gate the collection's `api.read.access`.
+
+### Token record
+
+`name`, `project` (binding - the token only works on collections resolving to this project; immutable),
+`scopes` (optional `[{collection, verbs[]}]`; empty = the whole project), `enabled`, `expiresAt`,
+`lastUsedAt`, `tokenHint` (last 4 characters, for display), `tokenHash` (never returned by any API).
+
+### Scaffolder integration
+
+A recipe may declare `"apiTokens": [{ "name": "{{namespace}}-api", "scopes": [...] }]`. Tokens are
+generated at apply time under the recipe's project; the plaintext appears once in the apply summary.
+Re-applying a recipe never re-issues an existing name+project token.
+
+### Permissions
+
+A new permission family `api-tokens.{read, create, update, delete}` is added to `permissionRegistry`.
+Base roles self-heal at boot against their seed definitions (append-only): the root role always
+receives every registry resource, and since 0.25.1 the base `admin` role includes `api-tokens` and
+`api-endpoints`. Custom roles are never touched - grant new families to them via the Roles editor.
+Note: a *seeded* permission removed from a base role is re-added at boot; use a custom role to run
+with less than the base set.
+
+---
+
+### Content API - `config/content-api.json`
+
+Settings for the read-only Content API at `/api/content/v1` (see `docs/api-reference.md`), edited at
+**System → Content API**. Optional: **absence means off**, so an upgrade exposes nothing.
+
+```json
+{
+  "enabled": false,
+  "access": "token",
+  "resources": {
+    "pages":  { "enabled": true },
+    "menus":  { "enabled": true },
+    "site":   { "enabled": true },
+    "search": { "enabled": true }
+  },
+  "formats": ["html"],
+  "listable": true,
+  "maxLimit": 200
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | boolean | `false` | Only a literal `true` turns it on. Off = every address answers `404` |
+| `access` | string | `"token"` | `"public"`, `"token"` (project API token) or a role name (Bearer access JWT, that role or more senior). Saving a role the site does not have is refused |
+| `resources.<name>.enabled` | boolean | `true` | Switch `pages`, `menus`, `site` or `search` off on its own |
+| `formats` | string[] | `["html"]` | Which of `html` / `markdown` a page may be asked for. Never empty - HTML is kept. Markdown is the source, shortcodes included |
+| `listable` | boolean | `true` | `false` removes the page list and keeps single pages |
+| `maxLimit` | number | `200` | Largest page size a list may ask for (1-200) |
+
+Unknown keys are dropped on save (`normaliseContentApiSettings()` in `server/services/contentApi.js`).
+A page opts out with front matter `api: false`.
+
+---
+
+## Custom API endpoints (API Builder)
+
+Named REST endpoints over collection data, served at `/api/x/<project><path>` (see
+`docs/api-reference.md`). Definitions are entries in the **`api-endpoints` preset collection**
+(always file-based) and are built in the admin under **Data → API Builder**, which includes a
+try-it console for live testing against the saved definition.
+
+| Field        | Type     | Notes |
+|--------------|----------|-------|
+| `name`       | string   | Display name |
+| `project`    | string   | URL namespace + access scoping - immutable after creation |
+| `path`       | string   | `/segments` or `:param` placeholders; unique path *shape* per project |
+| `collection` | string   | The collection to query; system-managed collections are refused |
+| `auth`       | string   | `public` \| `token` \| role name |
+| `mode`       | string   | `list` (paged payload) \| `single` (first match or 404) |
+| `filter`     | object   | `{field_op: value}`; values may embed `{{params.x}}` / `{{query.x}}` |
+| `sort`/`order`/`limit` | - | Query shape; `limit: 0` = no limit (max 500 otherwise) |
+| `fields`     | string[] | Response field allowlist; empty = all |
+| `enabled`    | boolean  | Disabled endpoints 404 |
+
+Scaffolder recipes may declare `"apiEndpoints": [{ "path": "/by-day/:date", "collection": "{{namespace}}-items", "filter": {...} }]` -
+created at apply time under the recipe's project, idempotent on re-apply (existing path shapes
+are left unchanged).
+
+Permission family `api-endpoints.{read, create, update, delete}` - included in the base
+`super-admin` and `admin` roles via the boot self-heal; custom roles need the grant via the
+Roles editor.
+
+An endpoint may only expose collections from **its own project or core** - the builder's
+collection picker filters accordingly, and the server refuses cross-project bindings (400) and
+collections outside the caller's access scope (403).
+
+---
+
+## `config/presets.json`
+
+Layout presets available when creating or editing a page.
+
+```json
+{
+  "default": {
+    "label": "Default",
+    "description": "Standard page with navbar and footer",
+    "navbar": true,
+    "footer": true,
+    "sidebar": false
+  },
+  "minimal": {
+    "label": "Minimal",
+    "description": "Clean page with no navbar or footer",
+    "navbar": false,
+    "footer": false,
+    "sidebar": false
+  }
+}
+```
+
+The key (e.g. `"default"`) is stored in the page's `layout` frontmatter field. Each preset object must have at least a `label` string.
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | string | Human-readable name shown in the page editor |
+| `description` | string | Optional description |
+| `navbar` | boolean | Whether the navbar is rendered for this layout |
+| `footer` | boolean | Whether the footer is rendered |
+| `sidebar` | boolean | Whether a sidebar column is rendered |
+
+---
+
+## `config/plugins.json`
+
+Stores the enabled state and user-overridden settings for each plugin. This file is managed by the **Plugins** admin panel.
+
+```json
+{
+  "analytics": {
+    "enabled": true,
+    "settings": {}
+  },
+  "domma-effects": {
+    "enabled": true,
+    "settings": {
+      "defaultDuration": 600,
+      "defaultAnimation": "fade",
+      "defaultThreshold": 0.1,
+      "respectMotion": false
+    }
+  }
+}
+```
+
+The key is the plugin's `name` field from its `plugin.json` manifest. Settings are merged with the plugin's own `config.js` defaults at runtime - the user's values take precedence.
+
+`locked: true` on an entry means the site's manager holds that switch: the admin here cannot switch the plugin on or off (the API answers 423). Only the manager writes it.
+
+---
+
+## `config/tools.json`
+
+The built-in Tools that can be switched off: `contacts`, `notes`, `todo`, `analytics` (0.88.0) and `seo` (0.90.0). Absent file or entry = on and unlocked. Managed at the top of the **Marketplace** screen (`#/plugins`), or by the site's manager.
+
+```json
+{
+  "notes": { "enabled": false },
+  "analytics": { "enabled": false, "locked": true }
+}
+```
+
+A Tool that is off keeps its data. Its API answers 404, its sidebar entry, notification and calendar sources go, and (for `analytics`) the page-view beacon is not emitted. Switching one off also switches off any enabled plugin that `requires` it - see `server/services/tools.js`.
+
+---
+
+## `config/connections.json` (Pro)
+
+Defines named MongoDB connections used by the storage adapter system. This file is absent in a standard installation, which means all collections use the default file-based adapter.
+
+```json
+{
+  "default": {
+    "type": "mongodb",
+    "uri": "mongodb://localhost:27017",
+    "database": "my_cms"
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Must be `"mongodb"` |
+| `uri` | string | MongoDB connection URI |
+| `database` | string | Database name within the MongoDB instance |
+
+A `connections.json.example` template is provided in the `config/` directory. To enable MongoDB for a collection, add a `storage` block to that collection's `schema.json`:
+
+```json
+{
+  "storage": {
+    "adapter": "mongodb",
+    "connection": "default"
+  }
+}
+```
+
+The `mongodb` package is an optional dependency - it is not required unless you configure a MongoDB connection.
+
+---
+
+## Page frontmatter
+
+Pages live as Markdown files in `content/pages/` with YAML frontmatter at the top:
+
+```yaml
+---
+title: My Page
+layout: default          # any preset key in config/presets.json
+description: SEO description
+status: published        # draft | published - drafts 404 publicly, preview when signed in
+visibility: public       # see below - controls who can view the page
+---
+```
+
+### `visibility`
+
+Controls page-level access. Three accepted shapes:
+
+| Value                              | Who can view                                                                            |
+|------------------------------------|-----------------------------------------------------------------------------------------|
+| `public` (or omitted)              | Everyone, including unauthenticated visitors                                            |
+| `private`                          | Super-admin only (level 0) - useful for staging pages                                   |
+| A role name (e.g. `user`)          | That role plus anyone more privileged (lower or equal role level)                       |
+| `=` + a role name (e.g. `=candidate`) | Holders of that role only (primary or additional role), plus the super-admin (level 0) |
+| An **array** of the above          | Anyone matching ANY entry (each entry follows its own rule above)                       |
+
+The array form makes "sibling role" gating natural - both roles can view the same page even if neither inherits from
+the other:
+
+```yaml
+---
+title: Members Area
+visibility: [candidate, employer]
+---
+```
+
+This grants access to `candidate`, `employer`, and anyone more privileged than either (typically administrators, who
+inherit access automatically through the role hierarchy). Note that a role on the SAME level also passes: if
+`candidate` and `employer` are both level 3, `visibility: candidate` lets employers in too.
+
+To keep a page (or a menu item) to one role alone, use the exact form:
+
+```yaml
+---
+title: My Applications
+visibility: "=candidate"        # candidates only - not employers, not admins
+---
+```
+
+Exact tokens skip the hierarchy: only users who hold that role pass, whether it is their primary role or one of their
+`additionalRoles`. The super-admin (level 0) still passes, as it does for `private`; an ordinary admin does not, so give
+an admin the role as an additional role if they need to see what candidates see. Exact and hierarchical tokens mix in
+an array: `["=candidate", "=employer"]` is "those two roles and nobody else". The page and menu editors offer both
+forms for every role ("Candidate and above", "Candidate only").
+
+The check is implemented by `checkVisibility(user, visibility)` in `server/middleware/auth.js`. The viewer is resolved
+on every page request (from the `dm_session` cookie or a Bearer token), because menus on a public page filter their
+items per viewer too. The response is cached per set of roles the viewer holds (`role${roles ?? 'anon'}`), so gated
+content never reaches the anonymous cache and anonymous visitors share a single entry.
+
+Anonymous visitors hitting a non-public page receive a 403 with a minimal access-denied response. Authenticated
+visitors whose role doesn't satisfy the requirement get the same 403. To redirect users to a sign-in page instead,
+intercept the 403 at your reverse proxy or use the `4xx` page customisation.
+
+### Other frontmatter fields
+
+| Field         | Type            | Description                                                                  |
+|---------------|-----------------|------------------------------------------------------------------------------|
+| `title`       | string          | Used as `<title>` (overridden by `seo.title`) and the page heading           |
+| `description` | string          | Meta description fallback                                                    |
+| `layout`      | string          | A preset key from `config/presets.json`: `default`, `with-sidebar`, `minimal`, `blank`, `landing`, `article`, `product`, `dashboard`, `wide` - see `docs/theming.md` |
+| `status`      | string          | `draft` or `published` - see "Draft previews" below                          |
+| `visibility`  | string\|string[]| As above                                                                     |
+| `seo`         | object          | SEO overrides - see "Page-level frontmatter overrides" above                 |
+| `tags`        | string[]        | Editorial tags - weighted in site search and shown (and searchable) in the admin Pages list. Blanks and duplicates are removed on save. These are **not** cache tags: a page's cache tags are derived automatically from the shortcodes it uses (see `docs/cache.md`) |
+| `dconfig`     | object          | Page-level `$.setup()` config; merged with inline `[dconfig]` blocks         |
+| `sortOrder`   | number          | Ordering hint used by page lists (default from `pageDefaults`, normally 99)  |
+| `category`    | string          | Free-form category shown in the page editor                                  |
+| `project`     | string          | Owning project slug. Blank or absent = inherit from the URL                  |
+| `theme`       | string          | Per-page theme override (a theme key such as `ocean-light`)                  |
+| `width`       | string          | `narrow`, `normal`, `wide` or `full` - overrides the layout's content width for this page (hand-written only) |
+| `sidebar`     | boolean         | Show the layout sidebar on this page even when the preset does not           |
+| `breadcrumbs` | boolean         | `false` hides the breadcrumb trail on this page                              |
+| `showInNav`   | boolean         | Legacy - no longer read by the public site and no longer offered in the editor (a stored value is kept). Navigation is managed in **Menus** |
+| `bundled`     | boolean         | Marks a page as shipped with the CMS (shown as a "Bundled" chip in the Pages list) |
+
+### Draft previews
+
+A page with `status: draft` returns 404 to the public, exactly as before. A
+signed-in user whose role holds the `pages.read` permission is instead served
+the real page - real layout, navbar, footer, theme, menus, custom CSS - with a
+draft banner fixed to the bottom of the viewport. Designers and developers can
+therefore verify a page at its real URL before it is released.
+
+The banner names the viewer, links to the page in the admin editor, and offers
+a Publish button. It is hidden from print output and can be dismissed for the
+current page view.
+
+Notes:
+
+- **Nothing is revealed to the public.** An anonymous visitor, or a signed-in
+  user without `pages.read`, gets the same 404 as a page that does not exist.
+- **Draft renders are never cached** (`Cache-Control: no-store, private`) and
+  never indexed (`X-Robots-Tag: noindex, nofollow`), so a preview can never be
+  replayed to an anonymous visitor from the response cache.
+- **Drafts stay out of `sitemap.xml`** and do not emit a `content:pageViewed`
+  hook, so previewing does not pollute analytics.
+- **A disabled project still wins.** Pages in a disabled project 404 for
+  everyone, previewers included - the project switch remains a hard kill.
+- Browser navigation is authenticated by the `dm_session` cookie set at login
+  (HttpOnly, SameSite=Lax, Secure over https, expiring with the access token).
+  It is read only when rendering public pages; every API route remains
+  Bearer-only, so the cookie grants no write authority.
+
+### Full-page preview in the editor
+
+The page editor's **Live Preview** tab renders the *unsaved* editor state through
+the server's real page pipeline - the same `parseMarkdown` and `renderPage` the
+public site runs on save - so layout, navbar, footer, theme, menus, `dconfig` and
+custom CSS are exactly what publishing would produce. The split-view pane beside
+the markdown still renders the body alone; that answers "did my shortcodes
+parse", this answers "is the page right".
+
+It re-renders about half a second after you stop typing, but only while the tab
+is on screen. Width buttons constrain the frame to 1024px or 390px to check
+tablet and mobile layout. The banner is deliberately absent here: the editor is
+already telling you what you are looking at.
+
+Backed by `POST /api/pages/preview/full` (`pages.read`), which takes
+`{urlPath, frontmatter, body}` and returns `{html}`.
+
+### Share links
+
+**Share link** in the Live Preview tab mints a URL that renders one unpublished
+page to someone with no account - a client, an external designer, a copywriter.
+
+- Scoped to **one page**. The page is named inside the signed token, so a holder
+  cannot repoint the link at anything else.
+- **Expiring**: 1 hour, 24 hours, 7 days or 30 days. 30 days is the ceiling.
+- **Revocable at any time.** Each token carries an id that must still be present
+  and unrevoked in `content/preview-links.json`; a signed token alone is not
+  enough. Revocation takes effect on the next request.
+- Responses carry `no-store`, `noindex, nofollow` and `Referrer-Policy:
+  no-referrer` - the credential is in the URL, so the token must not ride along
+  in `Referer` to third-party assets.
+- The page renders **as anonymous**: menus and role-gated shortcodes show the
+  recipient the least, not the most. The token satisfies that one page's own
+  gate and nothing else.
+- Links are dropped automatically when the page is deleted or renamed, so one
+  cannot outlive what it pointed at.
+- A disabled project still 404s, share link or not.
+
+Minting requires `pages.update`, not merely `pages.read`: handing an
+unauthenticated stranger a working URL is an act of publishing, however narrow.
+
+| Endpoint | Permission | Purpose |
+|---|---|---|
+| `GET /api/pages/preview-links[?urlPath=]` | `pages.read` | List links |
+| `POST /api/pages/preview-links` | `pages.update` | Mint (`{urlPath, expiresIn, label}`) |
+| `DELETE /api/pages/preview-links/:id` | `pages.update` | Revoke |
+
+---
+
+## Collection schema fields
+
+Collection schemas live at `content/collections/<slug>/schema.json`. Each field
+declaration looks like `{ name, label, type, required, ... }`. Supported `type`
+values include the obvious primitives (`text`, `textarea`, `number`, `date`,
+`boolean`, `select`, `multiselect`, `chooser`, `tags`, `email`) plus one
+relational type:
+
+### `type: "reference"` - relational field
+
+Stores the id of an entry from another collection. Auto-renders as a populated
+dropdown on forms, resolves to the target's display label everywhere the field
+is shown, and (optionally) links to the target's detail page.
+
+```json
+{
+  "name":      "jobId",
+  "label":     "Job",
+  "type":      "reference",
+  "required":  true,
+  "reference": {
+    "collection":    "jobs",
+    "displayField":  "title",
+    "searchField":   "title",
+    "linkTemplate":  "/jobs/{{id}}"
+  }
+}
+```
+
+| Sub-field      | Required | Description                                                              |
+|----------------|----------|--------------------------------------------------------------------------|
+| `collection`   | yes      | Slug of the target collection                                            |
+| `displayField` | no       | Field on the target whose value is shown (default `title`)               |
+| `searchField`  | no       | Field used for type-ahead picker filtering (default = `displayField`)   |
+| `linkTemplate` | no       | URL template; `{{id}}` is substituted with the target's id (URL-encoded) |
+
+**Cardinality** - set `multiple: true` on the field to store an array of ids
+(one-to-many). The form renders as a multi-select; display joins values with
+", ". Without `multiple`, the field stores a single id string.
+
+**Validation** - on every create/update, the target id is checked against the
+target collection. Unknown ids fail with `Validation failed: "Job" → no entry
+"abc" in "jobs"`.
+
+**Resolution** - `listEntries(slug, { resolveRefs: true })` decorates entries
+with a parallel `_refs` map:
+
+```js
+entry._refs.jobId = { id: 'abc', display: 'Senior Engineer', missing: false, link: '/jobs/abc' }
+```
+
+The `[collection]` shortcode, the Collection Browser, and the public read API
+all resolve references automatically. Missing-target records render as
+`<id> (missing)` rather than crashing the page.
+
+**Filtering** - reference fields participate in the `where_*` DSL using their
+id values:
+
+```
+[collection slug="applications" where_jobId="abc-123" /]
+```
+
+The Browser's filter rail also auto-renders a dropdown of resolved-label
+options when a reference field is in `filterable="…"`.
+
+### `type: "file"` - uploaded file field
+
+Stores an uploaded file's metadata: `{ url, name, size, mime }`. The actual
+bytes live in `content/media/` (under a uuid-prefixed filename so concurrent
+uploads of the same name don't collide).
+
+```json
+{
+  "name":     "resume",
+  "label":    "Resume",
+  "type":     "file",
+  "required": true,
+  "file": {
+    "accept":  "application/pdf",
+    "maxSize": 5242880
+  }
+}
+```
+
+| Sub-field | Required | Description                                                                          |
+|-----------|----------|--------------------------------------------------------------------------------------|
+| `accept`  | no       | Comma-separated mime types or wildcards (`image/*`, `application/pdf,image/jpeg`)   |
+| `maxSize` | no       | Maximum bytes (default 5 MB)                                                         |
+
+**Form rendering** - `<input type="file">` with the `accept` hint. Setting
+`multiple: true` on the field renders a multi-file picker (one file per entry
+update; the form takes the last selection).
+
+**Submission** - the form switches automatically to `multipart/form-data`
+when any file input has a selected file. The server-side handler:
+
+1. Validates each file against its field's `accept` and `maxSize`
+2. Sanitises the filename (lowercases, strips path chars, prepends a uuid)
+3. Saves to `content/media/<uuid>-<safe-name>`
+4. Replaces the entry's field value with the reference object
+
+**Display** - `[collection]`, the Collection Browser, and the public read API
+all render file references appropriately:
+
+- Image mimes (`image/png`, `image/jpeg`, etc.) → clickable `<img>` thumbnail
+- Everything else → `<a href download>filename</a>`
+
+Stored reference shape:
+
+```json
+{
+  "url":  "/media/abc12345-resume.pdf",
+  "name": "resume.pdf",
+  "size": 245678,
+  "mime": "application/pdf"
+}
+```
+
+**Security note** - the `/media/` URL is publicly served (the file is in
+`content/media/` which the CMS exposes statically). If your use case needs
+gated downloads (e.g. CVs only visible to the candidate + recruiters),
+serve the file through an authenticated route instead - that's outside the
+field type's scope.
+
+---
+
+## Row-level access (per-entry scoping)
+
+Actions, views, and (where wired) collection endpoints accept an `access.rowLevel`
+config that restricts operations to entries the user is allowed to touch.
+Three modes are supported, all checked async server-side via `checkEntryAccess()`.
+
+### `mode: 'owner'`
+
+Match the entry's `meta.createdBy` against the user. Standard "you only see
+entries you created":
+
+```json
+{ "mode": "owner" }
+```
+
+### `mode: 'field'`
+
+Match a data field on the entry against the user. Use when ownership is
+explicit (e.g. tickets routed to a specific assignee):
+
+```json
+{ "mode": "field", "field": "assignedTo" }
+```
+
+### `mode: 'reference'` - cross-collection scoping
+
+Resolve a reference field, then check ownership on the *target* entry.
+This is the recruiter pattern - "I can act on applications because I own
+the job they point at":
+
+```json
+{
+  "mode":             "reference",
+  "field":            "jobId",
+  "targetCollection": "jobs",
+  "targetField":      "createdBy"
+}
+```
+
+| Sub-field          | Required | Description                                                                       |
+|--------------------|----------|-----------------------------------------------------------------------------------|
+| `field`            | yes      | Reference field on THIS entry (e.g. `jobId`)                                      |
+| `targetCollection` | yes      | Collection slug to resolve `field` against                                        |
+| `targetField`      | no       | `'createdBy'` (default) checks `target.meta.createdBy`; any other value checks `target.data.<targetField>` |
+
+**Array references** are supported - access is granted when ANY of the
+targets is owned by the user (e.g. "I can see this entry because I own at
+least one of its parents").
+
+**Fail-closed semantics**: dangling references (target was deleted),
+misconfigured rules (missing fields), and unknown modes all return `false`.
+A typo in the config can't accidentally open data up.
+
+---
+
+## Multi-role users
+
+A user has ONE **primary role** (`user.role`) and an optional array of
+**additional roles** (`user.additionalRoles`). Permission, visibility, and
+row-access checks consult ALL of them and grant access if any one role
+satisfies - union semantics. Hierarchical-level comparisons (admin tier,
+"can manage this user") use the LOWEST level number across the user's roles,
+i.e. the user's most-privileged role wins.
+
+```json
+{
+  "id":              "ab3-...",
+  "email":           "alex@company.com",
+  "name":            "Alex",
+  "role":            "candidate",
+  "additionalRoles": ["recruiter"]
+}
+```
+
+That user can do everything a candidate can do AND everything a recruiter can
+do. The same person submitting an application gets `meta.createdBy` stamped
+with their id (as a candidate, via `scope="mine"`); the same person picking
+up applications to review acts as a recruiter (via `mode: "reference"`
+row-access on the recruiter's transition actions).
+
+### When to use multi-role
+
+- A single person fills more than one job - recruiter who also reviews
+  candidates, admin who also writes content, etc.
+- Migrating from another system where users had a role *set* rather than a
+  scalar role.
+- Granting temporary elevated access without changing the user's "home" role.
+
+### Helper API
+
+`server/services/userRoles.js`:
+
+| Helper | Use |
+|---|---|
+| `getEffectiveRoles(user)` | All roles, primary first, deduplicated (`[]` if user has none) |
+| `getEffectiveLevel(user)` | Lowest level across all roles (`Infinity` if no roles) |
+| `userHasRole(user, role)` | Exact-name match - does NOT walk the hierarchy |
+| `userHasAnyRole(user, [...])` | OR across the list |
+
+### Security guarantees
+
+- **Assignment requires `canManageUser`** - the actor must be more
+  privileged than EVERY role they're trying to assign as either primary or
+  additional. A regular admin can't make someone "additionally super-admin".
+- **JWT carries `additionalRoles`** - so the public-page visibility check
+  and every action's role gate see the same union the admin sees.
+- **`isAdmin(user)` uses effective level** - row-access bypass for admins
+  works correctly when admin is an additional role.
+- **Per-row cache key uses primary role only** - see `server/routes/public.js`:
+  multi-role users see correctly-gated content but their served HTML is the
+  cache variant for their primary role's tier. Acceptable trade for keeping
+  cache cardinality bounded.
+
+### Migration
+
+Existing users with no `additionalRoles` field behave identically to today
+- `getEffectiveRoles` returns `[user.role]`, `getEffectiveLevel` returns
+`getRoleLevel(user.role)`. No data backfill needed. The field becomes
+available when the admin user editor exposes it (the API accepts it now;
+the UI is the next step).
+
+---
+
+### Example: recruiter dashboard
+
+A recruiter has posted several jobs and should see only the applications to
+those jobs:
+
+```json
+// Action: "Mark application as reviewing"
+{
+  "slug":       "review-application",
+  "collection": "applications",
+  "transition": { "field": "status", "from": ["submitted"], "to": "reviewing" },
+  "access": {
+    "roles":    ["recruiter", "admin"],
+    "rowLevel": {
+      "mode":             "reference",
+      "field":            "jobId",
+      "targetCollection": "jobs",
+      "targetField":      "createdBy"
+    }
+  },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "reviewing" } }
+  ]
+}
+```
+
+Now `recruiter` user Bob can transition applications, but only for jobs Bob
+posted. Recruiter Alice can transition different applications. Neither can
+touch the other's. Admin bypasses the row-level check entirely (role level 0).
+
+The transitions UI (`[collection ... transitions]`) automatically filters
+out actions the user can't perform on each row - so each recruiter sees
+exactly the applications they're allowed to act on, with the right buttons.