docs: sessions, accounts, trusted senders, conversations, themes and the new reader

README: what the webmail now does, the architecture roles, a short guide with the
shortcuts, testing with a real database, and an honest list of what is not
finished. New docs/WEBMAIL.md as the reference for each feature and for the
colour system. OPERATIONS: sessions and trusted senders. DEPLOYMENT: the
two-step release as API calls, and what to expect when upgrading. MAILBOX-CORE:
the conversation invariants and migrations 0015 to 0018.

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

docs/DEPLOYMENT.md

@@ -218,6 +218,19 @@ IMAGE_TAG=sha-$(git rev-parse HEAD)
 # 2. then deploy
 ```
 
+On Coolify the two steps are two API calls, and the order matters: set the
+variable, then deploy, and only after the **Release workflow has finished green**
+(a deploy while it is still running pulls the previous images):
+
+```bash
+# 1. point the tag at the commit that was released
+curl -X PATCH "$COOLIFY_URL/api/v1/applications/$APP_UUID/envs" \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d "{\"key\":\"IMAGE_TAG\",\"value\":\"sha-$(git rev-parse HEAD)\"}"
+# 2. then deploy (a POST; a GET answers 405)
+curl -X POST "$COOLIFY_URL/api/v1/deploy?uuid=$APP_UUID" -H "Authorization: Bearer $TOKEN"
+```
+
 Confirm which one is actually serving before believing a green deployment:
 
 ```bash
@@ -225,7 +238,42 @@ curl -s https://<WEBMAIL_HOST>/user/login | grep -o '/_next/static/css/[a-z0-9]*
 ```
 
 The asset fingerprint changes with every build. If it did not move, the old
-image is still running whatever the deployment log said.
+image is still running whatever the deployment log said. A route that exists
+only in the new version is a surer check: an unauthenticated request to
+`/api/v1/mail/threads` answers `401` on a version that has conversations and
+`404` on one that does not.
+
+### Upgrading to sessions, accounts, trusted senders and conversations
+
+Three migrations run on the first start (the `migrate` service runs them before
+anything that needs them):
+
+| | Adds |
+| :--- | :--- |
+| `0016` | `trusted_senders` |
+| `0017` | The SQL subject helpers and a one-time grouping of older mail into conversations, by subject and only where a reply exists; an index for the conversation list |
+| `0018` | `mailboxes.conversation_view` (on by default) |
+
+They are additive and idempotent in effect; on a large mailbox `0017`'s grouping
+reads the whole `email_messages` table once. Nothing needs configuring.
+
+What people will notice the first time:
+
+- Sessions opened before the upgrade keep their old 8-hour expiry and are
+  replaced by 30-day ones at the next sign-in. A session that began before
+  accounts existed is added to the account switcher automatically.
+- Trusted-sender choices a person made in a browser are moved to the server the
+  first time the webmail loads there.
+- Right after a deploy, while the proxy is swapping containers, one page load
+  can meet a script from the other version. This was seen once, as a React
+  hydration error in the browser console on the sign-in page, and did not come
+  back on the next loads. If a page misbehaves in the first minute, reload it.
+
+Nothing about the upgrade needs new environment variables or ports. The webmail
+now serves `/manifest.webmanifest`, `/icon.svg`, `/favicon.ico` and
+`/icons/*`; they are public, like the sign-in page, and need no proxy rule
+beyond the one already sending the host to the web service. Installing the
+webmail as an app needs HTTPS, which the deployment already has.
 
 ## Troubleshooting