domma-cms 1.6.60 → 1.7.1

package/docs/editions-and-licences.md

@@ -0,0 +1,190 @@
+# Editions and licences
+
+What you get free with Domma CMS, what is paid, what "Pro" means, and how plugin licences work.
+Written for site owners. Prices: TBC.
+
+## In short
+
+- The CMS itself is free. Every core feature works without a licence.
+- Some plugins are free and ship with the CMS. Others are paid and need a licence.
+- A "Pro" plugin adds to, or replaces, a free Tool or plugin. If its licence lapses, the free one comes back.
+- A licence is either a **rental** (a site the Domma Manager runs for you) or **perpetual** (bought outright).
+- A rental stops when its term and grace period end. A perpetual licence never stops; only support and updates end.
+- A few features need MongoDB. One plugin, MongoDB Adapter, is only for sites run by the Domma Manager.
+
+## What the free CMS includes
+
+Everything in the core CMS is free:
+
+- **Content** - pages with a visual editor, version history, drafts and share links, shortcodes, blocks,
+  components and a media library.
+- **Design** - built-in themes, menus, right-click menus and a visitor theme switcher.
+- **Data** - collections on file storage, saved views, a form builder, and public collection displays.
+- **API** - the `/api/v1` collection API, the `/api/content/v1` Content API, API tokens and API Builder endpoints.
+- **Admin** - dashboard, notifications, in-admin docs, projects, roles and permissions.
+- **Built-in Tools** - Notes, Todo, Analytics, Contacts and SEO. Each can be switched off in the
+  Marketplace under "Built-in Tools".
+- **Marketplace** - installing, updating and switching plugins.
+
+## Core features that need MongoDB
+
+These are marked "Pro" in the CMS. They are not licensed. They switch on when the site has a MongoDB
+connection in `config/connections.json`:
+
+- **MongoDB storage** - keep any collection in MongoDB instead of files. Set it per collection on the
+  collection's Storage tab.
+- **Actions** - workflows that run steps against a collection entry. Without MongoDB the Actions screen
+  says they need MongoDB.
+
+Add a connection under **Data > Collections > Database connections** (admins only), or with
+`npm run pro enable`. On a site run by the Domma Manager, the MongoDB Adapter plugin sets the connection
+up for you (see below).
+
+The optional Redis cache driver is also described as a Pro feature. It needs Redis, not a licence.
+See `docs/cache.md`.
+
+## Free plugins
+
+These are marked `free` in their manifests and ship in the CMS `plugins/` folder. Switch them on in the
+Marketplace.
+
+- **Blog** - posts, categories and comments.
+- **Feedback** - tell Domma what is broken, missing or good, from your admin.
+- **Mail Reader** - a read-only IMAP mailbox reader.
+- **Security** - a health check, sign-in lockout, password rules and a sign-in log.
+- **Shopping Cart** - products, a storefront, a cart and checkout.
+
+## Paid plugins
+
+Every other plugin in the Marketplace is paid. A paid plugin is marked closed source. It needs a valid
+licence on the site, or it does not start. Paid plugins cannot be viewed or exported from the Marketplace.
+
+A plugin you write yourself is never asked for a licence.
+
+## What "Pro" means
+
+A Pro plugin builds on a free Tool or plugin. It does this in one of two ways:
+
+- **It replaces it** (`supersedes` in its manifest). The free one stops loading while the Pro one runs,
+  so you see one screen, not two. For a built-in Tool, the Pro plugin hides the Tool's sidebar entry and
+  takes over its screen. The Tool's data and API stay in place.
+- **It adds to it** (`requires` in its manifest). Both run. If the free one is switched off, the Pro one
+  does not start.
+
+| Pro plugin | Relationship |
+|---|---|
+| Blog Pro | Replaces Blog |
+| Contacts Pro | Requires and replaces the built-in Contacts Tool |
+| Email (email-pro) | Replaces Mail Reader |
+| Security Pro | Replaces Security |
+| SEO Pro | Requires the built-in SEO Tool |
+| Shopping Cart Pro | Requires Shopping Cart |
+| Analytics Pro | Separate from the built-in Analytics Tool; neither replaces the other |
+| Social Media Pro | No free edition |
+| Waypoint Pro | No free edition |
+
+### When a Pro licence lapses
+
+The replacement is worked out each time the site starts. Nothing is written to your settings. So when a Pro
+plugin stops running because its licence has lapsed:
+
+- the free plugin it replaced loads again on the next start, and
+- a built-in Tool it took over comes back.
+
+You are never left with less than a site that never bought the Pro plugin.
+
+## Licences
+
+### Where the licence lives
+
+A licence is a signed file called an entitlement. The CMS looks for it in two places, in this order:
+
+1. `plugins/<plugin>/.entitlement.json` - one plugin, one licence. A `.dcmsplugin` file carries it in.
+2. `config/entitlements/*.json` - site-wide licences.
+
+The file must be signed by the Domma Marketplace key. A missing, edited or wrongly signed file counts as
+unlicensed, and the plugin does not start.
+
+The licence is checked each time the site starts. A plugin that is refused is not switched off in your
+settings, so renewing brings it straight back on the next start.
+
+### Rental
+
+For a site run for you by the Domma Manager. The plugin is rented monthly alongside the hosting.
+
+- The plugin banner shows **Expires** and the date.
+- After the end date there is a grace period. The plugin keeps running and the banner shows
+  **Expired (date) (grace)**. The Marketplace marks it **Renew**. The grace period is set on the licence;
+  the Manager issues 7 days unless told otherwise.
+- After the grace period the plugin does not start. The Marketplace marks it **Expired**. Its data is kept.
+- A notice appears 14 days before the end date, during the grace period, and once it has stopped.
+
+### Perpetual
+
+For a site the Domma Manager does not run. You buy the plugin once, with a period of support.
+
+- The plugin banner shows **Support to** and the date.
+- When support ends, the banner shows **Support ended**. The plugin keeps running for good.
+- What ends is support and updates. Renewing support extends it.
+- A notice tells you when support and updates have ended.
+
+## Managed-only plugins
+
+**MongoDB Adapter** is only offered for sites run by the Domma Manager. The Manager creates a database and a
+user for the site, and writes the site's connection file. On a site the Manager does not run, the plugin
+would have nothing to do.
+
+When the Manager removes it, the site's connection file and database user are removed. The database itself
+is kept.
+
+## Plugins that need MongoDB
+
+- **MongoDB Adapter** - provides MongoDB to a managed site.
+- **Email (email-pro)** - search, threads, rules, scheduled sends, snooze and vacation replies need MongoDB.
+  Without it, reading, filing and sending still work.
+- **Data Transfer** - needs MongoDB only to move collections to or from MongoDB. Backups, restores and
+  clones work on file storage.
+- **Surveys** - uses MongoDB when there is a connection, and falls back to file storage when there is not.
+
+Garage and Messages work on either storage. The rest do not use MongoDB.
+
+## All Marketplace plugins
+
+| Plugin | Tier | Needs MongoDB | Managed-only | Notes |
+|---|---|---|---|---|
+| Analytics Pro | paid | No | No | Separate from the built-in Analytics Tool |
+| Blog | free | No | No | Ships with the CMS |
+| Blog Pro | paid | No | No | Replaces Blog |
+| Calendar | paid | No | No | Uses Contacts, Notes and Todo when they are on |
+| Contacts Pro | paid | No | No | Requires and replaces the built-in Contacts Tool |
+| Data Transfer | paid | Only to move to or from MongoDB | No | Backups and restores work on file storage |
+| Docs | paid | No | No | |
+| Email (email-pro) | paid | Partly | No | Replaces Mail Reader; some features need MongoDB |
+| Feedback | free | No | No | Ships with the CMS |
+| Garage | paid | No | No | Works on file or MongoDB storage |
+| Invoices | paid | No | No | Uses Contacts |
+| Job Board | paid | No | No | |
+| Mail Reader | free | No | No | Ships with the CMS |
+| Messages | paid | No | No | File storage unless moved to MongoDB |
+| MongoDB Adapter | paid | Provides it | Yes | Set up by the Domma Manager |
+| Security | free | No | No | Ships with the CMS |
+| Security Pro | paid | No | No | Replaces Security |
+| SEO Pro | paid | No | No | Requires the built-in SEO Tool |
+| Shopping Cart | free | No | No | Ships with the CMS |
+| Shopping Cart Pro | paid | No | No | Requires Shopping Cart |
+| Social Media Pro | paid | No | No | Uses SEO, Calendar and Blog when they are on |
+| Surveys | paid | Optional | No | Falls back to file storage |
+| Theme Roller | paid | No | No | |
+| Waypoint Pro | paid | No | No | |
+
+## Getting a licence
+
+Prices: TBC.
+
+- **A site run by the Domma Manager** - open **Marketplace > Browse**. It lists what your Manager offers.
+  Install brings a plugin in already licensed. A plugin not licensed yet is still listed; ask for it to be
+  added.
+- **Any other site** - buy the plugin and you receive a single `.dcmsplugin` file. Use **Install from
+  file** in the Marketplace banner. The same button installs later updates.
+
+To buy a plugin or renew a licence, contact Domma CMS.

package/docs/getting-started.md

@@ -0,0 +1,201 @@
+# Getting Started with Domma CMS
+
+## Prerequisites
+
+- **Node.js** 24 or later
+- **npm** 11 or later (bundled with Node 24+)
+- A terminal / command prompt
+
+## Quick Start
+
+The fastest way to create a new site is via `npx`, which requires no global install:
+
+```bash
+npx domma-cms@latest my-site
+cd my-site
+npm start
+```
+
+This scaffolds a new project in the `my-site/` directory and then, in one go:
+
+1. runs `npm install`,
+2. runs the terminal setup wizard (`npm run setup`, described below),
+3. seeds the default pages, forms and collections (`npm run seed`),
+4. writes a `.domma` version marker used by `npx domma-cms update`.
+
+You do not need to run `npm install` yourself. Options:
+
+| Flag | Effect |
+|---|---|
+| `--no-install` | Skip `npm install` (this also skips the setup wizard) |
+| `--no-setup` | Skip the terminal setup wizard - you can create the first admin in the browser instead |
+| `--no-seed` | Skip seeding default pages, forms and collections |
+| `--help` | Show usage |
+
+To update an existing project later, run `npx domma-cms update` from inside it (`--dry-run` previews the changes).
+
+## What the Scaffolder Creates
+
+```
+my-site/
+├── bin/                  # CLI entry point
+├── config/               # All configuration JSON files
+│   ├── auth.json
+│   ├── content.json
+│   ├── menus/            # Menu definitions (navbar, footer, etc.)
+│   ├── navigation.json
+│   ├── plugins.json
+│   ├── presets.json      # Page layout presets
+│   ├── server.json
+│   └── site.json
+├── content/              # All content as flat files
+│   ├── collections/      # Collection data (JSON entries)
+│   ├── media/            # Uploaded media files
+│   ├── pages/            # Markdown pages
+│   └── users/            # User accounts (JSON)
+├── plugins/              # Bundled plugins
+│   ├── blog/
+│   ├── mail-reader/
+│   ├── security/
+│   └── shopping-cart/
+├── admin/                # Admin SPA (Domma + Fastify)
+│   ├── css/
+│   ├── js/
+│   └── index.html
+├── public/               # Public site assets
+│   ├── css/site.css
+│   └── js/site.js
+├── scripts/              # Utility scripts (setup, seed, reset)
+├── server/               # Fastify server
+│   ├── middleware/
+│   ├── routes/
+│   ├── services/
+│   └── server.js
+├── .env                  # Secrets only (JWT_SECRET, NODE_ENV, ...)
+└── .domma                # Version marker used by `npx domma-cms update`
+```
+
+Other `content/` folders (blocks, forms, versions, sessions and so on) are created as the CMS needs them.
+
+## Running the Setup Wizard
+
+The scaffolder runs the setup wizard for you. You can run it again at any time:
+
+```bash
+npm run setup
+```
+
+The terminal wizard works through these steps, skipping any that are already done:
+
+1. **JWT secret** - generates a secure `JWT_SECRET` in `.env` (skipped if one is already set)
+2. **Instance secret** - generates `INSTANCE_SECRET` in `.env` (skipped if already set); Mail Reader seals stored mailbox passwords with it
+3. **Admin account** - only if no users exist: asks for your full name, email address and a password (minimum 8 characters), and creates a Super Admin in `content/users/<uuid>.json`
+4. **Site identity** - site title and tagline, written to `config/site.json` and the navbar brand (the SMTP From name follows the title while it still matches the old one)
+5. **Theme** - pick one of the bundled themes (Enter keeps `charcoal-dark`)
+6. **Port** - the server port (Enter keeps 4096), written to `config/server.json`
+
+### Setting up in the browser instead
+
+If you skipped the terminal wizard (`--no-setup`), open `/admin` while no users exist. The admin shows a setup form to create the first Super Admin, followed by a short onboarding wizard: name the site, pick a theme, done. Browser setup is refused once any user exists.
+
+## Starting the Server
+
+```bash
+npm start
+```
+
+For development with automatic restarts on file changes:
+
+```bash
+npm run dev
+```
+
+The server starts on port **4096** by default. Open `http://localhost:4096` to see your public site and `http://localhost:4096/admin` for the admin panel.
+
+## First Login
+
+1. Navigate to `http://localhost:4096/admin`
+2. Enter the email and password you provided during setup
+3. You will be issued a JWT access token (15 min expiry) and a refresh token (7 day expiry) - these are stored in the browser and refreshed automatically
+
+If you ever get locked out, use the user management script rather than a reset - for example `npm run users -- reset-password you@example.com` or `npm run users -- list`. (`npm run reset` is a full factory reset that also deletes your pages, media and collections - see below.) If the Security plugin's lockout has blocked you, run `node plugins/security/bin/unlock.js --all`.
+
+## Creating Your First Page
+
+1. In the admin sidebar, click **Pages**
+2. Click **New Page**
+3. Set a **URL path** (e.g. `/about`) - this maps directly to the public URL
+4. Give the page a **title** and choose a **layout** (for example default, with-sidebar, landing or article)
+5. Write content using Markdown in the editor; shortcodes such as `[card]`, `[grid]`, and `[slideover]` are supported
+6. Set **Status** to `published` and click **Save**
+
+The page is immediately available at `http://localhost:4096/about`.
+
+## What's Included by Default
+
+### Themes
+
+Twenty-eight themes ship out of the box - fourteen colour palettes each in a dark and a light variant:
+
+| Palette | Dark | Light |
+|---|---|---|
+| Charcoal | charcoal-dark | charcoal-light |
+| Ocean | ocean-dark | ocean-light |
+| Forest | forest-dark | forest-light |
+| Sunset | sunset-dark | sunset-light |
+| Royal | royal-dark | royal-light |
+| Lemon | lemon-dark | lemon-light |
+| Silver | silver-dark | silver-light |
+| Grayve | grayve-dark | grayve-light |
+| Mint | mint-dark | mint-light |
+| Unicorn | unicorn-dark | unicorn-light |
+| Dreamy | dreamy-dark | dreamy-light |
+| Christmas | christmas-dark | christmas-light |
+| Wedding | wedding-dark | wedding-light |
+| Corporate | corporate-dark | corporate-light |
+
+The public site theme and the admin theme are set independently in **Settings**.
+
+### Built-in features that used to be plugins
+
+Analytics (page-hit tracking), effects (scroll-triggered animations and the effect shortcodes) and the public theme switcher are now part of the core CMS - there is nothing to install or enable.
+
+### Plugins
+
+Four free plugins are bundled in `plugins/`:
+
+- **blog** - public blog with posts, categories and comments
+- **mail-reader** - read-only IMAP mailbox reader inside the admin
+- **security** - health check, sign-in lockout, password rules, sign-in log and scanner blocking
+- **shopping-cart** - products, storefront, cart and checkout (Stripe, PayPal or offline payment)
+
+A new project starts with all four disabled - enable the ones you want from the **Marketplace** screen in the admin (enabling Security is recommended). When an existing site is updated with `npx domma-cms update`, Security arrives switched on. Paid plugins (Theme Roller, Blog Pro and others) are installed from the Marketplace or from a `.dcmsplugin` file.
+
+### Page Layouts
+
+Nine layout presets are included (defined in `config/presets.json`):
+
+| Key | Description |
+|---|---|
+| `default` | Standard page with navbar and footer |
+| `with-sidebar` | Page with navbar, sidebar, and footer |
+| `minimal` | Clean page with no navbar or footer |
+| `blank` | Minimal page with no navbar or footer |
+| `landing` | Full-width landing page with navbar, no footer |
+| `article` | Narrow reading column for long-form prose and blog posts |
+| `product` | Full-width marketing page that keeps the footer |
+| `dashboard` | Wide layout for data-heavy or app-like pages; no footer |
+| `wide` | Standard page using a wide content column (about 75% of the viewport) |
+
+### npm Scripts
+
+| Script | Purpose |
+|---|---|
+| `npm start` | Start the server |
+| `npm run dev` | Start with `--watch` for development |
+| `npm run setup` | Interactive setup wizard (secrets, first admin, site identity, theme, port) |
+| `npm run seed` | Populate default pages, forms and collections |
+| `npm run users -- <command>` | Command-line user management (`list`, `reset-password`, `set-role`, `create`, ...) |
+| `npm run reset` | **Factory reset** (asks you to type `yes`): deletes all users, pages, media, collections (except roles) and form data, resets `site.json` and `navigation.json` to defaults, and resets `JWT_SECRET` to a placeholder |
+| `npm run fresh` | `reset` followed by `setup` - a clean install ready to use (it does not reseed; run `npm run seed` afterwards if you want the default content) |
+| `npm run build` | Bundle admin JS with esbuild |

package/docs/guides/form-triggers.md

@@ -0,0 +1,260 @@
+# Form Triggers
+
+A **trigger** is attached to a field and does something to the *form* when the answers meet a
+condition. "Are you over 18? No" ending the form there, saving what was answered and telling the
+admins is one trigger.
+
+It is the sibling of **Conditional Logic**, not a replacement for it:
+
+| | Conditional Logic | Triggers |
+|---|---|---|
+| Decides | how one **field** behaves (shown, required, valid, what its options are) | what the **form** does (banners, toasts, other fields, the submit button) |
+| Authored in | the field's ⚡ Conditional Logic panel | the field's 🎯 Triggers panel |
+| Stored as | `field.logic` | `field.triggers[]` |
+
+Both run on the same condition engine, so an operator behaves identically in either.
+
+---
+
+## Building one
+
+In **Forms > edit a form**, open a field's **🎯 Triggers** panel and click **Add trigger**.
+
+A trigger has three parts:
+
+1. **When** - one or more conditions, combined with *all of these are true* or *any of these is
+   true*. A condition can name **any** field on the form - the one the trigger hangs off is listed
+   first, marked *(this field)*, since "when this answer is No" is the usual case. That field is
+   also what "the rest of the form" is measured from.
+2. **Then** - what happens while (or when) the condition holds.
+3. **Otherwise** - optional; what happens while (or when) it does not.
+
+---
+
+## The two kinds of action
+
+This is the part worth reading twice, because it decides how everything behaves.
+
+**State actions apply *while* the condition holds and are reverted the moment it stops.** They are
+re-evaluated on every keystroke, so they cannot drift out of step with the answers.
+
+| Action | Effect |
+|---|---|
+| **Show a banner** | An inline message above the field, below it, or at the top of the form. Choose a level (info / success / warning / error) and whether the visitor can dismiss it. |
+| **Hide fields** | Removes them from the form. A hidden field is never required and its value is not submitted. |
+| **Disable fields** | Leaves them visible but unanswerable. Treated the same as hidden on submission - the visitor was given no way to answer. |
+| **Make fields required** | Adds the requirement on top of whatever the field already had. Hiding a field beats requiring it. |
+| **Block submission** | Refuses the submit and puts your reason under the button. |
+| **End the form here** | Masks everything after this field, shows your message in its place, and turns the submit button (a wizard's *Next* included) into *Finish*. See [Ending a form early](#ending-a-form-early). |
+
+**Event actions fire *once*, on the transition into that branch.** They are not undone, because an
+un-fired toast is not a thing.
+
+| Action | Effect |
+|---|---|
+| **Show a toast** | A transient corner message. |
+| **Jump to a wizard step** | Moves a multi-page form to a step, counting from 0. |
+| **Redirect after submit** | Sends the visitor to a URL once the submission is stored. Wins over the form's own success redirect. |
+| **Celebrate** | Fires a celebration effect. Respects `prefers-reduced-motion`. |
+| **Run a CMS action** | Runs an Actions artefact server-side, after the entry is stored. |
+| **Notify the admins** | Raises a notification in the admin when the form is submitted - the bell, and a desktop notification for anyone who turned those on. See [Telling the admins](#telling-the-admins). |
+
+Event actions do **not** fire on the initial render. A form that opens with an answer already in it
+- a wizard step revisited, a pre-filled value - would otherwise greet the visitor with a toast about
+a choice they have not just made. Tick **Only once** to fire the first time and never again.
+
+Swinging an answer back and forth *does* re-fire, because the `then` and `otherwise` branches are
+tracked separately. That is what "when you pick No" means.
+
+---
+
+## Ending a form early
+
+Some answers mean there is nothing more to ask - an applicant who is under age, a region you do not
+serve. **Block submission** refuses those outright, which also means nobody ever finds out they
+happened. **End the form here** finishes the form instead:
+
+- everything after the field is masked (removed from view), and your message takes its place
+- the submit button - or a wizard's *Next* - reads *Finish* (or your own button text)
+- *Finish* posts the answers given so far; the masked fields are neither required nor stored,
+  even where the form marks them required
+- the visitor sees your closing message, or the form's success message if you left it blank
+
+The field the trigger hangs off stays answerable. Change the answer and the rest of the form comes
+back, exactly as it was.
+
+The stored submission carries `meta.outcome`:
+
+```json
+{"type": "ended", "trigger": "trg-1789806137396-2yeti:then", "field": "over18"}
+```
+
+Untick **Save the answers given so far** to keep nothing: no submission is stored, and the form's
+own email, webhook and action do not run - there is no submission for them to report. A **Notify
+the admins** action on the same trigger still fires, so you still hear about it.
+
+Untick **Let the visitor finish** to stop the form dead instead: the rest is still masked and your
+message still shows, but the submit button (or a wizard's *Next*) is disabled and the server refuses
+the post. Nothing is sent, so nothing is saved and **Notify the admins** cannot fire - use it when
+the answer should simply go no further.
+
+A **Block submission** in force beats an ending: a refused form is not finished.
+
+---
+
+## Telling the admins
+
+**Notify the admins** raises a notification when the form is submitted with the condition holding -
+the server checks it against the posted answers, so it cannot be faked or skipped. The notice names
+the form, the question and the answer, and links to the submissions (or to the form, when nothing
+was saved). Its level maps onto the bell's severities, with *Error* shown as *critical*.
+
+Who receives it is a setting, not part of the form: **Notifications > settings**, source **Form
+triggers**. It goes to every admin by default. At most 30 are raised an hour, so a busy form cannot
+bury the inbox.
+
+For an **email** instead (or as well), use **Run a CMS action** with an Action whose steps include
+*Send an email*. Actions have a *Notify the admins* step too, for the same notice from anywhere an
+Action runs.
+
+---
+
+## Putting answers in messages
+
+A message can repeat what the visitor has answered. Write the field's name in double braces:
+
+> Name *is not empty* -> **Show a banner**: `Hello {{name}}, thanks for getting in touch.`
+
+The **Insert field** list beside each message box puts a token in at the cursor, so you do not need
+to remember the names.
+
+Tokens work in the messages the visitor sees: **Show a banner**, **Show a toast**, the reason under a
+**Block submission**, and the message and closing message of **End the form here**. A banner changes
+as the visitor types; a toast shows the answer at the moment it appears.
+
+What a token shows:
+
+- the answer as typed, on one line and cut off after 200 characters;
+- for a dropdown, radio, chooser or checkbox group, the option's label rather than its stored value,
+  with several choices joined by commas;
+- for a single tickbox, *Yes*, or nothing;
+- nothing at all for a password, file or image field, for a field that is empty, for a name that is
+  not on the form, and for a field a trigger has hidden, disabled or ended the form before.
+
+Answers are always shown as text: a visitor who types HTML into a field sees the characters, never
+the markup. The server fills the same tokens from the same answers, so a blocked submission's `400`
+and the closing message after an ending say exactly what the browser said.
+
+**Redirect after submit** and **Notify the admins** do not fill tokens yet - a web address and an
+admin notification need their own safety rules first.
+
+Tokens refer to fields by name, and renaming a field does not update them (the same is true of
+conditions). Saving warns about any token that will show as blank, so a rename is caught.
+
+---
+
+## Which fields an action addresses
+
+Actions that act on other fields offer three targets:
+
+| Target | Meaning |
+|---|---|
+| **The rest of the form** | Every field *after* this one, in form order |
+| **Every other field** | Every field on the form except this one |
+| **Chosen fields** | Exactly the fields you pick |
+
+**The field the trigger hangs off is never a target**, whichever you choose. A trigger that disabled
+its own field would freeze the form on the first wrong answer with no way back.
+
+---
+
+## It is enforced on the server too
+
+Everything a trigger decides about *submission* is re-evaluated on the server, from the same engine,
+when the form is posted:
+
+- a **blocked** submit is refused with its message, whatever the browser was told
+- **hidden** and **disabled** fields are neither required nor stored, even if a value is posted
+- **required** fields added by a trigger are enforced
+- an **ended** form is accepted with only the answers before the ending, and **notify** fires from
+  the server's own reading of the answers
+
+Re-enabling the button in dev tools gets you a 400, not a submission. The browser-side copy exists to
+answer immediately rather than after a round trip.
+
+---
+
+## Worked example: an age gate
+
+On an "Are you over 18?" radio field:
+
+- **When** `over18` (this field) equals `no`
+- **Then**
+  - End the form here: *"Sorry - you must be 18 or over to apply."*, closing message *"Thanks for
+    your time."*
+  - Notify the admins, warning: *"Under-age applicant"*
+- **Otherwise**
+  - Show a toast, success: *"Thanks - carry on."*
+
+Answering *no* masks everything below and turns the button into *Finish*; finishing saves the
+answer, thanks the visitor and puts a notice in the admins' bell. Answering *yes* brings the form
+back and toasts once.
+
+To refuse outright rather than record anything, use **Block submission** (with a banner and
+**Disable fields** to show why) instead of ending the form.
+
+---
+
+## Stored shape
+
+```json
+{
+  "name": "over18",
+  "type": "radio",
+  "options": ["yes", "no"],
+  "triggers": [
+    {
+      "id": "trg-1789806137396-2yeti",
+      "enabled": true,
+      "when": {"all": [{"field": "over18", "operator": "equals", "value": "no"}]},
+      "then": [
+        {"type": "end-form", "message": "Sorry - you must be 18 or over to apply.",
+         "finishLabel": "Finish", "doneMessage": "Thanks for your time."},
+        {"type": "notify", "message": "Under-age applicant", "level": "warning"}
+      ],
+      "otherwise": [
+        {"type": "toast", "message": "Thanks - carry on.", "level": "success"}
+      ]
+    }
+  ]
+}
+```
+
+`when` takes the same `{all: [...]}` / `{any: [...]}` condition groups conditional logic uses, with
+the same operators, including the array semantics for checkbox groups and multi-select choosers -
+a positive operator passes when **any** selected value matches, a negative when **none** does.
+
+---
+
+## Notes and limits
+
+- A trigger with conditions but no actions is dropped on save rather than stored as an empty card.
+- An unknown action type is ignored rather than breaking the form, so a record written by a newer
+  version degrades instead of failing.
+- Two triggers redirecting at once is an authoring mistake, not a case the server resolves cleverly:
+  the first one wins.
+- **Jump to a wizard step** needs a multi-page form; on a single-page form it does nothing.
+- `end-form` always reaches the rest of the form; it takes no target. `record: false` turns saving
+  off, `finish: false` disables the submit altogether, and `finishLabel` / `doneMessage` are
+  optional.
+- Only the first ending in force speaks - two panels saying "stop" would be one too many.
+- Banners and toasts are the browser's business, so they leave no trace in the submission record.
+  What a trigger fired on is the answer it tested, and that answer is stored - read the decision back
+  from there.
+
+---
+
+## Related
+
+- [Multi-Page Forms](multi-page-forms.md)
+- [Configuration](../configuration.md)