docs(website): §7 rewritten for SMTP, plus an upgrade-notes home #178

wtclaude · 2026-08-29T02:02:38Z

wtclaude commented

2026-08-29 02:02:38 +00:00

What & why

Engagement Phase 1's documentation — §6.0b row 1's docs/ column. Companion to website#165 (and runicgateway.com#21); land together.

`website/BACKEND_DESIGN.md` §7 — rewritten, not amended

The plan is explicit that this section has to be replaced: it documented Gmail OAuth2 as the mechanism, so amending it would leave the shape of the old design behind. §7 now covers the transport registry and why credentialFields is one declaration three consumers read; the credential blob and its fail-safe decrypt; the no-phone-home rule and its CI guardrail; the three SMTP postures as a table (relay first, per §7.1 Q5); why Send test is the only verification left now that the sender is operator-typed; the five failure contracts in one place; and the silent upgrade.

Corrected alongside it: the §2 tree (email.router.js is 4 routes, and mailer.js is no longer "if SMTP unset"), the PR-4 route-count note, the /contact row, and the /dashboard row — which now returns warnings[].

`website/UPGRADE_NOTES.md` — new, and not just for this phase

Phases 1b, 6, 10 and 13 each owe an operator release note too, and website/ has no CHANGELOG and cuts no Gitea releases, so there was nowhere for one to go. This is that home: newest first, one entry per upgrade that needs an operator to act.

Scoped deliberately. Most upgrades need nothing — the schema replays on every boot — so an entry is not a changelog line. The entries worth writing are the ones that fail quietly, which is precisely what the Gmail removal does: mail stops, nothing errors, and the only signal is a dashboard warning. The first entry says what changed, the exact settings for each of the three postures, the two fields that cause most failures, what happens if you do nothing, and what happens to the stored token.

Linked from the repo README's website/ index.

`website/ENGAGEMENT.md` — Phase 1 marked built, with what differed

An "as built" block under Phase 1, recording four things that are not what the plan above it says:

Only the transport half of §3.1 was built. registerDeliveryChannel has no consumer until Phase 4, and a registered channel nothing calls is a shape frozen before anything tried to use it.
enabled now gates every sender, which it did not before — the direct senders bypassed the toggle entirely. A deliberate behaviour change, and the only one in the phase.
The G22 warning reads the deprecated column on purpose. refresh_token_enc stays unread as configuration, but its presence is exactly "this deployment had working mail before the upgrade".
npm run swagger had to be fixed first (website#164). The "per-file route limit" that phases 8 and 9 recorded does not exist — the real rule is that nothing reaching .test( may sit inside a route statement. That matters to every later phase in this workstream, all of which add routes, which is why it is written down here and not only in the fix.

The status line at the top now says Phase 1 is built and everything from 1b on is still design.

How it was tested

Markdown only. Every relative link in the new and changed files resolves; the UPGRADE_NOTES.md row was added to the README index and the reciprocal link from §7 checked by hand.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Engagement **Phase 1**'s documentation — §6.0b row 1's `docs/` column. Companion to **website#165** (and **runicgateway.com#21**); land together. ### `website/BACKEND_DESIGN.md` §7 — rewritten, not amended The plan is explicit that this section has to be replaced: it documented Gmail OAuth2 *as* the mechanism, so amending it would leave the shape of the old design behind. §7 now covers the transport registry and why `credentialFields` is one declaration three consumers read; the credential blob and its fail-safe decrypt; the no-phone-home rule and its CI guardrail; **the three SMTP postures** as a table (relay first, per §7.1 Q5); why Send test is the only verification left now that the sender is operator-typed; the five failure contracts in one place; and the silent upgrade. Corrected alongside it: the §2 tree (`email.router.js` is 4 routes, and `mailer.js` is no longer "if SMTP unset"), the PR-4 route-count note, the `/contact` row, and the **`/dashboard` row — which now returns `warnings[]`**. ### `website/UPGRADE_NOTES.md` — new, and not just for this phase Phases 1b, 6, 10 and 13 each owe an operator release note too, and `website/` has no CHANGELOG and cuts no Gitea releases, so there was nowhere for one to go. This is that home: newest first, one entry per upgrade that needs an operator to *act*. Scoped deliberately. Most upgrades need nothing — the schema replays on every boot — so an entry is not a changelog line. **The entries worth writing are the ones that fail quietly**, which is precisely what the Gmail removal does: mail stops, nothing errors, and the only signal is a dashboard warning. The first entry says what changed, the exact settings for each of the three postures, the two fields that cause most failures, what happens if you do nothing, and what happens to the stored token. Linked from the repo README's `website/` index. ### `website/ENGAGEMENT.md` — Phase 1 marked built, with what differed An "as built" block under Phase 1, recording four things that are **not** what the plan above it says: 1. **Only the transport half of §3.1 was built.** `registerDeliveryChannel` has no consumer until Phase 4, and a registered channel nothing calls is a shape frozen before anything tried to use it. 2. **`enabled` now gates every sender**, which it did not before — the direct senders bypassed the toggle entirely. A deliberate behaviour change, and the only one in the phase. 3. **The G22 warning reads the deprecated column on purpose.** `refresh_token_enc` stays unread as *configuration*, but its presence is exactly "this deployment had working mail before the upgrade". 4. **`npm run swagger` had to be fixed first** (website#164). The **"per-file route limit" that phases 8 and 9 recorded does not exist** — the real rule is that nothing reaching `.test(` may sit inside a route statement. That matters to every later phase in this workstream, all of which add routes, which is why it is written down here and not only in the fix. The status line at the top now says Phase 1 is built and everything from 1b on is still design. ## How it was tested Markdown only. Every relative link in the new and changed files resolves; the `UPGRADE_NOTES.md` row was added to the README index and the reciprocal link from §7 checked by hand. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-29 02:02:41 +00:00

docs(website): §7 rewritten for SMTP, plus an upgrade-notes home 6f6b54a509

Engagement Phase 1's documentation (ENGAGEMENT.md §6.0b, row 1).

BACKEND_DESIGN.md §7 is REWRITTEN rather than amended, as the plan
requires: it documented Gmail OAuth2 as the mechanism. It now covers the
transport registry and why credentialFields is a single declaration
three consumers read, the credential blob and its fail-safe decrypt, the
no-phone-home rule and its CI guardrail, the three SMTP postures, why
Send test is the only verification left, the five failure contracts, and
the silent upgrade. The §2 tree, the PR-4 route-count note, the contact
row and the dashboard row are corrected alongside it — the dashboard now
returns warnings[].

UPGRADE_NOTES.md is new, and is the home for every later phase's
operator note as well (1b, 6, 10 and 13 each owe one). Newest first, and
scoped deliberately: an upgrade that needs nothing does not get an entry.
The entries worth writing are the ones that fail QUIETLY, which is
exactly what the Gmail removal does — mail stops, nothing errors, and
the only signal is a dashboard warning.

ENGAGEMENT.md records Phase 1 as built, with the four things that are
not what the plan says: only the transport half of §3.1 was built (a
channel nothing calls is a shape frozen too early), `enabled` now gates
every sender where it used to gate none of the direct ones, the G22
warning reads the deprecated column on purpose, and `npm run swagger`
had to be fixed first — the "per-file route limit" phases 8 and 9
recorded does not exist, and the real rule matters to every later phase
here, all of which add routes.

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

whitlocktech merged commit cde362e588 into edge

2026-08-29 02:10:03 +00:00

whitlocktech deleted branch docs/engagement-phase-1

2026-08-29 02:10:04 +00:00

whitlocktech referenced this issue from a commit

2026-08-29 02:10:05 +00:00

Merge pull request 'docs(website): §7 rewritten for SMTP, plus an upgrade-notes home' (#178) from docs/engagement-phase-1 into edge

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#178