docs/email-sync.md

@@ -0,0 +1,49 @@
+## Core Rules
+
+1. **User.email is source of truth** - Always overrides member email when linking
+2. **DB constraints** - Prevent duplicates within same table (users.email, members.email)
+3. **Custom validations** - Prevent cross-table conflicts only for linked entities
+4. **Sync is bidirectional**: User ↔ Member (but User always wins on link)
+
+---
+
+## Decision Tree
+
+```
+Action: Create/Update/Link Entity with Email X
+│
+├─ Does Email X violate DB constraint (same table)?
+│  └─ YES → ❌ FAIL (two users or two members with same email)
+│
+├─ Is Entity currently linked? (or being linked?)
+│  │
+│  ├─ NO (unlinked entity)
+│  │  └─ ✅ SUCCESS (no custom validation)
+│  │
+│  └─ YES (linked or linking)
+│     │
+│     ├─ Action: Update Linked User Email
+│     │  ├─ Email used by other member? → ❌ FAIL (validation)
+│     │  └─ Email unique? → ✅ SUCCESS + sync to member
+│     │
+│     ├─ Action: Update Linked Member Email  
+│     │  ├─ Email used by other user? → ❌ FAIL (validation)
+│     │  └─ Email unique? → ✅ SUCCESS + sync to user
+│     │
+│     ├─ Action: Link User to Member (both directions)
+│     │  ├─ User email used by other member? → ❌ FAIL (validation)
+│     │  └─ Otherwise → ✅ SUCCESS + override member email
+
+```
+
+## Sync Triggers
+
+| Action | Sync Direction | When |
+|--------|---------------|------|
+| Update linked user email | User → Member | Email changed |
+| Update linked member email | Member → User | Email changed |
+| Link user to member | User → Member | Always (override) |
+| Link member to user | User → Member | Always (override) |
+| Unlink | None | Emails stay as-is |
+
+