How to read the docs

The documentation catalog is the left nav. Start with this page, then the canonical data model and repository structure.

Working rule

MailMessage is the logical message. MessageInstance is the provider/account occurrence. Cardinality is 1:N.

PostgreSQL hosting, required environment variables, and the migration runner are in persistence and environments and ADR 0002. Application sessions (signed HTTP-only cookie, no external IdP) are in application authentication and ADR 0005. Provider token ciphertext and key separation are in token encryption and ADR 0004.

Jira project MAIL is the implementation plan. Architecture decisions that change hosting or queue technology belong in docs/decisions/. Untrusted HTML, SSRF holds, and the policy gateway are in security and policy and ADR 0019. MVP release readiness, the 04_MVP §11 evidence matrix, and the operator deploy runbook are in MVP release checklist, deploy and operate, and ADR 0029.

AI classification and extraction are gated by the golden-set harness and ADR 0020. The runner uses fixtures only and must not call mail provider adapters. Suggested drafts (MAIL-170) are local copy-out recommendations; see suggested drafts and ADR 0021. Human overrides become the current Classification; identity hygiene accept stays in-app — human corrections, identity hygiene, and ADR 0024. User-requested mailbox writes go through safe provider write-back and ADR 0025. Follow-on adapters and gated inventory are in follow-on providers, gated inventory, and ADR 0027. Application sessions can be issued from Sign in with Apple (ADR 0028). Operational health probes and the /ops admin view are in operational health and ADR 0026. Application-owned backup, recovery mode, and the restore runbook are in backup and restore. Sprint 07 Stream B records replay, privacy, restore, AI golden-set, and p95 evidence in NFR release gates.