Merge pull request 'docs(website): the engagement release note — three things that arrive switched off' (#199) from docs/engagement-phase-13-upgrade-notes into edge

Reviewed-on: #199
Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>

website/UPGRADE_NOTES.md

@@ -13,6 +13,111 @@ action, whether it is required, and what happens if you do nothing.
 
 ---
 
+## Engagement: rules, an in-app inbox, and three things that arrive switched off
+
+**Required.** The engagement workstream, Phases 1–12. Three separate actions, and the two that matter
+most are the ones nothing will tell you about.
+
+### What changed
+
+The site now has a general notification engine. A **trigger** fires (a forum post, a house going
+IDOC, a governor being appointed), a **rule** decides who hears about it and through which
+**channel**, and a **template** decides what it says. All of it is admin-editable under
+**Admin → Engagement** — Rules, Audiences, Templates, Triggers, Send Log and Suppressions.
+
+Players get an in-app inbox at **Account → Notifications**, with per-channel switches at **Account →
+Notification settings**, and the same inbox in the Android app.
+
+### What you must do
+
+Three things, in this order. The first is a required upgrade step for anyone running a shard; the
+second and third are only required if you were relying on the behaviour they change.
+
+#### 1. Update the shard — the wire protocol is now 5
+
+**Required if this deployment has a shard connected.** Update in this order:
+
+1. the website (this image),
+2. the **UO module to 0.5.0** — **Admin → Modules**, paste the 0.5.0 release install-manifest
+   URL, then **restart the server**: modules are read from disk at boot, so nothing changes until
+   you do. It declares `coreApi ^1.9.0`, and a core older than that will refuse to *load* it (the
+   install itself still succeeds) — the module then shows as failed on that screen, naming the
+   version it needs. That is the check working, but it means step 1 has to be finished first;
+3. the **shard**, with `installer update` on the shard host. That is what pairs a protocol-5 sidecar
+   with a protocol-5 overlay; the installer refuses to pair a mismatched one by design.
+
+**The order matters, and step 2 is the one that starts the clock.** The protocol pin lives in the UO
+module's schema: on the first boot after the module updates, `uo_link_config.protocol` moves to 5 and
+the site starts sending `X-UOLink-Version: 5`. A shard still on 4 answers `409` from that moment on,
+so shard data stops. Nothing is lost and nothing is corrupted — the site degrades to showing the
+shard offline, exactly as it does when the sidecar is down — but it stays that way until the shard is
+updated. If you cannot update the shard in the same window, update the site and leave the module on
+its current version until you can.
+
+Protocol 5 adds a decay schedule and owner account to `house.decay`, fee and owner state to
+`vendor.listing`, and a new `account.login.result`. Those three fields are what the shard-driven
+rules are built on; a shard on 4 could not feed them.
+
+#### 2. Team notification email arrives switched off
+
+**Required if your Teams rely on email.** Team email used to send automatically. It now runs through
+the engagement engine like everything else, as four rules — and like every rule on the platform, they
+are seeded **disabled**. Nothing mails until an operator switches one on.
+
+Open **Admin → Engagement → Rules** and enable the Team rules you want. A banner on that screen says
+the same thing while they are all off, and disappears when one is enabled.
+
+**Only email moved.** The push tickle and the Discord bridge are unchanged and kept working through
+the upgrade, so the app and your Discord channel behave exactly as before. Per-member Team
+preferences and unsubscribe links still apply above the rules.
+
+#### 3. News push stops until you switch it on
+
+**Required if you publish news and expect it to notify.** Publishing a news post used to send a push
+tickle directly. That call is now an engagement trigger, seeded — again — as a **disabled** rule. A
+deployment that upgrades and does nothing else tickles nobody on the next publish.
+
+Same screen: **Admin → Engagement → Rules**, enable the news rule.
+
+This is deliberate rather than an oversight. The alternative was to keep the old direct tickle beside
+the new trigger for one release, and an exception with no owner is one nobody removes.
+
+### Behaviour changes that need no action
+
+- **An unsubscribe link now turns off one channel, not everything.** The old link muted a user
+  outright, which silenced push as well as mail. It now switches off exactly the channel the link was
+  in.
+- **Email and push are opt-in; the in-app inbox is on.** A user who changes nothing receives in-app
+  items and no mail. That matches the Team preference model already in use, and it is why enabling a
+  rule does not by itself produce a mail storm.
+- **A rule cannot mail more people than its trigger allows.** Every trigger declares an audience
+  ceiling, and a rule is checked against it — so a staff-only event cannot be given a public
+  audience, whatever the rule says.
+- **Bounces now suppress an address.** A hard bounce or a rejected recipient stops further mail to
+  that address and is listed under **Admin → Engagement → Suppressions**, which is also the only
+  screen that can lift one. An address that has stopped receiving mail is the first thing to check
+  there.
+
+### If you do nothing
+
+The site upgrades, the in-app inbox works, and no mail is sent — because every rule is off and email
+needs both a transport (see the SMTP entry below) and a user who opted in. What you lose silently is
+**Team email** and **news push**, both of which were sending before the upgrade and stop at it. If
+you also leave the UO module on its current version, the shard keeps working on protocol 4 and none
+of the shard-driven rules exist yet.
+
+### Data
+
+Nothing is dropped and no row is deleted. New tables cover rules, segments, templates, the outbox,
+the send log, cooldowns, suppressions, per-channel preferences and the in-app inbox.
+`team_notification_prefs` is kept and still consulted — per-Team granularity did not move.
+
+**Nothing in this schema expires on its own.** Finished outbox rows, the send log and the suppression
+list are kept until you remove them; there is no retention sweep. On a busy deployment those tables
+grow without limit, which is worth knowing before it is worth acting on.
+
+---
+
 ## Email addresses are now unique, and some accounts may lose theirs
 
 **Required only if the dashboard says so.** Engagement Phase 1b.