Merge pull request 'docs(website): the seeded template set as built (engagement Phase 5a)' (#185) from docs/engagement-templates into edge

Companion to website#TBD. §6.0b assigns this phase two documents; both land here.

ENGAGEMENT.md gains an "As built — 5a" section: the three decisions the survey
forced, the argument for two registries rather than one, why the ternaries stayed
at the call site, and the two behaviour changes an operator will notice.

BACKEND_DESIGN.md gains the `engagement_templates` table, the two-block-registry
split, the token grammar, and the §7 note that mail is now multipart.

Co-Authored-By: Claude <noreply@anthropic.com>

website/BACKEND_DESIGN.md

@@ -619,6 +619,78 @@ a rule's budget and mute it.
 appear here, and neither do they appear in the engagement log lines, which carry variable *names* and
 counts only.
 
+### engagement_templates  — the message bodies (engagement phase 5a)
+| col | type | notes |
+|---|---|---|
+| id | INT AUTO_INCREMENT PK | |
+| `key` | VARCHAR(96) NOT NULL **UNIQUE** | the stable id a rule's `template_keys` map and `mailer` name |
+| name | VARCHAR(160) NOT NULL | what the admin list shows |
+| trigger_id / trigger_version | VARCHAR(96) NULL / INT NULL | **no foreign key**, for the reason `engagement_rules.trigger_id` has none: a trigger is declared in code. NULL = a reusable template not tied to one trigger, which is what every transactional seed is |
+| channel | VARCHAR(32) NOT NULL | one template per channel; a rule names a set |
+| subject | VARCHAR(300) NULL | email only, and it interpolates. NULL is how a non-email template says it has none |
+| blocks | MEDIUMTEXT NOT NULL | a JSON block array, validated + sanitized on write against the `email.*` registry — never raw operator HTML |
+| text_body | MEDIUMTEXT NULL | an authored plain-text part that **replaces** the generated one; NULL = generated from each block's `toText` |
+| status | ENUM('draft','published') DEFAULT 'draft' | |
+| protected | TINYINT(1) DEFAULT 0 | editable, not deletable — the `pages.protected` flag, for the same reason: the system breaks without a password-reset body |
+| seed_key / seed_version / customized | VARCHAR(96) NULL / INT NULL / TINYINT(1) DEFAULT 0 | the "ship a better default without stealing an operator's work" mechanism — see below |
+| updated_by | INT NULL FK→users(id) ON DELETE SET NULL | |
+| created_at / updated_at | DATETIME | |
+
+`INDEX(trigger_id, channel, status)`, `INDEX(seed_key)`.
+
+**The three seed columns are one mechanism, and the guard lives in SQL.** On boot the seeder runs an
+`INSERT IGNORE` per shipped template and, when the row already exists, a single
+`UPDATE … WHERE seed_key = ? AND customized = 0 AND seed_version < ?`. A read-then-write would leave a
+window in which a concurrent boot overwrites an edit an operator made a moment earlier; putting
+`customized = 0` in the UPDATE's own WHERE closes it. (MariaDB's `ON DUPLICATE KEY UPDATE` cannot carry
+a WHERE, which is why this is two statements rather than the upsert ENGAGEMENT.md §4.6.1 sketches.) A
+customized row whose shipped default has moved on is **surfaced**, never applied.
+
+**A missing or unusable row renders the shipped default rather than nothing.** `renderByKey` falls back
+to the in-code seed whenever the row is absent or its `blocks` will not parse — before the first seed
+runs, after a restore that dropped the table, or on a row hand-edited in the database. That fallback is
+what makes it safe for a password-reset mail to depend on this table at all.
+
+### The two block registries — pages and mail (engagement phase 5a)
+
+`server/src/blocks/` (the CMS page family) and `server/src/emailBlocks/` (`email.heading`, `email.text`,
+`email.button`, `email.divider`, `email.image`, `email.itemList`) are **siblings, not one registry**.
+Three reasons, in order of what they cost if ignored:
+
+1. **Email blocks render on the server.** A page block carries `schema` / `sanitize` / `cacheTTL` and is
+   drawn by React in `client/src/blocks/`; a mail body is a string this process produces, so an email
+   definition carries `toHtml` and `toText`. `registerBlock` freezes a fixed field set and would drop
+   both silently.
+2. **One registry would be one namespace.** The page registry's only server consumer is
+   `pages.model.js`; putting `email.heading` in that Map makes a CMS page containing an email block
+   validate and save, with nothing on the client able to draw it.
+3. The entry shapes differ — `cacheTTL` and `container` mean nothing to a mail body, a renderer nothing
+   to a cached page block.
+
+What *is* shared is shared by binding rather than by copy: `propHelpers`, the envelope/id/nesting walk
+(`makeValidateBlocks`) and the validate-then-sanitize order (`makeSanitizeBlocks`) are factories the two
+registries each bind. ENGAGEMENT.md §4.4's "do not build a second editor" is honoured where it is about
+the editor — Phase 5b drives the `email.*` family through the existing block/prop-panel machinery.
+
+### Template variables — the token grammar (engagement phase 5a)
+
+`{{ name }}`, a bare declared variable name, and nothing else: no filters, no conditionals, no loops, no
+dotted paths. Repetition is a block (`email.itemList` renders a declared *list* variable), which is why
+the grammar needs no loop. Three consequences worth knowing before authoring one:
+
+- **Interpolation is HTML-escaped in the HTML part and raw in the text part.** There is no raw-HTML
+  variable type (§4.6.2) — a module supplies data, not markup.
+- **A URL built from a variable is re-checked after substitution.** A stored `{{resetUrl}}` says nothing
+  about where it points; a substituted value that is not http(s)/same-origin loses its href and renders
+  as inert text rather than as a link a reader has no reason to distrust.
+- **Presentational conditionals live at the call site**, not in the template. `mailer` computes
+  ` for the account “Darrow”` with a ternary and passes the *result* as a variable, whose declared
+  `example` shows exactly what it produces.
+
+Four **ambient** variables — `siteName`, `siteUrl`, `logoUrl`, `year` — are available to every template
+and are merged **over** whatever a caller passes. A caller supplies the message; the deployment supplies
+its identity, and letting a caller override it would mean mail that claims to be from somewhere else.
+
 ### mobile_auth_sessions / mobile_auth_codes  — mobile SSO bridge (M9)
 
 Two short-lived, self-pruning tables that bridge a browser SSO redirect flow to a native client. They
@@ -1400,6 +1472,19 @@ must land an admin on a screen that says "unconfigured", not a 500 that takes th
 it. `provider` and `refresh_token_enc` remain as **deprecated, unread columns** under the
 additive-only discipline.
 
+**What each sender still owns is its recipient, its headers and its failure contract — not what it
+says.** Engagement Phase 5a moved every subject and body out of `mailer.js` into `engagement_templates`
+rows (§4.6.1); the file's five senders call one seam, `engagement/templates.renderByKey`, which falls
+back to the shipped seed when the row is missing or unusable. Two consequences:
+
+- **Mail is now `multipart/alternative`.** Nothing here had an HTML part before. The **text part is
+  byte-identical** to what the deleted literals built — pinned by `test/emailTemplates.test.js`, whose
+  expected strings *are* those literals — and the HTML part is new, table-based and inline-styled.
+- **Subjects now resolve the deployment's own name.** They interpolate `{{siteName}}`, which is
+  `settings.getInstanceName()` — the admin-set `site_title`, falling back to `BRAND_NAME`. On a
+  deployment that never set a site title nothing changes; on one that did, the subject finally says
+  what the site calls itself.
+
 **No phone-home.** No transport may ship a default host, port, endpoint or sender
 ([`ENGAGEMENT.md`](ENGAGEMENT.md) §3.2). A transport with no operator configuration is
 `unconfigured` and its channel is off — it never falls back to a destination we chose.

website/ENGAGEMENT.md

@@ -1317,7 +1317,8 @@ change is not complete until `docs/` reflects it" — is the floor; this table i
 | **3** Channel preferences | `website/BACKEND_DESIGN.md` route table · `android/PLAN.md` §11 | — |
 | **4a** Engine | `website/ENGAGEMENT.md` (rules/cooldown/outbox as built, and the two §4 defects it corrects) · `BACKEND_DESIGN.md` table inventory | — |
 | **4b** Rules screen ✅ | `website/BACKEND_DESIGN.md` route table (the twelve routes, incl. the `PATCH …/enabled` argument and the count-only preview) · `website/ENGAGEMENT.md` §5.1a composition UI | Landed with the phase (docs#184) |
-| **5a/5b** Templates + editor | `website/ENGAGEMENT.md` §4.6 · a template-authoring section in `BACKEND_DESIGN.md` or its own doc | **`runicgateway.com`**: a new admin docs page for the template editor |
+| **5a** Templates ✅ | `website/ENGAGEMENT.md` §4.6 as built · `BACKEND_DESIGN.md` — the `engagement_templates` table, the two block registries, the token grammar, and §7's multipart/subject changes | Landed with the phase |
+| **5b** The editor | `website/ENGAGEMENT.md` §4.6.2 as built · `BACKEND_DESIGN.md` route table | **`runicgateway.com`**: a new admin docs page for the template editor |
 | **6** Email channel + Teams migration | `website/TEAMS.md` §6.3/§6.4 **rewritten** — the Team pipeline it describes no longer exists as its own thing | **`runicgateway.com`**: `administration/teams.mdx` notification section |
 | **7** In-app channel (core+web) | `website/BACKEND_DESIGN.md` routes + tables · `website/ENGAGEMENT.md` | **`runicgateway.com`**: `notifications-and-email.mdx` gains the in-app channel |
 | **8** In-app (Android) | `android/PLAN.md` | `android-app/README.md` |
@@ -2074,7 +2075,7 @@ refuses anything else, and it also refuses an id with no dot in it at all.
 Two slices, landing in this order **on purpose** — the seeded set has to exist before the editor, so the
 editor is opening something rather than facing a blank page.
 
-**5a — storage, blocks, renderer, seeds.** `engagement_templates`, the `email.*` block family with
+**5a — storage, blocks, renderer, seeds.** ✅ `engagement_templates`, the `email.*` block family with
 `toText`, the HTML + plain-text renderer, brand-value resolution, and the §4.6.1 seeded set. The five
 transactional bodies move out of `mailer.js` into seeded rows and `mailer` renders them. **No editor
 yet** — this slice is provably done when the same mail goes out from a template that used to come from a
@@ -2098,6 +2099,149 @@ operator-authored HTML; it must be sandboxed (`<iframe sandbox>` with no `allow-
 `about:blank` origin) so it never executes under the site's origin, and `sanitizeHtml` runs on write as
 well as on render. Worth a `test/csp.test.js` sibling asserting the preview frame's attributes.
 
+#### As built — 5a (2026-08-29)
+
+Built as website#TBD. Three decisions were settled by the org lead before any code, each because the
+tree contradicted something the plan assumed.
+
+| | Question the survey raised | Decision |
+| --- | --- | --- |
+| **The HTML part** | **Not one existing mail has one.** All six senders in `mailer.js` set `text:` only, so "renders byte-comparably" is a statement about a *text* body and whether 5a introduces HTML to live mail was an open choice | **Multipart now, text byte-identical.** The text part is byte-for-byte what went out before; the HTML alternative is new. The renderer is therefore exercised by real mail in the phase that builds it rather than shipping dead until 5b |
+| **The block registry** | **The server block registry has no renderer of any kind.** Page blocks are drawn by React on the client; `registerBlock` freezes a fixed field set and would silently DROP a `toHtml`/`toText` | **A sibling registry, with the machinery shared by binding.** §4.4's "do not build a second editor" is about the editor, and 5b still drives these through the existing block/prop-panel machinery |
+| **The seed scope** | §4.6.1 lists nine seeds but `teamNotify`/`teamDigestWorker` are explicitly Phase 6's to rewrite | **Seed all nine, wire the six transactional.** Phases 6 and 7 open something rather than each shipping seeds of their own |
+
+**And a correction to §4.6.1 itself:** it lists `auth.email-verify` as "*(new — Phase 9)*". Phase 1b
+already shipped `mailer.sendEmailVerification`, so it is a **current** message type, not a future one —
+six bodies moved, not five, and all six are pinned by the byte-comparison test.
+
+##### The two registries are siblings, and that is an argument rather than a preference
+
+Sharing one Map would have cost three things. Email blocks **render on the server** and so carry
+`toHtml`/`toText`, which the page registry's frozen entry shape has nowhere to put. One Map is one
+namespace, and the page registry's only server consumer is `pages.model.js` — so `email.heading` in it
+means a CMS page containing an email block validates and saves, with nothing on the client able to draw
+it. And the entry shapes genuinely differ: `cacheTTL` and `container` mean nothing to a mail body.
+
+What *is* the same rule for both is shared by binding, not by copy. `blocks/validateBlocks.js` and
+`sanitizeBlocks.js` became factories over a registry lookup (`makeValidateBlocks` /
+`makeSanitizeBlocks`), each exporting the page-bound instance every existing caller already imports, and
+`emailBlocks/` binds the same walk to its own registry. The envelope rules, id uniqueness, schema
+dispatch and the validate-then-sanitize order therefore cannot drift between the families. There is a
+test asserting both directions of the isolation: an `email.heading` fails page validation, and a plain
+`heading` fails email validation.
+
+##### The token grammar has no conditional, so the ternaries stayed at the call site
+
+`{{ name }}`, a bare declared variable, and nothing else — no filters, conditionals, loops or dotted
+paths. Repetition is a block (`email.itemList` renders a declared *list* variable), which is the one
+place a template needs "for each" and it already has a typed, validated home.
+
+That has a visible consequence. `mailer` built ` for the account “Darrow”` with a ternary, and a
+logic-free template cannot. So the ternary stays where a ternary belongs and its **result** arrives as a
+variable — `forWhom`, `roleLabel`, `invitedBy`, `moreNote` — each declared with an `example` showing
+exactly what it produces, leading space and quotes included. It is not pretty in the editor and it is
+the price of not giving operator-authored data a conditional to get wrong. **Both branches of every
+ternary are asserted**, because the empty one is what a template language with a conditional would most
+likely get wrong.
+
+Where a conditional would otherwise be reached for, "nothing in, nothing out" stands in: a block whose
+content interpolates to nothing renders nothing, in **both** parts. `{{moreNote}}` on its own line is a
+line the caller can decline to supply.
+
+##### Three properties of the renderer that are load-bearing
+
+- **The shell contributes structure and no content.** No appended footer, no injected logo, no "sent by"
+  line. An unsubscribe line is a *variable inside the template*, so an operator can move it, reword it,
+  or see that a transactional mail correctly has none — and, more importantly, the HTML and text parts
+  say the same things. A footer in one and not the other is a deliverability signal and means the text
+  reader is told less than the HTML reader.
+- **Only the accent comes from the theme.** Every shipped preset is a DARK palette, and §4.6.2 already
+  names the failure: a light-only template "renders as unreadable dark-on-dark in about a third of
+  inboxes", because clients invert or force their own background. Deriving a light palette from a dark
+  one is a guess at six colours; taking the one colour that carries the brand is exact. §4.6.1's
+  property 2 holds either way — no seeded template contains a hex code, asserted by a test.
+- **A URL built from a variable is re-checked after substitution.** A stored `{{resetUrl}}` says nothing
+  about where it points. Checking only the literal would let a variable carrying `javascript:` become an
+  href; a substituted value that fails `isSafeUrl` loses its href and renders as inert text rather than
+  vanishing, because silently dropping it would hide from the reader that the mail meant to offer them
+  something.
+
+##### A missing row renders the shipped default, which is what makes the whole move safe
+
+`renderByKey` falls back to the in-code seed whenever the row is absent or its `blocks` will not parse:
+before the first seed runs, after a restore that dropped the table, on a row hand-edited in the
+database. Without it, moving a password-reset body into a table would have made every failure mode of
+that table a failure mode of account recovery. `protected = 1` stops the last of those from being
+reachable through the API at all.
+
+##### The seed guard is in the SQL, not in a read-then-write
+
+`INSERT IGNORE`, then `UPDATE … WHERE seed_key = ? AND customized = 0 AND seed_version < ?`. A check in
+JavaScript followed by an UPDATE leaves a window in which a concurrent boot overwrites an edit an
+operator made a moment earlier, and a deployment can start two app processes at once. MariaDB's
+`ON DUPLICATE KEY UPDATE` cannot carry a WHERE, which is why this is two statements rather than the
+upsert §4.6.1 sketches.
+
+Related, and recorded because [Phase 4a](#as-built--4a-2026-08-29) was bitten by the same thing: the
+connector defaults **`foundRows: true`**, so `affectedRows` on an UPDATE counts *matched* rows. For the
+seeder that is harmless (its WHERE only matches a row that will change); for an operator's save it is
+the semantics wanted — re-saving a template unchanged is a success, not a 404. Both are now stated in
+the code rather than relied on.
+
+##### Two behaviour changes an operator will notice
+
+1. **Mail is multipart.** A client that prefers HTML now shows a branded body where it used to show
+   plain text. Nothing a text-only reader sees has changed.
+2. **Subjects resolve the deployment's own name.** They interpolate `{{siteName}}`, which is
+   `settings.getInstanceName()` — the admin-set `site_title` falling back to `BRAND_NAME`, rather than
+   `BRAND_NAME` alone. On an instance that never set a site title nothing changes; on one that did, the
+   subject finally says what the site calls itself.
+
+Also inherited rather than introduced, and now visible: `admin.contact-message` declares **both**
+`fromLabel` and `fromName` — the same missing name with the two different fallbacks the literal used
+('a visitor' in the subject, 'unknown' in the body). Kept exactly, asserted, and now editable by whoever
+wants one word.
+
+##### One defect this phase found in a Phase 1 check
+
+`npm run check:hosts` (§3.2 rule 4) read the template key **`auth.email-verify`** as the hostname
+`auth.email`. `.email` is a real TLD and the pattern's trailing `\b` matches between `l` and `-`, so any
+engagement identifier whose label happens to end in a TLD tripped it — and §4.6.1 names that key. Fixed
+with a `(?![-\w])` after the TLD: a real hostname's TLD is its last label, so a following `-` or word
+character means the match is a truncation of a longer identifier. Everything a host *is* followed by (a
+quote, `/`, `:`, `?`) still matches, and the checker's own suite gained both the identifiers it must now
+accept and two real `.email` hosts it must still catch.
+
+##### Verification
+
+- **31 new server tests** (`test/emailTemplates.test.js`) and 3 added to the host-check suite. Full
+  server suite green: 1388 passing, with the one known Windows CRLF artifact
+  (`engagement-triggers.json` byte comparison) and `honeypot.test.js`'s 10-second pool-acquire flake
+  under full-suite parallelism, both of which reproduce on clean `edge`. `routes.manifest` /
+  `routes.guards` need `modules/uo` moved aside, as ever; 5a adds no routes.
+- **The seeder's SQL against a real MariaDB**, because the unit tests stub `seedOne` and therefore prove
+  the loop rather than the statements — the exact shape of Phase 4a's `foundRows` trap, where a stub
+  agreed with a broken query. First run 9 inserted; second 9 skipped; after a `seedVersion` bump 8
+  updated and the customized row skipped, keeping both its words and its old version, and surfaced by
+  `staleCustomized`. The blocks JSON round-tripped through `MEDIUMTEXT`, and `update()` twice with
+  identical values returned true both times.
+- **Real mail, end to end**, through nodemailer and SMTP into a mailpit catcher: all five senders, the
+  message arriving as `multipart/alternative; charset=utf-8` with the curly quotes correctly
+  quoted-printable-encoded, the button rendering with its bare URL beneath it, and the text part
+  matching the deleted literal.
+- **The same seed rows, two deployments.** Run as *UOMysticmoon* with a gold accent and as *Vesper Isle*
+  with a blue one, changing only stored settings: the subjects and the button colour follow the
+  deployment, from identical rows. §5a's fourth acceptance criterion, proved rather than argued.
+- **A contact message carrying `<script>alert(1)</script> & <img src=x onerror=…>`**, sent for real:
+  escaped in the HTML part, raw in the text part, no live tag in the delivered message.
+- One accidental proof worth keeping: an early rig run had a `settings` table missing `updated_at`, and
+  `ambient()` degraded to the `BRAND_*` env values with a warning and sent the mail anyway. That path
+  is not otherwise easy to reach.
+
+**Still 5b's:** the editor, the admin Templates screen, the template CRUD routes, the save-time
+undeclared-variable refusal (`variablesFor` is in place and is what it will ask), the sandboxed preview
+and its CSP test, and the `runicgateway.com` admin docs page §6.0b assigns the pair.
+
 ---
 
 ### Phase 6 — The email channel on the engine, and the Teams migration