feat: harden gmail sync foundation

docs/gmail-correspondence-phase1.md

@@ -0,0 +1,55 @@
+# Smart Gmail Job Correspondence Integration
+
+## Phase split
+
+### Phase 1
+Deterministic, high-trust Gmail job correspondence integration:
+- OAuth/account connection
+- token refresh lifecycle
+- sync-state tracking
+- manual sync/backfill
+- dedup by Gmail message id
+- deterministic job-linking + confidence routing
+- review queue for medium-confidence items
+- unmatched thread suggestions
+- global inbox + per-job timeline
+
+### Phase 2
+Prepared, not deeply implemented in this slice:
+- semantic Gmail-to-job disambiguation
+- richer recruiter/company/role extraction
+- stage/status hinting
+- interview/rejection/offer extraction
+- follow-up/reply suggestion generation
+
+## Foundation decisions
+
+- Phase 1 remains useful without AI/Ollama.
+- Deterministic evidence remains the primary truth source.
+- Future AI enrichment attaches reasons/confidence alongside deterministic evidence rather than replacing it.
+- Gmail sync state is now durable on the Gmail connection record:
+  - `LastSyncAttemptedAt`
+  - `LastSyncSucceededAt`
+  - `LastSyncMode`
+  - `LastSyncSource`
+  - `LastSyncStatus`
+  - `LastSyncError`
+
+## Current code seams
+
+- Gmail OAuth and token lifecycle: `JobTrackerApi/Services/GmailOAuthService.cs`
+- Gmail endpoints: `JobTrackerApi/Controllers/GmailController.cs`
+- Gmail connection persistence: `Models/GmailConnection.cs`
+- Correspondence persistence: `Models/Correspondence.cs`
+- Per-job correspondence UX: `job-tracker-ui/src/components/Correspondence.tsx`
+- Future Phase 2 AI seam: `JobTrackerApi/Services/GmailCorrespondenceEnrichment.cs`
+
+## What Phase 2 should plug into later
+
+The `IGmailCorrespondenceEnrichmentService` seam is intended to accept normalized Gmail message/thread context and return optional semantic hints:
+- probable job match
+- richer confidence rationale
+- extracted recruiter/company/role entities
+- lightweight stage hints
+
+Phase 1 should never require this service to return anything useful. The default runtime implementation remains a no-op.