docs(admin): email is SMTP now, and the Gmail connect flow is gone #21

wtclaude · 2026-08-29T02:03:03Z

wtclaude commented

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

What & why

Engagement Phase 1's share of this repo — §6.0b row 1's "Other repos" column. Companion to website#165 and docs#178; land together.

Four pages described a delivery path that no longer exists. One of them under the heading "There is no SMTP option", which is now the exact opposite of true.

`administration/notifications-and-email.mdx`

The Email section is rewritten around the three postures the org lead settled (§7.1 Q5), leading with a relay:


A relay — recommended	Mailgun / SES / Postmark. Deliverability is the hard part of sending mail and this is the option where somebody else owns it
A mailbox provider over SMTP — simplest	`smtp.gmail.com:587` with an app password. Named explicitly as the migration off the removed OAuth2 flow
Your own MTA	Port 25, no credentials

Two cautions carry the failures that produce no error at all, which is why they need a page rather than a tooltip: Implicit TLS left on for port 587 hangs rather than failing, and a Send from address the relay will not accept is an SPF/DMARC rejection that looks like nothing from the outside. Send test is what proves both, and it names them.

An upgrade aside covers the deployment this actually happens to — mail stops, nothing errors, the dashboard warns — and says plainly that SSO is unaffected, since email merely borrowed the Google client. Removing the borrow removes a trap: rotating the SSO secret used to break outbound mail silently.

The other three

troubleshooting.mdx — "Connect Gmail" is replaced, and the section gains the two silent failures above plus the enabled toggle, which now gates every message rather than some of them.
configuration.mdx — loses the "configure Google on the Authentication page first" ordering constraint, which went with the borrowed client. Email now depends on nothing else on the site.
architecture/system-architecture.mdx — the encrypted-at-rest list said "the Gmail refresh token"; it is now the mail transport's credentials, which are write-only in the API like the sidecar token.

Deliberately not touched

src/data/platform.json and src/data/capabilities.mjs belong to Phase 12. The capabilities line still claims a web notification channel that does not exist until Phase 7, and correcting it now would be a claim about a phase that has not shipped.

This lands on edge, so none of it is published while main still carries the Gmail flow. checkFacts fetches each fact's authority from the source repo's main, so it stays green through the whole edge period — as designed.

How it was tested

npm run build — clean, 50 pages.
npm run check (Astro type check) — 0 errors, 0 warnings.
npm run check:links — 2409 internal links resolve, 124 repository links point at a branch.
GITEA_TOKEN=… npm run check:facts — 19 facts agree with their authorities.
check:tokens, check:brand, check:datasafety, check:quickstart, check:reference, check:sidebar, check:screens, check:a11y, check:csp — all clean.
npm test — 42 passing.

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 share of this repo — §6.0b row 1's "Other repos" column. Companion to **website#165** and **docs#178**; land together. Four pages described a delivery path that no longer exists. One of them under the heading **"There is no SMTP option"**, which is now the exact opposite of true. ### `administration/notifications-and-email.mdx` The Email section is rewritten around the three postures the org lead settled (§7.1 Q5), leading with a relay: | | | | --- | --- | | **A relay** — recommended | Mailgun / SES / Postmark. Deliverability is the hard part of sending mail and this is the option where somebody else owns it | | **A mailbox provider over SMTP** — simplest | `smtp.gmail.com:587` with an **app password**. Named explicitly as the migration off the removed OAuth2 flow | | **Your own MTA** | Port 25, no credentials | Two cautions carry the failures that produce **no error at all**, which is why they need a page rather than a tooltip: *Implicit TLS* left on for port 587 hangs rather than failing, and a **Send from** address the relay will not accept is an SPF/DMARC rejection that looks like nothing from the outside. Send test is what proves both, and it names them. An upgrade aside covers the deployment this actually happens to — mail stops, nothing errors, the dashboard warns — and says plainly that **SSO is unaffected**, since email merely borrowed the Google client. Removing the borrow removes a trap: rotating the SSO secret used to break outbound mail silently. ### The other three - **`troubleshooting.mdx`** — "Connect Gmail" is replaced, and the section gains the two silent failures above plus the `enabled` toggle, which now gates *every* message rather than some of them. - **`configuration.mdx`** — loses the "configure Google on the Authentication page first" ordering constraint, which went with the borrowed client. Email now depends on nothing else on the site. - **`architecture/system-architecture.mdx`** — the encrypted-at-rest list said "the Gmail refresh token"; it is now the mail transport's credentials, which are **write-only** in the API like the sidecar token. ### Deliberately not touched `src/data/platform.json` and `src/data/capabilities.mjs` belong to **Phase 12**. The capabilities line still claims a web notification channel that does not exist until Phase 7, and correcting it now would be a claim about a phase that has not shipped. This lands on `edge`, so none of it is published while `main` still carries the Gmail flow. `checkFacts` fetches each fact's authority from the source repo's `main`, so it stays green through the whole edge period — as designed. ## How it was tested - `npm run build` — clean, 50 pages. - `npm run check` (Astro type check) — 0 errors, 0 warnings. - `npm run check:links` — 2409 internal links resolve, 124 repository links point at a branch. - `GITEA_TOKEN=… npm run check:facts` — 19 facts agree with their authorities. - `check:tokens`, `check:brand`, `check:datasafety`, `check:quickstart`, `check:reference`, `check:sidebar`, `check:screens`, `check:a11y`, `check:csp` — all clean. - `npm test` — 42 passing. ## 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:03:04 +00:00

docs(admin): email is SMTP now, and the Gmail connect flow is gone 2da014790e

Engagement Phase 1's share of this repo (docs/website/ENGAGEMENT.md
§6.0b). Four pages described a delivery path that no longer exists — one
of them under the heading "There is no SMTP option", which is now the
opposite of true.

notifications-and-email.mdx: the Email section is rewritten around the
three postures the org lead settled on (§7.1 Q5), leading with a relay
and naming smtp.gmail.com:587 with an app password as the migration off
OAuth2. Two cautions carry the failures that produce no error at all —
Implicit TLS left on for port 587, which hangs, and an operator-typed
sender the relay will not accept, which is an SPF/DMARC rejection that
looks like nothing. Send test is what proves both.

troubleshooting.mdx gains those two, plus the enabled toggle, which now
gates every message rather than some of them.

configuration.mdx loses the "set up Google first" ordering constraint,
which is gone with the borrowed client. system-architecture.mdx's
encrypted-at-rest list is corrected: the Gmail refresh token is replaced
by the transport credentials, which are write-only like the sidecar
token.

This lands on `edge`, so nothing here is published while `main` still
carries the Gmail flow. platform.json and capabilities.mjs are untouched
— they belong to Phase 12.

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

whitlocktech merged commit 5ba91717c0 into edge

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

whitlocktech deleted branch docs/engagement-phase-1-smtp

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

whitlocktech referenced this issue from a commit

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

Merge pull request 'docs(admin): email is SMTP now, and the Gmail connect flow is gone' (#21) from docs/engagement-phase-1-smtp into edge

wtclaude referenced this pull request

2026-09-01 18:00:42 +00:00

docs(site): the engagement system — cutover 7 of 7 (`edge` → `main`) #28

Sign in to join this conversation.