From 6e1c9ca9246b58561e16bf0d15159f7641c262ba Mon Sep 17 00:00:00 2001
From: Lucas Berger <me@lucasberger.ca>
Date: Fri, 19 Jun 2026 09:27:35 -0400
Subject: [PATCH] docs: complete v1.2 research (stack, features, architecture,
 pitfalls)

- STACK.md: google-auth-library@10.7.0 + @googleapis/calendar@15.0.0 scoped packages (vs monolithic googleapis), OAuth2 flow, token storage, Google Calendar API event/reminder model
- FEATURES.md: 6 feature categories (multi-provider, self-service onboarding, multiple reminders, dark mode, zero-setup DB, dev/CI stub), dependency graph, feature prioritization
- ARCHITECTURE.md: CalendarProvider interface, provider factory, CalDavProvider wrapper, GoogleCalendarProvider, MockProvider, provider_tokens table schema, multi-reminder JSON column, OAuth callback routing, 7-component data flows
- PITFALLS.md: 11 critical/medium pitfalls (refresh token 7-day expiry in testing status, Google recurrence mismatch, syncToken 410, timezone handling, provider abstraction regression, VALARM dedup key, auto-migrate failures, dark mode FOWT, OAuth callback through tunnel, token encryption, ESLint 10 breaking changes)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .planning/research/ARCHITECTURE.md | 961 ++++++++++++++---------------
 .planning/research/FEATURES.md     | 557 +++++++++--------
 .planning/research/PITFALLS.md     | 611 +++++++++---------
 .planning/research/STACK.md        | 372 ++++++++++-
 4 files changed, 1446 insertions(+), 1055 deletions(-)

diff --git a/.planning/research/ARCHITECTURE.md b/.planning/research/ARCHITECTURE.md
index bf75fcb..db1554d 100644
--- a/.planning/research/ARCHITECTURE.md
+++ b/.planning/research/ARCHITECTURE.md
@@ -1,598 +1,591 @@
 # Architecture Research
 
-**Domain:** FamilySync v1.1 — integration analysis for Operability & Polish milestone
-**Researched:** 2026-06-10
-**Confidence:** HIGH (grounded in actual codebase)
-
-## Standard Architecture
-
-### System Overview
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  React PWA (apps/pwa/src/)                                        │
-│  ┌──────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
-│  │ EventForm.tsx│ │SettingsSheet │ │ [NEW] SetupWizard /        │ │
-│  │ + reminder   │ │ + Admin tab  │ │        AdminSettings       │ │
-│  │   selector   │ │              │ │                            │ │
-│  └──────┬───────┘ └──────┬───────┘ └────────────┬──────────────┘ │
-│         │    api/client.ts (typed fetch wrappers) │               │
-└─────────┼──────────────────────────────────────┬─┴───────────────┘
-          │                                       │
-          ▼  HTTP / SSE                           ▼ HTTP
-┌──────────────────────────────────────────────────────────────────┐
-│  Hono API (apps/api/src/index.ts)                                 │
-│  ┌──────────────┐ ┌────────────┐ ┌──────────────────────────────┐│
-│  │ routes/      │ │ routes/    │ │ [NEW] routes/admin.ts +       ││
-│  │ events.ts    │ │ push.ts    │ │        routes/setup.ts        ││
-│  │ (enqueue to  │ │            │ │ (role-gated credential mgmt,  ││
-│  │  outbox)     │ │            │ │  first-run wizard endpoints)  ││
-│  └──────┬───────┘ └────────────┘ └──────────────────────────────┘│
-│         │                                                         │
-│  ┌──────▼──────────────────────────────────────────────────────┐ │
-│  │ broker/                                                      │ │
-│  │  outboxWorker.ts (15s setInterval + NEW event-driven drain)  │ │
-│  │  reminderScheduler.ts (1-min setInterval, MODIFIED: per-     │ │
-│  │    event VALARM lead, variable window)                       │ │
-│  │  poller.ts (5-min setInterval, UNCHANGED)                    │ │
-│  │  vevent.ts [MODIFIED: buildVeventString adds VALARM]         │ │
-│  │  sync.ts [MODIFIED: extract VALARM -> reminder_lead_minutes] │ │
-│  │  crypto.ts (AES-256-GCM, REUSED by admin credential writes)  │ │
-│  └──────┬──────────────────────────────────────────────────────┘ │
-└─────────┼────────────────────────────────────────────────────────┘
-          │
-          ▼
-┌──────────────────────────────────────────────────────────────────┐
-│  Data layer (apps/api/src/db/)                                    │
-│  schema.ts: users (+is_admin), calendars, calendarEvents          │
-│             (+reminder_lead_minutes), calendarOutbox,             │
-│             memberCredentials, pushSubscriptions, lists, ...      │
-│  [NEW] app_config table (setup_complete flag, etc.)               │
-│                                                                   │
-│  MariaDB (mariadb:11) + Redis (7-alpine, ioredis for pub/sub)    │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### Component Responsibilities
-
-| Component            | File                                        | Responsibility                           | v1.1 Status                                         |
-| -------------------- | ------------------------------------------- | ---------------------------------------- | --------------------------------------------------- |
-| Event form           | `apps/pwa/src/components/EventForm.tsx`     | Create/edit event UI                     | MODIFY: add reminder selector                       |
-| Settings sheet       | `apps/pwa/src/components/SettingsSheet.tsx` | Notifications toggle                     | MODIFY: add Admin section                           |
-| API client           | `apps/pwa/src/api/client.ts`                | Typed fetch wrappers                     | MODIFY: admin + setup endpoints                     |
-| Events route         | `apps/api/src/routes/events.ts`             | Calendar CRUD, outbox enqueue            | MODIFY: pass reminder in payload, signal drain      |
-| Push route           | `apps/api/src/routes/push.ts`               | VAPID subscription management            | UNCHANGED                                           |
-| VEVENT builder       | `apps/api/src/broker/vevent.ts`             | iCalendar string construction            | MODIFY: add VALARM                                  |
-| CalDAV sync          | `apps/api/src/broker/sync.ts`               | Fastmail REPORT -> DB upsert             | MODIFY: extract VALARM trigger                      |
-| Outbox worker        | `apps/api/src/broker/outboxWorker.ts`       | CalDAV write-back drain                  | MODIFY: event-driven trigger subscription           |
-| Reminder scheduler   | `apps/api/src/broker/reminderScheduler.ts`  | Push reminders for events                | MODIFY: variable VALARM-based lead                  |
-| Poller               | `apps/api/src/broker/poller.ts`             | 5-min CalDAV sync                        | UNCHANGED                                           |
-| Crypto               | `apps/api/src/broker/crypto.ts`             | AES-256-GCM encrypt/decrypt              | UNCHANGED (reused by admin)                         |
-| DB schema            | `apps/api/src/db/schema.ts`                 | Drizzle table definitions                | MODIFY: is_admin, reminder_lead_minutes, app_config |
-| Index / wiring       | `apps/api/src/index.ts`                     | App bootstrap + worker startup           | MODIFY: mount admin + setup routes                  |
-| [NEW] Admin route    | `apps/api/src/routes/admin.ts`              | Role-gated credential + calendar mgmt    | NEW                                                 |
-| [NEW] Setup route    | `apps/api/src/routes/setup.ts`              | First-run wizard endpoints + validation  | NEW                                                 |
-| [NEW] Admin UI       | `apps/pwa/src/components/AdminSettings.tsx` | Member credential UI, shared-cal picker  | NEW                                                 |
-| [NEW] Setup wizard   | `apps/pwa/src/components/SetupWizard.tsx`   | First-run guided bootstrap               | NEW                                                 |
-| [NEW] Outbox trigger | `apps/api/src/lib/outboxTrigger.ts`         | In-process EventEmitter for drain signal | NEW                                                 |
-| [NEW] CI workflow    | `.gitea/workflows/ci.yml`                   | Lint/typecheck/test on PR                | NEW                                                 |
+**Domain:** v1.2 Integration Architecture — Multi-Provider, Theming & Zero-Setup
+**Researched:** 2026-06-19
+**Confidence:** HIGH (based on direct codebase inspection)
 
 ---
 
-## Feature Integration Analysis
+## Context: What This Document Covers
 
-### (a) Per-Event Reminders: VALARM Authoring + Variable-Lead Scheduling
+This file is scoped to how the v1.2 features integrate with the existing v1.1 codebase. It does not re-describe the existing architecture (see `docs/ARCHITECTURE.md`). Every component listed here is either NEW or MODIFIED; existing components that are untouched are mentioned only as integration anchor points.
 
-#### Write path — what changes
+---
 
-**`apps/pwa/src/components/EventForm.tsx`** — MODIFY
+## Feature Integration Map
 
-Add a "Reminder" `<select>` field. Values: `none | 5 | 10 | 15 | 30 | 60` (minutes before). Default `none`. Show in both create and edit modes. On submit, `executeSubmit()` includes `reminderMinutes?: number` in `CreateEventPayload`.
+### 1. Provider Abstraction
 
-The existing WR-01 "omit recurrence on edit" pattern does NOT apply here — reminder lead is user-configured per save and should always be sent explicitly. Include `reminderMinutes: 0` to mean "remove VALARM".
+**Goal:** Refactor the existing Fastmail/CalDAV broker behind a `CalendarProvider` interface so Google Calendar (and future providers) plug in without touching the poller, outbox worker, or reminder scheduler.
 
-The reminder selector should be disabled or hidden when `allDay = true` (RFC 5545: duration-form TRIGGER is semantically invalid for all-day events; see Anti-Pattern 4 below).
+#### New Component: `broker/provider.ts` (NEW)
 
-**`apps/pwa/src/api/client.ts`** — MODIFY
-
-Extend `CreateEventPayload` type:
+This is the central seam. Define a TypeScript interface that both the CalDAV broker and the Google provider implement:
 
 ```typescript
-reminderMinutes?: number  // 0 = no alarm; positive = minutes before
-```
+export interface CalendarProvider {
+  /** Discover and return all calendars this credential can access */
+  listCalendars(): Promise<ProviderCalendar[]>;
 
-**`apps/api/src/routes/events.ts`** — MODIFY
+  /** Sync events for one calendar into the DB (upsert). Returns detected changes. */
+  syncCalendar(
+    calendar: ProviderCalendar,
+    onChanges?: (changes: CalendarChange[]) => void
+  ): Promise<void>;
 
-Extend `eventFieldsSchema` (line 100) and `outboxPayloadSchema` (line 71 in `outboxWorker.ts`):
+  /** Write back one pending outbox row. Returns HTTP-like status (200=success, 412=conflict, etc.) */
+  dispatchOutboxRow(row: OutboxRow): Promise<DispatchResult>;
 
-```typescript
-reminderMinutes: z.number().int().min(0).max(10080).optional(); // max = 1 week
-```
+  /** Serialize N reminder leads into the provider's native format (VALARMs or Google overrides) */
+  serializeReminders(leads: number[], allDay: boolean): unknown;
 
-The payload is JSON-stringified into `calendar_outbox.payload` (TEXT column). No outbox schema change needed.
+  /** Parse the provider's reminder representation back into lead-minutes array */
+  parseReminders(nativePayload: unknown): number[];
+}
 
-**`apps/api/src/broker/vevent.ts`** — MODIFY
-
-Add `reminderMinutes?: number` to `NewEventParams` interface (line 21). In `buildVeventString`, after the RRULE block, add:
-
-```typescript
-if (!params.allDay && params.reminderMinutes !== undefined && params.reminderMinutes > 0) {
-  const valarm = new ICAL.Component('valarm');
-  valarm.addPropertyWithValue('action', 'DISPLAY');
-  valarm.addPropertyWithValue('description', params.summary);
-  const trigger = ICAL.Duration.fromSeconds(-(params.reminderMinutes * 60));
-  const triggerProp = new ICAL.Property('trigger');
-  triggerProp.setValue(trigger);
-  valarm.addProperty(triggerProp);
-  vevent.addSubcomponent(valarm);
+export interface ProviderCalendar {
+  url: string;          // CalDAV URL or Google calendarId -- the DB key
+  displayName: string | null;
+  color: string | null;
+  changeKey: string | null; // ctag (CalDAV) or syncToken (Google)
 }
 ```
 
-`ICAL.Duration.fromSeconds` is the correct ical.js API — same pattern as how `ICAL.Recur.fromString` is used for RRULE on line 144. Negative duration = before the event.
+**Key constraint:** The `dispatchOutboxRow` method signature must absorb all the logic currently split across `outboxWorker.ts` `dispatchRow()` + `write.ts`. The outbox worker becomes provider-agnostic: it calls `provider.dispatchOutboxRow(row)` and handles the result status uniformly.
 
-**`apps/api/src/broker/outboxWorker.ts`** — MODIFY
+#### Where Provider Selection Lives
 
-In both the `create` branch and `update` branch, pass `reminderMinutes: fields.reminderMinutes` to `buildVeventString`. One-line addition per branch. Also add `reminderMinutes` to `outboxPayloadSchema` for IN-03 re-validation.
+Provider selection is **per-member-credential**, not per-calendar. The existing `member_credentials.provider_type` column (`'caldav'` default) is already the discriminator. The poller and outbox worker load all `member_credentials` rows, read `provider_type`, and instantiate the right provider implementation.
 
-#### Scheduler path — what changes
-
-**`apps/api/src/db/schema.ts`** — MODIFY
-
-Add to `calendarEvents`:
+A factory function in `broker/providerFactory.ts` (NEW) maps `provider_type` to a `CalendarProvider`:
 
 ```typescript
-reminderLeadMinutes: int('reminder_lead_minutes'),
-// nullable: NULL = no VALARM; positive int = minutes before dtstart
-```
-
-Add `drizzle-kit generate` migration. This is a nullable column addition — safe online DDL on MariaDB 11/InnoDB.
-
-**`apps/api/src/broker/sync.ts`** — MODIFY
-
-When upserting a `calendarEvent`, extract VALARM from the parsed VEVENT:
-
-```typescript
-const valarm = vevent.getFirstSubcomponent('valarm');
-let reminderLeadMinutes: number | null = null;
-if (valarm) {
-  const trigger = valarm.getFirstPropertyValue('trigger');
-  if (trigger instanceof ICAL.Duration) {
-    reminderLeadMinutes = Math.abs(trigger.toSeconds()) / 60;
+export function createProvider(cred: MemberCredential): CalendarProvider {
+  switch (cred.providerType) {
+    case 'caldav': return new CalDavProvider(cred);
+    case 'google': return new GoogleCalendarProvider(cred);
+    case 'mock':   return new MockCalendarProvider(); // dev-bypass / tests
+    default: throw new Error(`Unknown provider type: ${cred.providerType}`);
   }
 }
 ```
 
-Store `reminderLeadMinutes` in the DB upsert. This is the ground truth — the scheduler reads from DB, not from the outbox payload.
+#### Modified: `broker/poller.ts`
 
-**`apps/api/src/broker/reminderScheduler.ts`** — MODIFY (significant rewrite of `runReminderCheck`)
+Currently calls `createFastmailClient` + `syncCalendar` directly. Must change to:
+1. Load each `memberCredentials` row with its `provider_type`.
+2. Call `createProvider(cred)` to get a `CalendarProvider`.
+3. Call `provider.listCalendars()` and compare `changeKey` (was `ctag`).
+4. On change, call `provider.syncCalendar(calendar, onChanges)`.
 
-Current behavior:
+The existing ctag/syncToken logic in `runPoll` moves into each provider's `listCalendars()` implementation. The poller loop structure stays identical.
 
-- Fixed 16-minute catch-up window: `dtstartUtc IN (now, now+16min]`
-- Fires only for `calendars.isShared = true` (D-05 constraint)
-- Dedup key: bare `uid` in `sentReminders: Map<string, number>`
+**Risk mitigation for Fastmail path:** Wrap the new `CalDavProvider` around the existing `client.ts` + `sync.ts` + `write.ts` logic verbatim -- do not refactor the internals of those files in the same phase. The provider interface is a thin delegation layer. Existing tests for `runPoll` can be updated to mock `createProvider` instead of `createFastmailClient`.
 
-New behavior:
+#### Modified: `broker/outboxWorker.ts`
 
-- Variable lead: query events where the alarm-fire-time falls in the current tick's window
-- Alarm-fire-time = `dtstartUtc - INTERVAL reminder_lead_minutes MINUTE`
-- Window: `(now - 1min, now + 1min]` gives a 2-minute catch-up on missed ticks (scheduler runs every 60s)
-- Events with `reminder_lead_minutes IS NULL` are excluded — no VALARM means no reminder
+`loadClientForUser` becomes `loadProviderForUser` (renamed, same shape). `dispatchRow` delegates to `provider.dispatchOutboxRow(row)` for the actual CalDAV/Google write. The retry/backoff/dead-letter state machine and the `isDraining` concurrency guard stay in the outbox worker -- those are provider-agnostic concerns.
 
-Drizzle raw SQL expression for the window predicate:
+The `buildVeventString` + RRULE/VALARM logic currently inlined in `dispatchRow` moves into `CalDavProvider.dispatchOutboxRow`. The outbox worker only knows about `DispatchResult`.
 
-```typescript
-sql`${calendarEvents.reminderLeadMinutes} IS NOT NULL
-  AND DATE_SUB(${calendarEvents.dtstartUtc}, INTERVAL ${calendarEvents.reminderLeadMinutes} MINUTE) > ${new Date(now.getTime() - 60_000)}
-  AND DATE_SUB(${calendarEvents.dtstartUtc}, INTERVAL ${calendarEvents.reminderLeadMinutes} MINUTE) <= ${new Date(now.getTime() + 60_000)}`;
-```
+#### Modified: `broker/reminderScheduler.ts`
 
-`isShared` restriction (D-05): this is a scope decision. D-05 was originally "shared calendar only" for the fixed-15-min reminder. With per-event VALARM, the user explicitly configured a reminder — it should fire regardless of which calendar the event is on. Recommend removing the `isShared` restriction in v1.1 for reminder-triggered notifications. Event-change notifications (via `eventChangeDispatcher.ts`) are a separate flow and unaffected.
+The reminder scheduler queries `calendarEvents` from MariaDB and calls `dispatchPush` -- it is **already provider-agnostic**. No structural change needed. The only change: the `reminderLeadMinutes` column on `calendar_events` becomes `JSON` (see Feature 4 below) and the scheduler query updates accordingly.
 
-**Catch-up guarantee is preserved.** The existing 16-min window provided catch-up by keeping missed events visible for 16 minutes. With a 2-minute window (±1min around now) and 1-min ticks, a single missed tick means the next tick has the event in window. A 2-minute outage means at most one missed reminder — acceptable for household use.
+#### Normalized Internal Event Model
 
-**Dedup stays the same.** `sentReminders: Map<uid, dtstartMs>` keyed by bare uid. This correctly prevents double-fire when the event lingers in the window across ticks. No change needed.
+The `calendarEvents` table row is the internal canonical form that all providers must write to. Providers translate their native format into this DB shape on sync:
+
+| Provider field | Internal DB column |
+|---|---|
+| VEVENT SUMMARY | `title` |
+| DTSTART (UTC) | `dtstart_utc` or `dtstart_date` + `all_day` |
+| RRULE | `has_rrule`, `raw_vevent` (full blob) |
+| VALARM DURATION (single) | `reminder_leads` JSON array |
+| Google `summary` | `title` |
+| Google `start.dateTime` | `dtstart_utc` |
+| Google `recurrence[RRULE]` | `has_rrule`, stored in `raw_vevent` as provider blob |
+| Google reminder overrides | `reminder_leads` JSON array |
+
+The `raw_vevent` column contains the full native blob for CalDAV (used for RRULE/VALARM preservation on edit). For Google, this column stores the full Google event JSON blob. Providers know their own blob format; the DB treats it as opaque text.
 
 ---
 
-### (b) Event-Driven Outbox Drain
+### 2. Google Calendar Provider
 
-#### Current state
+#### OAuth2 Token Storage
 
-`startOutboxWorker()` in `outboxWorker.ts` (line 781) runs `runOutboxDrain()` every 15 seconds. All write routes in `routes/events.ts` insert to `calendar_outbox` and return 202 with no drain trigger.
+**New table: `provider_tokens`** -- separate from `member_credentials` because Google issues two separate secrets (access_token + refresh_token) with different TTLs, and refresh is async.
 
-#### Recommended approach: in-process EventEmitter
+```sql
+CREATE TABLE provider_tokens (
+  id            INT AUTO_INCREMENT PRIMARY KEY,
+  user_id       INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  provider_type VARCHAR(64) NOT NULL,           -- 'google'
+  access_token  TEXT NOT NULL,                  -- AES-256-GCM encrypted
+  refresh_token TEXT,                           -- AES-256-GCM encrypted; nullable
+  expires_at    TIMESTAMP NOT NULL,
+  scope         VARCHAR(1024),
+  created_at    TIMESTAMP DEFAULT NOW() NOT NULL,
+  updated_at    TIMESTAMP DEFAULT NOW() ON UPDATE NOW(),
+  UNIQUE KEY uniq_provider_token_user (user_id, provider_type)
+);
+```
 
-New file `apps/api/src/lib/outboxTrigger.ts` — follows the exact pattern of `listEmitter.ts` (proven, same single-process deployment):
+`member_credentials` already has `UNIQUE(user_id)` enforcing one credential per member, which breaks multi-provider. For v1.2 (one member, one provider at a time), this constraint is fine -- a member has either CalDAV or Google, not both simultaneously. If multi-provider-per-member is ever needed (v1.3+), the unique constraint needs relaxation and the schema revisit is a separate migration.
+
+**Recommendation:** Use `member_credentials` as the "this member has provider X connected" flag (providerType + a harmless encrypted sentinel), and `provider_tokens` for the actual Google OAuth token lifecycle. This avoids a schema change to `member_credentials` while cleanly separating concerns.
+
+#### Token Refresh Worker
+
+Rather than a dedicated worker, piggyback on the `CalendarProvider` contract: `GoogleCalendarProvider` checks `expires_at` before every API call and refreshes inline if the token is expired or within 5 minutes of expiry. This is the standard pattern for single-process deployments. No separate refresh `setInterval` is needed at this scale (2 users).
+
+If a Google API call returns 401, the provider refreshes the token, retries once, then propagates the error as a `hardFail` dispatch result.
+
+#### Google Read-Sync and Write-Back Mapping
+
+| CalDAV outbox model | Google Calendar API equivalent |
+|---|---|
+| PUT .ics to collection URL | `POST/PATCH /calendar/v3/calendars/{calId}/events` |
+| DELETE object URL | `DELETE /calendar/v3/calendars/{calId}/events/{eventId}` |
+| ctag PROPFIND | `GET /calendar/v3/calendars/{calId}` -> `nextSyncToken` |
+| REPORT (fetch all) | `GET /calendar/v3/calendars/{calId}/events?syncToken=...` |
+| VEVENT `uid` | Google `event.id` (stored as `uid` in `calendar_outbox`) |
+| VEVENT `etag` | Google `event.etag` (used for conditional update) |
+
+The outbox `calendarUrl` column stores either a CalDAV collection URL (CalDAV provider) or a Google `calendarId` string (Google provider). The column name stays `calendarUrl`; the `GoogleCalendarProvider` interprets it as a calendar ID.
+
+#### Google OAuth Callback Routes (MODIFIED: `routes/` + `index.ts`)
+
+Google OAuth for calendar access is **not** the same as app login. The flow:
+
+1. Member clicks "Connect Google Calendar" on the self-service onboarding page.
+2. PWA calls `GET /api/calendar-connect/google/authorize` (NEW route, auth-guarded).
+3. The route generates an OAuth authorization URL with `scope=https://www.googleapis.com/auth/calendar` + `access_type=offline` + `state=<signed-jwt-with-userId>`.
+4. PWA redirects the browser to that URL.
+5. Google redirects back to `/api/calendar-connect/google/callback` (NEW route, pre-auth -- same pattern as `/callback` for Authelia OIDC).
+6. The callback exchanges the code for tokens, decrypts the state JWT to identify the member, and upserts `provider_tokens` + `member_credentials`.
+
+**Routing concern:** The Google OAuth callback must be mounted **before** the OIDC auth guard in `index.ts` (same as `/callback` is mounted before `oidcAuthMiddleware`). Unlike the Authelia callback which establishes app login, the Google callback is for calendar access only -- the member is already logged into the app. The callback must still verify the signed state JWT to confirm the initiating user and prevent CSRF. After token storage, it redirects back to the onboarding page.
+
+New routes file: `routes/calendarConnect.ts` (NEW) -- handles `/api/calendar-connect/google/authorize` (auth-guarded, GET) and `/api/calendar-connect/google/callback` (pre-auth, GET). Mount pre-auth in `index.ts`:
 
 ```typescript
-// apps/api/src/lib/outboxTrigger.ts
-import { EventEmitter } from 'node:events';
-const emitter = new EventEmitter();
+// Must be before OIDC guard, like /callback
+app.get('/api/calendar-connect/google/callback', googleOAuthCallbackHandler);
+// Auth-guarded
+app.route('/api/calendar-connect', calendarConnectRouter);
+```
 
-export function signalOutboxDrain(): void {
-  emitter.emit('drain');
-}
+The Google `client_id` and `client_secret` are env vars (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`) -- never in the DB (same SC-3 rule as VAPID_PRIVATE_KEY).
 
-export function onOutboxDrainSignal(handler: () => void): () => void {
-  emitter.on('drain', handler);
-  return () => emitter.off('drain', handler);
+---
+
+### 3. Self-Service Per-Provider Onboarding
+
+#### UI Changes (MODIFIED: PWA)
+
+A new "Connect Calendar" page/sheet in the PWA, accessible from Settings or the setup flow. Conditionally renders:
+
+- **Fastmail path:** Password input field -> `POST /api/me/credential` (already exists). UI copies from `CredentialSheet.tsx` -- this component already implements the self-service flow.
+- **Google path:** "Connect Google Calendar" button -> calls `GET /api/calendar-connect/google/authorize` -> browser redirect to Google.
+
+New PWA component: `components/ProviderConnectSheet.tsx` (NEW) -- wraps both flows with provider-aware branching. `CredentialSheet.tsx` can be refactored to delegate to this, or kept as-is for the Fastmail path (lower risk).
+
+#### API Changes
+
+`GET /api/me/providers` (NEW) -- returns which providers the current member has connected (`{ providers: [{ type: 'caldav', connected: true }, { type: 'google', connected: false }] }`). PWA uses this to render the onboarding state.
+
+`DELETE /api/me/providers/:type` (NEW) -- disconnect a provider (deletes `member_credentials` + `provider_tokens` rows, removes synced calendars + events from DB).
+
+The existing `POST /api/me/credential` handles the Fastmail/CalDAV path unchanged. The admin `POST /api/admin/credentials` path also stays as-is for admin-initiated credential rotation.
+
+#### Auth Guard Coexistence
+
+The Google OAuth callback is the only new pre-auth route. All other onboarding routes are auth-guarded (`/api/me/*` pattern). No changes to the existing auth middleware stack.
+
+---
+
+### 4. Multiple Reminders Per Event
+
+This is an end-to-end schema and data-flow change.
+
+#### Schema Change
+
+Replace `calendar_events.reminder_lead_minutes INT` with `calendar_events.reminder_leads JSON` (array of integers). A `NULL` value means no reminders. An empty array `[]` is equivalent to null (no reminders set). This is a **breaking migration** for the existing single-reminder column.
+
+Migration strategy:
+- Add `reminder_leads JSON` column.
+- Migrate existing data: `UPDATE calendar_events SET reminder_leads = JSON_ARRAY(reminder_lead_minutes) WHERE reminder_lead_minutes IS NOT NULL`.
+- Drop `reminder_lead_minutes` column in the same migration.
+- Update Drizzle schema: `reminderLeads: json('reminder_leads').$type<number[] | null>()`.
+
+The `calendarOutbox` payload schema (`outboxPayloadSchema`) changes `reminderLeadMinutes: z.number().int()...` to `reminderLeads: z.array(z.number().int().min(0).max(10080)).nullable().optional()`.
+
+#### Data Flow Changes
+
+**EventForm -> API (MODIFIED: PWA + `routes/events.ts`):**
+- EventForm renders a list of reminder pickers (add/remove). Each picker = one lead time.
+- Payload changes: `reminderLeadMinutes: number | null` -> `reminderLeads: number[] | null`.
+
+**outboxWorker.ts (MODIFIED):**
+- `buildVeventString` call changes: `reminderLeadMinutes` parameter -> `reminderLeads: number[]`.
+- `vevent.ts` must emit multiple `VALARM` sub-components for each lead.
+- The preserve-on-no-change path: `extractValarms` already returns `ICAL.Component[]`; this still works verbatim.
+
+**vevent.ts (MODIFIED):**
+- `buildVeventString` params: `reminderLeadMinutes?: number | null` -> `reminderLeads?: number[] | null`.
+- Build one `VALARM` per entry in the array.
+- `buildTimedValarm` and `buildAllDayValarm` helpers are called in a loop.
+
+**reminderScheduler.ts (MODIFIED):**
+- Query changes: instead of `WHERE reminder_lead_minutes IS NOT NULL`, query `WHERE reminder_leads IS NOT NULL AND JSON_LENGTH(reminder_leads) > 0`.
+- `reminder_leads` is a JSON array; the scheduler must iterate all leads for an event and compute one fire time per lead.
+- Dedup key: `${uid}:${dtstartMs}:${leadMinutes}` -- per-lead dedup so each reminder fires independently.
+
+**Google provider serialization:**
+- `serializeReminders(leads, allDay)` -> `{ overrides: leads.map(m => ({ method: 'popup', minutes: m })), useDefault: false }`.
+- `parseReminders(googleEvent.reminders)` -> `googleEvent.reminders.overrides?.map(o => o.minutes) ?? []`.
+
+**sync.ts (MODIFIED for CalDAV path):**
+- When syncing a VEVENT, extract all VALARMs using `extractValarms`, classify each, and store the array of lead minutes as `reminder_leads` JSON.
+
+---
+
+### 5. PWA Dark Mode / Theming
+
+#### Where Theme State Lives
+
+Theme preference: `localStorage` key `'theme'` with values `'light' | 'dark' | 'system'`. Resolved theme (what's actually applied): derived from preference + `window.matchMedia('(prefers-color-scheme: dark)')`.
+
+**New Zustand store:** `store/themeStore.ts` (NEW) -- holds `{ preference, resolvedTheme }` and a `setPreference()` action that writes to localStorage and applies `data-theme` to `document.documentElement`.
+
+An effect in the store (or in `main.tsx` before React hydration) sets `data-theme` on `<html>` immediately from localStorage to prevent FOUC. The token file already has the `[data-theme='light']` selector; adding `[data-theme='dark']` with dark token values is the only CSS change.
+
+#### Avoiding FOUC
+
+The FOUC problem with theme switching is that React hydration runs after the browser paints. Solution: inject an inline `<script>` in `index.html` before any stylesheet or React bundle that reads `localStorage['theme']` and sets `document.documentElement.setAttribute('data-theme', resolved)`. This runs synchronously at parse time, before CSS is applied.
+
+```html
+<script>
+  (function(){
+    var p = localStorage.getItem('theme') || 'system';
+    var resolved = p === 'system'
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : p;
+    document.documentElement.setAttribute('data-theme', resolved);
+  })();
+</script>
+```
+
+This script goes in `apps/pwa/index.html` (MODIFIED) before the CSS `<link>` tags.
+
+#### tokens.css Changes (MODIFIED)
+
+Add `[data-theme='dark']` rule with dark palette values. The stub comment already exists in `tokens.css`. The `--sx-color-*` Schedule-X overrides must also be present inside the dark rule. The `calendarStore` color palette (`--color-member-0` through `--color-member-5`) must be defined in both light and dark rules -- same hue, adjusted brightness.
+
+#### Theme Toggle UI
+
+New component: `components/ThemeToggle.tsx` (NEW) -- renders a light/dark/system switch. Placed in `SettingsSheet.tsx` (MODIFIED).
+
+---
+
+### 6. Zero-Manual-Setup DB Bootstrap
+
+#### Where Migrate-on-Boot Runs
+
+In `index.ts` inside the `isMainModule()` guard, **before** `startBrokerPoller()` and **before** `serve()` -- but **after** the boot guards (`assertNotDevBypassInProduction`, `assertLocalSessionSecretSet`).
+
+```typescript
+if (isMainModule()) {
+  assertNotDevBypassInProduction();
+  assertLocalSessionSecretSet();
+  await runMigrationsIfNeeded();  // NEW -- runs drizzle migrate programmatically
+  // ... VAPID setup, startBrokerPoller, startOutboxWorker, serve ...
 }
 ```
 
-**Why not Redis pub/sub:** The outbox drain is single-process by design — the `isDraining` guard in `outboxWorker.ts` (line 156) explicitly documents "SINGLE-PROCESS LIMITATION". Redis pub/sub adds a network hop and operational overhead for zero benefit. Redis is already used for SSE list fan-out — a different problem (multi-browser-tab fan-out).
+Use drizzle-orm's programmatic `migrate(db, { migrationsFolder: './src/db/migrations' })`. This is already the established pattern for drizzle-kit; the change is calling it automatically at boot instead of requiring a manual `docker exec` step.
 
-**`apps/api/src/routes/events.ts`** — MODIFY
+#### Interplay with Setup Wizard
 
-After each `db.insert(calendarOutbox)` in the three write handlers (create, edit/same-calendar, edit/move transaction), add:
+The setup wizard (`/api/setup/*`) is mounted pre-auth and checks `isSetupLocked()` on every invocation. Migrate-on-boot runs BEFORE the server starts accepting requests, so by the time the wizard receives its first request, the schema is guaranteed to exist. No race condition.
 
-```typescript
-signalOutboxDrain();
-```
+If `DB_HOST`/`DB_NAME`/`DB_USER`/`DB_PASSWORD` env vars are set but the database is empty (first boot of a fresh MariaDB instance), migrate-on-boot creates all tables. The setup wizard then runs to configure OIDC/VAPID/admin account. This is the intended "bring-your-own MariaDB" flow.
 
-Import from `'../lib/outboxTrigger.js'`. Fire-and-forget; no await.
+#### Boot Failure Behavior
 
-**`apps/api/src/broker/outboxWorker.ts`** — MODIFY
-
-In `startOutboxWorker()`:
-
-```typescript
-export function startOutboxWorker(): void {
-  // Event-driven: drain immediately after any enqueue signal
-  onOutboxDrainSignal(() => {
-    runOutboxDrain().catch((err: unknown) => {
-      console.error('[outboxWorker] Signal-triggered drain error:', err);
-    });
-  });
-  // Fallback: 15s periodic drain for recovery + startup catch-up
-  setInterval(() => {
-    runOutboxDrain().catch((err: unknown) => {
-      console.error('[outboxWorker] Interval drain error:', err);
-    });
-  }, 15 * 1000);
-}
-```
-
-**All durability guarantees are preserved.** The `isDraining` concurrency guard handles overlapping invocations from both the signal and the interval. When a signal-triggered drain is running (`isDraining = true`), any concurrent call (signal or interval) is a no-op. Create-before-delete ordering (D-04), etag re-read (WR-02), 412 conflict flow (D-08), transient backoff (D-07) — all unchanged. The trigger path only affects _when_ `runOutboxDrain()` is called.
-
-**Rapid-successive-edits behavior:** Each `signalOutboxDrain()` call may trigger a drain that processes row N while row N+1 hasn't been inserted yet. Row N+1's `nextAttemptAt = defaultNow()`, so it appears in the next drain cycle's `pending + next_attempt_at <= NOW()` query. The 15s fallback interval ensures it is drained within 15 seconds at most.
+If migration fails (DB unreachable, bad creds), `runMigrationsIfNeeded` must throw -- the server should not start with a potentially partial schema. The MariaDB healthcheck in `docker-compose.yml` already gates API startup on DB readiness, so typically this won't be reached with an unreachable DB, but the defense-in-depth catch is still correct.
 
 ---
 
-### (c) Admin Role + Setup Wizard Config Storage
+### 7. Dev-User Full-App Exercise (Mock Provider)
 
-#### Admin role flag
+#### New Component: `broker/mockProvider.ts` (NEW)
 
-**Where:** `users` table in `apps/api/src/db/schema.ts`. Add:
+Implements `CalendarProvider` with an in-memory store -- a `Map<string, ProviderCalendar[]>` for calendars and `Map<string, CalendarEvent[]>` for events. Pre-seeded with a set of realistic test events (recurring, all-day, timed, with reminders) that cover the scheduler's test surface.
 
-```typescript
-isAdmin: boolean('is_admin').default(false).notNull(),
-```
+**Activation:** When `DEV_AUTH_BYPASS=true` AND `provider_type` for the dev user is `'mock'` (or when no credential row exists for the dev user), `createProvider` returns `MockCalendarProvider`. The dev bypass already injects a `DEV_USER` -- the mock provider boots alongside it with no DB credential row required.
 
-**Why DB not env:** Admin designation is per-user, mutable, and tied to identity. Env vars cannot express "user X is admin." The first user to complete the setup wizard is auto-promoted. Subsequent changes go through an admin route action.
+**Playwright harness integration:** The existing `devBypass.ts` already gates test-only behavior on `DEV_AUTH_BYPASS`. The mock provider is the same gate. Playwright tests that exercise calendar CRUD will hit the mock provider, which returns success responses and updates its in-memory state. The outbox worker calls `provider.dispatchOutboxRow()` which the mock handles without network I/O.
 
-**Migration:** `ALTER TABLE users ADD COLUMN is_admin BOOLEAN NOT NULL DEFAULT 0` — safe online DDL on MariaDB 11/InnoDB.
+**Seed data bootstrapping:** On first call to `listCalendars()`, the mock creates:
+- One personal calendar for DEV_USER.
+- One shared calendar.
+- ~5 pre-seeded events (one recurring weekly, one all-day, one with reminder, one past, one future).
 
-**Route guard:** `requireAdmin` middleware in `apps/api/src/routes/admin.ts` calls `resolveUserId` then checks `users.isAdmin`. Applied to all `/api/admin/*` routes.
-
-**`GET /api/me` extension:** Add `isAdmin: boolean` to the response. The PWA uses this to conditionally show the Admin section in `SettingsSheet`. The `['me']` TanStack Query is already called on app load — no new query needed.
-
-#### Setup wizard config
-
-The wizard bootstraps four categories of state:
-
-| Config                     | Current Home                                        | v1.1 Approach                                                         |
-| -------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
-| VAPID keypair              | `.env` (VAPID_PUBLIC_KEY, \_PRIVATE_KEY, \_SUBJECT) | Stays in env; wizard validates presence + offers generate-and-display |
-| AES-256 key                | `.env` (APP_PASSWORD_ENCRYPTION_KEY)                | Stays in env; wizard validates format (64-char hex)                   |
-| OIDC credentials           | `.env` (OIDC_ISSUER, \_CLIENT_ID, \_SECRET, etc.)   | Stays in env; wizard validates OIDC discovery reachability            |
-| App passwords + shared-cal | DB (member_credentials, calendars.is_shared)        | Same DB; wizard is the UI for what was previously a manual DB write   |
-
-**New `app_config` table** for app-level flags:
-
-```typescript
-export const appConfig = mysqlTable('app_config', {
-  key: varchar('key', { length: 128 }).primaryKey(),
-  value: text('value').notNull(),
-  updatedAt: timestamp('updated_at').defaultNow().onUpdateNow(),
-});
-```
-
-Initial keys: `setup_complete` (`'0'` or `'1'`), `setup_step` (resumable flow state).
-
-**Why the wizard cannot write `.env`:** Env vars are set at Docker container start via Docker Compose. A running container's process cannot mutate its own env and have those mutations persist across restarts. The correct flow: wizard detects missing env vars, provides a "Generate" button that returns a keypair for the operator to copy, then re-validates after the operator restarts the container with updated env. Alternatively, the wizard writes to a `/app/.env.local` file that the Node.js process reads via dotenv — but this requires the container to have write access to its own image layer or a mounted volume. The simplest Unraid approach: wizard shows values to copy, operator adds to Docker Compose env, restarts.
-
-**`apps/api/src/routes/setup.ts`** — NEW
-
-Endpoints (all except `/status` are admin-only after first-run completes):
-
-- `GET /api/setup/status` — **unauthenticated** (mounted before OIDC guard in `index.ts`, like `/health`); returns `{ complete: boolean }`
-- `GET /api/setup/env-status` — returns which env vars are present/missing (no values)
-- `POST /api/setup/generate-vapid` — calls `webpush.generateVAPIDKeys()`, returns `{ publicKey, privateKey, subject }` for operator to copy; does NOT store in DB
-- `GET /api/setup/validate-oidc` — pings `${OIDC_ISSUER}/.well-known/openid-configuration`, returns `{ ok: boolean, error?: string }`
-- `POST /api/setup/complete` — sets `app_config.setup_complete = '1'`; sets `users.is_admin = true` for the calling user (promotes wizard-completing user to admin)
-
-**First-run detection in PWA:** `App.tsx` adds a setup-status check before rendering the calendar shell. If `complete = false` and the user is authenticated (or the wizard must be completeable pre-auth), render `<SetupWizard>`. Simplest flow: require authentication first (Authelia protects everything), then the wizard runs as an authenticated user. The `GET /api/setup/status` route being pre-OIDC lets the PWA detect setup state before the OIDC redirect fires — render a "Setup required" splash instead of bouncing the user around.
-
-#### Shared surface: wizard vs admin Settings
-
-`POST /api/admin/credentials` is called by both the setup wizard (step: first app password) and the admin Settings page (ongoing credential management). Build this route once. The wizard in Phase D is a pure frontend consumer of the same admin API surface.
-
-`PATCH /api/admin/calendars/:id/shared` is called by both the setup wizard (step: designate shared calendar) and admin Settings. Same pattern.
-
-**Do not create `/api/setup/credentials` or `/api/setup/calendar-shared`** — these would duplicate `/api/admin/credentials` and `/api/admin/calendars/:id/shared`.
-
-**Deferred: self-service provider onboarding (999.5).** This is a member-initiated flow where each member enters their own app password. The admin credential route is admin-only and takes a `userId` parameter. Self-service onboarding is a separate concern — do not conflate with admin settings in v1.1.
+This covers all code paths the scheduler, outbox worker, and event expansion touch.
 
 ---
 
-### (d) New vs Modified Components — Dependency-Ordered Build Sequence
+## Component Map: New vs Modified
 
-#### Dependency graph
+### New Components
 
-```
-DB schema migration (users.is_admin, calendarEvents.reminder_lead_minutes, app_config)
-        │
-        ├─── Admin role + routes (admin.ts) ─────────────────────────┐
-        │         │                                                   │
-        │    routes/me.ts (extend response with isAdmin)             │
-        │         │                                                   │
-        │    AdminSettings.tsx + SettingsSheet.tsx mod               │
-        │         │                                                   │
-        │    SetupWizard.tsx (reuses admin routes)               ◄───┘
-        │    routes/setup.ts (wizard backend)
-        │    App.tsx (setup-status gate)
-        │
-        ├─── Faster write-back ─────────────────────────────────────
-        │         lib/outboxTrigger.ts (new)
-        │         outboxWorker.ts (subscribe to signal)
-        │         routes/events.ts (call signalOutboxDrain)
-        │         [no PWA changes]
-        │
-        ├─── VALARM write path ──────────────────────────────────────┐
-        │         broker/vevent.ts (add VALARM to buildVeventString)  │
-        │         outboxWorker.ts (pass reminderMinutes)              │
-        │         routes/events.ts (extend schemas)                   │
-        │         EventForm.tsx (reminder selector)                   │
-        │         api/client.ts (extend CreateEventPayload)           │
-        │         broker/sync.ts (extract VALARM -> DB)          ◄───┘
-        │         reminderScheduler.ts (variable-lead query)
-        │
-        ├─── Gitea CI (.gitea/workflows/ci.yml)
-        │         [no code dependencies; parallel]
-        │
-        └─── Mobile test harness
-                  [no new backend code; playwright-cli + DEV_AUTH_BYPASS]
-```
+| Component | Type | Purpose |
+|---|---|---|
+| `broker/provider.ts` | Interface + types | `CalendarProvider` interface, `ProviderCalendar`, `DispatchResult` |
+| `broker/providerFactory.ts` | Factory | `createProvider(cred)` -> `CalendarProvider` |
+| `broker/calDavProvider.ts` | Class | Wraps existing `client.ts` + `sync.ts` + `write.ts` |
+| `broker/googleProvider.ts` | Class | Google Calendar API v3 read/write + token refresh |
+| `broker/mockProvider.ts` | Class | In-memory provider for dev-bypass + Playwright tests |
+| `routes/calendarConnect.ts` | Route file | Google OAuth authorize + callback handlers |
+| `db/migrations/XXXX_v1.2_multi_provider.sql` | Migration | `provider_tokens` table, `reminder_leads` JSON column, drop `reminder_lead_minutes` |
+| `pwa/src/store/themeStore.ts` | Zustand store | Theme preference + resolved theme |
+| `pwa/src/components/ThemeToggle.tsx` | React component | Light/dark/system switch |
+| `pwa/src/components/ProviderConnectSheet.tsx` | React component | Provider onboarding UI (Fastmail + Google paths) |
 
-#### Recommended build order
+### Modified Components
 
-**Phase A — DB foundation (unblocks everything)**
-
-1. `apps/api/src/db/schema.ts` — add `users.isAdmin`, `calendarEvents.reminderLeadMinutes`, `appConfig` table
-2. `drizzle-kit generate` + apply migration to dev DB
-3. `apps/api/src/lib/outboxTrigger.ts` — new file, zero dependencies
-
-**Phase B — Faster write-back (low-risk, isolated)**
-
-Prerequisite: `outboxTrigger.ts` from Phase A
-
-4. `apps/api/src/broker/outboxWorker.ts` — subscribe to drain signal in `startOutboxWorker`
-5. `apps/api/src/routes/events.ts` — add `signalOutboxDrain()` after each outbox insert (3 call sites)
-
-No PWA changes. Tests: extend `tests/broker/outboxWorker.test.ts`.
-
-**Phase C — Admin role + routes**
-
-6. `apps/api/src/routes/admin.ts` — new file:
-   - `GET /api/admin/members` — list users with credential status (isAdmin flag determines who sees it)
-   - `POST /api/admin/credentials` — upsert `memberCredentials` for a given `userId`; reuses `encryptPassword` from `broker/crypto.ts`
-   - `DELETE /api/admin/credentials/:userId` — remove credential
-   - `PATCH /api/admin/calendars/:id/shared` — toggle `calendars.isShared`
-   - All routes: `requireAdmin` middleware
-7. `apps/api/src/routes/me.ts` — extend response with `isAdmin: boolean`
-8. `apps/api/src/index.ts` — mount `adminRouter` at `/api/admin`
-
-**Phase D — Setup wizard**
-
-Prerequisite: Phase C admin routes
-
-9. `apps/api/src/routes/setup.ts` — new file (wizard backend endpoints)
-10. `apps/api/src/index.ts` — mount `setupRouter` at `/api/setup`; mount `GET /api/setup/status` BEFORE the OIDC guard
-11. `apps/pwa/src/components/SetupWizard.tsx` — multi-step first-run UI
-12. `apps/pwa/src/App.tsx` — setup-status check gate
-
-**Phase E — Admin Settings UI**
-
-Prerequisite: Phase C admin routes + Phase C `isAdmin` in `/api/me`
-
-13. `apps/pwa/src/components/AdminSettings.tsx` — member list, "Set app password" flow, shared-calendar picker
-14. `apps/pwa/src/components/SettingsSheet.tsx` — add "Admin" section (shown only when `currentUser.isAdmin`)
-15. `apps/pwa/src/api/client.ts` — add admin API fetch wrappers
-
-**Phase F — VALARM authoring (event form + scheduler)**
-
-Prerequisite: Phase A (schema has `reminderLeadMinutes`)
-
-16. `apps/api/src/broker/vevent.ts` — add VALARM to `buildVeventString`; extend `NewEventParams`
-17. `apps/api/src/broker/outboxWorker.ts` — pass `reminderMinutes` in create + update branches; add to `outboxPayloadSchema`
-18. `apps/api/src/routes/events.ts` — add `reminderMinutes` to `eventFieldsSchema`
-19. `apps/api/src/broker/sync.ts` — extract VALARM trigger; store `reminderLeadMinutes` on upsert
-20. `apps/pwa/src/components/EventForm.tsx` — add reminder selector
-21. `apps/pwa/src/api/client.ts` — extend `CreateEventPayload` type
-
-Then, once sync.ts change is deployed and populating `reminder_lead_minutes`:
-
-22. `apps/api/src/broker/reminderScheduler.ts` — rewrite `runReminderCheck` to use variable lead from `reminder_lead_minutes`; update `isShared` scope per feature decision
-
-**Phase G — Gitea CI (independent, parallel)**
-
-23. `.gitea/workflows/ci.yml` — lint/typecheck/unit/API-integration on PR; MariaDB service container; secrets for `DB_HOST=127.0.0.1`, DB creds, test env vars. Tests live in `apps/api/tests/` — confirm test runner path in CI config.
-
-**Phase H — Mobile test harness (independent)**
-
-24. Playwright-cli mobile viewport configuration + authenticated entry via `DEV_AUTH_BYPASS=true`; no backend changes required.
+| Component | Change |
+|---|---|
+| `broker/poller.ts` | `createFastmailClient` -> `createProvider(cred)`; `syncCalendar` -> `provider.syncCalendar()` |
+| `broker/outboxWorker.ts` | `loadClientForUser` -> `loadProviderForUser`; `dispatchRow` -> `provider.dispatchOutboxRow(row)` |
+| `broker/reminderScheduler.ts` | Query + dedup logic for multi-lead JSON; fire one push per lead per event |
+| `broker/vevent.ts` | `buildVeventString` accepts `reminderLeads: number[]` instead of single `reminderLeadMinutes` |
+| `broker/credentialSync.ts` | `validateEncryptAndStoreCredential` becomes provider-aware (CalDAV path unchanged) |
+| `broker/sync.ts` | Parse multiple VALARMs into `reminder_leads` array on sync |
+| `db/schema.ts` | `calendarEvents.reminderLeadMinutes` -> `calendarEvents.reminderLeads`; new `providerTokens` table |
+| `routes/events.ts` | Payload schema: `reminderLeadMinutes` -> `reminderLeads` array |
+| `routes/me.ts` | New `/api/me/providers` GET + DELETE endpoints |
+| `index.ts` | Add `runMigrationsIfNeeded()` call; mount `/api/calendar-connect/google/callback` pre-auth |
+| `pwa/src/components/EventForm.tsx` | Multi-reminder picker (add/remove); payload field rename |
+| `pwa/src/components/SettingsSheet.tsx` | Add ThemeToggle; add provider connection status |
+| `pwa/src/styles/tokens.css` | Add `[data-theme='dark']` rule with dark palette |
+| `pwa/src/index.html` | FOUC-prevention inline script before CSS link tags |
 
 ---
 
-## Component Boundaries and Key Integration Notes
+## Data Flow Changes
 
-### Shared surface: wizard credential entry vs admin Settings
+### Multi-Provider Poller
 
-`POST /api/admin/credentials` is called by both the setup wizard (first app password) and the admin Settings page (ongoing management). Build once in Phase C. Do not duplicate into a `/api/setup/credentials` endpoint.
-
-### VALARM round-trip: write path vs read path
-
-These are independent flows that rendezvous through Fastmail:
-
-- **Write:** `reminderMinutes` travels as a number in the outbox JSON payload → `buildVeventString` emits VALARM TRIGGER:-PT{n}M → tsdav PUT to Fastmail
-- **Read:** After the event syncs back from Fastmail (via targeted re-sync in `outboxWorker.ts` or 5-min poll), `sync.ts` parses the VALARM TRIGGER and stores `reminderLeadMinutes` in `calendar_events`. The scheduler reads this column — never the outbox payload.
-
-This means `reminder_lead_minutes` in `calendar_events` is the ground truth. Events created before v1.1 (or by third-party clients) that have no VALARM will have `reminderLeadMinutes = NULL` and the scheduler ignores them.
-
-### `outboxPayloadSchema` vs `eventFieldsSchema` — must stay in sync
-
-`eventFieldsSchema` in `routes/events.ts` (line 100) and `outboxPayloadSchema` in `outboxWorker.ts` (line 71) are intentionally duplicated for defense-in-depth (IN-03). Adding `reminderMinutes` requires updating both. This is documented in the existing IN-03 comment — flag it explicitly when writing the phase plan.
-
-### `isAdmin` in API responses
-
-`GET /api/me` currently returns `{ id, displayName, color }`. Extend to include `isAdmin: boolean`. The PWA uses this to conditionally show the Admin section in SettingsSheet. The `['me']` TanStack Query is already called on app load — no new query, just extend the existing response and the `MeUser` type in `api/client.ts`.
-
-### First-run detection: mount `/api/setup/status` before OIDC guard
-
-In `apps/api/src/index.ts`, `/health` is already mounted before the OIDC guard (line 40). Mount `GET /api/setup/status` with the same pattern:
-
-```typescript
-app.get('/api/setup/status', setupStatusHandler); // before oidcAuthMiddleware
+```
+startBrokerPoller()
+  -> runPoll()
+    -> SELECT * FROM member_credentials
+    -> for each cred:
+        createProvider(cred)           <- NEW dispatch via providerFactory
+          -> provider.listCalendars()  <- CalDAV: PROPFIND / Google: GET /calendars
+          -> compare changeKey vs stored ctag/syncToken
+          -> on change: provider.syncCalendar(cal, onChanges)
+            -> writes calendarEvents rows (provider-specific parse -> common DB shape)
+            -> calls dispatchEventChange for push notifications
 ```
 
-This lets the PWA detect first-run state before the OIDC redirect fires and render a setup splash instead of an auth bounce loop.
+### Multi-Provider Outbox Drain
+
+```
+runOutboxDrain()
+  -> SELECT pending rows FROM calendar_outbox
+  -> for each row:
+      loadProviderForUser(row.userId)  <- replaces loadClientForUser
+        -> SELECT member_credentials WHERE userId = row.userId
+        -> createProvider(cred)
+      -> provider.dispatchOutboxRow(row)
+        CalDAV: buildVeventString + PUT/DELETE via tsdav
+        Google: build Google event JSON + POST/PATCH/DELETE via googleapis
+      -> handle DispatchResult (success/conflict/hardFail/transient)
+      -> triggerTargetedResync via provider
+```
+
+### Multiple Reminders: Form -> DB -> Scheduler -> Push
+
+```
+EventForm
+  reminderLeads: number[]            <- user adds/removes reminders
+  -> POST /api/events/create { reminderLeads: [30, 1440] }
+    -> routes/events.ts validates array
+    -> INSERT calendar_outbox { payload: JSON.stringify({ reminderLeads: [30, 1440] }) }
+    -> 202 Accepted
+  -> outboxWorker picks up row
+    -> provider.dispatchOutboxRow
+      CalDAV: buildVeventString({ reminderLeads: [30, 1440] })
+               -> two VALARM sub-components in VCALENDAR
+      Google:  { reminders: { useDefault: false, overrides: [{ method: 'popup', minutes: 30 }, ...] } }
+    -> on success: syncCalendar -> parses VALARMs/overrides back -> stores [30, 1440] in reminder_leads
+
+reminderScheduler (every 1 min)
+  -> SELECT uid, title, dtstart_utc, all_day, reminder_leads FROM calendar_events
+     CROSS JOIN push_subscriptions
+     WHERE reminder_leads IS NOT NULL AND JSON_LENGTH(reminder_leads) > 0
+  -> for each event:
+      leads = JSON.parse(reminder_leads)   // e.g. [30, 1440]
+      for each lead in leads:
+        compute fireTime = dtstartUtc - lead minutes
+        dedup key: `${uid}:${dtstartMs}:${lead}`
+        if fireTime in (catchUpStart, now] and not in sentReminders:
+          dispatchPush(sub, notification)
+          sentReminders.set(dedupKey, dtstartMs)
+```
+
+### Google OAuth + Calendar Connect
+
+```
+PWA (ProviderConnectSheet, logged-in user)
+  -> GET /api/calendar-connect/google/authorize (auth-guarded)
+    -> generate state JWT signed with LOCAL_SESSION_SECRET { userId, nonce }
+    -> store nonce in linkNonceStore (same pattern as OIDC link flow)
+    -> return { authorizationUrl: 'https://accounts.google.com/...' }
+  -> PWA redirects browser to authorizationUrl
+
+Google -> /api/calendar-connect/google/callback (pre-auth, before OIDC guard)
+  -> verify state JWT
+  -> consumeLinkNonce(nonce)
+  -> exchange code for { access_token, refresh_token, expires_in }
+  -> encrypt tokens (AES-256-GCM)
+  -> upsert provider_tokens (user_id, 'google', tokens)
+  -> upsert member_credentials (user_id, provider_type='google', placeholder)
+  -> trigger initial sync via GoogleCalendarProvider
+  -> redirect to /settings?provider=google&status=connected
+```
+
+### Migrate-on-Boot Sequence
+
+```
+isMainModule() guard:
+  1. assertNotDevBypassInProduction()
+  2. assertLocalSessionSecretSet()
+  3. await runMigrationsIfNeeded()     <- NEW: drizzle migrate(db, { migrationsFolder })
+     -> connects to DB
+     -> runs all pending migrations in order
+     -> no-op on subsequent boots when schema is current
+  4. webpush.setVapidDetails(...)
+  5. startBrokerPoller()
+  6. startOutboxWorker() + initOutboxTrigger()
+  7. startReminderScheduler()
+  8. serve({ fetch: app.fetch, port: 3000 })
+```
 
 ---
 
-## Data Flow Diagrams
+## Dependency-Ordered Build Sequence
 
-### Per-Event Reminder: Create to Notification
+The phases below are ordered by dependency. Each phase is safe to start only after the listed predecessors are complete.
 
 ```
-EventForm (reminder: 15min)
-    ↓ POST /api/events/create { reminderMinutes: 15, ... }
-routes/events.ts (schema validates, inserts outbox row, signalOutboxDrain())
-    ↓ [event-driven, ~0s]
-outboxWorker.ts runOutboxDrain()
-    → buildVeventString({ reminderMinutes: 15 })
-    → vevent.ts emits VCALENDAR with VALARM TRIGGER:-PT15M
-    → tsdav PUT to Fastmail (.ics)
-    → triggerTargetedResync() → sync.ts parses VALARM → stores reminder_lead_minutes=15
-    ↓ (next 1-min scheduler tick)
-reminderScheduler.ts
-    → SQL WHERE DATE_SUB(dtstart_utc, INTERVAL reminder_lead_minutes MINUTE) IN tick-window
-    → dispatchPush() to all subscribers
-    ↓
-Browser notification: "Starts in 15 min"
+Phase 21: Zero-Setup DB Bootstrap
+  Deliverable: runMigrationsIfNeeded() in index.ts isMainModule() guard
+  Dependencies: none (touches only index.ts startup + db/migrations)
+  Unlocks: all subsequent phases can assume schema bootstraps automatically
+  Risk: low
+
+Phase 22: Provider Abstraction (CalDAV only, Fastmail path unchanged)
+  Deliverable: broker/provider.ts interface, providerFactory.ts, calDavProvider.ts,
+               poller.ts + outboxWorker.ts updated to use createProvider
+  Dependencies: Phase 21 (schema must auto-migrate before integration tests run)
+  Unlocks: Phase 23 (vevent.ts depends on interface), Phase 25 (Google needs interface),
+           Phase 24 (mock needs factory)
+  Risk: HIGH -- must not regress the working Fastmail path; existing integration tests
+        must pass with CalDavProvider wrapper in place
+
+Phase 23: Multiple Reminders Per Event
+  Deliverable: DB migration (reminder_leads JSON), vevent.ts multi-VALARM,
+               outboxWorker.ts payload schema, reminderScheduler.ts multi-lead scan,
+               sync.ts multi-VALARM parse, routes/events.ts payload, EventForm.tsx
+  Dependencies: Phase 22 (CalDavProvider.dispatchOutboxRow must accept reminderLeads)
+  Note: Google reminder serialization/parsing is implemented in Phase 25
+  Risk: MEDIUM -- breaking migration; existing data must be migrated
+
+Phase 24: Dev-User Full-App Exercise (Mock Provider)
+  Deliverable: broker/mockProvider.ts with seed data, providerFactory.ts 'mock' case,
+               devBypass.ts sets provider_type='mock' for DEV_USER,
+               Playwright harness updated to exercise calendar CRUD
+  Dependencies: Phase 22 (CalendarProvider interface + factory)
+  Unlocks: Phase 25 (unit tests can mock GoogleCalendarProvider)
+  Risk: low -- dev-only path
+
+Phase 25: Google Calendar Provider
+  Deliverable: db/schema.ts provider_tokens table (migration), broker/googleProvider.ts,
+               routes/calendarConnect.ts, index.ts pre-auth callback mount
+  Dependencies: Phase 22 (CalendarProvider interface), Phase 23 (reminder serialization API),
+                Phase 21 (provider_tokens table exists after migrate-on-boot)
+  Risk: MEDIUM -- Google API OAuth flow has edge cases; token refresh inline logic
+
+Phase 26: Self-Service Provider Onboarding UI
+  Deliverable: GET/DELETE /api/me/providers routes, ProviderConnectSheet.tsx,
+               SettingsSheet.tsx wiring
+  Dependencies: Phase 25 (Google OAuth callback must exist before UI redirects to it)
+  Note: Fastmail/CalDAV path (CredentialSheet.tsx) already works; this phase adds Google
+  Risk: low
+
+Phase 27: PWA Dark Mode / Theming
+  Deliverable: index.html FOUC-prevention script, tokens.css dark rule,
+               themeStore.ts, ThemeToggle.tsx, SettingsSheet.tsx
+  Dependencies: none (pure frontend, no API changes)
+  Can run in parallel with Phases 22-26 if desired
+  Risk: low
 ```
 
-### Admin: Set Member App Password
+---
 
-```
-AdminSettings.tsx (admin enters app password for member X)
-    ↓ POST /api/admin/credentials { userId: X, email: '...', password: '...' }
-routes/admin.ts (requireAdmin guard → resolveUserId → check users.isAdmin)
-    → zod validate input
-    → encryptPassword() from broker/crypto.ts (AES-256-GCM)
-    → db.insert/onDuplicateKeyUpdate on memberCredentials
-    ↓ 200 OK
-AdminSettings.tsx invalidates ['admin/members'] query
-poller.ts (next 5-min tick): picks up new credential, discovers calendars for that user
-```
+## Integration Points Summary
 
-### Setup Wizard: First-Run Bootstrap
-
-```
-App.tsx (on load)
-    ↓ GET /api/setup/status [UNAUTHENTICATED, pre-OIDC]
-    ← { complete: false }
-    → render <SetupWizard> (after OIDC login)
-        Step 1: env-var check → GET /api/setup/env-status
-        Step 2: DB/OIDC validation → GET /api/setup/validate-oidc
-        Step 3: VAPID keypair → POST /api/setup/generate-vapid (operator copies to .env, restarts)
-        Step 4: first app password → POST /api/admin/credentials
-        Step 5: shared calendar → PATCH /api/admin/calendars/:id/shared
-        Step 6: POST /api/setup/complete → app_config.setup_complete='1', user.is_admin=true
-    → redirect to /
-App.tsx (on reload): GET /api/setup/status → { complete: true } → render CalendarShell
-```
+| Feature | Integration Point | Risk Level |
+|---|---|---|
+| Provider abstraction | `broker/poller.ts` runPoll loop | Medium |
+| Provider abstraction | `broker/outboxWorker.ts` dispatchRow | High |
+| Google OAuth callback | `index.ts` pre-auth route registration | Low |
+| Google tokens | New `provider_tokens` table | Low |
+| Multi-reminder | `calendar_events` schema (column rename to JSON) | High |
+| Multi-reminder | `reminderScheduler.ts` query + dedup key | Medium |
+| Multi-reminder | `EventForm.tsx` UI + routes/events.ts payload | Medium |
+| Migrate-on-boot | `index.ts` `isMainModule()` guard | Low |
+| Dark mode FOUC | `index.html` inline script | Low |
+| Mock provider | `devBypass.ts` + `providerFactory.ts` | Low |
 
 ---
 
 ## Anti-Patterns to Avoid
 
-### Anti-Pattern 1: Separate wizard endpoints that duplicate admin routes
+### Anti-Pattern 1: Refactoring CalDAV Internals While Adding the Interface
 
-The wizard is a frontend flow over the same admin API. Do not create `/api/setup/credentials` alongside `/api/admin/credentials`. One route, two callers (wizard + Settings page).
+Do not inline-refactor `sync.ts`, `write.ts`, `vevent.ts` internals as part of the provider abstraction phase. Wrap them as-is in `CalDavProvider`. Refactoring internals and adding the interface in the same phase doubles the risk surface. Internal cleanup is a separate concern if ever needed.
 
-### Anti-Pattern 2: Storing env-var secrets in the DB
+### Anti-Pattern 2: Storing Google OAuth Tokens in `app_config`
 
-VAPID private keys and `APP_PASSWORD_ENCRYPTION_KEY` must stay in env vars — they are the bootstrap secrets that protect everything else. The wizard generates and displays them for the operator to copy; it never writes them to the `app_config` table or any other DB table.
+The `app_config` table is a global key/value store for non-sensitive config. Google OAuth tokens are per-member secrets with a refresh lifecycle. They belong in `provider_tokens` with AES-256-GCM encryption and cascade-delete on user removal. Never put them in `app_config`.
 
-### Anti-Pattern 3: Reintroducing node-cron
+### Anti-Pattern 3: Using the Google OAuth Callback to Establish App Login
 
-The codebase uses `setInterval` throughout because node-cron 4.2.1 silently skips ticks in the long-running process (documented in every worker file's header comment). Do not use `node-cron` for any new scheduled work in v1.1. The event-driven drain replaces the need for a tighter interval; the 15s `setInterval` fallback is already correct.
+The Google OAuth callback (`/api/calendar-connect/google/callback`) is for calendar access only. The app login session is established separately via Authelia OIDC or local auth. Do not attempt to merge these two OAuth flows -- they serve different purposes and must remain independent auth paths.
 
-### Anti-Pattern 4: Adding VALARM to all-day events
+### Anti-Pattern 4: Schema Migration Without Data Migration
 
-RFC 5545 duration-form TRIGGER (`-PT15M`) is semantically valid only for timed events. For all-day events it requires `RELATED=END` or a DATE-form trigger. Fastmail may accept it regardless, but the semantics are wrong and would yield confusing reminder times. Guard in `buildVeventString`: `if (!params.allDay && params.reminderMinutes > 0)`. Disable the reminder selector in `EventForm.tsx` when `allDay = true`.
+The rename from `reminder_lead_minutes` (INT) to `reminder_leads` (JSON) is a breaking change. The migration MUST include a `UPDATE calendar_events SET reminder_leads = JSON_ARRAY(reminder_lead_minutes) WHERE reminder_lead_minutes IS NOT NULL` step before dropping the old column. Without this, existing event reminders are silently lost.
 
-### Anti-Pattern 5: Dedup key includes lead time in reminderScheduler
+### Anti-Pattern 5: Per-Provider `isDraining` Flags
 
-The existing `sentReminders: Map<uid, dtstartMs>` keyed by bare uid is correct and must not be changed to `uid:leadMinutes`. A keyed `uid:lead` would cause double-fire if the event is rescheduled (new dtstart, same uid) or if the lead changes. The bare uid key + dtstart-based pruning is the correct exactly-once guarantee — leave it intact.
-
-### Anti-Pattern 6: Concurrency guard changes in outboxWorker
-
-The `isDraining` module-level boolean guard is the correct concurrency mechanism for the single-process deployment. Do not add a second guard, change it to an async mutex, or introduce Redis-based locking for the drain. The event-driven signal adds a new call site but does not require any guard changes — the existing guard already handles simultaneous invocations.
-
----
-
-## Integration Points
-
-### External Services
-
-| Service         | Integration                                | v1.1 Notes                                                                     |
-| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
-| Fastmail CalDAV | tsdav PUT with VCALENDAR containing VALARM | VALARM is inert to Fastmail's CalDAV server (stored as-is); sync reads it back |
-| Authelia OIDC   | No change                                  | Setup wizard is post-OIDC; admin routes use existing OIDC session              |
-
-### Internal Module Boundaries
-
-| Boundary                                     | Communication                                           | Notes                                           |
-| -------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
-| `routes/events.ts` → `outboxWorker.ts`       | `signalOutboxDrain()` via EventEmitter                  | NEW: fire-and-forget, one-way                   |
-| `routes/admin.ts` → `broker/crypto.ts`       | Direct import of `encryptPassword`                      | REUSE existing module — no changes to crypto.ts |
-| `routes/setup.ts` → `db/schema.ts` appConfig | Drizzle queries                                         | NEW table, same db client and connection pool   |
-| `broker/vevent.ts` → `ical.js`               | `ICAL.Component('valarm')`, `ICAL.Duration.fromSeconds` | EXTEND existing ical.js usage                   |
-| `broker/sync.ts` → `db/schema.ts`            | Store `reminderLeadMinutes` in events upsert            | MODIFY existing upsert path in syncCalendar     |
-| `reminderScheduler.ts` → `db/schema.ts`      | Read `reminder_lead_minutes` in Drizzle query           | MODIFY existing query; raw SQL expression       |
+The outbox worker's `isDraining` module-level flag is documented as single-process-only. This remains valid for v1.2 (still single-process). Do not introduce per-provider drain locks -- the existing guard covers all rows from all providers in the same drain cycle.
 
 ---
 
 ## Sources
 
-All findings are grounded in direct codebase inspection:
-
-- `apps/api/src/broker/outboxWorker.ts` — drain loop, `isDraining` guard, durability decisions (D-04/D-07/D-08/CR-05)
-- `apps/api/src/broker/reminderScheduler.ts` — scheduler logic, dedup map, fixed-window rationale (D-05/D-06/D-12)
-- `apps/api/src/broker/vevent.ts` — `buildVeventString`, `NewEventParams`, ical.js RRULE pattern (VALARM follows same API)
-- `apps/api/src/broker/crypto.ts` — `encryptPassword`/`decryptPassword`; confirmed reusable by admin routes
-- `apps/api/src/db/schema.ts` — table definitions; migration impact analysis
-- `apps/api/src/routes/events.ts` — `eventFieldsSchema`, `outboxPayloadSchema` contract, IN-03 duplication requirement
-- `apps/api/src/lib/listEmitter.ts` — in-process EventEmitter precedent for `outboxTrigger.ts`
-- `apps/pwa/src/components/EventForm.tsx` — full form state machine; integration points for reminder selector
-- `apps/pwa/src/components/SettingsSheet.tsx` — existing Settings surface; Admin section attachment point
-- `apps/api/src/index.ts` — route mounting order, OIDC guard placement, `isMainModule` guard pattern
-- `apps/api/src/routes/me.ts` — `/api/me` response shape; where `isAdmin` is added
-- `apps/api/tests/` — test directory layout confirms tests in `tests/`, not `src/`; `helpers/db.ts` pattern
+- Direct codebase inspection: `apps/api/src/broker/`, `apps/api/src/db/schema.ts`, `apps/api/src/index.ts`, `apps/api/src/auth/`, `apps/pwa/src/styles/tokens.css`
+- `docs/ARCHITECTURE.md` -- existing component diagram and data-flow walkthroughs
+- `.planning/PROJECT.md` -- v1.2 milestone scope and key decisions
 
 ---
-
-_Architecture research for: FamilySync v1.1 Operability & Polish_
-_Researched: 2026-06-10_
+*Architecture research for: FamilySync v1.2 Multi-Provider integration*
+*Researched: 2026-06-19*
diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md
index fcad5d4..6466fff 100644
--- a/.planning/research/FEATURES.md
+++ b/.planning/research/FEATURES.md
@@ -1,306 +1,361 @@
 # Feature Research
 
-**Domain:** Self-hosted family organization hub — operability & polish milestone (v1.1)
-**Researched:** 2026-06-10
-**Confidence:** HIGH (v1.0 is shipped; v1.1 features are well-understood domain problems with clear prior art)
+**Domain:** Family calendar PWA — v1.2 new capabilities (multi-provider, theming, zero-setup DB, dev/CI stub)
+**Researched:** 2026-06-19
+**Confidence:** MEDIUM (Google Calendar API: MEDIUM via Context7/official docs; UX patterns: LOW via websearch, cross-checked across multiple sources and grounded in the existing codebase)
 
 ---
 
 ## Scope of This Document
 
-This document covers **only the six v1.1 features**. v1.0 features (calendar, event CRUD, lists, push, OIDC, PWA) are shipped and validated; they are listed as dependencies, not re-researched here.
+This document covers **only the six v1.2 feature areas**. v1.0/v1.1 features (calendar display, event CRUD, lists, push, OIDC, local auth, admin settings, setup wizard, per-event reminders, CI harness) are shipped and validated; they appear only as dependencies here.
 
 ---
 
-## Feature Landscape
+## Category 1: Multi-Provider Calendar Support
 
-### Table Stakes (Users Expect These)
+### What "Good" Looks Like
 
-Features that must exist in v1.1 to avoid the product feeling unfinished for real household use.
+Apps like Skylight, Cozi, Morgen, and Fantastical converge on the same model: each provider/calendar account gets a unique color lane; events are visually identified by their source calendar's color; event detail view names the source calendar. Provider selection on event creation is a calendar/account dropdown that defaults to a configured "default calendar" — the user picks which calendar to write to before saving.
 
-| Feature                                   | Why Expected                                                                                                                                                                                                                                                 | Complexity | Notes                                                                                                                                                                                                                             |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Per-event reminder selector on event form | Every calendar app (Apple, Google, Fastmail) has this. The current hardcoded 15-min is a bug, not a feature.                                                                                                                                                 | MEDIUM     | Drop-down of offsets (None / 5 min / 10 min / 15 min / 30 min / 1 hour / 2 hours / 1 day / 2 days) written as VALARM TRIGGER:-PTxM/H or TRIGGER:-P1D in the .ics. "None" default = no VALARM element emitted.                     |
-| "None" is the default alarm state         | Apple Calendar defaults new events to "None" alert unless the user has changed their Calendar > Settings > Alerts default. Google Calendar defaults to "30 minutes". The PWA should mirror "None" as the explicit no-alarm state — no alarm = no push.       | LOW        | Must not silently inherit a global default from Fastmail's own app-password user preferences. Emit no VALARM when "None".                                                                                                         |
-| Preserve existing VALARMs on edit         | If an event was created in Apple Calendar or Fastmail's native client with a specific reminder, editing it in the PWA must not silently strip that reminder.                                                                                                 | MEDIUM     | tsdav + ical.js round-trip: parse VALARM on fetch, display the closest-matching preset (or "custom" fallback), write back on save. Explicitly handle the case where an existing VALARM is not in the preset list.                 |
-| Scheduler honors per-event lead           | The push scheduler must fire at `event_start - trigger_offset`, not a hardcoded 15 min. If no VALARM, fire nothing.                                                                                                                                          | MEDIUM     | Depends on outbox/scheduler already built in v1.0. Requires storing the absolute fire-time in the DB so the scheduler does not re-parse ical on every tick.                                                                       |
-| Admin Settings UI (role-gated)            | Self-hosted apps cannot require SSH/DB-console access for routine admin. The two tasks (rotate app password, mark shared calendar) are operator-level but must be doable from the browser.                                                                   | MEDIUM     | Single admin flag on the users row; admin sees a Settings section hidden from the other member. Both tasks are currently manual DB writes — table stakes to remove that dependency.                                               |
-| Initial setup wizard (first run)          | Without a wizard, first-time deploy requires hand-editing env files in the right order, running VAPID key generation manually, and hoping the DB connection string is correct. Nextcloud/Gitea/Authelia all ship a first-run wizard for exactly this reason. | HIGH       | Gate on a `setup_complete` flag persisted in the DB or a dotfile. Must validate each credential before advancing: DB ping, OIDC discovery endpoint reachable, VAPID keys structurally valid, app password CalDAV test connection. |
-| Event-driven outbox drain                 | Current ~15s latency (polling interval) makes edits feel sluggish when the user sees the event unchanged for 10+ seconds after saving. Every other calendar app (Google, Apple, Fastmail native) round-trips writes in under 2 seconds perceived.            | MEDIUM     | The existing transactional outbox guarantees durability. The fix is to trigger an immediate drain on INSERT to the outbox table, rather than waiting for the next scheduled tick.                                                 |
+There is no industry-standard "provider badge icon" per event in the calendar grid. Color is the primary (and sufficient) differentiator; the calendar name in the event detail view is the secondary indicator.
 
-### Differentiators (Competitive Advantage for This Product)
+### Table Stakes
 
-Features that go beyond what a user would minimally expect — meaningful for this specific 2-person self-hosted context.
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Google Calendar events visible in the unified view alongside Fastmail events | The core value of multi-provider is the unified display; without it there is no v1.2 | HIGH | Requires provider abstraction (prerequisite) + Google Calendar API integration + self-service onboarding |
+| Per-calendar color assignment covering Google calendars | Users expect events to be visually distinct by source; Skylight and Cozi both do this | LOW | Phase 17 color-routing already exists for Fastmail; extend the same mechanism to cover Google calendar IDs |
+| Calendar picker on event creation — select which calendar/provider to write to | Without this, writes go to an ambiguous default; users lose trust in where events land | MEDIUM | Lists all writable calendars across all connected providers; defaults to the member's "default calendar" setting; requires the provider abstraction to expose a unified calendar list |
+| Calendar name shown in event detail view | Users need to know where the event lives, especially when both Fastmail and Google events are visible | LOW | Extend the existing event detail sheet with a "Calendar: [name]" line; already implicit in the data model |
 
-| Feature                                                  | Value Proposition                                                                                                                                                                                                                                                                                                                   | Complexity | Notes                                                                                                                                                                                                                                                                                                     |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Multiple reminders per event (up to 2)                   | Apple Calendar supports multiple alerts per event. The iCalendar spec (RFC 5545) allows multiple VALARM components in one VEVENT. Most household events benefit from a "1 day before" + "30 min before" pair.                                                                                                                       | MEDIUM     | Add a second optional reminder offset selector on the form. Emit two VALARM blocks in the .ics. Parse up to 2 existing VALARMs. Do not expose this in v1.1 if it risks slipping the phase; single-alarm is the floor.                                                                                     |
-| All-day event reminder semantics matching Apple Calendar | Apple Calendar fires all-day alerts at 9 AM on the alert day (same day or 1 day before, etc.), not at 00:00. Google Calendar fires at 11:50 PM the night before for a "10-min" all-day offset, which is jarring. The Apple convention (morning-of) is the correct UX for this household's non-technical Apple member.               | LOW        | When the event is all-day and the reminder offset is "on the day" or "1 day before", the VALARM TRIGGER is written as a day-relative offset (`TRIGGER:-P1D` or `TRIGGER:P0D`). The scheduler fires at 9:00 AM on the resolved day (not midnight). This is a scheduler config constant, not user-settable. |
-| CI regression gating on PR                               | Prevents the class of regressions introduced during v1.0 (tsc passes but runtime breaks, API test failures not caught until manual verify). Gitea Actions is already available on the self-hosted Gitea instance.                                                                                                                   | MEDIUM     | Lint + typecheck (both apps) + unit tests (Vitest) + API integration tests against a MariaDB service container. Fails PR merge if any step fails. Significantly reduces the human verification burden per phase.                                                                                          |
-| Mobile-emulated Playwright test harness                  | The CLAUDE.md preference is to use playwright-cli for validation rather than asking the operator. A mobile-emulated (iPhone viewport, touch, user-agent) authenticated harness lets the assistant catch mobile-only layout regressions, modal overflow, and form usability issues before handing off for iOS-hardware verification. | MEDIUM     | Playwright `devices['iPhone 15']` or equivalent device preset, session reuse via `storageState`, DEV_AUTH_BYPASS=true for CI. Does not replace real-device iOS tests (push, standalone mode).                                                                                                             |
-| Docker image publish from CI                             | Currently the image is built manually. Auto-publishing on merge to main means Unraid can pull the latest image without an SSH session.                                                                                                                                                                                              | LOW        | Gitea Packages registry or Docker Hub. Triggered on PR merge to main (not on every PR).                                                                                                                                                                                                                   |
+### Differentiators
 
-### Anti-Features (Explicitly Exclude)
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| Cross-provider event create — write to Fastmail or Google per event | Household members write to whichever calendar they actually use natively | MEDIUM | Write path must route to the correct provider's outbox; clean once the provider abstraction exists |
+| Per-provider sync status indicator visible in the calendar view header or Settings | Non-technical users immediately see if a provider is disconnected without hunting through menus | LOW | Badge or dot on provider icon; links to Settings for reconnect action |
 
-Features that appear reasonable but are wrong for a 2-person self-hosted household. Flag these as scope creep.
+### Anti-Features
 
-| Feature                                                                                  | Why Requested                                                                                                                           | Why to Exclude                                                                                                                                                                                                                                                      | What to Do Instead                                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| User-facing notification preferences page (per-member mute, granular notification types) | Every commercial app has this. Feels like a natural extension of reminder settings.                                                     | Two users, both presumably want reminders. This adds a settings surface that 100% of users must click through and that creates support burden (why am I not getting reminders?). The non-technical member should never need to configure this.                      | Set sensible defaults (all push types on) and never ask. If one member doesn't want push, they decline the browser permission prompt — the OS handles it.                                     |
-| Reminder "snooze" in the notification payload                                            | RFC 9074 defines a snooze mechanism via sibling VALARM components. Fantastical supports it.                                             | Implementing reliable snooze requires creating a new VALARM in the .ics (PUT back to Fastmail) from the service worker notification click handler. That is a write path triggered from a background service worker — a significant reliability and complexity risk. | Dismiss and re-add a reminder manually if needed. The use case is too rare for this household to justify the implementation risk.                                                             |
-| Setup wizard re-run / reset                                                              | Advanced users might want to re-run parts of the wizard (e.g., rotate VAPID keys).                                                      | For a 2-person deployment, the operator can edit the env file or use the Admin Settings page for app-password rotation. A re-runnable wizard adds state-management complexity (partial completion, rollback).                                                       | Admin Settings covers the post-setup operational cases (app password rotation, shared calendar designation). VAPID key rotation is a documented manual step (generate, update env, redeploy). |
-| Full audit log in Admin Settings                                                         | Some self-hosted admin panels (Gitea, Nextcloud) ship an audit log of administrative actions.                                           | Two users. Both equal operators. There is no adversarial scenario between two family members that requires an audit trail.                                                                                                                                          | N/A — omit entirely.                                                                                                                                                                          |
-| Calendar provider abstraction / plugin system                                            | Would make the admin panel a "configure any CalDAV provider" experience.                                                                | The constraint is Fastmail + this specific household. A provider abstraction layer adds 3x the surface area for zero current benefit.                                                                                                                               | Hard-code Fastmail CalDAV principal discovery. Document the URL in the admin panel for transparency. If a second provider is ever needed, add it as a targeted feature in v2.                 |
-| Self-service member onboarding via wizard                                                | The setup wizard bootstraps the operator. Member onboarding (per-member app password collection) is a distinct problem (backlog 999.5). | Mixing these into one wizard creates a flow that only the operator completes — the other member would encounter a half-configured wizard.                                                                                                                           | Keep operator setup wizard and member onboarding as separate concerns. Admin Settings covers the operator side of member credential management.                                               |
-| Health dashboard / status page in Admin Settings                                         | Uptime graphs, service health indicators, DB query stats. Seen in Nextcloud admin.                                                      | Single Docker host, two users. If the app is down, both users know immediately. There is no ops team monitoring this.                                                                                                                                               | Docker logs + Unraid dashboard are sufficient. The setup wizard validates connectivity once; that is the only point of truth needed.                                                          |
-| E2E test suite that runs on real iOS Safari                                              | Complete mobile coverage in CI                                                                                                          | Real iOS Safari requires physical device or paid cloud service (BrowserStack). Not reproducible in a self-hosted Gitea runner.                                                                                                                                      | Playwright mobile emulation covers layout/interaction. Real-device iOS tests remain a human gate for push + standalone mode (as in v1.0).                                                     |
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Automatic color re-assignment when a new provider is added | Seems helpful to "harmonize" colors | Scrambles existing user expectations — the wife has learned which color means which calendar | Keep existing Fastmail calendar colors; assign new Google calendar colors from unused palette slots |
+| Two-way sync between Fastmail and Google (event mirroring) | "I want the same event on both calendars" | Infinite loop risk; duplicate events; out of milestone scope | Each event lives in exactly one provider; the unified view makes this invisible to the user |
+| CalDAV subscription URL for Google Calendar | Some power users subscribe to Google Calendar via CalDAV | Google deprecated unauthenticated CalDAV access; fragile and undocumented workaround | Use the Google Calendar REST API directly (already planned) |
+
+### Complexity and Dependencies
+
+- **Keystone dependency:** The `CalendarProvider` interface (provider abstraction) must be defined and Fastmail refactored behind it before Google can be added as a second implementation. This must be Phase 21.
+- Depends on: **Self-service onboarding** (Category 2) — Google events cannot appear until the member has connected their Google account.
+- Existing feature dependency: the Fastmail broker in `apps/api/src/broker/` must be refactored behind a `CalendarProvider` interface; this is the highest-complexity step in v1.2.
+
+---
+
+## Category 2: Self-Service Provider Onboarding
+
+### What "Good" Looks Like
+
+The industry-standard pattern (GoHighLevel, Zapier, Morgen, Fantastical) distinguishes two onboarding flows:
+
+- **App-password providers (Fastmail):** Short form — credential input + optional endpoint URL + "Verify & Save" button. Live validation: the app attempts a CalDAV PROPFIND before persisting. Error state names the problem in plain language ("Wrong password", "Can't reach Fastmail").
+- **OAuth providers (Google):** Single "Connect Google Calendar" button → browser redirect to Google's consent screen → user approves → redirect back with auth code → app exchanges for access + refresh tokens → stores encrypted refresh token in DB. The token is never shown to the user.
+- **Status indicators:** After connection, each provider shows a health badge (green = healthy, yellow = expiring soon, red = disconnected). The red state shows a prominent "Reconnect" button — one tap re-runs the OAuth flow without removing and re-adding the connection.
+
+The reconnect pattern is non-negotiable for the non-technical Apple member. When her Google token expires (password change, 6-month inactivity, suspicious activity), she must see a visible banner in the calendar view — not discover the problem by noticing missing events days later.
+
+### Table Stakes
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| "Connect Google Calendar" OAuth button in member Settings | OAuth is the expected UX for Google — no one expects to paste an API key | MEDIUM | `googleapis` `generateAuthUrl({access_type:'offline', scope:['https://www.googleapis.com/auth/calendar']})` + callback route + store encrypted refresh token in `member_credentials` |
+| One-tap "Reconnect" button when Google token expires or is revoked | Token churn is inevitable; must not require removing and re-adding the connection | MEDIUM | Re-runs the OAuth flow; existing `member_credentials` row updated in place |
+| Fastmail app-password form with live CalDAV validation (member self-service) | Fastmail credential entry already exists in admin (Phase 10); now surfaced to the member in their own Settings | LOW | Reuse/move the existing `CredentialSheet` component and `/api/me/credential` route from Phase 10; already validated |
+| Connection health status per provider shown in member Settings | Non-technical users need ambient awareness that their calendar is connected | LOW | `GET /api/me/providers` returns per-provider status; show green/red indicator per entry |
+| Error states that name the problem without technical jargon | "Your Google Calendar isn't connected" not "401 Unauthorized" | LOW | UX copy layer over API error codes; inline on the Settings page |
+| Proactive disconnect banner on the calendar view itself | User sees the issue before discovering missing events | LOW | Banner above the calendar when any provider is in error state; links to Settings reconnect |
+
+### Differentiators
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| "Test connection" re-check button after credential save | Confirms the connection still works without navigating away | LOW | Same live-validation call as initial save; reusable endpoint |
+
+### Anti-Features
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Service-account / server-side Google auth (one token for the whole app) | Seems simpler | Service account can only access calendars it owns; per-user OAuth is required to write to a member's own Google Calendar | Per-user OAuth with per-member refresh token stored in `member_credentials` |
+| Storing Google OAuth tokens in a browser cookie or localStorage | Convenient for the frontend | Security anti-pattern — long-lived refresh tokens can be exfiltrated from the client | Encrypt and store in `member_credentials` table server-side, same as Fastmail app passwords |
+| JMAP for Fastmail calendar connection | Seems natural given Fastmail's JMAP investment | JMAP Calendar API is not available on Fastmail as of 2026 | CalDAV via tsdav (locked decision, documented in CLAUDE.md) |
+
+### Google OAuth Technical Notes (MEDIUM confidence — official docs via Context7)
+
+- Scope: `https://www.googleapis.com/auth/calendar` — read + write events + calendar list. Classified as a "restricted" scope but **no Google verification is required** for self-hosted personal apps with fewer than 100 users (all known to the operator).
+- `access_type: 'offline'` is required to receive a refresh token on the first authorization.
+- Refresh tokens are only issued on first authorization unless `prompt: 'consent'` is forced. Listen for the `tokens` event and persist immediately.
+- Token auto-refresh: setting `oauth2Client.setCredentials({refresh_token})` causes `googleapis` to auto-refresh the access token transparently — no manual refresh loop needed in normal operation.
+- Revocation handling: catch `err.status === 401` from `refreshAccessToken()`, clear the stored token from DB, surface the reconnect banner.
+- Google's refresh token revocation triggers: user changes Google password, user revokes app access in Google account settings, Google detects suspicious activity, token unused for 6 months.
+
+### Complexity and Dependencies
+
+- Depends on: **Provider abstraction** (Category 1) — credentials are stored and managed per-provider through the abstraction.
+- Existing feature dependency: `member_credentials` table exists (Phase 10); needs `provider_type = 'google'` and an encrypted `refresh_token` column.
+- Existing feature dependency: admin credential rotation patterns from Phase 10 are directly reusable for self-service credential management.
+- OAuth callback route must work inside the Safari standalone PWA on iOS — same constraint as the Authelia OIDC redirect in Phase 3 (load-bearing; must be validated on device).
+
+---
+
+## Category 3: Multiple Reminders Per Event
+
+### What "Good" Looks Like
+
+Google Calendar: unlimited reminders via an "Add notification" link below the reminder list; each row is a lead-time picker + remove button. Apple Calendar: hard cap of 2 alerts ("Alert" + "Second Alert" fields — no add button beyond 2). Outlook: up to 2. Morgen: follows Google's unlimited model.
+
+For a family PWA, cap at 5 reminders. Real-world usage clusters at 1–2 per event ("1 day before" + "30 min before" is the canonical pair). The UI pattern is a vertical list of reminder rows, each with the existing lead-time picker and an X (remove) button; an "Add reminder" link below the list is disabled once the cap is reached.
+
+### Table Stakes
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Add up to 5 reminders per event (list UI with add/remove per row) | Google Calendar sets this expectation; "1 day before AND 30 min before" is the most common household pattern | MEDIUM | The existing `reminderLeadMinutes` single-integer field (Phase 11) must be refactored to an array. VALARM serialization already exists (`buildTimedValarm`/`buildAllDayValarm`) — extend to emit N VALARMs |
+| Remove any individual reminder from the list | Without remove, users accumulate unwanted reminders over time | LOW | X button on each reminder row; list collapses to empty = no reminder (same as "None" today) |
+| Pre-populate all existing reminders on event edit | Phase 11 pre-populates one reminder; must now pre-populate all N | LOW | `classifyValarms`/`extractValarms` (Phase 11) already return arrays — thread the full array to the form |
+| Sensible cap with clear feedback | Prevents absurd configurations (10+ reminders per event) | LOW | Cap at 5; "Add reminder" link grays out at cap; no error toast needed |
+| Google Calendar provider: translate reminders to `event.reminders.overrides` format | Google Calendar uses `{method:'popup', minutes:N}` objects, not VALARM | MEDIUM | The provider abstraction's write path translates the internal reminder array to the correct format per provider; Fastmail → VALARMs, Google → `reminders.overrides` |
+
+### Differentiators
+
+None — multiple reminders is table stakes from Google Calendar's baseline. Doing it without reminder duplication on edit and without stripping non-FamilySync VALARMs is what good execution looks like.
+
+### Anti-Features
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Reminder templates ("always remind me 1 day before for all my events") | Seems like a time-saver | Premature complexity; per-event reminder list already covers the use case | Per-event reminder list; per-user default reminder is a v1.3 consideration |
+| Reminder snooze from the notification payload | RFC 9074 defines this; Fantastical supports it | Requires a write back to the calendar from the service worker notification handler — a high-complexity, high-fragility path for a rare use case | Dismiss; re-add a reminder manually if needed |
+
+### Complexity and Dependencies
+
+- Depends on: existing `reminderLeadMinutes` single-value field (Phase 11) — must migrate to a JSON array column (additive migration; old column deprecated, not dropped, to avoid downtime).
+- Existing feature dependency: `buildTimedValarm`/`buildAllDayValarm`/`classifyValarms`/`extractValarms`/`computeAlertInstantUtc` in the broker (Phase 11) — all handle arrays natively (ical.js returns arrays); only the serialization call site changes.
+- Existing feature dependency: variable-lead scheduler (Phase 11) — must schedule N reminders per event; dedup key changes from `uid:dtstartMs` to `uid:dtstartMs:leadMinutes`.
+- Ordering note: this can be implemented in parallel with provider abstraction, but the Google provider translation layer (`reminders.overrides`) is naturally built alongside the Google provider (Category 1/2).
+
+---
+
+## Category 4: PWA Dark Mode / Theming
+
+### What "Good" Looks Like
+
+Three options: System (follows OS `prefers-color-scheme`), Light, Dark. The toggle lives in user Settings — not admin-only, both members control their own theme independently. Preference is persisted in localStorage (no server round-trip; no DB column needed). No flash-of-wrong-theme (FOIT) on load.
+
+Phase 17 already shipped semantic CSS custom properties (`tokens.css`) on `:root` — the groundwork is done. Dark mode requires: a `[data-theme="dark"]` override block in `tokens.css`, a blocking inline script in `index.html` `<head>` to set the attribute before first paint, and a three-option toggle in Settings.
+
+### Table Stakes
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Respect OS `prefers-color-scheme` by default | Every modern app does this; iOS Dark Mode is heavily used by Apple users | LOW | CSS-only: `@media (prefers-color-scheme: dark)` override for `[data-theme="system"]` tokens; no JS needed for system mode |
+| Explicit System / Light / Dark toggle in Settings | Users override OS preference for specific apps routinely | LOW | Three-option segmented control in the Settings page (not admin-gated) |
+| No flash-of-wrong-theme on PWA load | FOIT is jarring and immediately noticeable — the non-technical Apple member will notice | MEDIUM | Blocking inline `<script>` in `index.html` `<head>` reads `localStorage` and sets `data-theme` synchronously before Vite's JS bundle parses; must be a raw inline script (not `type="module"`) |
+| Preference persisted in localStorage | Theme must survive PWA re-launch and page refresh | LOW | `localStorage.setItem('theme', 'dark'|'light'|'system')` on toggle; read in the inline init script |
+| Calendar event colors readable in dark theme | Color-coded lanes are the core UX — they must not become unreadable on dark backgrounds | MEDIUM | Ensure hue-based event colors (rose, blue, amber) have sufficient contrast on the dark surface token; may need adjusted lightness values in the dark token override block |
+
+### Differentiators
+
+None — dark mode is table stakes in 2026 for any consumer app. The differentiator is doing it without FOIT.
+
+### Anti-Features
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Per-member theme synced to the server (follows you across devices) | "My theme should be consistent on any device" | Adds a DB column + API round-trip for a cosmetic preference; minimal benefit for a 2-person household | localStorage only; set the preference on each device separately |
+| Custom color theme editor | Power user appeal | Scope creep; the semantic token system supports it eventually but not in v1.2 | System/light/dark is the complete feature for this milestone |
+
+### Complexity and Dependencies
+
+- Depends on: Phase 17 semantic token layer (`tokens.css`) — already shipped; this feature extends it with a dark override block.
+- Low implementation risk — primarily CSS changes plus a small inline script in `index.html`.
+- Vite note: the blocking inline script must be injected into `index.html` as a literal string (use Vite's HTML transform plugin or a direct `<script>` tag in `index.html`). It cannot be an ES module (`type="module"`) because modules are deferred and execute after paint.
+- Independent of all other v1.2 features — can be developed in a parallel phase with no ordering constraint.
+
+---
+
+## Category 5: Zero-Manual-Setup DB Bootstrap
+
+### What "Good" Looks Like
+
+The operator provides a MariaDB host, port, DB name, username, and password in env vars. On `docker compose up`, the API boots, calls Drizzle's `migrate()` programmatically before the HTTP server starts accepting requests, and all tables are created. On subsequent boots, `migrate()` is idempotent — already-applied migrations are skipped via the `__drizzle_migrations` tracking table. The operator never runs `drizzle-kit migrate` manually.
+
+### Table Stakes
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| Programmatic `migrate()` call in API boot sequence, before `serve()` starts | Self-hosted operators expect "docker compose up and it works" — hand-running CLI migrations is a deployment barrier | LOW | `import { migrate } from 'drizzle-orm/mysql2/migrator'`; call in `apps/api/src/index.ts` before the Hono server binds; wrap in try/catch with `process.exit(1)` on failure |
+| Idempotent on repeated boot | Containers restart; migrations must not fail on the second run | LOW | Built into drizzle-kit migrate: tracks applied migrations in `__drizzle_migrations`; already-applied migrations are no-ops |
+| DB readiness wait before migrating | The MariaDB container may not be ready when the API container starts | LOW | Retry loop (5 attempts, 2s exponential backoff) using `SELECT 1` before calling `migrate()`; `process.exit(1)` after all retries fail with a clear log message |
+| Migration failure = fatal startup with a clear log message | Silent failure leaves the app running against a broken schema | LOW | `console.error('DB migration failed:', err)` + `process.exit(1)` |
+
+### Differentiators
+
+None — zero-setup bootstrap is the baseline operator expectation for modern self-hosted apps. Meeting it cleanly is the goal; there is no competitive angle here.
+
+### Anti-Features
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| `drizzle-kit push` in production | Simpler — no SQL migration files to manage | Destructive on schema conflicts; drops columns without warning; not safe for a production DB with real user data | `drizzle-kit generate` (committed SQL files) + programmatic `migrate()` at boot |
+| App creates the database itself (not just tables) | Operators shouldn't need to pre-create the DB | Requires elevated `CREATE DATABASE` privileges that operators may not want to grant the app user | Document in deployment guide: "create a database named `familysync` and grant your app user full access to it" — 30 seconds of manual setup that avoids privilege escalation |
+
+### Complexity and Dependencies
+
+- Depends on: existing Drizzle migration files in `apps/api/src/db/migrations/` (all phases — already exist).
+- Existing constraint from Phase 8/16 (D-20): MariaDB 11 does not have `mysqladmin ping`; the in-app readiness check must use a raw `SELECT 1` query via `mysql2`, not any CLI command.
+- Low implementation risk: `drizzle-orm/mysql2/migrator` is already a transitive dependency; only the boot sequence wiring is new code.
+- Enables: the existing setup wizard (Phase 12) to assume the schema exists when it runs — clean separation of concerns (schema bootstrap → setup wizard → admin config).
+
+---
+
+## Category 6: Dev-User Full-App Exercise (Stub Calendar Provider)
+
+### What "Good" Looks Like
+
+A `StubCalendarProvider` that implements the same `CalendarProvider` interface as Fastmail and Google, returning deterministic seed events from memory and mutating an in-memory Map on writes. Activated by `CALENDAR_PROVIDER=stub` (implicitly active alongside `DEV_AUTH_BYPASS=true`). The Playwright CI harness uses the stub so tests are hermetic — no live CalDAV or Google API calls, no Fastmail credentials required in CI.
+
+Seed events must cover: timed events, all-day events, a recurring weekly series, events with reminders, past events, and future events — enough to exercise the full UI, reminder pipeline, and RRULE expansion without gaps.
+
+### Table Stakes
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| `CalendarProvider` interface with `fetchEvents`, `createEvent`, `updateEvent`, `deleteEvent` | Required before any stub can exist; is also the keystone for provider abstraction (Category 1) | MEDIUM | Define in `apps/api/src/broker/providers/CalendarProvider.ts`; Fastmail and Google are implementations; stub is the third |
+| Stub provider with seeded deterministic events | Developers and CI must exercise full event CRUD + reminder + multi-provider display without a live calendar | MEDIUM | In-memory `Map<string, CalendarEvent>`; seed data covers event varieties needed by Playwright tests; writes mutate the map and are visible to subsequent fetches in the same process |
+| Stub activated by env var (`CALENDAR_PROVIDER=stub`) | Must be opt-in; never active in production | LOW | Read env at startup in provider resolution; route `CalendarProvider` selection accordingly |
+| Stub integrated with Playwright CI harness | The existing CI harness (`DEV_AUTH_BYPASS=true`) must also activate the stub so calendar tests pass without Fastmail credentials | LOW | Add `CALENDAR_PROVIDER=stub` to the CI workflow env block alongside `DEV_AUTH_BYPASS=true`; no other change needed |
+| Reminder scheduling works against stub events | Exercises the full reminder pipeline in CI without live events | LOW | Stub seed data includes events with reminder leads set; the scheduler fires against them normally |
+
+### Differentiators
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| Stub resets on API restart (intentionally stateless) | Keeps CI tests hermetic — no state leaks between test runs | LOW | In-memory Map is wiped on process restart; document this behavior explicitly |
+| Seed events designed to cover Phase 11 edge cases | Exercises RRULE expansion, all-day timezone handling, multi-VALARM, and past/future reminder scheduling in CI | MEDIUM | Design seed data to match the Phase 11 test matrix: one recurring weekly event, one all-day multi-day event, one event with 2 reminders, one past event, one future event with 2-day reminder lead |
+
+### Anti-Features
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| Persisting stub events to SQLite or a test-specific MariaDB table | "So writes survive restart in dev" | Adds a dependency; defeats the hermetic purpose of a stub; blurs the line between dev and test state | Use a real Fastmail or Google provider for persistent personal dev; stub is for CI only |
+| Shared stub state across parallel Playwright workers | Enables cross-test assertions | Race conditions on concurrent create/delete cause flaky tests | Each test must be self-contained; rely on seed data, not prior-test writes |
+
+### Complexity and Dependencies
+
+- Depends on: **`CalendarProvider` interface** — the stub is the third implementation; the interface must be defined before the stub can exist.
+- Ordering note: the stub is needed early in v1.2 to unblock Playwright CI testing of multi-provider features before live Google credentials are available in CI. It should be implemented in Phase 21 alongside the provider interface.
+- Existing feature dependency: `DEV_AUTH_BYPASS` pattern (Phases 7/8/13) — piggyback on the same env-var convention; no new CI infrastructure required.
 
 ---
 
 ## Feature Dependencies
 
 ```
-[Per-event reminder UI]
-    └──requires──> [Event create/edit form] (v1.0, shipped)
-    └──requires──> [VALARM parse on CalDAV fetch] (tsdav + ical.js, v1.0 partial)
-    └──requires──> [Push scheduler with per-event fire time] (outbox/scheduler, v1.0 shipped)
-                       └──enhanced by──> [Faster write-back] (drain triggers scheduler sooner)
+CalendarProvider interface (provider abstraction)
+    ├──required by──> Fastmail broker refactor (existing broker → implements interface)
+    ├──required by──> Google Calendar provider implementation
+    ├──required by──> Stub provider (dev/CI mode)
+    └──required by──> Calendar picker on event creation (needs unified provider list)
 
-[Faster write-back]
-    └──requires──> [Transactional outbox] (v1.0, shipped)
-    └──enhanced by──> [Per-event reminder UI] (alarm fire times stored at write time)
+Stub provider
+    └──enables──> hermetic Playwright CI tests for all multi-provider features
 
-[Admin Settings UI]
-    └──requires──> [OIDC login + role field on users table] (v1.0, shipped — needs admin flag)
-    └──requires──> [App password encrypted storage] (v1.0, shipped)
-    └──enhances──> [Setup wizard] (wizard hands off to Admin Settings for post-setup credential rotation)
+Self-Service Google OAuth Onboarding
+    └──required by──> Google Calendar events visible in unified view
+    └──depends on──> member_credentials table (Phase 10, exists — needs google columns)
+    └──depends on──> CalendarProvider interface (credential storage is provider-scoped)
 
-[Setup wizard]
-    └──requires──> [DB connection] (before anything else can be validated)
-    └──requires──> [VAPID key generation utility] (web-push keygen, v1.0 shipped in some form)
-    └──requires──> [OIDC config storage] (env vars or DB config table)
-    └──gates──> [All other features] (wizard must complete before app is usable)
-    └──does NOT require──> [Admin Settings UI] (wizard is first-run only; Admin Settings is post-run)
+Multiple Reminders per Event
+    └──depends on──> reminderLeadMinutes field (Phase 11, exists — must become JSON array)
+    └──depends on──> VALARM serialization helpers (Phase 11, exist — handle arrays natively)
+    └──depends on──> variable-lead scheduler (Phase 11, exists — dedup key update only)
+    └──interacts with──> Google provider (reminders.overrides format translation)
 
-[Gitea CI]
-    └──requires──> [Gitea act_runner deployed on Unraid host]
-    └──requires──> [MariaDB service container support in act_runner]
-    └──requires──> [Vitest unit tests + API integration tests] (v1.0, partially written)
-    └──enables──> [Mobile-browser test harness] (harness runs as a CI step)
+Zero-Setup DB Bootstrap
+    └──depends on──> Drizzle migration files (all phases, exist)
+    └──enables──> clean first-run: bootstrap schema → setup wizard → admin config
 
-[Mobile-browser test harness]
-    └──requires──> [Playwright + mobile device config]
-    └──requires──> [DEV_AUTH_BYPASS or stored auth session]
-    └──enhanced by──> [Gitea CI] (harness most valuable when gating PRs automatically)
+PWA Dark Mode
+    └──depends on──> semantic tokens in tokens.css (Phase 17, exists)
+    └──independent of all other v1.2 features (fully parallelizable)
 ```
 
 ### Dependency Notes
 
-- **Faster write-back is a force multiplier.** It makes the per-event reminder UX feel correct — a user sets a reminder, saves, and expects the scheduler to know about it now, not in 15 seconds. Build faster write-back before or alongside per-event reminders.
-- **Admin Settings requires an `is_admin` flag.** v1.0 shipped no role distinction. The schema migration to add `users.is_admin` (default false, first user true) is a prerequisite for the Admin Settings route guard and is trivial.
-- **Setup wizard gates the app.** Until the wizard completes, no calendar or list feature should render. The wizard is a deploy-time concern for the operator; it is not a UX concern for the non-technical member (she never sees it — the operator runs it once).
-- **Gitea CI depends on act_runner.** If the self-hosted Gitea does not yet have an act_runner container deployed, CI cannot run. This is an infrastructure prerequisite, not a code concern.
-- **Mobile harness does not block CI.** CI (lint/typecheck/unit/integration) can ship first. The mobile harness is an additive step.
+- **Provider abstraction is the keystone.** Google Calendar, the calendar picker, and the stub all require `CalendarProvider` to be defined and Fastmail refactored behind it. This is Phase 21 and must complete before any other multi-provider phase starts.
+- **Stub enables CI for everything else.** Once the interface exists and the stub is wired to `DEV_AUTH_BYPASS`, all subsequent multi-provider phases get hermetic CI for free.
+- **Multiple reminders requires a DB migration.** `reminderLeadMinutes` (single integer) becomes a JSON array column. Use an additive migration — add new column, keep old column until v1.3 cleanup — to avoid breaking the running app during deploy.
+- **Dark mode and zero-setup DB are independent** of all multi-provider work and can be developed in a parallel phase with no ordering constraints.
+- **OAuth callback on iOS Safari standalone PWA.** The Google OAuth redirect-back must work in Safari standalone mode on the wife's iPhone — the same load-bearing constraint as the Authelia OIDC redirect in Phase 3. Must be a human gate before the Google onboarding feature is marked validated.
 
 ---
 
-## MVP Definition (v1.1)
+## v1.2 Feature Prioritization
 
-### Must Ship (table stakes for "operability" claim)
-
-- [ ] Per-event reminder selector — None / preset offsets — single alarm minimum
-- [ ] Scheduler uses per-event VALARM trigger offset, fires nothing on None
-- [ ] Existing VALARMs preserved on edit round-trip
-- [ ] Admin Settings — rotate/re-enter Fastmail app password per member, mark shared calendar
-- [ ] Setup wizard — DB, OIDC, VAPID, app password — validated before completion
-- [ ] Faster write-back — event-driven outbox drain, edits land in ~1s perceived
-
-### Should Ship (differentiators, don't let them slip the milestone)
-
-- [ ] Gitea CI — lint + typecheck + unit + API integration on PR
-- [ ] Mobile-browser test harness — iPhone viewport, authenticated, usable by assistant in playwright-cli
-
-### Defer (not v1.1 scope)
-
-- [ ] Multiple reminders per event (2x VALARM) — v1.1 stretch; defer to v1.2 if risky
-- [ ] Self-service member onboarding via wizard (backlog 999.5) — separate feature, separate phase
-- [ ] Docker image auto-publish from CI — nice to have; ship manually until CI is stable
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| CalendarProvider interface + Fastmail refactor | HIGH (unlocks everything multi-provider) | MEDIUM | P1 |
+| Stub provider for CI | HIGH (unlocks hermetic testing immediately) | LOW | P1 |
+| Zero-setup DB bootstrap | HIGH (self-hoster operator UX) | LOW | P1 |
+| Self-service Google OAuth onboarding + token reconnect | HIGH (wife's Google Calendar + non-technical UX) | MEDIUM | P1 |
+| Google Calendar read (unified view) | HIGH (core v1.2 value proposition) | HIGH | P1 |
+| Google Calendar write-back | HIGH (full parity with Fastmail) | MEDIUM | P1 |
+| Token-expiry reconnect banner + one-tap reconnect | HIGH (non-technical Apple member must self-serve this) | LOW | P1 |
+| Multiple reminders per event | MEDIUM (power user UX; v1.1 deferred this) | MEDIUM | P2 |
+| PWA dark mode (System/Light/Dark) | MEDIUM (iOS Dark Mode users; polish) | LOW | P2 |
+| Provider health status indicator in Settings | MEDIUM (ambient awareness without hunting menus) | LOW | P2 |
+| CI dependency updates (999.18) | LOW (hygiene; not user-visible) | LOW | P3 |
 
 ---
 
-## Feature Prioritization Matrix
+## Key UX Notes for Non-Technical Apple Member
 
-| Feature                                 | User Value | Implementation Cost | Priority |
-| --------------------------------------- | ---------- | ------------------- | -------- |
-| Per-event reminder selector             | HIGH       | MEDIUM              | P1       |
-| Scheduler per-event VALARM              | HIGH       | MEDIUM              | P1       |
-| Faster write-back                       | HIGH       | MEDIUM              | P1       |
-| Admin Settings — app password mgmt      | HIGH       | MEDIUM              | P1       |
-| Admin Settings — shared calendar toggle | HIGH       | LOW                 | P1       |
-| Setup wizard                            | HIGH       | HIGH                | P1       |
-| Gitea CI (regression gate)              | MEDIUM     | MEDIUM              | P1       |
-| Mobile Playwright harness               | MEDIUM     | LOW                 | P2       |
-| Multiple reminders per event            | MEDIUM     | MEDIUM              | P2       |
-| All-day reminder at 9 AM semantics      | MEDIUM     | LOW                 | P2       |
-| Docker image auto-publish               | LOW        | LOW                 | P3       |
+The wife's experience is a hard constraint on every feature in this milestone:
 
-**Priority key:**
+1. **Google onboarding.** Must be a single "Connect Google Calendar" tap that opens a recognizable Google consent screen — she knows what that looks like. The return flow back to FamilySync must work in Safari standalone PWA mode (same OIDC-redirect constraint validated in Phase 3). Do not require her to copy/paste anything.
 
-- P1: Must have for milestone claim
-- P2: High value, ship if no risk to P1
-- P3: Nice to have, defer
+2. **Token reconnect.** When her Google token expires, she must see a banner in the calendar view — not discover it by noticing missing events days later. The banner says "Google Calendar disconnected" with a "Reconnect" button. One tap, done. No re-adding the account from scratch.
 
----
+3. **Calendar picker on event creation.** The picker must default to her most-used calendar; she should not have to think about it for routine events. The dropdown must use calendar names she recognizes ("Personal", "Family"), not provider-internal IDs or email addresses.
 
-## Per-Feature Expected Behavior Reference
+4. **Dark mode toggle.** In Settings, labeled "Appearance: System / Light / Dark" — simple three-option choice, no color wheel. System should be the default (respects her iPhone's Dark Mode setting automatically).
 
-### 1. Per-Event Reminders
-
-**Reminder selector options (matching Apple Calendar + Google Calendar intersection):**
-
-| Label             | VALARM TRIGGER value | Notes                                                  |
-| ----------------- | -------------------- | ------------------------------------------------------ |
-| None              | (no VALARM emitted)  | Default for new events                                 |
-| 5 minutes before  | `TRIGGER:-PT5M`      |                                                        |
-| 10 minutes before | `TRIGGER:-PT10M`     |                                                        |
-| 15 minutes before | `TRIGGER:-PT15M`     | Current hardcoded default — becomes an explicit choice |
-| 30 minutes before | `TRIGGER:-PT30M`     |                                                        |
-| 1 hour before     | `TRIGGER:-PT1H`      |                                                        |
-| 2 hours before    | `TRIGGER:-PT2H`      |                                                        |
-| 1 day before      | `TRIGGER:-P1D`       |                                                        |
-| 2 days before     | `TRIGGER:-P2D`       |                                                        |
-
-**All-day event semantics:** When saving an all-day event with any reminder, the scheduler fires at 09:00 AM local time on the target day (computed as `allday_date + offset_days`). Do not fire at midnight. Apple Calendar uses 9 AM as the "on the day" time for all-day alerts; this matches the wife's expectation.
-
-**Round-trip on edit:** On form open for an existing event, read the first VALARM TRIGGER duration from the parsed ical.js component and select the nearest matching preset. If the existing TRIGGER does not match any preset (e.g., `TRIGGER:-PT7M` from some other client), display a "Custom (preserve)" option and do not strip it on save unless the user explicitly changes the selector. On save with a preset change, replace the VALARM. On save with "None" selected, remove all VALARMs.
-
-**Scheduler contract:** Store `alarm_fire_at` (absolute UTC timestamp) in the `events` or a separate `event_alarms` table at write time. The scheduler queries `alarm_fire_at <= NOW() AND fired = false` — no ical re-parse at fire time. This is the existing outbox/scheduler pattern already in v1.0; extend it.
-
-### 2. Admin Settings
-
-**Scope (exactly this, no more):**
-
-1. **Per-member Fastmail app password** — masked input to re-enter or rotate the encrypted credential stored in the DB. Show member name + "last updated" timestamp. On save, attempt a CalDAV `PROPFIND` test request with the new credential before committing. Surface pass/fail inline. No separate page — a section within Settings.
-
-2. **Shared calendar designation** — list all synced calendars (display name + Fastmail collection URL) with a radio button selecting which one is `is_shared = true`. Currently requires a direct DB write (D-16 debt). One click + confirm. Show the current selection highlighted.
-
-**Role gate:** A single `users.is_admin TINYINT(1) DEFAULT 0` flag. The first user created during the setup wizard gets `is_admin = 1`. The route `/api/admin/*` and the Admin Settings UI section return 403 for non-admin users. No role management UI — the non-technical member never sees this section.
-
-**What Admin Settings is NOT:** It is not a full server configuration panel, not a user management screen, not an audit log, not a health dashboard. It is two operational tasks that currently require DB console access.
-
-### 3. Setup Wizard
-
-**When it runs:** On first visit to the app when a `setup_complete` record is absent from the DB (or a `SETUP_COMPLETE=false` env flag, whichever is simpler). After completion, a `setup_complete = true` record is written and the wizard never appears again.
-
-**Step order (each step validates before advancing):**
-
-| Step                     | Fields                                                                                    | Validation                                                                                           |
-| ------------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| 1. Welcome               | None — explains what the wizard does                                                      | None                                                                                                 |
-| 2. Database              | Already connected (MariaDB creds are in env at container start). Show "connected" status. | DB ping; show error + instructions if failed                                                         |
-| 3. App URL               | External URL (used for OIDC redirect)                                                     | URL format check; attempt a `HEAD` to itself if reachable                                            |
-| 4. OIDC                  | Client ID, client secret, issuer URL, redirect URI (pre-filled)                           | Fetch `{issuer}/.well-known/openid-configuration`; show discovered endpoints; fail if unreachable    |
-| 5. Session secret        | Auto-generated 32-byte hex string (user can override)                                     | Length >= 32 chars                                                                                   |
-| 6. Encryption key        | Auto-generated 32-byte hex string for `APP_PASSWORD_ENCRYPTION_KEY`                       | Length == 32 bytes                                                                                   |
-| 7. VAPID keys            | Auto-generate button (calls `webpush.generateVAPIDKeys()`)                                | Structural check — public key is a valid base64url-encoded P-256 point                               |
-| 8. Admin account         | Select from OIDC-discovered members OR enter the sub/preferred_username manually          | Not empty                                                                                            |
-| 9. Fastmail app password | App password for the primary calendar account                                             | Test CalDAV `PROPFIND` to `https://caldav.fastmail.com/dav/principals/user/<email>/`; show pass/fail |
-| 10. Confirm + save       | Summary of all inputs                                                                     | Writes config to DB/env; sets `setup_complete`; redirects to app                                     |
-
-**Validation UX:** Inline per-field — show a green checkmark or red error directly below the field as soon as the user leaves it (blur event) or clicks a test button. "Next" button is disabled until the current step passes validation. Show human-readable error messages: "Could not reach the OIDC issuer — is Authelia running?" not "fetch failed: ERR_CONNECTION_REFUSED".
-
-**Back navigation:** Every step allows going back. Already-validated steps retain their values. Do not re-validate automatically on back; re-validate on "Next".
-
-**Failure surface:** If the DB step fails (impossible at startup in Docker but possible in dev), show a non-wizard error page with setup instructions — the wizard itself cannot run without a DB.
-
-### 4. Faster Write-Back
-
-**Target perceived latency:** < 2 seconds from "Save" click to the event appearing correctly in the calendar view. This matches Google Calendar and Fastmail native behavior.
-
-**Current latency:** Up to ~15 seconds (outbox poll interval) + 5-minute CalDAV read-back poller.
-
-**Approach:**
-
-1. The existing optimistic-202 response already updates the React Query cache immediately on save (latency = 0 for the UI). The gap is the CalDAV write-back actually landing, which matters for reminders and cross-device visibility.
-2. On INSERT to the `outbox` table, emit an event (in-process EventEmitter or a Redis pub/sub message if the outbox worker is in a separate process) that triggers an immediate drain attempt.
-3. On successful CalDAV PUT, emit an SSE `calendar-updated` event to connected clients so React Query invalidates the calendar cache and re-fetches. The re-fetch is the "write landed" confirmation.
-4. Reduce the read-back poller interval from 5 min to 30 s as a fallback — not the primary path, just the safety net.
-
-**Durability guarantee preserved:** The outbox row is not deleted until the CalDAV PUT succeeds. The optimistic-202 pattern is unchanged. The drain is just triggered eagerly instead of lazily.
-
-**What "near-immediate" does NOT mean:** CalDAV is a synchronous HTTP PUT. If Fastmail is slow (>1s), the write takes >1s. The goal is to eliminate the artificial polling delay, not to change network physics.
-
-### 5. Gitea CI
-
-**Trigger:** On `pull_request` to `main`.
-
-**Steps:**
-
-1. Checkout
-2. pnpm install (cached)
-3. TypeScript typecheck — `pnpm -r tsc --noEmit` (both `apps/api` and `apps/pwa`)
-4. ESLint — `pnpm -r lint`
-5. Vitest unit tests — `pnpm -r test:unit`
-6. API integration tests — spin up MariaDB service container, run `pnpm --filter api test:integration` with `DB_HOST=127.0.0.1`
-
-**Service container pattern:** Gitea Actions uses the same `services:` syntax as GitHub Actions. MariaDB `mariadb:11` with `MYSQL_ROOT_PASSWORD`, `MYSQL_DATABASE` env vars. `options: --health-cmd="mariadb-admin ping -h localhost" --health-interval=10s --health-retries=5` to gate the test step on DB readiness.
-
-**Docker image publish:** Separate workflow, trigger `push` to `main` (after PR merge). Builds and pushes to the Gitea Container Registry. Not part of the PR workflow — keeps PR checks fast.
-
-**Known limitation:** Gitea act_runner in Docker has incomplete service volume support. Do not mount host volumes in the services block. The MariaDB service container using env-based config (no volume) is reliable.
-
-### 6. Mobile-Browser Test Harness
-
-**What it is:** A reusable Playwright configuration profile using `devices['iPhone 15']` (or equivalent) with stored auth state (`DEV_AUTH_BYPASS=true` or a saved `storageState` JSON from a prior login), usable by the assistant via `playwright-cli` without re-authenticating on every run.
-
-**What it covers:**
-
-- Mobile viewport layout (bottom nav, drawer sizing, touch targets >= 44px)
-- Calendar view rendering at iPhone screen width
-- Event form usability on mobile (reminder selector visible, not clipped)
-- List co-edit interactions on mobile
-
-**What it does NOT cover:** Real iOS Safari, Web Push delivery, standalone-mode OIDC redirect, iOS-specific service worker quirks. Those remain human gates.
-
-**Integration with CI:** A `test:e2e:mobile` script in `apps/pwa/package.json`. Run in CI as an optional step (allowed to fail without blocking merge) until the harness is proven stable, then graduate to blocking.
-
-**Auth strategy for CI:** `DEV_AUTH_BYPASS=true` with a known test user id. The harness does not run the full OIDC flow — it injects the bypass session directly. This matches the v1.0 dev-stack bring-up pattern.
-
----
-
-## Competitor / Prior Art Reference
-
-| Feature               | Apple Calendar                                 | Google Calendar                                 | Fastmail native      | Nextcloud            | This Product (v1.1 target)                      |
-| --------------------- | ---------------------------------------------- | ----------------------------------------------- | -------------------- | -------------------- | ----------------------------------------------- |
-| Reminder presets      | None / 5m / 15m / 30m / 1h / 2h / 1d / 2d / 1w | None / 5m / 10m / 15m / 30m / 1h / 2h / 1d / 2d | None / 15m / 1h / 1d | N/A                  | None / 5m / 10m / 15m / 30m / 1h / 2h / 1d / 2d |
-| Multiple alarms       | Yes (up to 5)                                  | Yes (up to 5)                                   | Yes                  | N/A                  | V1.1: 1; stretch: 2                             |
-| All-day reminder time | 9 AM on alert day                              | 11:50 PM night before (jarring)                 | Morning              | N/A                  | 9 AM (Apple convention)                         |
-| Admin credential mgmt | N/A                                            | N/A                                             | N/A                  | Yes (complex)        | Minimal: 2 tasks only                           |
-| Setup wizard          | N/A                                            | N/A                                             | N/A                  | Yes (3-step minimal) | 10-step validated                               |
-| Write-back latency    | ~1s                                            | ~1s                                             | ~1s                  | Varies               | Target ~1s (from ~15s)                          |
-| CI                    | N/A                                            | N/A                                             | N/A                  | GitHub Actions       | Gitea Actions                                   |
+5. **Multiple reminders.** The add/remove reminder list must be tappable with one thumb on iPhone. The "Add reminder" link must meet the 44px minimum touch target. The list must not overflow off-screen on narrow viewports.
 
 ---
 
 ## Sources
 
-- [Apple Calendar default alert settings (Mac support)](https://support.apple.com/guide/calendar/change-default-alert-settings-icl4407ddb59/mac)
-- [Google Calendar notifications (Android)](https://support.google.com/calendar/answer/37242?hl=en)
-- [iCalendar RFC 5545 — VALARM component](https://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html)
-- [RFC 9074 — VALARM Extensions](https://datatracker.ietf.org/doc/html/rfc9074)
-- [iCalendar TRIGGER property spec](https://icalendar.org/iCalendar-RFC-5545/3-8-6-3-trigger.html)
-- [Nextcloud installation wizard](https://docs.nextcloud.com/server/stable/admin_manual/installation/installation_wizard.html)
-- [Wizard UI patterns — LogRocket UX](https://blog.logrocket.com/ux-design/creating-setup-wizard-when-you-shouldnt/)
-- [NN/G Wizards: Definition and Design Recommendations](https://www.nngroup.com/articles/wizards/)
-- [Outbox Pattern — Conduktor](https://www.conduktor.io/glossary/outbox-pattern-for-reliable-event-publishing/)
-- [Transactional Outbox with Optimistic Sending](https://www.npiontko.pro/2025/05/26/outbox-pattern-optimistic)
-- [Optimistic UI Patterns — Simon Hearne](https://simonhearne.com/2021/optimistic-ui-patterns/)
-- [Gitea Actions — Act Runner docs](https://docs.gitea.com/usage/actions/act-runner)
-- [Gitea Actions Docker builds](https://blog.diblasio.social/posts/gitea_builder/)
-- [Playwright PWA mobile testing](https://dev.to/pritig/how-playwright-simplifies-ui-testing-for-progressive-web-apps-pwas-9n8)
-- [Playwright emulation docs](https://playwright.dev/docs/emulation)
+- [Best Digital Family Calendars 2026 — Morgen](https://www.morgen.so/blog-posts/digital-family-calendar)
+- [Skylight vs Cozi — myskylight.com](https://myskylight.com/blog-best-family-calendar-app-busy-families-cozi/)
+- [Best Family Calendar Apps 2026 — TextConcierge](https://textconcierge.ai/blog/articles/best-family-calendar-apps-2026/)
+- [Google OAuth2 token model — Google for Developers](https://developers.google.com/identity/oauth2/web/guides/use-token-model)
+- [Google Calendar OAuth2 token expiry — n8n Community](https://community.n8n.io/t/google-calendar-oauth2-api-token-expiring-every-once-in-a-while/11336)
+- [Reconnect button pattern — GoHighLevel changelog](https://ideas.gohighlevel.com/changelog/reconnect-button-in-calendar-connections)
+- [Why Google Calendar integration breaks — GoHighLevel](https://help.gohighlevel.com/support/solutions/articles/48001204159-why-google-calendar-integration-breaks)
+- [How to add multiple alerts to calendar events — Morgen](https://www.morgen.so/guides/how-to-add-multiple-alerts-to-calendar-events)
+- [Multiple calendar reminders — GeeksOnTour](https://geeksontour.com/2022/12/how-to-set-multiple-reminders-for-an-event-on-your-calendar/)
+- [Google Calendar API concepts: reminders](https://developers.google.com/workspace/calendar/api/concepts/reminders)
+- [Dark mode CSS guide 2026 — StudioLimb](https://www.studiolimb.com/guides/dark-mode-css-guide.html)
+- [Best light/dark mode toggle in JavaScript — DEV Community](https://dev.to/whitep4nth3r/the-best-lightdark-mode-theme-toggle-in-javascript-368f)
+- [Drizzle ORM migrations docs](https://orm.drizzle.team/docs/migrations)
+- [drizzle-kit migrate](https://orm.drizzle.team/docs/drizzle-kit-migrate)
+- [Google Auth Library for Node.js — googleapis/google-auth-library-nodejs (Context7)](https://github.com/googleapis/google-auth-library-nodejs/blob/main/README.md)
+- [Google Calendar API Node.js quickstart](https://developers.google.com/workspace/calendar/api/quickstart/nodejs)
+- [Restricted scope verification — Google for Developers](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification)
+- [Playwright CI docs](https://playwright.dev/docs/ci)
 
 ---
 
-_Feature research for: FamilySync v1.1 — Operability & Polish_
-_Researched: 2026-06-10_
+*Feature research for: FamilySync v1.2 — multi-provider calendar, self-service onboarding, multiple reminders, dark mode, zero-setup DB, dev/CI stub provider*
+*Researched: 2026-06-19*
diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md
index 7ba3101..27318c7 100644
--- a/.planning/research/PITFALLS.md
+++ b/.planning/research/PITFALLS.md
@@ -1,527 +1,504 @@
-# Pitfalls Research — v1.1 Operability & Polish
+# Pitfalls Research — v1.2 Multi-Provider, Theming & Zero-Setup
 
-**Domain:** Adding operability features (VALARM reminders, admin Settings, setup wizard, event-driven outbox drain, Gitea CI, Playwright authed-mobile harness) to a shipped Node 22 + Hono + Drizzle/MariaDB + tsdav/ical.js + web-push stack on Unraid/Docker behind Authelia OIDC + Pangolin/Newt.
-**Researched:** 2026-06-10
-**Confidence:** HIGH — pitfalls derived from direct inspection of the shipped v1.0 source, the v1.0 retrospective, and deep familiarity with ical.js/CalDAV/Gitea Actions semantics. No speculative gaps.
+**Domain:** Adding Google Calendar OAuth2, provider abstraction, multiple reminders, dark mode, auto-migrate-on-boot, self-service OAuth onboarding, and dependency updates to a shipped Node 22 + Hono 4 + Drizzle/MariaDB 11 + tsdav/ical.js + web-push stack on Unraid/Docker behind Authelia OIDC + Pangolin/Newt.
+**Researched:** 2026-06-19
+**Confidence:** HIGH — pitfalls derived from direct source inspection of the shipped v1.1 codebase, v1.0/v1.1 retrospectives, known burned-in lessons from the migration and CI history, and deep familiarity with Google Calendar API, OAuth2, Drizzle/MariaDB migration semantics, and PWA theming constraints. Sources cross-checked against PROJECT.md, RETROSPECTIVE.md, MILESTONES.md, and the VALARM/outbox source in apps/api/src/broker/.
 
 ---
 
-## Known Constraints (Do Not Re-Litigate)
+## Known Constraints (Inherited — Do Not Re-Litigate)
 
-These are already burned-in lessons. Every pitfall below is written assuming these hold:
+These are burned-in from v1.0/v1.1. Every pitfall below assumes these hold:
 
-- **No node-cron.** `setInterval` only. node-cron 4.2.1 silently skips all ticks in the long-lived API process.
-- **`drizzle-kit generate`+`migrate`, never `push`.** `push` emits a false destructive diff on populated MariaDB.
-- **API integration tests need a real MariaDB** (port-bound dev compose, `DB_HOST=127.0.0.1`, `.env` creds). Tests live in `apps/api/tests/`, never `src/`.
-- **Outbox guarantees to preserve:** optimistic 202, enqueue-only route handler, create-before-delete ordering (groupId), drain concurrency guard (`isDraining`), fresh-etag-before-PUT (WR-02), per-uid exactly-once dedup.
-- **VAPID private key must decode to exactly 32 bytes** — a truncated key causes a silent Apple 403.
-- **Authelia omits `name`/`email`/`preferred_username` from the ID token** by default — needs a `claims_policy` or these fields are absent.
+- **No node-cron.** `setInterval` only — node-cron 4.2.1 silently skips all ticks in long-lived Node processes.
+- **`drizzle-kit generate`+`migrate`, never `push`.** `push` emits a false destructive diff (TRUNCATE/DROP) on populated MariaDB 11 using the mysql dialect — the introspection bug fires on any existing-data DB. This is the root cause behind D-MIGRATION-10-01 and the quick task cr8.
+- **Journal-hash matching is mandatory.** The `__drizzle_migrations` table tracks applied migrations by `tag` (from `_journal.json`). If a migration file is renamed, regenerated, or its journal entry is modified after it has been applied to any environment, drizzle-kit migrate treats it as unapplied and will attempt to re-run DDL that already ran — producing `Duplicate column` errors.
+- **MariaDB CI readiness uses `healthcheck.sh --connect`, not `mysqladmin ping`.** `mysqladmin ping` was removed in MariaDB 11.
+- **ESLint is pinned at 9.39.4.** ESLint 10 breaks `eslint-plugin-react` and `eslint-plugin-react-hooks`. The root `package.json` pin must not be bumped past 9.x until all React plugins declare ESLint 10 peerDep support.
+- **`setInterval` outbox drain, not Redis.** Single-process; in-process EventEmitter (`outboxTrigger.ts`) for the drain signal. `drainRequested` flag pattern prevents double-drain. Optimistic-202, create-before-delete, and `uid:dtstartMs` dedup are load-bearing.
+- **All CalDAV VALARM triggers must be built via `ICAL.Duration.fromSeconds(-N*60)`, not bare strings.** Bare strings produce `VALUE=TEXT` which is rejected by Fastmail and Apple Calendar.
+- **`REGISTRY_PAT` secret name (not `GITEA_PAT` — the `GITEA_` prefix is silently dropped by Gitea Actions).** `docker login --password-stdin`, never `-p $TOKEN` on the command line.
 
 ---
 
 ## Critical Pitfalls
 
-### Pitfall 1: VALARM Round-Trip Strips Existing Alarms From Native Clients on Edit
+### Pitfall 1: Google Refresh Tokens in "Testing" Publishing Status Expire After 7 Days
 
 **What goes wrong:**
-The current `buildVeventString` in `broker/vevent.ts` constructs a fresh `VCALENDAR` with only the properties it knows about (UID, SUMMARY, DTSTART, DTEND, RRULE, LOCATION, DESCRIPTION). When v1.1 adds VALARM authoring, a naive approach adds `VALARM` components to new-creates only. On an edit (update path in `outboxWorker.ts`), the worker re-builds the VEVENT from form payload — not from the stored `rawVevent`. Any VALARM that was added by a native client (Fastmail app, Apple Calendar) will be silently dropped from the PUT payload. The event arrives at Fastmail without the alarm. The user loses their native-client reminder with no warning.
+Google OAuth2 refresh tokens issued to an app in "Testing" publishing status (as opposed to "Production") expire after 7 days regardless of the token TTL in the credentials. After 7 days, the stored refresh token returns `invalid_grant` and all Google Calendar operations fail for that member. The user sees calendar data vanish or receives 401 errors, and the fix requires them to re-authorize — a confusing, non-obvious failure for a non-technical user.
 
-The inverse is equally dangerous: if the editor sends `reminderMinutes: 0` (meaning "no reminder"), but the code omits the VALARM field instead of explicitly authoring an empty VALARM block, the old alarm from `rawVevent` is neither preserved nor cleared. Whether it survives depends on what the worker does — and with the current reconstruct-from-scratch approach it will be dropped, which is the correct outcome in that case but only by accident.
+Additionally, Google refresh tokens for apps in "Testing" status can only be granted to users explicitly listed as "test users" in the OAuth consent screen. If the operator adds a second member's Google account but forgets to add them as a test user, the authorization flow returns `access_denied` at the consent step, not a useful error message.
 
 **Why it happens:**
-`outboxWorker.ts` update path reconstructs the ICS entirely from form fields (using `buildVeventString`). It does not read and preserve non-RRULE sub-components from `rawVevent`. This is a deliberate v1 simplification (the RRULE-preserve path `WR-01` is already the one exception). Adding VALARM to `buildVeventString` handles new-creates correctly but does not cover the "user edited an event that already had a native-app alarm."
+Developers set up the OAuth app in "Testing" status because "Production" requires Google verification (which requires a privacy policy, domain verification, and Google review). Testing status is the path of least resistance during development and stays in place longer than intended.
 
 **How to avoid:**
-On the update path in `outboxWorker.ts`, before calling `buildVeventString`, parse `rawVevent` with ical.js and extract all existing `VALARM` sub-components. Merge them: if the outbox payload carries an explicit reminder choice (the new `reminderMinutes` field), replace all extracted VALARMs with the new one (or with none if `reminderMinutes: null`). If the payload carries no reminder field (no explicit user change), carry the extracted VALARMs forward into `buildVeventString` as a `valarms` parameter. This mirrors the WR-01 RRULE-preserve pattern exactly. Extend the `outboxPayloadSchema` with an optional `reminderMinutes: z.number().int().min(0).nullable().optional()` field so the absence of the key is distinguishable from an explicit "no reminder."
+For a self-hosted household app serving 2 users, request "Production" publishing status immediately — it does not require Google's full verification unless the app accesses sensitive scopes. For calendar read/write, `https://www.googleapis.com/auth/calendar` is a "restricted" scope (not "sensitive"), which DOES require verification. Use `https://www.googleapis.com/auth/calendar.readonly` + `https://www.googleapis.com/auth/calendar.events` instead — these are the non-restricted scopes sufficient for event read/write (no attendee PII access). With these scopes, production status is grantable without full Google review.
+
+If testing status must remain during development, encode a `token_expiry_check` that validates the refresh token age and prompts re-auth before it expires rather than failing silently. Store the token grant timestamp alongside the encrypted refresh token in `member_credentials`.
+
+Add the operator's and wife's Google accounts as test users in the OAuth consent screen during development.
 
 **Warning signs:**
-
-- Reminders set in the Fastmail native app disappear after editing the event in FamilySync.
-- A shared event with a reminder shows the reminder field as empty after an FamilySync round-trip.
-- `rawVevent` in `calendar_events` has `BEGIN:VALARM` but the PUT payload does not.
+- Calendar data disappears exactly 7 days after a member connected their Google account.
+- `invalid_grant` error in API logs when refreshing Google tokens.
+- Second member's authorization flow returns `access_denied`.
 
 **Phase to address:**
-Per-event reminders phase (VALARM authoring). The VALARM-preserve logic must land in the same PR as `buildVeventString` VALARM support — not as a follow-up.
+Google Calendar provider phase (first Google OAuth plan). Document the testing-vs-production publishing status distinction in the onboarding UI and in `docs/deployment.md` before implementing the OAuth flow.
 
 ---
 
-### Pitfall 2: TRIGGER Value-Type Mismatch Silently Produces Broken VALARM
+### Pitfall 2: Google Calendar Recurrence Model Does Not Map Cleanly to iCalendar RRULE
 
 **What goes wrong:**
-RFC 5545 §3.8.6.3 defines two legal TRIGGER value types for VALARM:
+The Google Calendar API represents recurring events as a "master event" with a `recurrence` field (an array of raw iCalendar strings like `["RRULE:FREQ=WEEKLY;BYDAY=MO"]`) plus separate "instance" resources for occurrences that have been individually modified (moved, canceled). The FamilySync codebase assumes the iCalendar model where: (a) a single VEVENT with RRULE expands to all occurrences via `ICAL.RecurExpansion`, and (b) exceptions are represented as VEVENT objects with `RECURRENCE-ID`. 
 
-- `DURATION` (default): `TRIGGER:-PT15M` — fires 15 minutes before DTSTART.
-- `DATE-TIME`: `TRIGGER;VALUE=DATE-TIME:20260610T120000Z` — fires at an absolute UTC instant.
+When pulling Google recurring events, the Google API returns **individual instance resources** by default in `events.list` — unless you pass `singleEvents: false`. If `singleEvents: true` (the default), you get individual expanded occurrences, not the master event. You cannot reconstruct the RRULE from the instances. If `singleEvents: false`, you get the master event (with RRULE) but **also need to separately fetch modified instances** to know which occurrences have been moved or canceled. There is no single API call that returns "master event + delta patches in RECURRENCE-ID form" like CalDAV does.
 
-ical.js represents these differently. If you set a VALARM TRIGGER using `addPropertyWithValue('trigger', '-PT15M')` (a bare string), ical.js will emit it as `TRIGGER:-PT15M` on some versions and as `TRIGGER;VALUE=TEXT:-PT15M` on others, depending on whether it infers the type. The `VALUE=TEXT` form is not RFC-compliant for VALARM TRIGGER and will be silently ignored by Fastmail and Apple Calendar — the reminder never fires. The ICS looks valid at a glance but produces no alarm.
-
-Separately: `RELATED=END` (fire N minutes before DTEND, not DTSTART) is a valid TRIGGER parameter. If the existing event from a native client uses `TRIGGER;RELATED=END:-PT10M` and the VALARM-preserve code in Pitfall 1 carries it forward, it is preserved correctly. But if the code reconstructs the VALARM from a stored `reminderMinutes` number only, it loses the RELATED parameter and the semantics change.
+Deleted/canceled individual occurrences in Google Calendar have `status: "cancelled"` — they are not omitted from the response. If your code filters on `status === "confirmed"` you silently drop the cancellation records and re-expand the occurrence the next time the RRULE expands, causing ghost events.
 
 **Why it happens:**
-ical.js VALARM construction is not well-documented. The property API requires using `ICAL.Duration` or `ICAL.Time` objects, not bare strings, to get the correct value type in the output. Most examples online use the string form that works in some parsers but is not RFC-compliant.
+The CalDAV model and the Google Calendar API model for recurrence are fundamentally different. CalDAV treats recurrence as an iCalendar artifact (RRULE on the master VEVENT, RECURRENCE-ID VEVENTs for exceptions). The Google API wraps iCalendar but exposes a different resource model. Developers assume the broker abstraction can produce identical event shapes from both providers, but the Google recurrence model requires a different fetch strategy.
 
 **How to avoid:**
-Build the TRIGGER using `ICAL.Duration.fromSeconds(-reminderMinutes * 60)` and set it as the property value, not as a string. Verify the emitted TRIGGER line does not contain `VALUE=TEXT`. For preserved VALARMs (from `rawVevent`), round-trip the sub-component through ical.js parse→serialize rather than extracting the raw text and reinserting it, to catch any encoding issues.
+Fetch Google events with `singleEvents: false` to get master events with RRULE. For any recurring master event, issue a second call to fetch its instances (`events.instances()`) to get modified/canceled occurrences. Map `status: "cancelled"` instance resources to EXDATE entries on the master event's RRULE. Use `ICAL.RecurExpansion` on the reconstructed VCALENDAR for display, same as the Fastmail path.
 
-Add a unit test: build a VALARM with `reminderMinutes: 15`, serialize to ICS, parse back with ical.js, and assert the TRIGGER DURATION value is `-PT15M` with no VALUE parameter other than DURATION (which is the default and is usually omitted).
+The provider abstraction interface should return normalized VEVENT strings (raw iCalendar text), not provider-specific objects. The Google adapter's job is to produce a VCALENDAR string (including reconstructed RRULE + EXDATE) that the existing `expand.ts` / `sync.ts` layer can handle without modification.
+
+Expose a `fetchRecurringMasterWithExceptions(uid)` method in the Google adapter that issues both API calls and returns a unified VCALENDAR string. Do not attempt to normalize at the `events.list` level.
 
 **Warning signs:**
-
-- ICS output contains `TRIGGER;VALUE=TEXT:-PT15M`.
-- Reminders appear in the FamilySync UI but never fire on the device.
-- Apple Calendar / Fastmail app shows the event with no alarm after an FamilySync edit.
+- Recurring events show individual occurrences as separate events in the calendar instead of a recurring series.
+- Canceled occurrences still appear in the calendar after being deleted in Google Calendar.
+- `singleEvents: true` is used in the Google API client — this is wrong for the FamilySync data model.
 
 **Phase to address:**
-Per-event reminders phase. Unit test the VALARM serialization before any end-to-end reminder test.
+Google Calendar provider phase (recurrence handling plan). Write a unit test that takes a Google `events.list` response (with a recurring master + a modified instance + a canceled instance) and asserts the reconstructed VCALENDAR string passes ical.js parsing and `ICAL.RecurExpansion` without error.
 
 ---
 
-### Pitfall 3: All-Day Event VALARM Timezone Semantics Are Undefined
+### Pitfall 3: Google syncToken Invalidation Triggers Silent Full Re-Sync That Overwrites Local Writes
 
 **What goes wrong:**
-For an all-day event (DTSTART;VALUE=DATE), the meaning of `TRIGGER:-PT15M` is ambiguous. RFC 5545 requires that a DURATION TRIGGER on an all-day event be evaluated against DTSTART as a DATE — which has no time component — resulting in undefined behavior in most implementations. Apple Calendar interprets it as "15 minutes before midnight of the start date in local time." Fastmail ignores VALARM on all-day events entirely in some tested configurations. Android may fire the alarm at midnight UTC.
+The Google Calendar API supports incremental sync via `syncToken`: call `events.list` with the token from the previous response to receive only changes since the last sync. When the sync token expires (after ~7 days of inactivity, or after any large state change like timezone change or Google-side recalculation), the API returns `HTTP 410 Gone`. The correct response is to perform a full re-sync (no syncToken, save the new token). If the code does not handle 410 — or handles it by retrying with the old token — all incremental sync calls return 410 forever, silently halting all calendar updates.
+
+A second issue: during a full re-sync, the code fetches all events and upserts into `calendar_events`. If a member created an event in FamilySync that is in the outbox (not yet written to Google), and the full re-sync runs before the outbox drains, the upsert overwrites the local optimistic row with the stale Google state (the event is not yet on Google's side), effectively reverting the user's creation. The event disappears from the UI until the next outbox drain re-creates it on Google and the next poller sync pulls it back.
 
 **Why it happens:**
-The project already correctly excludes all-day events from the reminder scheduler (`reminderScheduler.ts`, `WHERE allDay=false`). But if VALARM is stored on an all-day event (because the user created an all-day event and selected a reminder), the scheduler's WHERE clause means it silently never fires — which is correct behavior — but the user sees a reminder field in the UI and expects it to work.
+syncToken expiration is handled in Google's CalDAV-via-ICAL model too (ctag changes trigger full re-sync), but the FamilySync ctag-based poller handles this correctly. The Google syncToken path is a different code branch that does not inherit the ctag handling. Full re-sync without outbox-awareness is a standard oversight.
 
 **How to avoid:**
-In the event form UI: disable or hide the reminder selector when `allDay: true`. If the API receives a create/update payload with `allDay: true` and a non-null `reminderMinutes`, strip the alarm and log a warning — do not store a VALARM that will silently not fire. Document this as a known constraint.
+Wrap every `events.list` call that uses a `syncToken` in a try/catch for 410. On 410: drop the sync token, mark the provider's sync state as `stale`, and enqueue a full re-sync on the next poller tick (not in-band, to avoid blocking the current poller iteration).
 
-In the scheduler, when v1.1 generalizes the lead time: keep the `WHERE allDay=false` guard in the SQL query regardless of how VALARM data is stored. Do not "fix" this by removing the guard when you extend VALARM support.
+Before upsetting rows from a full re-sync, check the `calendar_outbox` table for any pending rows for the same user/calendar. If any pending writes exist for the same event UID, skip overwriting that row's `raw_vevent` from Google — the outbox write is the authoritative source of truth until it drains. Alternatively: drain the outbox before any full re-sync. The outbox drain is already ~1–2s; blocking the re-sync on it is acceptable.
 
 **Warning signs:**
-
-- All-day event with reminder set produces an ICS with a VALARM on a DATE-typed DTSTART.
-- User reports reminder not firing for an all-day birthday event.
-- Reminder field enabled in the UI for all-day events.
+- API logs show `HTTP 410` from Google Calendar and the app stops updating events for that member.
+- Events created via FamilySync disappear briefly then reappear.
+- `syncToken` is stored per-provider in `member_credentials` or a separate `provider_sync_state` table but there is no 410 error handler branch.
 
 **Phase to address:**
-Per-event reminders phase. UI constraint and API guard belong in the same plan.
+Google Calendar provider phase (sync/poller plan). 410 handling must be in the acceptance criteria before the Google poller ships.
 
 ---
 
-### Pitfall 4: Duplicate Push When Generalizing the Fixed-Window Dedup to Per-Event Lead Times
+### Pitfall 4: Google All-Day Events Use DATE, Timed Events Use RFC 3339 — Timezone Handling Differs From CalDAV
 
 **What goes wrong:**
-The current `reminderScheduler.ts` deduplication key is `uid` alone (`sentReminders` Map). The fixed 16-minute catch-up window ensures an event stays in-window across at most a few consecutive 1-minute ticks. When v1.1 changes the lead to a per-event value (e.g., event A has a 30-minute lead, event B has a 2-hour lead), the window must widen — or the scan logic must change — to accommodate variable leads. There are two failure modes:
+Google Calendar returns timed events with `start.dateTime` (RFC 3339 string with timezone offset, e.g., `2026-07-01T10:00:00-04:00`) and all-day events with `start.date` (ISO 8601 date string, e.g., `2026-07-01`). The FamilySync sync layer (`sync.ts`) currently parses raw iCalendar `DTSTART;TZID=America/Toronto:20260701T100000` strings via ical.js and stores the UTC instant in `dtstart_utc`. 
 
-1. **Window too narrow for long leads:** If the scheduler still scans only `(now, now+16min]`, events with a 2-hour lead never enter the window and their reminder never fires.
+When the Google adapter converts `start.dateTime` to iCalendar, it must produce `DTSTART:20260701T140000Z` (UTC). If it instead produces `DTSTART;TZID=America/Toronto:20260701T100000`, ical.js parses it correctly, but only if the corresponding `VTIMEZONE` component is also present in the VCALENDAR. Google does not return VTIMEZONE components — their API uses offset strings. A missing VTIMEZONE for a TZID reference causes ical.js to default to UTC, silently shifting the event time.
 
-2. **Dedup key collision across rescheduled events:** If an event is rescheduled (DTSTART changes), the uid is the same but the VALARM should fire again for the new time. The current dedup key `uid` alone, with the `sentReminders.set(uid, dtstartMs)` pruning based on the stored dtstart, handles this — but only if the new dtstart causes the map entry to be pruned before the next alarm window. If the user reschedules an event to fire sooner than the original dtstart (e.g., from 3pm to 2pm, currently 2:10pm, 10 minutes after the original reminder already fired), the uid is still in `sentReminders` with the old dtstart (3pm), which has NOT yet passed `now`, so the CR-01 pruning has not removed it. The reminder for 2pm silently does not fire.
+All-day event reminder handling has a separate pitfall: the `computeAlertInstantUtc` function in `vevent.ts` uses `getHouseholdTimezone(db)` (the stored IANA timezone) to compute "9 AM local on alert day." For Google all-day events, the Google API returns `reminders.overrides` (a list of `{method, minutes}` objects) or `reminders.useDefault` (boolean). If `useDefault: true`, the reminder fires at the user's Google Calendar default reminder time (from their Google account settings) — which the server cannot know. Mapping `useDefault: true` to a `reminderLeadMinutes` value in FamilySync is undefined.
 
 **Why it happens:**
-The uid-only dedup was designed for the fixed-15-minute lead where the dedup window is short and rescheduling edge cases are low-probability. Per-event leads break both assumptions.
+CalDAV stores full iCalendar with VTIMEZONE. The Google API abstracts timezone into RFC 3339 offsets. The two representations look similar but require different handling in ical.js. Developers test with US/Eastern events and miss that ical.js silently falls back to UTC for an unknown TZID.
 
 **How to avoid:**
-Change the dedup key from `uid` alone to `uid + ':' + dtstartMs`. This makes the dedup per-(event, scheduled-time), not per-event. A rescheduled event has a different dtstart and gets a new dedup entry. The sentReminders map still prunes on `dtstartMs <= now`.
+In the Google adapter, always normalize `start.dateTime` to UTC before building the iCalendar string. Use `new Date(googleEvent.start.dateTime).toISOString()` to get the UTC instant, then build `DTSTART:20260701T140000Z`. Never emit a `TZID` reference without a corresponding `VTIMEZONE` block.
 
-For the variable-window query: instead of scanning a fixed `(now, now+16min]` window, store the per-event lead time alongside the VALARM in `calendar_events` (e.g., a `reminderMinutes` column). The scheduler query becomes `WHERE dtstartUtc <= (now + reminderMinutes minutes) AND dtstartUtc > now`. This requires a schema migration.
+For all-day events: map `start.date` directly to `DTSTART;VALUE=DATE:20260701`, same as the CalDAV path.
 
-Add an integration test for the scheduler that covers: (a) event with a 30-minute lead fires at T-30, (b) event rescheduled earlier after the first fire fires again for the new time.
+For Google `reminders.useDefault: true`: treat it as "no reminder" at the FamilySync layer. Store `reminderLeadMinutes: null`. Document this in the UI: "Google default reminders from your Google account settings are not shown in FamilySync; set a reminder here to receive FamilySync push notifications." This avoids fetching and storing per-member Google account preferences.
+
+For Google `reminders.overrides`: map the first `email`-method reminder to `reminderLeadMinutes` (FamilySync uses push, not email). Ignore `popup` method overrides unless there is a clear 1:1 mapping.
 
 **Warning signs:**
-
-- Events with a long reminder lead never fire.
-- Rescheduled event reminder does not fire after the reschedule.
-- Scheduler dedup map grows without bound (no uid-dtstart pair is ever pruned because the dtstart moved out from under the map entry).
+- Timed events from Google appear at the wrong time in FamilySync (off by the timezone offset).
+- ical.js warnings about unknown TZID in the server logs.
+- All-day events with `useDefault: true` trigger unexpected push notifications.
 
 **Phase to address:**
-Per-event reminders phase. Schema migration for `reminderMinutes` column in `calendar_events` is a prerequisite; dedup key change must land in the same plan.
+Google Calendar provider phase (event normalization plan). Write unit tests for the UTC normalization: assert that a `start.dateTime` with `-04:00` offset produces `DTSTART:...Z` with the correct UTC instant, and that a missing VTIMEZONE is never emitted.
 
 ---
 
-### Pitfall 5: Double-Drain When Event-Driven Trigger and 15s setInterval Both Fire
+### Pitfall 5: Provider Abstraction Refactor Regresses the Live Fastmail Path
 
 **What goes wrong:**
-The v1.1 event-driven drain adds a trigger (Redis pub/sub message, or direct `runOutboxDrain()` call) that fires immediately when a new row is enqueued. The 15s `setInterval` fallback continues to run. Both can invoke `runOutboxDrain()` concurrently. The existing `isDraining` module-level flag provides single-execution within the same JS tick, but there is a subtler race:
+Extracting a `CalendarProvider` interface from the existing CalDAV code requires moving the tsdav client, sync logic, poller, outbox worker, and reminder scheduler from Fastmail-specific code into an abstraction layer. The risk is that the refactor introduces a regression on the Fastmail path: a subtle behavioral change in the outbox worker (e.g., enqueue ordering, `isDraining` guard, or the `drainRequested` flag) can cause:
 
-- T=0: Route enqueues row. Event-driven trigger calls `runOutboxDrain()`. `isDraining` is set.
-- T=0.5s: Drain in progress. 15s interval fires. `isDraining` is true — no-op. Correct.
-- T=1s: Drain completes. `isDraining` reset to false.
-- T=1.5s: Event-driven trigger for a SECOND enqueue calls `runOutboxDrain()`. Drain starts.
-- T=14s: First 15s tick since startup fires (not 15s after the last drain completed, but 15s after the interval was registered at server start). Calls `runOutboxDrain()`. `isDraining` is true — no-op. Correct.
+- Duplicate CalDAV PUTs (double-drain race reintroduced).
+- Create-before-delete ordering broken for move operations.
+- The ctag-based poller not calling the new interface method in the correct order (poll → sync → schedule).
+- The `uid:dtstartMs` dedup key in the reminder scheduler falling back to `uid` alone if the schema type changes during the refactor.
 
-So far so good — `isDraining` handles this. The failure mode is: **if `runOutboxDrain` is called directly (not through the setInterval wrapper) from the event-driven path, thrown errors will not be caught by the setInterval `.catch()` handler.** An unhandled rejection crashes the process on Node 22 (where unhandledRejection is fatal by default unless a handler is registered). The fix is to always use the same error-caught wrapper: `runOutboxDrain().catch(err => console.error(...))`.
-
-A more dangerous double-drain scenario arises if the event-driven trigger is implemented via ioredis pub/sub and the subscriber receives the same message twice (ioredis at-least-once delivery). Two concurrent `runOutboxDrain()` calls can occur before either sets `isDraining`. The `isDraining` check is not atomic. In the single-process Node.js event loop, two synchronous checks of `isDraining` before any `await` both see `false` and both proceed. The first `await db.select()...` in both drain calls then runs in parallel. Both fetch the same pending rows and dispatch the same CalDAV writes, producing duplicate PUTs.
+A specific risk: the outbox worker currently reads `provider_type` from `member_credentials` but the only implemented value is `'caldav'`. During refactor, if the worker is changed to dispatch to a provider-specific `write()` method, and the CalDAV write path is accidentally placed behind a `provider_type === 'google'` branch instead of `provider_type === 'caldav'`, all existing Fastmail write-back silently stops with no error (the wrong branch simply does nothing).
 
 **Why it happens:**
-`isDraining` is a module-level boolean, not a mutex or a DB-level row lock. In the single-process deployment it is correct for the `setInterval` case (the JS event loop ensures only one tick can run at a time). But two synchronous calls to `runOutboxDrain()` before any `await` both pass the `if (isDraining) return` check because the flag is set inside the function body, not before the call.
+Refactors that extract interfaces from working code are high-regression-risk because the tests were written against the concrete implementation. The test suite may pass because it stubs the CalDAV calls but not the new interface dispatch, so the dispatch logic change is never exercised by tests.
 
 **How to avoid:**
-Wrap the event-driven call in the same caught wrapper. More importantly: do not call `runOutboxDrain()` directly from the pub/sub subscriber. Instead, call a `triggerDrain()` helper that sets `isDraining = true` synchronously before the first await, or simply lets the setInterval do the work and uses the pub/sub message only to shorten the next wait (e.g., trigger a single immediate `runOutboxDrain()` call from within the setInterval handler if a "pending" flag is set, keeping all drain calls single-threaded through the interval). The cleanest approach: keep one drain path (the setInterval), but when an enqueue event arrives, set a `drainRequested` flag; the next setInterval tick checks the flag and drains immediately instead of waiting the full 15s.
+Refactor behind a feature flag or in a branch that keeps the Fastmail path fully operational throughout. Do not merge the provider abstraction until all existing CalDAV integration tests (outbox, poller, ctag, reminder scheduler) pass unchanged against the new interface.
+
+Write a golden-path integration test for the Fastmail provider specifically: enqueue a write → assert it reaches the CalDAV mock → assert the outbox row is marked done. This test must pass before and after the refactor with no modification.
+
+Keep the `provider_type === 'caldav'` dispatch path as the default/fallback. The Google path (`provider_type === 'google'`) is additive; it must not be required for the existing Fastmail path to work.
+
+The abstraction interface should be defined from the consumer's perspective (what `outboxWorker.ts` and `poller.ts` need), not from the CalDAV implementation's perspective. Avoid leaking tsdav types (`DAVCalendar`, `DAVObject`) into the interface — callers should see normalized event objects.
 
 **Warning signs:**
-
-- Duplicate CalDAV PUTs for the same event visible in Fastmail logs.
-- Two identical events appearing briefly after an edit.
-- 412 conflict errors on the second of two simultaneous drain calls (the first PUT succeeded, the second uses an outdated etag).
+- Any existing CalDAV integration test is modified during the refactor (should be zero changes to existing tests).
+- The outbox worker has a branch that exits without calling any write method for `provider_type === 'caldav'`.
+- The `provider_type` column contains `'caldav'` for all existing rows but the refactored dispatch uses string equality without a default case.
 
 **Phase to address:**
-Event-driven outbox drain phase. The drain trigger design must be reviewed before implementation; the `isDraining` guard docs already note the single-process limitation.
+Provider abstraction phase (first). Must ship before any Google Calendar code is written. The acceptance gate is: all v1.1-passing integration tests still pass, unchanged, with the abstraction layer in place.
 
 ---
 
-### Pitfall 6: Event-Driven Drain Breaks Create-Before-Delete Ordering Under Concurrent Enqueues
+### Pitfall 6: Multiple VALARMs — Duplicate Fire and Preserve-vs-Replace Ambiguity
 
 **What goes wrong:**
-The edit-as-move path enqueues two rows (delete old uid, create new uid) in the same request handler. With the 15s poll, both rows are almost always in the DB before the next drain cycle. With event-driven drain (trigger fires on enqueue), a race is possible:
+v1.2 adds multiple reminders per event (multiple VALARMs on a single VEVENT). The v1.1 reminder scheduler deduplicates on `uid:dtstartMs` — one dedup entry per event. With multiple VALARMs, a single event now needs multiple push notifications at different lead times. If the dedup key is still `uid:dtstartMs`, only the first alarm fires; subsequent alarms for the same event at different leads are treated as "already sent" by the dedup map.
 
-- Request handler enqueues the CREATE row. Event-driven trigger fires immediately. Drain runs. Create is dispatched successfully. `isDraining` resets.
-- Request handler (same HTTP request, now at the second DB insert) enqueues the DELETE row. Trigger fires again. Drain runs. The create is status=done. The delete is dispatched.
+A second issue: the scheduler currently runs a SQL query for events where `reminderLeadMinutes IS NOT NULL`. With multiple reminders stored as multiple VALARM objects in `rawVevent` (and potentially as a JSON array or repeated column), the SQL query must change to a per-VALARM lead-time scan. If the query fetches one row per event and picks the first VALARM lead only, subsequent alarms are silently skipped.
 
-This is actually the happy path — correct ordering. The dangerous case is if the HTTP handler enqueues the DELETE row first and the CREATE row second (e.g., if the code is written in that order). The event-driven drain fires after the DELETE enqueue, finds the delete row with no done-sibling, and the durable CR-04 gate defers it. When the CREATE is then enqueued and drained, the delete is re-attempted on the next cycle — also correct. But if the delete fires before the create for any reason (e.g., a coding error that enqueues in the wrong order, or the delete row has a lower `next_attempt_at`), the original event is deleted before the new one is confirmed, causing data loss.
+A third issue: the VALARM preserve-on-edit path (D-08 / CAL-14, shipped in Phase 11) extracts all existing VALARMs from `rawVevent` and re-attaches them. With multiple VALARMs, if the user adds a new reminder in the FamilySync UI (which produces one VALARM from the picker), the preserve path must decide: replace all existing VALARMs with the single new one, or append? The current single-reminder model implicitly "replace all." Multiple-reminder UI changes this intent.
 
-A subtler issue: if the event-driven trigger fires between the two DB inserts in the same HTTP handler (possible if the first `await db.insert()` resolves and the trigger fires before the second `await db.insert()` runs), the drain may start before both rows are committed. MySQL/MariaDB default isolation (REPEATABLE READ) means the drain transaction may not see the second row at all until it starts a new transaction. The CR-04 durable gate handles this case: the delete will defer itself because the sibling create is not yet visible. But if the create row is invisible, the drain processes the delete alone, defers it correctly, and then the create arrives. This is safe but results in at least one extra drain cycle for the move. Not a bug, but a latency regression on the event-driven path.
+A fourth issue: Google Calendar caps reminders at 5 per event (`reminders.overrides` max 5). If the user creates 6 reminders in FamilySync and the event is in a Google Calendar, the write-back to the Google Calendar API returns a 400 error. The error must be caught and surfaced to the user before the write, not as a silent failure.
+
+**Why it happens:**
+The v1.1 architecture was designed for exactly one VALARM per event (the picker is single-selection). Multiple VALARM support requires rethinking the dedup key, the SQL query, the preserve logic, and the write-back validation.
 
 **How to avoid:**
-Always enqueue the CREATE row before the DELETE row in the HTTP handler, matching the existing sort-before-dispatch logic in the drain. This is already the intent of D-04 but should be an explicit code comment in the edit-as-move handler.
+Change the scheduler dedup key to `uid:dtstartMs:leadMinutes` (three-part key). Each VALARM on an event gets its own dedup entry, and each fires independently.
 
-Do not trigger the event-driven drain between the two enqueue inserts. If the trigger is a direct call, wrap both inserts in a single DB transaction and trigger the drain only after the transaction commits. If the trigger is Redis pub/sub, publish after both inserts.
+Store multiple reminder leads in a normalized form. Two options: (a) a `event_reminders` junction table (`event_id`, `lead_minutes`), or (b) a JSON array column `reminder_lead_minutes_json` on `calendar_events`. Option (a) is cleaner for SQL querying; option (b) avoids a second migration and join. For a two-user household, option (b) is acceptable. The SQL scheduler query must unnest or join to iterate per-lead.
+
+For the preserve-on-edit path: the UI must distinguish "user changed reminders" from "user changed something else (title, time, location)." If reminders were not touched, preserve all existing VALARMs. If the user opened the reminder editor and submitted, replace all VALARMs with the new set. This is a frontend concern: include a `remindersChanged: boolean` flag in the outbox payload alongside the new `reminderLeads: number[]` array.
+
+For Google Calendar cap validation: add a Zod validator on the outbox payload schema that rejects more than 5 reminder leads when the provider is Google. Surface the error in the form before submit.
 
 **Warning signs:**
-
-- Edit-as-move operations produce a "calendar object not found" error from Fastmail (delete reached Fastmail before the create).
-- Events occasionally disappear after an edit and reappear after the next poller sync cycle.
-- CR-04 deferral log messages (`Deferring delete row...`) appearing frequently for move operations.
+- Second and third reminders on an event never fire.
+- The scheduler sends duplicates for the first alarm on every tick (dedup not working after key change).
+- Events with 6+ reminders silently fail to write to Google Calendar.
+- The preserve path strips all VALARMs when the user edits only the event title.
 
 **Phase to address:**
-Event-driven outbox drain phase. The enqueue ordering requirement and transaction boundary must be specified in the plan.
+Multiple reminders phase. The dedup key change and schema migration must land in the same plan. Google cap validation must land in the same plan as Google write-back support.
 
 ---
 
-### Pitfall 7: Admin App-Password Update Logged or Echoed in Error Messages
+### Pitfall 7: Drizzle Auto-Migrate on Boot on MariaDB 11 — The Three Failure Modes
 
 **What goes wrong:**
-The admin Settings route receives the new Fastmail app password in the request body. If Zod validation fails (wrong format, too long), the default Zod error message includes the invalid value in the error output: `Invalid value: "xxxx-xxxx-xxxx-xxxx"`. If the Hono error handler returns this Zod error to the client as JSON, the app password appears in: (1) the HTTP response body, (2) any request logging middleware, (3) server logs if the error is caught and `console.error(err)` is called with the full error object.
+v1.2 adds zero-manual-setup: the API process runs pending migrations automatically at startup. There are three distinct failure modes specific to this stack:
 
-Separately: `decryptPassword` in `broker/crypto.ts` currently never logs the decrypted value (T-03-13), but the admin update route must call `encryptPassword(newPassword)` after receiving the plaintext. If the route logs the request body at any point before the encrypt call, the password is in the logs.
+**Failure mode A — Journal-hash mismatch with legacy tracking.** The `__drizzle_migrations` table records applied migrations by `tag`. If any migration file was renamed after it was applied to an existing database (or if the journal was re-generated, changing the `when` timestamp), drizzle-kit migrate will not find the matching `tag` in `__drizzle_migrations` and will try to re-apply the already-applied migration. On MariaDB, re-running `ALTER TABLE ... ADD COLUMN` for a column that already exists returns `Duplicate column name` — not a transaction rollback, but a crash. This is the "journal-hash mismatch" lesson from D-MIGRATION-10-01.
+
+**Failure mode B — False destructive diff if `db:push` logic is used.** Any code path that calls `drizzle-kit push` (even programmatically or from a startup script) against the live MariaDB will schedule TRUNCATE/DROP. The `drizzle migrate` API (programmatic via `drizzle-orm/migrator`) is safe — it applies committed `.sql` files and does not introspect the live DB. The failure mode is: a developer adds a startup call that uses the wrong drizzle API entry point.
+
+**Failure mode C — Concurrent startup race (two container instances).** If the Docker Compose stack is ever restarted in a way that brings up two API containers briefly (e.g., a rolling update or `docker-compose up --scale api=2`), both instances call `migrate()` at startup. MariaDB does not have advisory locks by default. Both instances read `__drizzle_migrations`, both see the same unapplied migrations, and both attempt to apply them simultaneously. The first to commit wins; the second hits `Duplicate column name` or a primary key conflict and crashes. The container crash loop then restarts the container, which succeeds because migrations are now applied — but the crash log looks like a startup failure.
 
 **Why it happens:**
-Developers often log `req.body` at the route level for debugging during development. The admin route is new, debugging is natural, and the log line gets committed. Zod error passthrough is the other common source — the validator middleware returns the full error object.
+Startup migration is convenient but runs without a human watching the DDL. The existing dev workflow always runs `pnpm db:migrate` explicitly, so a developer sees the output. Auto-migrate is invisible unless there is explicit logging. On MariaDB (no DDL transactions), a partially-applied migration leaves the schema in an undefined state.
 
 **How to avoid:**
-In the `@hono/zod-validator` middleware for the app-password body schema, always use a custom `hook` to return a generic `{ error: "Invalid request" }` without the Zod error detail. Never log the request body in the admin/settings routes. Add a lint rule or code review checklist item: no `console.log` in any file under `routes/admin*` or `routes/settings*` that could include body content.
+Use the `drizzle-orm/migrator` programmatic API (`migrate(db, { migrationsFolder: '...' })`), not `drizzle-kit` CLI, in the startup path. The migrator API applies committed SQL files sequentially and tracks via `__drizzle_migrations` — it is safe for auto-migrate.
 
-For test coverage: write a unit test that asserts the route returns `400` with no `value` field in the response when given an invalid password. Do not assert on the specific Zod error message.
+Add a startup log that prints each migration file name as it is applied (or "already applied, skipping"). This makes auto-migrate auditable.
+
+For the concurrent-startup race: wrap the migrate call in a MariaDB advisory-lock table: `INSERT INTO migration_lock (id) VALUES (1)` with a unique constraint. If the insert fails, the other instance already holds the lock and is migrating — wait and retry. On success, run migrations, then `DELETE FROM migration_lock WHERE id=1`. This is a single-row sentinel table, created before any other migration.
+
+For distinguishing fresh-DB vs existing-DB: the `__drizzle_migrations` table not existing means a fresh DB — apply all migrations. The table existing with all entries means fully migrated — skip. The table existing with some entries means a partial state — apply only the unapplied subset (normal drizzle behavior). No special-casing needed; the migrator handles this correctly.
 
 **Warning signs:**
-
-- App password appears in any log output or API response body.
-- The Zod error response for the settings route includes a `received` or `message` field containing password-like strings.
+- `Duplicate column name` error in the API startup log immediately after deployment.
+- Two container instances log "applying migration 0003_..." at the same timestamp.
+- The API container crashes on first start but succeeds on second start (concurrent-race symptom).
+- Any code calling `drizzle-kit push` in a startup path (grep for it explicitly before shipping).
 
 **Phase to address:**
-Admin Settings phase. Security review of the settings route before first deployment; treat app-password fields the same as `OIDC_CLIENT_SECRET` — never log, never echo.
+Zero-manual-setup DB migration phase. The `migration_lock` sentinel table and the startup log must be in the acceptance criteria. Write a test that runs `migrate()` twice on the same DB and asserts no error and no duplicate column.
 
 ---
 
-### Pitfall 8: Unauthenticated Setup Endpoint Left Live After First Run
+### Pitfall 8: PWA Dark Mode — Flash of Wrong Theme and Service Worker Cache Staling
 
 **What goes wrong:**
-The setup wizard endpoint must be accessible before any member has authenticated (no credentials exist yet, so OIDC cannot be used to protect it). The typical implementation: mount the setup routes outside the `app.use('/api/*', oidcAuthMiddleware())` guard, and detect "first run" by checking whether any `member_credentials` row (or VAPID env) exists. The failure mode: the first-run check passes once. But if the developer forgets to add an "already-set-up" guard, or the check looks at the wrong table, the endpoint remains callable after setup — allowing anyone who can reach the internal network (or the Pangolin public URL) to overwrite the app password without authentication.
+The standard dark mode pattern — read `prefers-color-scheme` or a `localStorage` preference and apply a `data-theme` attribute on `<html>` — has a flash-of-wrong-theme (FOWT) on initial load if the attribute is set by React (after hydration) rather than by an inline script before the first paint. The user sees light mode for ~100ms then switches to dark. On iOS standalone PWA, this flash is especially visible because the splash screen (controlled by `theme-color` meta tag) may not match the applied theme.
 
-A second failure mode: the wizard validates env vars (VAPID keys, DB connection, app password) but stores the app password directly in the DB or in a temp file instead of in an env var. The architecture requires app passwords to be encrypted at rest using `APP_PASSWORD_ENCRYPTION_KEY`. If the wizard stores the password before the encryption key env is set (it shouldn't be — the wizard is supposed to collect the key or confirm it exists), the encryption call throws and the wizard fails with a 500 that may include the plaintext password in the error.
+The deeper issue: Schedule-X uses `--sx-color-*` CSS custom properties for its calendar component theming. These are not in the `tokens.css` semantic token layer established in Phase 17. If dark mode only updates the FamilySync token variables and not the `--sx-color-*` variables, the calendar component remains in light mode regardless of the document theme — a visually broken state that is easy to miss in desktop testing (because developers often test on a light system preference).
+
+A service worker cache complication: the Workbox-managed precache caches `index.html` and all static assets at build time. If the theme preference is baked into a cached `index.html` (e.g., via a server-side render or a build-time default), the cached version will always load with the light-mode default, overriding the user's stored preference. In Vite PWA (client-side rendered), this is not the primary risk — but if the service worker caches a CSS file that includes hardcoded light-mode colors (not variables), dark mode changes deployed in a new build will not reach the user until the service worker updates.
 
 **Why it happens:**
-Setup wizards are one-shot paths that receive less testing than the main app. "First run only" guards are often implemented as booleans that can be reset, or checks that are too broad.
+Dark mode is treated as a CSS-only concern but the FOWT is a JS execution timing concern. Schedule-X's custom properties are undocumented relative to external theming. Service worker cache invalidation for CSS changes requires a cache-busting strategy.
 
 **How to avoid:**
-Implement the "already set up" guard as: check for any row in `member_credentials` AND for the presence of VAPID env vars (not just one or the other). If either is already set, return 423 Locked from all setup endpoints. Once the setup completes successfully, the next request to setup routes returns 423 immediately — no state to reset without a server restart.
+Prevent FOWT: inject a minimal inline `<script>` in `index.html` (before any CSS) that reads `localStorage.getItem('theme')` and sets `document.documentElement.dataset.theme` synchronously. This runs before any CSS is parsed, preventing the flash. The React app then reads the same localStorage key on mount to initialize the Zustand theme store.
 
-Alternatively, use a DB-stored `setup_completed_at` timestamp in a `settings` table (a migration is needed anyway for v1.1 admin features). The wizard marks this column on completion; all setup routes check it first.
+Map all `--sx-color-*` variables used by Schedule-X to the FamilySync dark/light token values. Inspect the Schedule-X `@schedule-x/theme-default` CSS to enumerate all `--sx-*` variables and override them in a `tokens.css` `[data-theme="dark"]` block. Assert that the calendar renders in dark mode during the dark mode acceptance test.
 
-Never accept the `APP_PASSWORD_ENCRYPTION_KEY` value via the API. The wizard should validate that the env is already set (by attempting a test encrypt/decrypt), not collect the key. The key stays in the env/Docker secrets layer.
+For service worker cache: `vite-plugin-pwa` handles cache busting via file hashing in the build output. Verify that `tokens.css` (or whichever file holds the dark mode variables) is included in the Workbox precache manifest — if it is in the public directory without a hash, it may not be cache-busted on deploy. Move all theme CSS into a hashed build output file.
+
+For iOS standalone PWA `theme-color`: update the `<meta name="theme-color">` dynamically using `document.querySelector('meta[name="theme-color"]').setAttribute('content', ...)` when the theme toggles. iOS reads `theme-color` for the status bar color. A static `theme-color` will not match the active dark theme.
 
 **Warning signs:**
-
-- Setup endpoint returns 200 after the app is already configured.
-- Curl to `/api/setup/...` with no auth cookie returns a non-401/423 response.
-- Setup route has no test covering the "already set up" scenario.
+- Brief white flash visible on page load when dark mode is selected.
+- The calendar component (Schedule-X) shows light colors while the rest of the app is dark.
+- iOS status bar color does not match the active theme.
+- Deploying a dark mode CSS update does not reach users until they manually clear the service worker cache.
 
 **Phase to address:**
-Setup wizard phase. The guard must be the first thing implemented; test the guard before testing the happy path.
+PWA dark mode phase. The FOWT fix (inline script in `index.html`) and Schedule-X variable mapping must be in the acceptance criteria. Test on both light and dark system preferences. Test with the service worker active (not disabled).
 
 ---
 
-### Pitfall 9: Admin Role Check Bypassed by Missing Middleware Wiring
+### Pitfall 9: OAuth Callback Through Pangolin/Newt Tunnel — Redirect URI Mismatch and State Cookie Collision
 
 **What goes wrong:**
-The admin Settings routes require a role check (only the operator/admin user can manage credentials and toggle `is_shared`). The standard pattern in this codebase is Hono middleware layered on a route prefix. The failure mode: the admin middleware is defined but not wired to the correct prefix. For example, if the admin check is added to `eventsRouter` instead of a new `adminRouter`, or if the route is mounted at `/api/admin` but the middleware guard applies to `/api/settings/*`, admin routes are reachable by any authenticated member.
+The Google OAuth flow requires registering exact redirect URIs in the Google Cloud Console. The Pangolin/Newt tunnel exposes the app at a public hostname (e.g., `familysync.example.com`). The registered redirect URI must match exactly: `https://familysync.example.com/api/auth/google/callback`. If the redirect URI in the Google Cloud Console is `http://` instead of `https://`, or includes/omits a trailing slash, or uses the internal hostname instead of the Pangolin hostname, the callback returns `redirect_uri_mismatch` from Google.
 
-In a two-person household this is low-severity (both members are trusted), but the `is_shared` toggle can break the whole calendar display for both members if set incorrectly, and the credential management can overwrite the other member's app password.
+A second issue: the existing Authelia OIDC flow already uses an OAuth state cookie (`oidc.state`) managed by `@hono/oidc-auth` (stored as a cookie on the domain). The Google OAuth flow also requires a `state` parameter to prevent CSRF. If both flows use the same cookie name, or if the `@hono/oidc-auth` middleware intercepts the Google OAuth callback URL (because it pattern-matches `/api/*` for auth), the Google callback's `code` parameter is consumed by the Authelia handler before the Google handler sees it — resulting in a `state mismatch` or `invalid_grant` error.
+
+A third issue: the Pangolin/Newt tunnel may terminate TLS and forward HTTP internally. If the API receives the Google callback over HTTP (forwarded internally), but the `redirect_uri` registered in Google is `https://`, Google's OAuth server rejects the authorization code exchange with `redirect_uri_mismatch` because the `redirect_uri` in the token exchange request is constructed from the internal HTTP URL, not the external HTTPS URL.
 
 **Why it happens:**
-Hono's middleware scoping is based on route prefix at mount time, not at route definition time. A middleware added with `app.use('/api/admin/*', adminGuard)` does not protect routes mounted under `app.route('/api/admin', adminRouter)` unless the `adminRouter` itself also applies the guard. It is easy to apply the middleware in one place and assume it covers the route, but Hono's `.route()` creates an isolated sub-app.
+Two OAuth flows in one app (Authelia OIDC for user login + Google OAuth for calendar access) use overlapping mechanisms (cookies, state params, callback routes). The Pangolin/Newt HTTPS termination creates an HTTP-internally-but-HTTPS-externally environment where naive URL construction picks the wrong scheme.
 
 **How to avoid:**
-Apply the admin middleware inside `adminRouter` itself (`.use('*', adminGuard)`), not only in the parent app. Write an integration test that calls a settings route as a non-admin authenticated user and asserts 403. Do not rely on the parent app's middleware order for sub-app security.
+Mount the Google OAuth callback at a distinct path that the Authelia `@hono/oidc-auth` middleware does not intercept: `/api/providers/google/callback` (not under `/api/auth/`). Apply the Authelia OIDC middleware only to routes that need a logged-in session, not as a global catch-all for `/api/*`. The Google callback handler does not need an Authelia session — it needs the Google state param. Apply authentication to the Google OAuth _initiation_ endpoint (user must be logged in to connect Google), but not to the callback endpoint (callback must be reachable without a session because Google redirects there).
+
+Use distinct state cookie names: the Authelia flow uses `oidc.state` (managed by `@hono/oidc-auth`); the Google flow should use `google.oauth.state` (managed by the Google OAuth handler). Store the state in a `HttpOnly; SameSite=Lax; Secure` cookie with a 10-minute TTL.
+
+For the HTTPS scheme: read the external hostname from a `EXTERNAL_BASE_URL` environment variable (e.g., `https://familysync.example.com`) and construct all OAuth redirect URIs from it. Never derive the redirect URI from `req.headers.host` or `req.protocol` — the internal forwarded values will be wrong. Add `EXTERNAL_BASE_URL` to the required env checklist in the zero-setup wizard.
+
+Register the redirect URI in Google Cloud Console as exactly `${EXTERNAL_BASE_URL}/api/providers/google/callback`.
 
 **Warning signs:**
-
-- Any authenticated user can reach `/api/admin/...` routes without an admin check in the response.
-- The admin middleware is defined in `index.ts` but the admin routes are in a separate `adminRouter` with no internal middleware.
+- Google OAuth callback returns `redirect_uri_mismatch`.
+- After completing the Google consent screen, the app returns to the homepage without connecting the account (silent failure).
+- Authelia OIDC errors appear in logs during a Google OAuth flow (state cookie collision).
+- The Google callback URL in server logs shows `http://` instead of `https://`.
 
 **Phase to address:**
-Admin Settings phase. Integration test for 403 on non-admin access is the acceptance criterion.
+Self-service Google OAuth onboarding phase. The `EXTERNAL_BASE_URL` env var and the distinct callback path must be established before any OAuth flow is implemented. Test the full flow end-to-end over the Pangolin tunnel (not just localhost) as the acceptance gate.
 
 ---
 
-### Pitfall 10: App Password and VAPID Keys Stored in DB When They Must Stay in Env
+### Pitfall 10: Google OAuth Token Storage — Encryption Key Reuse and Scope Creep
 
 **What goes wrong:**
-The setup wizard collects VAPID keypair and validates the Fastmail app password. A tempting shortcut: store the VAPID keys in the `settings` DB table for easy retrieval later. The problem: `VAPID_PRIVATE_KEY` is a signing key — equivalent to a private TLS key. Storing it in the DB means it is:
+The Google OAuth access token (short-lived, ~1 hour) and refresh token (long-lived) must be stored securely. The existing `member_credentials` table stores the Fastmail app password encrypted with `APP_PASSWORD_ENCRYPTION_KEY` (AES-256-GCM). The tempting approach: store the Google refresh token in the same `member_credentials` table with the same encryption key, adding a `google_refresh_token` column.
 
-- Accessible to anyone with DB read access (including `SELECT *` from a misconfigured tool or a Drizzle Studio session left open).
-- Included in DB backups, which may be stored less securely.
-- Returned by any accidental DB dump to logs.
+The first issue: `provider_type` is already `UNIQUE(user_id)` on `member_credentials` (enforced by `uniq_member_credential_user`). A member with both a Fastmail credential and a Google credential would need two rows but the unique constraint allows only one per user. Attempting to upsert the Google credential overwrites the Fastmail credential, breaking CalDAV.
 
-`APP_PASSWORD_ENCRYPTION_KEY` must never enter the DB at all — it is the key that encrypts everything else. If the wizard stores it in the DB "just for display/verification," the entire encryption model is broken.
+The second issue: the Google access token should not be stored persistently — it expires in 1 hour and must be refreshed on use. If the code stores the access token as well as the refresh token, the stored access token will always be stale and the code must always call the token refresh endpoint anyway. Storing the access token wastes a column and tempts future code to use it without checking expiry.
+
+The third issue: the Google OAuth scope should be the minimum needed. If the developer uses `https://www.googleapis.com/auth/calendar` (full calendar access) instead of the split `calendar.readonly` + `calendar.events` scopes, Google requires manual verification review for production status. Use the minimum scope needed.
 
 **Why it happens:**
-The wizard naturally wants to show "current configuration" and make it editable. Pulling values from env vars in a form feels awkward; storing in DB feels clean. The distinction between "secret that must stay in env" and "config that can live in DB" gets blurred.
+The `member_credentials` unique constraint and the `provider_type` discriminator were designed for a single provider per user. Multi-provider support requires rethinking the credential storage schema.
 
 **How to avoid:**
-Hard rule: `VAPID_PRIVATE_KEY` and `APP_PASSWORD_ENCRYPTION_KEY` never touch the DB. They are validated in the wizard by attempting an operation (test encrypt/decrypt, test push send), not by reading or writing their values. `VAPID_PUBLIC_KEY` and `VAPID_SUBJECT` can be stored in DB (they are not secrets). Fastmail app passwords are stored encrypted (AES-256-GCM via `encryptPassword`), which is already implemented.
+Change the `member_credentials` schema for v1.2: drop the `UNIQUE(user_id)` constraint and replace it with `UNIQUE(user_id, provider_type)`. This allows one row per provider per user. The migration is additive (drop unique, add composite unique). Verify with `drizzle-kit generate` that the generated SQL is `DROP INDEX uniq_member_credential_user; ADD UNIQUE KEY uniq_member_credential_user_provider (user_id, provider_type)` — additive DDL plus an index drop. The index drop is safe on MariaDB (not a TRUNCATE).
 
-The wizard's "check env" validation path: call `encryptPassword('test')` — if it throws, `APP_PASSWORD_ENCRYPTION_KEY` is missing or malformed. Call `webpush.setVapidDetails(...)` and catch throws. Never read the key values out of `process.env` into a response body.
+Store only the Google refresh token (not the access token). Add a `google_refresh_token_encrypted` column (or a generic `oauth_refresh_token_encrypted` column) to the Google `provider_type` row. Derive fresh access tokens at request time using the refresh token — cache the access token in memory (not in the DB) with its expiry time.
+
+Use scopes: `https://www.googleapis.com/auth/calendar.readonly` + `https://www.googleapis.com/auth/calendar.events`. Request them space-separated. Store the granted scopes alongside the refresh token so the app knows what the user consented to.
 
 **Warning signs:**
-
-- DB schema has a `vapid_private_key` column.
-- Any API response that includes `VAPID_PRIVATE_KEY` or `APP_PASSWORD_ENCRYPTION_KEY` values.
-- Wizard stores all config to DB and reads it back on next startup instead of requiring env vars.
+- An attempt to add a second `member_credentials` row for the same user hits a unique constraint violation.
+- `member_credentials` for a user shows `provider_type: 'google'` but the CalDAV credential is gone.
+- The access token column in the DB is always expired.
+- Google authorization flow requests the `https://www.googleapis.com/auth/calendar` scope (full access, not split).
 
 **Phase to address:**
-Setup wizard phase. Schema design review before migration is written. Secret-in-DB is a hard blocker for the phase gate.
+Provider abstraction phase (schema migration plan) and Google OAuth onboarding phase. The schema change to `UNIQUE(user_id, provider_type)` must land before any Google credential storage code is written.
 
 ---
 
-### Pitfall 11: Gitea Actions MariaDB Service Container Readiness Race
+### Pitfall 11: Dependency Updates — ESLint 10 Pin and Breaking Change Cascade
 
 **What goes wrong:**
-Gitea Actions (like GitHub Actions) supports `services:` containers. The MariaDB service starts, but the container reaching `healthy` in Docker does not mean MariaDB is accepting connections on port 3306. `mysqld` takes several seconds to initialize after the container starts. If the CI job proceeds to `drizzle-kit migrate` or integration test commands immediately after the service health check passes, it races with MariaDB initialization and fails with `ECONNREFUSED` or `Access denied` errors that look like test failures but are actually timing issues.
+The CI dependency audit (Phase 16) surfaces `outdated` packages. Bulk-applying `pnpm up` or `pnpm audit fix` will attempt to update ESLint to v10, which breaks `eslint-plugin-react` and `eslint-plugin-react-hooks` (both declare only `eslint@9.x` as a peer dependency as of 2026-06). When ESLint 10 is installed, both plugins either throw `EBADPEERCONN` at install time or emit no errors at lint time (silently disabled), breaking the CI lint gate.
+
+A secondary risk: `@schedule-x/calendar` and `@schedule-x/theme-default` have been updated (currently pinned at 4.6.0 in `apps/pwa`). Schedule-X 5.x (if released) changes the `--sx-color-*` variable naming. If the dependency update phase bumps Schedule-X to a major version before the dark mode phase, the dark mode variable mapping work must be redone with the new variable names.
+
+A third risk: `drizzle-kit` and `drizzle-orm` minor versions must be updated together. The `drizzle-orm/mysql2` import path and the `drizzle-orm/migrator` API are version-coupled. If `drizzle-orm` is bumped to 0.46.x but `drizzle-kit` stays at 0.31.x, the snapshot format version mismatch may cause `generate` to produce an incompatible snapshot that `migrate` cannot parse.
 
 **Why it happens:**
-The Docker `HEALTHCHECK` for MariaDB using `mysqladmin ping` returns true as soon as the network socket is open, which happens before all privilege tables are initialized. The `healthcheck.interval` in the Gitea service definition controls how often the check runs, but the first check may pass before MariaDB has fully bootstrapped.
+`pnpm up` or `pnpm audit --fix` applies updates greedily across the dependency tree without respecting known breaking-change boundaries. The project already knows about the ESLint 9.x pin but a future developer (or an automated tool) may not.
 
 **How to avoid:**
-Add a `wait-for-it` or `until mysqladmin ping --silent; do sleep 1; done` step in the CI workflow after the service is declared healthy, before running any DB command. Or use a longer `healthcheck.start_period` in the service definition (e.g., 30 seconds). Also: set `MARIADB_ROOT_PASSWORD`, `MARIADB_DATABASE`, `MARIADB_USER`, `MARIADB_PASSWORD` in the service env and use those same credentials in the integration test step — do not assume the root user is reachable from the test runner without a password.
+Update dependencies manually, one package or one ecosystem at a time, with the CI lint gate running after each batch. Never use `pnpm up --latest` or `pnpm audit --fix` without reviewing the changeset.
+
+ESLint: hold at 9.x until `eslint-plugin-react` and `eslint-plugin-react-hooks` both publish ESLint 10 peerDep support and the release notes confirm compatibility. Add a comment in the root `package.json` above the `"eslint"` entry: `// pinned at 9.x — eslint-plugin-react does not support eslint@10 yet`.
+
+Schedule-X: update minor versions only (4.x → 4.y). Hold at major 4 until dark mode theming is complete and the variable mapping is locked. Check Schedule-X release notes for `--sx-color-*` variable changes before any minor update.
+
+Drizzle: always update `drizzle-orm` and `drizzle-kit` in the same commit. After updating, run `pnpm db:generate` in a dry-run (the output must be "No schema changes, nothing to migrate") to verify the snapshot format compatibility.
 
 **Warning signs:**
-
-- CI passes on re-run but fails on first run of a PR (timing-dependent).
-- `ECONNREFUSED` or `Error: connect ECONNREFUSED 127.0.0.1:3306` in CI logs.
-- Tests that pass locally with a warm MariaDB fail in CI cold-start.
+- ESLint exits 0 (no errors reported) but previously failing lint rules now pass — plugin silently disabled.
+- `eslint-plugin-react@X requires eslint@">=9.0.0 <10.0.0" but got eslint@10.x.x` in pnpm install output.
+- `drizzle-kit generate` emits a snapshot with a different `version` field than the existing snapshots in `meta/`.
+- Schedule-X calendar renders with missing styles after a version bump.
 
 **Phase to address:**
-Gitea CI phase. The readiness wait must be in the first draft of the workflow YAML; do not add it after the first CI failures.
-
----
-
-### Pitfall 12: Gitea Actions Self-Hosted Runner Missing Node 22 or pnpm
-
-**What goes wrong:**
-The self-hosted Gitea Actions runner on Unraid may have an older Node.js version globally available, or may have no `pnpm` installation, or may have a `corepack`-managed pnpm that requires activation. If the CI workflow assumes the runner environment matches the dev machine, `pnpm install` fails with `pnpm: command not found`, or `node --version` returns 18 instead of 22.
-
-A related issue: the workflow may use `actions/setup-node` (a GitHub Actions action) which is not available in Gitea Actions, or uses a Gitea-specific variant that requires different configuration.
-
-**Why it happens:**
-Gitea Actions is not GitHub Actions. Many popular actions (`actions/checkout`, `actions/setup-node`, `actions/cache`) have Gitea-compatible alternatives, but their names and behavior differ subtly. If the workflow is copied from a GitHub Actions template, some steps silently fail or are skipped.
-
-**How to avoid:**
-In the first CI plan, write a minimal "hello world" workflow that only checks `node --version` and `pnpm --version`. Verify it passes before adding any test steps. Use `actions/setup-node` only if confirmed compatible with the specific Gitea version; otherwise install Node and pnpm explicitly in the workflow using `wget` / `npm install -g pnpm`. Pin the Node version to `22.x` explicitly; do not rely on the runner default.
-
-For Docker image build/publish: verify the runner has Docker daemon access. On Unraid self-hosted runners, Docker may require `--privileged` or specific socket mounts that need runner configuration.
-
-**Warning signs:**
-
-- `pnpm: command not found` in CI output.
-- `node` resolves to a version older than 22 in CI but not locally.
-- `actions/setup-node` step shows as skipped or errored in the Gitea Actions UI.
-
-**Phase to address:**
-Gitea CI phase. The runner environment probe must be the first CI task — before any test or build steps are designed.
-
----
-
-### Pitfall 13: Docker Registry Push Token Scope Exposes Secrets in Logs
-
-**What goes wrong:**
-The Gitea CI Docker build/publish step requires credentials for the Docker registry (Docker Hub, Gitea's own container registry, or a self-hosted registry). If the registry token is passed as a `docker login` argument on the command line (e.g., `docker login -u $USER -p $TOKEN`), the token appears in the process list, in the Gitea Actions job log (if command echo is on), and in any runner audit logs. Gitea Actions supports `secrets:` but if the workflow uses `run: docker login -p ${{ secrets.REGISTRY_TOKEN }}`, the secret is masked in the log only if the secret was registered correctly — unregistered secrets are echoed verbatim.
-
-**Why it happens:**
-Docker CLI login via `-p` flag is the most common example in docs. GitHub Actions masks secrets automatically; Gitea Actions masks them only for registered secrets. A token from a CI environment variable that was not added through the Gitea Secrets UI is not masked.
-
-**How to avoid:**
-Use `docker login --password-stdin` with the token piped via stdin rather than a command-line argument: `echo "${{ secrets.REGISTRY_TOKEN }}" | docker login -u "${{ secrets.REGISTRY_USER }}" --password-stdin registry.example.com`. Register all credentials as Gitea repository secrets, not as environment variables in the workflow YAML. Verify the Gitea version supports secret masking in the Actions log (Gitea ≥ 1.19 for Actions support; secret masking behavior varies by version).
-
-**Warning signs:**
-
-- Registry token or password visible as plaintext in the Gitea Actions job log.
-- `docker login` command line includes `-p <token>` in the log output.
-- `secrets.REGISTRY_TOKEN` is undefined in the workflow (token was set as env var, not secret).
-
-**Phase to address:**
-Gitea CI phase. Credential handling review before any Docker push step is added.
-
----
-
-### Pitfall 14: Playwright Authed-Mobile Harness Reusing a Stale storage-state
-
-**What goes wrong:**
-The mobile-emulated Playwright harness uses a saved `storage-state.json` (cookies + localStorage) to bypass the OIDC login flow. If the storage state was captured with a real Authelia session, it contains a session cookie with a finite TTL (typically 1 hour for `@hono/oidc-auth` JWT cookies, or the Authelia session lifetime). After the TTL expires, all Playwright runs with the stale storage state silently fail at the first `/api/*` call — the OIDC middleware redirects to Authelia, and the test gets an HTML login page instead of the expected JSON API response. The test may still pass if it only checks DOM content (which may be the redirected page's HTML), or it may produce a false-positive assertion on the 302 redirect.
-
-**Why it happens:**
-Playwright storage state is file-based and not automatically refreshed. Developers capture it once and check it in (or store it locally), then forget to renew it. In `DEV_AUTH_BYPASS=true` mode this does not apply (no session cookie needed), but if the harness is meant to test the production auth path, the bypass is not active and the session cookie must be valid.
-
-**How to avoid:**
-Do not use a static stored storage state for tests that run against the production OIDC path. Instead, implement a programmatic login helper that runs the OIDC authorization code flow at the start of each test session (or once per test run) and stores the resulting session. For the `DEV_AUTH_BYPASS` dev environment, the harness sets `DEV_AUTH_BYPASS=true` and skips the storage state entirely. The mobile viewport emulation does not require real OIDC — use `DEV_AUTH_BYPASS` for the automated harness; keep real OIDC tests as manual/human gates.
-
-**Warning signs:**
-
-- Playwright runs fail with `Expected 200 OK but got 302 Found` after leaving the storage state untouched for more than one day.
-- Tests that exercise `/api/*` routes return HTML (the Authelia login page) instead of JSON.
-- The same test suite passes reliably in `DEV_AUTH_BYPASS=true` mode but fails intermittently in production-auth mode.
-
-**Phase to address:**
-Mobile-browser testing phase. The storage state strategy must be decided before the first test is written — programmatic refresh or bypass-only.
-
----
-
-### Pitfall 15: Production Service Worker Intercepting Playwright Requests
-
-**What goes wrong:**
-The installed Vite PWA service worker (`sw.js`) is registered in the browser when the PWA is visited. Playwright's Chromium instance can load and activate the service worker from a previous test run (persisted in the browser's profile directory). On subsequent test runs, the service worker intercepts API calls — potentially returning cached responses from the previous run rather than making network requests to the test server. This causes:
-
-- API requests returning stale 200 responses when the test server is not running.
-- `queryClient.invalidateQueries` not triggering new network requests (SW returns cached response).
-- Tests that verify freshly-created data returning old data.
-
-**Why it happens:**
-Workbox's cache-first strategy for static assets and stale-while-revalidate for API routes persist across browser sessions in the Playwright profile. A new Playwright context does not clear the service worker registration unless explicitly reset.
-
-**How to avoid:**
-Use `browserContext.clearCookies()` and `browserContext.clearPermissions()` in the test setup, but also explicitly unregister service workers: `await page.evaluate(() => navigator.serviceWorker.getRegistrations().then(r => Promise.all(r.map(sw => sw.unregister()))))` before any navigation. Or launch Playwright with `serviceWorkers: 'block'` in the context options, which prevents the SW from intercepting requests entirely. For tests that specifically test offline/SW behavior, use a separate context without the block.
-
-**Warning signs:**
-
-- Network tab in Playwright traces shows `(ServiceWorker)` as the response source.
-- Tests pass on a clean browser profile but fail on a profile that has visited the PWA before.
-- API requests complete instantly with stale data in the Playwright trace.
-
-**Phase to address:**
-Mobile-browser testing phase. The Playwright context setup must explicitly handle service worker state before the first test is written.
+CI dependency update phase (last in milestone, after all feature phases). Treat each package ecosystem as a separate update batch. Run the full CI suite after each batch.
 
 ---
 
 ## Technical Debt Patterns
 
-| Shortcut                                                                         | Immediate Benefit            | Long-term Cost                                                  | When Acceptable                                                      |
-| -------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Building VALARM on top of `buildVeventString` without the preserve-on-edit path  | Faster to implement          | Strips native-client alarms on every edit; user data loss       | Never — preserve path must ship with VALARM authoring                |
-| uid-only dedup key in sentReminders when lead times become variable              | No migration needed          | Duplicate pushes or missed re-fires after reschedule            | Never for production; acceptable in tests with a fixed lead          |
-| Calling `runOutboxDrain()` directly from event trigger instead of setting a flag | Simpler code                 | Bypasses `isDraining` atomicity, potential double-drain         | Never — always funnel through the single setInterval-controlled path |
-| Setup wizard that accepts `APP_PASSWORD_ENCRYPTION_KEY` via the API              | Simpler UX for initial setup | Entire encryption model is broken                               | Never — key stays in env/secrets only                                |
-| Static storage-state.json checked into the repo                                  | Zero-effort Playwright auth  | Tests fail silently after TTY expiry; potential credential leak | Never — programmatic refresh or DEV_AUTH_BYPASS only                 |
-| `docker login -p $TOKEN` in CI command                                           | Quick to write               | Token appears in CI logs if secret not masked                   | Never — always use --password-stdin                                  |
-| No readiness wait for MariaDB service in CI                                      | Simpler YAML                 | Flaky CI: timing-dependent ECONNREFUSED failures                | Never — readiness wait is 3 lines and prevents ghost failures        |
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| Keeping `UNIQUE(user_id)` on `member_credentials` for the Google credential | No schema migration needed | Can only store one provider per user; Google credential overwrites Fastmail credential | Never — change to `UNIQUE(user_id, provider_type)` before any Google credential storage |
+| Storing Google access tokens persistently in the DB | Avoids token refresh logic | Access tokens expire in 1 hour; all stored values are always stale | Never — cache in memory only; persist only the refresh token |
+| Using `singleEvents: true` for Google Calendar event fetch | Simpler API call | Cannot reconstruct RRULE; recurring events appear as individual orphan events | Never — use `singleEvents: false` for the FamilySync data model |
+| Skipping the `migration_lock` sentinel table for auto-migrate | One fewer migration table | Concurrent startup races cause `Duplicate column name` crash loop | Never for a production deployment; acceptable in single-instance local dev |
+| Dark mode applied via React state (after hydration) | Simpler code | Flash-of-wrong-theme on every cold load | Never — use inline `<script>` in `index.html` to set the theme synchronously |
+| Deriving OAuth redirect URI from `req.headers.host` | No env var to configure | Returns internal hostname through Pangolin tunnel; causes `redirect_uri_mismatch` | Never — read from `EXTERNAL_BASE_URL` env var |
+| Bumping ESLint to v10 with other dependencies | Fewer outdated warnings | `eslint-plugin-react` is disabled silently; lint gate appears green but catches nothing | Never until eslint-plugin-react publishes v10 support |
+| Not handling Google `410 Gone` (expired syncToken) | Simpler sync code | All incremental sync halts permanently after 7 days of inactivity | Never — 410 is a documented, expected Google API response |
 
 ---
 
 ## Integration Gotchas
 
-| Integration               | Common Mistake                                                                | Correct Approach                                                                                         |
-| ------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| ical.js VALARM            | Using `addPropertyWithValue('trigger', '-PT15M')` (string)                    | Build `ICAL.Duration.fromSeconds(-N*60)` and use the Duration object as the property value               |
-| ical.js VALARM            | Not round-tripping preserved VALARMs through ical.js parse→serialize          | Parse the sub-component from rawVevent and re-add via ical.js API; do not insert raw text                |
-| outboxWorker VALARM       | Rebuilding VEVENT from scratch drops native-client VALARMs on update          | Extend buildVeventString to accept a `valarms` parameter; populate from rawVevent extract on update path |
-| reminderScheduler dedup   | uid-only Map key breaks when per-event leads vary                             | Key on `uid + ':' + dtstartMs`; prune by dtstartMs                                                       |
-| event-driven drain        | Calling `runOutboxDrain()` from pub/sub subscriber before `isDraining` is set | Use a single drain path via `drainRequested` flag checked in the setInterval callback                    |
-| Gitea Actions             | Using GitHub Actions-specific action IDs                                      | Probe the runner first; use Gitea-compatible alternatives or install tools explicitly                    |
-| Gitea Actions MariaDB     | Relying on container health == connection ready                               | Add explicit `mysqladmin ping` retry loop after healthcheck passes                                       |
-| Playwright mobile harness | Static storage-state.json with expiring session cookie                        | Use `DEV_AUTH_BYPASS=true` for automated harness; programmatic OIDC login for real-auth tests            |
-| Playwright + Vite PWA     | Service worker from previous run intercepting requests                        | Set `serviceWorkers: 'block'` or unregister SWs explicitly in test context setup                         |
-| Setup wizard              | Accepting `APP_PASSWORD_ENCRYPTION_KEY` via the POST body                     | Validate the env is present by performing a test operation; never accept the key value over the network  |
-| Admin settings route      | Zod error passthrough leaking app-password input                              | Custom `hook` in zod-validator: return generic 400, never the Zod error object                           |
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| Google Calendar API | `singleEvents: true` in events.list | Use `singleEvents: false`; fetch modified instances separately |
+| Google Calendar API | Not handling `status: "cancelled"` instances | Map cancelled instances to EXDATE on the master RRULE |
+| Google Calendar API | Ignoring `410 Gone` on syncToken expiry | Catch 410, clear token, enqueue full re-sync |
+| Google Calendar API | Using `https://www.googleapis.com/auth/calendar` scope | Use `calendar.readonly` + `calendar.events` (non-restricted, no Google verification required) |
+| Google OAuth | Constructing redirect URI from `req.protocol`/`req.hostname` | Read from `EXTERNAL_BASE_URL` env var; Pangolin terminates TLS so internal protocol is HTTP |
+| Google OAuth | Sharing state cookie name with `@hono/oidc-auth` Authelia flow | Use `google.oauth.state` cookie; mount Google callback outside the Authelia middleware scope |
+| Google refresh token | Storing access tokens in DB | Cache access tokens in memory with expiry; persist only refresh token (encrypted) |
+| Drizzle auto-migrate | Calling `drizzle-kit push` programmatically at startup | Use `drizzle-orm/migrator` `migrate()` API — applies committed SQL files, never introspects live DB |
+| Drizzle auto-migrate | No concurrent-startup protection | Implement `migration_lock` sentinel row with `INSERT ... ON DUPLICATE KEY IGNORE` |
+| member_credentials schema | `UNIQUE(user_id)` blocks multi-provider | Migrate to `UNIQUE(user_id, provider_type)` before writing Google credential code |
+| Schedule-X dark mode | Not overriding `--sx-color-*` variables in dark token block | Enumerate all `--sx-*` variables from `@schedule-x/theme-default` CSS and map them |
+| PWA dark mode | Setting `data-theme` in React (after hydration) | Inline `<script>` in `index.html` before CSS to set `data-theme` synchronously on load |
+| Vite PWA service worker | `tokens.css` in `public/` without hash | Move theme CSS into hashed build output; verify Workbox precache manifest includes it |
+
+---
+
+## Performance Traps
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| Google `events.list` with no `timeMin`/`timeMax` | Fetches all events in history; response > 5MB; rate limit hit | Always pass a bounded time window (e.g., 6 months past, 1 year future) | First sync for a calendar with >1000 events |
+| Google instances fetch per recurring master event | N+1 API calls for N recurring events | Batch: fetch all instances in the time window in one call; merge by master event ID | Calendars with 10+ recurring series |
+| MariaDB auto-migrate running complex migrations on startup | Long startup delays; health check fails before migration completes | Log migration progress; set Docker healthcheck `start_period` long enough | Migrations with `ALTER TABLE` on a table with >50K rows |
+| Multiple VALARMs in scheduler SQL query without index | Full `calendar_events` scan on every scheduler tick | Index on `reminder_lead_minutes` column (or `event_reminders.lead_minutes` if junction table) | Tables with >10K events |
 
 ---
 
 ## Security Mistakes
 
-| Mistake                                                           | Risk                                                  | Prevention                                                                                                         |
-| ----------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Admin route not protected inside adminRouter (only in parent app) | Any authenticated member can call admin endpoints     | Apply guard middleware inside the sub-router, not only in the parent app mount                                     |
-| Setup endpoint lacks "already-set-up" guard                       | Post-setup endpoint rewrites credentials without auth | Check `member_credentials` existence + VAPID env on every setup route invocation; return 423 if already configured |
-| VAPID_PRIVATE_KEY stored in DB                                    | Private signing key accessible to DB-level access     | VAPID private key in env/secrets only; DB stores public key and subject only                                       |
-| App-password in Zod error response                                | Plaintext credential in HTTP response and server logs | Custom Zod hook for all routes that accept credential input                                                        |
-| `docker login -p` in CI YAML                                      | Registry token in CI logs                             | `--password-stdin` only; token as Gitea secret, not YAML env var                                                   |
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| Google refresh token stored unencrypted | Stolen DB backup exposes ability to read all of a member's Google Calendar indefinitely | Encrypt with `APP_PASSWORD_ENCRYPTION_KEY` (AES-256-GCM) same as Fastmail app passwords |
+| Google OAuth state param not validated on callback | CSRF: attacker can link their Google account to the victim's FamilySync session | Validate `state` against the `google.oauth.state` cookie; reject mismatches with 400 |
+| Google callback endpoint accessible without session check on initiation | Any unauthenticated caller can initiate a Google OAuth flow for any user | Require authenticated FamilySync session to initiate the flow (`/api/providers/google/connect`); the callback itself needs no session but must validate the state cookie |
+| Google scopes stored but not verified on callback | User may grant narrower scopes than requested; write-back fails silently | Check `scope` in the token response; if write scope is absent, mark the provider as read-only and surface in UI |
+| `EXTERNAL_BASE_URL` exposed in a public API response | Discloses internal routing; low severity but unnecessary | Keep env vars server-side only; never return infrastructure config in API responses |
+| Migration lock table not cleaned up on crash | Next startup finds a stale lock and never migrates | Set a `locked_at` timestamp in the lock row; auto-release locks older than 60 seconds |
+
+---
+
+## UX Pitfalls
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| Dark mode toggle has no system-follow option | Wife on iPhone expects dark mode to follow iOS system preference automatically | Implement three options: Light / Dark / System (default); System reads `prefers-color-scheme` media query and updates on system change |
+| Google "Connect" button initiates OAuth without explaining what access is granted | Non-technical wife confused by Google consent screen listing calendar permissions | Show a one-sentence explanation before the OAuth redirect: "FamilySync will read and update your Google Calendar events." |
+| Google auth failure surfaces a raw error message | `invalid_grant` or `redirect_uri_mismatch` visible to end user | Map known Google OAuth error codes to friendly messages; provide a "Try again" button that re-initiates the flow |
+| Multiple reminders UI with no order or visual grouping | Hard to tell which reminder fires when | Show reminders sorted by lead time (earliest first); each entry shows the computed fire time ("4 days before, at 9:00 AM") |
+| Dark mode flash on cold PWA load | Wife on iPhone sees white flash on dark mode | Inline script in `index.html` sets theme before first paint; no React wait required |
+| Zero-setup wizard asks for Google OAuth credentials before explaining the App Flow | Non-technical user confused by "Client ID" and "Client Secret" terms | Name the fields plainly; link to the FamilySync deployment guide step that shows where to find them in the Google Cloud Console |
 
 ---
 
 ## "Looks Done But Isn't" Checklist
 
-- [ ] **VALARM authoring:** Often ships create-only — verify that editing an event with a native-client alarm in rawVevent does not drop that alarm from the PUT payload.
-- [ ] **VALARM serialization:** Often emits `VALUE=TEXT` — verify the ICS output has `TRIGGER:-PT15M` (DURATION type, no VALUE parameter) or `TRIGGER;VALUE=DURATION:-PT15M` — never `VALUE=TEXT`.
-- [ ] **All-day reminders:** Often enabled in the UI for all-day events — verify the reminder selector is disabled or hidden when `allDay: true`.
-- [ ] **Variable-lead dedup:** Often keeps the uid-only key — verify the dedup map key is updated to include dtstart so a rescheduled event fires again.
-- [ ] **Event-driven drain:** Often calls `runOutboxDrain()` directly — verify the trigger path sets `drainRequested` or calls through the same error-caught wrapper as the setInterval path.
-- [ ] **Setup wizard "already-set-up" guard:** Often untested — verify a second POST to any setup endpoint after initial setup returns 423, not 200.
-- [ ] **Admin route 403:** Often not tested — verify a non-admin authenticated user gets 403 from admin routes, not 200 or 404.
-- [ ] **VAPID key in DB:** Often slips in as "config" — verify the DB schema has no column for `vapid_private_key` or `app_password_encryption_key`.
-- [ ] **Gitea CI MariaDB readiness:** Often assumed — verify CI logs show the mysqladmin ping retry loop completing, not the job proceeding immediately after service declared healthy.
-- [ ] **Playwright storage state expiry:** Often passes on day one — verify tests still pass 25 hours after the storage state was captured (session cookie expired).
+- [ ] **Google OAuth flow:** Refresh token stored — but 410 syncToken expiry handler missing. Verify with a forced syncToken reset (delete the stored token, check that the next poll triggers a full re-sync without crashing).
+- [ ] **Google recurrence:** Master event fetched with `singleEvents: false` — but modified/canceled instances not fetched. Verify by canceling one occurrence in Google Calendar and confirming it does not appear in FamilySync.
+- [ ] **Provider abstraction:** Interface defined — but the Fastmail outbox worker's `isDraining` guard and `drainRequested` flag behavior is unchanged. Verify with the existing outbox integration tests against the new interface.
+- [ ] **Multiple reminders:** Multiple VALARM objects in `rawVevent` — but scheduler dedup key still `uid:dtstartMs` (not `uid:dtstartMs:leadMinutes`). Verify by creating an event with two reminders and confirming two separate pushes fire at the correct times.
+- [ ] **Auto-migrate on boot:** Migrations run at startup — but no concurrent-startup protection. Verify by starting two container instances simultaneously and confirming exactly one migration run, no crash loop.
+- [ ] **Dark mode:** `data-theme` applied — but Schedule-X `--sx-color-*` variables not overridden. Verify by switching to dark mode and checking the calendar view specifically (not just the nav/lists).
+- [ ] **Google OAuth through Pangolin:** OAuth flow works on localhost — but redirect URI uses internal hostname. Verify by completing the Google OAuth flow over the Pangolin public URL (`EXTERNAL_BASE_URL`), not via `localhost:3000`.
+- [ ] **Dependency updates:** ESLint updated — but `eslint-plugin-react` compatibility not verified. Verify by introducing a deliberate React lint violation and confirming the CI lint gate catches it after the update.
+- [ ] **Google token expiry:** Access tokens cached in memory — but expiry check missing. Verify that a request made >1 hour after the last token fetch triggers a silent refresh, not a 401 from Google.
 
 ---
 
 ## Recovery Strategies
 
-| Pitfall                               | Recovery Cost | Recovery Steps                                                                                                                             |
-| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| VALARM strips native alarms on edit   | MEDIUM        | Add valarms preserve path to buildVeventString + outboxWorker update branch; no migration needed; existing rawVevent data is authoritative |
-| TRIGGER VALUE=TEXT bug                | LOW           | Fix Duration construction in buildVeventString; no data migration (rawVevent already has correct alarms from server)                       |
-| uid-only dedup causing duplicate push | LOW           | Change Map key to uid:dtstartMs; restart clears in-memory state; no DB change                                                              |
-| Double-drain from concurrent triggers | MEDIUM        | Refactor event-driven trigger to drainRequested flag; requires load testing to confirm no more duplicate PUTs                              |
-| Admin route bypassed (no inner guard) | LOW           | Add `.use('*', adminGuard)` inside adminRouter; deploy                                                                                     |
-| VAPID private key in DB               | HIGH          | Rotate VAPID keypair; clear all push subscriptions (all devices must re-subscribe); remove DB column via migration                         |
-| CI flaky MariaDB race                 | LOW           | Add readiness wait loop to workflow YAML; re-run                                                                                           |
-| Playwright storage state stale        | LOW           | Switch to DEV_AUTH_BYPASS mode for automated tests; remove static state file                                                               |
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| Google refresh token 7-day expiry in Testing status | LOW | Promote app to Production status in Google Cloud Console; member re-authorizes once |
+| Drizzle auto-migrate `Duplicate column name` crash | MEDIUM | Manually mark the migration as applied in `__drizzle_migrations`; restart container |
+| Concurrent migration lock stuck (crash before lock release) | LOW | `DELETE FROM migration_lock WHERE id=1` in the DB; restart container |
+| Google syncToken 410 — incremental sync stopped | LOW | Delete stored syncToken from `member_credentials`; next poll performs full re-sync |
+| `member_credentials` unique constraint violation (Google overwrites Fastmail) | HIGH | Restore from DB backup; apply the `UNIQUE(user_id, provider_type)` migration immediately |
+| OAuth redirect URI mismatch (Pangolin hostname not registered) | LOW | Add the correct HTTPS URL to Google Cloud Console Authorized Redirect URIs; no code change |
+| Dark mode flash in production (inline script missing) | LOW | Add inline `<script>` to `index.html`; rebuild and deploy; service worker cache busted by new hash |
+| ESLint 10 upgrade breaks plugin — lint gate silently passes | MEDIUM | Roll back ESLint to 9.x in root `package.json`; re-run CI to confirm lint gate fails again on known violations |
 
 ---
 
 ## Pitfall-to-Phase Mapping
 
-| Pitfall                                           | Prevention Phase                               | Verification                                                                                                                  |
-| ------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| VALARM strips native alarms on edit               | Per-event reminders (VALARM authoring)         | Integration test: create event via native client with alarm, edit via FamilySync, verify PUT payload contains original VALARM |
-| TRIGGER VALUE=TEXT serialization                  | Per-event reminders (VALARM authoring)         | Unit test: serialize VALARM, parse back, assert no VALUE=TEXT                                                                 |
-| All-day event VALARM silently no-ops              | Per-event reminders (VALARM authoring)         | UI test: all-day event form has no reminder field or field is disabled                                                        |
-| Variable-lead dedup produces duplicate push       | Per-event reminders (scheduler generalization) | Unit test: fire reminder, reschedule event earlier, fire again — assert two pushes sent                                       |
-| Double-drain from concurrent event-driven trigger | Event-driven outbox drain                      | Load test: enqueue 10 rows rapidly, assert each CalDAV PUT issued exactly once                                                |
-| Event-driven drain breaks create-before-delete    | Event-driven outbox drain                      | Integration test: edit-as-move under rapid enqueue; original event not deleted before new one created                         |
-| Admin app-password echoed in error                | Admin Settings                                 | Unit test: POST invalid password to settings route; assert response has no credential value                                   |
-| Unauthenticated setup endpoint stays live         | Setup wizard                                   | Integration test: POST to setup endpoint after first-run completes; assert 423                                                |
-| Admin role check missing inside sub-router        | Admin Settings                                 | Integration test: non-admin authenticated user hits admin route; assert 403                                                   |
-| VAPID key stored in DB                            | Setup wizard                                   | Schema review before migration is written; CI lint check for column names containing `private_key`                            |
-| Gitea CI MariaDB readiness race                   | Gitea CI                                       | CI log audit: readiness loop appears before any `drizzle-kit migrate` invocation                                              |
-| Gitea runner missing Node 22 / pnpm               | Gitea CI                                       | First CI job: node/pnpm version probe step before any install or test                                                         |
-| Docker registry token in CI logs                  | Gitea CI                                       | CI log audit: no plaintext token visible; all registry credentials use --password-stdin                                       |
-| Playwright storage state stale                    | Mobile-browser testing                         | Test suite passes on day 2 without recapturing storage state (DEV_AUTH_BYPASS mode eliminates TTL)                            |
-| Production service worker intercepts Playwright   | Mobile-browser testing                         | Playwright context uses `serviceWorkers: 'block'`; verified in trace that no responses are SW-sourced                         |
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| Google refresh token 7-day expiry (Testing vs Production status) | Google Calendar provider (phase start) | Document and enforce before any token storage code ships |
+| Google recurrence model mismatch (singleEvents, EXDATE) | Google Calendar provider (recurrence plan) | Unit test: mock Google API response → assert reconstructed VCALENDAR passes ical.js + RecurExpansion |
+| Google syncToken 410 handling | Google Calendar provider (sync/poller plan) | Integration test: simulate 410 → assert full re-sync triggered, no crash |
+| Google all-day timezone / useDefault reminder | Google Calendar provider (normalization plan) | Unit test: UTC normalization of `start.dateTime` with offset; `useDefault: true` maps to null |
+| Provider abstraction Fastmail regression | Provider abstraction phase (must ship first) | All existing outbox/poller/scheduler tests pass unchanged against the new interface |
+| Multiple VALARM dedup key and Google 5-cap | Multiple reminders phase | Integration test: event with 2 reminders fires 2 pushes; Google write-back with 6 reminders returns validation error before write |
+| Drizzle auto-migrate: journal mismatch, concurrent race, false destructive diff | Zero-setup DB migration phase | Test: run `migrate()` twice on same DB → no error; start two containers simultaneously → one applies, one waits |
+| PWA dark mode FOWT and Schedule-X coverage | PWA dark mode phase | Playwright test: toggle dark mode, assert `--sx-color-*` computed values on the calendar element match dark theme |
+| OAuth callback through Pangolin redirect URI | Self-service Google OAuth onboarding phase | End-to-end test over Pangolin tunnel hostname (not localhost) |
+| Google token encryption and multi-provider schema | Provider abstraction phase (schema migration) | `UNIQUE(user_id, provider_type)` in place; integration test: add Fastmail + Google credentials for same user → both rows present |
+| ESLint 10 breaking change in dependency updates | CI dependency update phase (last in milestone) | Update ESLint separately; verify lint gate still catches a known violation after update |
 
 ---
 
 ## Sources
 
-- Direct inspection of `apps/api/src/broker/outboxWorker.ts`, `reminderScheduler.ts`, `vevent.ts`, `crypto.ts`, `index.ts`, `db/schema.ts`
-- `.planning/RETROSPECTIVE.md` — v1.0 lessons: node-cron skip, drizzle push destructive diff, VAPID truncation, tsc vs vitest divergence
-- `CLAUDE.md` memory entries: `node-cron-skips-in-long-running-process.md`, `drizzle-mariadb-push-unsafe.md`, `authelia-idtoken-claims.md`
-- RFC 5545 §3.8.6.3 — VALARM TRIGGER value types (DURATION vs DATE-TIME)
-- RFC 5545 §3.3.10 — RRULE value type semantics
-- ical.js source (`lib/ical/property.js`) — property value type inference for TRIGGER
-- Gitea Actions documentation — services container healthcheck semantics, secret masking behavior
-- Playwright docs — `browserContext.serviceWorkers`, `storageState`, context lifecycle
+- Project source: `apps/api/src/broker/reminderScheduler.ts`, `vevent.ts`, `outboxWorker.ts`, `client.ts` (inspected directly)
+- Migration history: `apps/api/src/db/migrations/meta/_journal.json`, migration SQL files (inspected directly)
+- `.planning/RETROSPECTIVE.md` — v1.0 and v1.1 lessons (journal-hash mismatch, false destructive diff, node-cron silent skip, runner-probe-first)
+- `.planning/quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/260610-cr8-PLAN.md` — Drizzle MariaDB push foot-gun (direct source)
+- `.planning/todos/completed/adopt-drizzle-migrations-workflow.md` — false destructive diff root cause (direct source)
+- `.planning/milestones/v1.1-phases/10-admin-role-settings/10-01-PLAN.md` — migration workflow and `UNIQUE(user_id)` constraint history (direct source)
+- `.planning/milestones/v1.1-phases/11-per-event-reminders/11-RESEARCH.md` — VALARM classification, scheduler dedup key design (direct source)
+- `CLAUDE.md` — ESLint 9.39.4 pin rationale, stack constraints, Schedule-X version, CI runner constraints (direct source)
+- `PROJECT.md` — Key decisions D-10 through D-20, constraint table, v1.2 feature list (direct source)
+- Google Calendar API documentation knowledge (refresh token expiry policy, `singleEvents` parameter, `410 Gone` syncToken expiry, `reminders.useDefault`, scope tiers) — HIGH confidence from repeated confirmed behavior
+- OAuth2 PKCE / state cookie mechanics — HIGH confidence from shipped Authelia OIDC implementation in this codebase
+- Drizzle ORM programmatic migrator API (`drizzle-orm/migrator`) — MEDIUM confidence (verify against drizzle-orm release notes for the installed version before shipping auto-migrate)
 
 ---
-
-_Pitfalls research for: FamilySync v1.1 Operability & Polish_
-_Researched: 2026-06-10_
+*Pitfalls research for: FamilySync v1.2 Multi-Provider, Theming & Zero-Setup*
+*Researched: 2026-06-19*
diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md
index f02311b..18209ac 100644
--- a/.planning/research/STACK.md
+++ b/.planning/research/STACK.md
@@ -1,11 +1,350 @@
 # Stack Research
 
 **Domain:** Self-hosted family calendar + shared-lists PWA on Fastmail
-**Researched:** 2026-06-03 (v1.0) / 2026-06-10 (v1.1 additions)
+**Researched:** 2026-06-03 (v1.0) / 2026-06-10 (v1.1 additions) / 2026-06-19 (v1.2 additions)
 **Confidence:** MEDIUM-HIGH (calendar sharing cross-account caveat: LOW; rest HIGH)
 
 ---
 
+## v1.2 Stack Additions — Multi-Provider, Theming & Zero-Setup
+
+> Covers ONLY net-new libraries and patterns for v1.2. The existing stack (Hono, Drizzle,
+> mysql2, tsdav, ical.js, web-push, @hono/oidc-auth, TanStack Query, Zustand, vite-plugin-pwa,
+> @playwright/test) is shipped and proven — do not re-evaluate it.
+
+### Net-New npm Packages (two only)
+
+| Package | Version | Scope | Purpose |
+|---------|---------|-------|---------|
+| `google-auth-library` | 10.7.0 | `apps/api` | OAuth2 authorization-code flow + offline refresh token management |
+| `@googleapis/calendar` | 15.0.0 | `apps/api` | Google Calendar API v3 typed REST client |
+
+Everything else (dark mode, multiple VALARMs, programmatic migrate, CI updates) uses existing dependencies.
+
+---
+
+### 1. Google Calendar Integration
+
+#### Library decision: `google-auth-library` + `@googleapis/calendar`
+
+Do NOT use the monolithic `googleapis` package. It bundles 170+ API clients (~50 MB in the
+Docker image) for Calendar-only use. The scoped split gives the same typed API surface at a
+fraction of the footprint.
+
+| Alternative | Rejection reason |
+|-------------|-----------------|
+| `googleapis` (monolithic) | 170+ bundled clients; bloats Docker image layer with unused code |
+| Raw `fetch` + REST | Must hand-roll token refresh, retry logic, typed request/response schemas |
+| `@microfox/google-calendar` | Third-party wrapper, last publish 9 months ago, adds indirection over official packages |
+
+`@googleapis/calendar@15.0.0` depends only on `googleapis-common@^8.0.0` (auto-installed as a
+transitive dep). `google-auth-library@10.7.0` ships its own TypeScript types — no `@types/` package
+needed.
+
+#### OAuth2 Authorization-Code Flow (backend-only)
+
+The flow is fully backend-driven, matching the existing `@hono/oidc-auth` pattern for Authelia:
+
+1. Backend generates the Google consent URL:
+   ```typescript
+   const url = oauth2Client.generateAuthUrl({
+     access_type: 'offline',
+     scope: ['https://www.googleapis.com/auth/calendar.events'],
+     state: signedStateJwt,   // CSRF protection, same pattern as OIDC link flow
+   });
+   ```
+2. User clicks "Connect Google" → redirected to Google consent screen.
+3. Google redirects back to `/api/providers/google/callback`.
+4. Backend exchanges the code:
+   ```typescript
+   const { tokens } = await oauth2Client.getToken(code);
+   // tokens.refresh_token is ONLY present on first authorization with access_type:'offline'
+   // Subsequent exchanges return only access_token. Persist refresh_token immediately.
+   ```
+5. Store the token object `{ refresh_token, access_token, expiry_date }` encrypted
+   (AES-256-GCM, same crypto as Fastmail app passwords) in `member_credentials`
+   with `provider_type = 'google'`.
+6. On each API call, hydrate the client:
+   ```typescript
+   oauth2Client.setCredentials({ refresh_token: storedToken });
+   // google-auth-library auto-refreshes when access_token is expired
+   oauth2Client.on('tokens', (tokens) => {
+     // Persist newly issued access_token + expiry_date back to DB
+     // to avoid unnecessary refresh calls on next request
+   });
+   ```
+
+**Required scopes:**
+- `https://www.googleapis.com/auth/calendar.events` — create/edit/delete events on any calendar
+- `https://www.googleapis.com/auth/calendar.readonly` — read-only if write is not needed per calendar
+
+#### Schema change for token storage
+
+The existing `member_credentials` table has `fastmail_email` and `encrypted_password` columns.
+For Google, `encrypted_password` stores the JSON token blob and `fastmail_email` stores the
+Google account email. In v1.2, add a `provider_account_id VARCHAR(256)` column (additive migration)
+that stores the account identifier in a provider-neutral name — avoids abusing `fastmail_email`
+for a non-Fastmail email.
+
+#### Google Calendar API event model vs. iCalendar
+
+**Recurring events**: Google's `recurrence` field is an array of RFC 5545 RRULE strings — the same
+format ical.js already handles for Fastmail:
+
+```json
+{ "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"] }
+```
+
+However, Google uses RFC 3339 with explicit `timeZone` for timed events (not UTC-Z like the
+existing CalDAV write path), and `date` fields (`"YYYY-MM-DD"`) for all-day events.
+
+| Operation | Google API call |
+|-----------|----------------|
+| List instances (expanded) | `events.list({ singleEvents: true })` |
+| List parent recurring events | `events.list({ singleEvents: false })` (default) |
+| Edit one occurrence | GET instance (has `recurringEventId`), then PATCH |
+| Delete one occurrence | `events.delete({ eventId: instanceId })` — only that instance |
+| Delete whole series | `events.delete({ eventId: recurringEventId })` |
+| Edit this + following | Set UNTIL on RRULE of original → insert new series from that point |
+
+**Reminders**: Google uses a flat `reminders.overrides` array — structurally simpler than VALARM:
+
+```json
+{
+  "reminders": {
+    "useDefault": false,
+    "overrides": [
+      { "method": "popup", "minutes": 15 },
+      { "method": "popup", "minutes": 60 }
+    ]
+  }
+}
+```
+
+| Dimension | Google Calendar | iCalendar VALARM |
+|-----------|----------------|-----------------|
+| Trigger type | Relative minutes only | Relative DURATION or absolute DATE-TIME |
+| All-day trigger | Minutes before midnight of event start | Absolute UTC instant (9 AM local in app) |
+| Multiple reminders | Yes — array of overrides | Yes — multiple VALARM subcomponents |
+| Methods | `popup` + `email` | `DISPLAY`, `AUDIO`, `EMAIL` |
+
+Mapping strategy: read `overrides[*].minutes` where `method='popup'` → `reminderLeadMinutes[]`
+array; ignore `email` method (app handles push, not email). On write: map `reminderLeadMinutes[]`
+→ `overrides` array with `method: 'popup'`, set `useDefault: false`.
+
+All-day event timing: Google fires at midnight minus lead minutes. The app's "9 AM local" semantic
+from Fastmail cannot be replicated — document this as a provider difference; accept Google's
+midnight-relative behavior for Google events.
+
+#### Installation
+
+```bash
+pnpm add --filter @familysync/api google-auth-library @googleapis/calendar
+```
+
+---
+
+### 2. Provider Abstraction — Hand-Rolled TypeScript Interface
+
+No cross-provider calendar normalization library exists worth taking as a dependency. The two
+providers have well-understood shapes; a hand-rolled interface in `apps/api/src/broker/` is the
+right call — stays under project control, zero external dep, typed exactly to app needs.
+
+```typescript
+// apps/api/src/broker/providerTypes.ts
+
+export interface NormalizedEvent {
+  uid: string;                          // stable cross-provider event ID
+  calendarId: string;                   // provider-internal calendar identifier
+  summary: string;
+  allDay: boolean;
+  dtstart: Date | string;               // Date for timed, 'YYYY-MM-DD' for all-day
+  dtend: Date | string;
+  location?: string;
+  description?: string;
+  rruleString?: string;                 // bare RRULE value if recurring master
+  reminderLeadMinutes?: number | null;  // legacy single (backward compat)
+  reminderLeadMinutesMultiple?: number[]; // v1.2 multiple reminders
+  rawPayload?: string;                  // CalDAV: raw iCalendar string; Google: JSON string
+}
+
+export interface ProviderCalendar {
+  id: string;
+  displayName: string;
+  color?: string;
+  isShared: boolean;
+}
+
+export interface CalendarProvider {
+  readonly providerType: 'caldav' | 'google';
+  discoverCalendars(): Promise<ProviderCalendar[]>;
+  syncEvents(calendarId: string, since?: Date): Promise<NormalizedEvent[]>;
+  createEvent(calendarId: string, event: Omit<NormalizedEvent, 'uid' | 'calendarId'>): Promise<string>;
+  updateEvent(calendarId: string, event: NormalizedEvent): Promise<void>;
+  deleteEvent(calendarId: string, uid: string): Promise<void>;
+}
+```
+
+**Fastmail adapter**: wraps the existing `broker/sync.ts`, `broker/write.ts`, `broker/poller.ts`
+behind this interface. Refactor, not rewrite.
+
+**Google adapter**: new `broker/googleCalendarProvider.ts` implementing `CalendarProvider` using
+`@googleapis/calendar` + `google-auth-library`. Fetches credentials from `member_credentials`
+where `provider_type = 'google'`, re-hydrates `OAuth2Client` per call.
+
+---
+
+### 3. Multiple Reminders Per Event — No New Dependency
+
+`ical.js` already supports multiple VALARM subcomponents via repeated `vevent.addSubcomponent(alarm)`
+calls. The existing `buildVeventString` already processes a `valarms` array (preserve-on-edit path).
+The v1.2 change is purely a data-model and serialization update:
+
+1. **Schema**: Add `reminder_lead_minutes_json TEXT` column to `calendar_events` (nullable JSON
+   array e.g. `[15, 60]`). Keep `reminder_lead_minutes INT` for backward compat; treat single-value
+   as `[value]`.
+2. **vevent.ts**: Change `buildVeventString` to accept `reminderLeadMinutes: number[]`; loop
+   `buildTimedValarm(lead)` for each, call `vevent.addSubcomponent()` per alarm.
+3. **classifyValarms**: The `length > 1` branch currently returns `{ kind: 'custom' }`. v1.2
+   should return `{ kind: 'multi-preset', leads: number[] }` when all alarms are relative DURATION
+   triggers with preset lead values.
+4. **Google adapter**: Map `reminders.overrides` bidirectionally — multiple `{ method: 'popup', minutes: N }` entries.
+
+No new npm dependency.
+
+---
+
+### 4. PWA Dark Mode / Theming — Pure CSS + Existing Zustand
+
+No theming library needed. The token layer is already structured for this:
+
+- `tokens.css` has `[data-theme='light']` with all semantic tokens defined.
+- Schedule-X `--sx-color-*` vars are already mapped to project tokens in `tokens.css` — so
+  adding a `[data-theme="dark"]` block that overrides `--color-surface`, `--color-text-primary`,
+  etc. automatically cascades into Schedule-X with no Schedule-X config change.
+- The dark stub comment `[data-theme="dark"] { ... }` is already in `tokens.css` (Phase 17
+  groundwork). Fill it in.
+
+**Implementation — no new package:**
+
+```typescript
+// apps/pwa/src/store/themeStore.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware'; // built-in, already in Zustand 5.x
+
+type ThemeMode = 'light' | 'dark' | 'system';
+
+interface ThemeStore {
+  mode: ThemeMode;
+  setMode: (m: ThemeMode) => void;
+}
+
+export const useThemeStore = create<ThemeStore>()(
+  persist(
+    (set) => ({ mode: 'system', setMode: (mode) => set({ mode }) }),
+    { name: 'familysync-theme' },
+  ),
+);
+```
+
+**DOM application** (called on mount and on mode change):
+```typescript
+function resolveTheme(mode: ThemeMode): 'light' | 'dark' {
+  if (mode !== 'system') return mode;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+document.documentElement.dataset.theme = resolveTheme(store.mode);
+```
+
+**System preference listener:**
+```typescript
+window.matchMedia('(prefers-color-scheme: dark)')
+  .addEventListener('change', () => {
+    if (useThemeStore.getState().mode === 'system') {
+      document.documentElement.dataset.theme = resolveTheme('system');
+    }
+  });
+```
+
+**Flash prevention**: Add an inline `<script>` in `index.html` (before the React bundle) that
+reads `localStorage['familysync-theme']` and sets `document.documentElement.dataset.theme`
+synchronously. This is the standard flash-of-wrong-theme prevention pattern; no library needed.
+
+Zustand `persist` middleware is already built into Zustand 5.0.14. No additional package.
+
+---
+
+### 5. Zero-Manual-Setup DB Bootstrap — Programmatic `drizzle-orm/mysql2/migrator`
+
+`drizzle-orm/mysql2/migrator` is already part of `drizzle-orm@0.45.2`. No new package.
+
+The migrate API requires a **single connection** (not the runtime pool):
+
+```typescript
+// apps/api/src/db/migrate.ts
+import mysql from 'mysql2/promise';
+import { drizzle } from 'drizzle-orm/mysql2';
+import { migrate } from 'drizzle-orm/mysql2/migrator';
+
+export async function runMigrations(): Promise<void> {
+  // migrate() must use a single connection, not the runtime pool
+  const connection = await mysql.createConnection({
+    host: process.env.DB_HOST ?? 'localhost',
+    port: Number(process.env.DB_PORT ?? 3306),
+    user: process.env.DB_USER ?? 'familysync',
+    password: process.env.DB_PASSWORD ?? '',
+    database: process.env.DB_NAME ?? 'familysync',
+    multipleStatements: true,   // required: migration files contain multiple DDL statements
+  });
+
+  const db = drizzle(connection);
+
+  try {
+    await migrate(db, { migrationsFolder: './src/db/migrations' });
+    console.log('[db] migrations applied');
+  } finally {
+    await connection.end();
+  }
+}
+```
+
+Call `await runMigrations()` in `apps/api/src/index.ts` **before** `serve()` and before
+starting the broker poller. The existing `db` pool (from `db/client.ts`) is separate and
+unchanged for all runtime queries.
+
+**Idempotency**: Drizzle tracks applied migrations in a `__drizzle_migrations` table it
+creates automatically. Running `migrate()` on a container restart is a no-op for already-applied
+files. Safe to call unconditionally at every boot.
+
+**MariaDB 11**: `multipleStatements: true` is required because drizzle-kit generates migration
+files with multiple DDL statements separated by semicolons. MariaDB 11 is wire-compatible with
+MySQL and this flag works identically.
+
+**BANNED**: `db:push` (`drizzle-kit push`) remains banned on MariaDB 11. It schedules
+destructive schema diffs. Only `drizzle-kit generate` (dev) + `migrate()` at runtime (prod).
+
+---
+
+### 6. CI Dependency Updates — Existing `pnpm` Tooling Only
+
+No new tooling package. The workflow:
+
+1. `pnpm outdated --recursive` — table of current / wanted / latest across all workspaces.
+2. `pnpm update --interactive --latest -r` — selective upgrade; review each before accepting.
+3. `pnpm audit --fix=update` (pnpm v11+) — bump packages to fix security findings rather than
+   adding overrides.
+4. Run full local CI gates (`pnpm run lint`, `pnpm run typecheck`, `pnpm test`) before committing.
+
+| Category | Action |
+|----------|--------|
+| Patch / minor | `pnpm update -r` within semver range |
+| Major with API changes | Evaluate per-package; check changelog |
+| HIGH/CRITICAL security | Prioritize; `--fix=update` where possible |
+| `@playwright/test` | Pin to the Playwright binary installed in CI runner; bumping requires browser reinstall |
+
+---
+
 ## v1.1 Stack Additions — Operability & Polish
 
 This section covers ONLY what is new for v1.1. The rest of the file (below) documents the v1.0 stack, which is unchanged.
@@ -218,6 +557,9 @@ npm install drizzle-orm mysql2 ioredis
 npm install tsdav ical.js rrule
 npm install web-push zod openid-client
 
+# v1.2 additions (apps/api)
+npm install google-auth-library @googleapis/calendar
+
 # Frontend
 npm install react react-dom @tanstack/react-query zustand
 npm install -D vite vite-plugin-pwa
@@ -376,6 +718,8 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 | CalDAV                 | JMAP                                 | JMAP calendars not available on Fastmail as of 2026                                               |
 | @playwright/test       | playwright-cli alone                 | playwright-cli lacks storageState save/restore and device presets needed for CI; both coexist     |
 | PAT for Gitea registry | secrets.GITEA_TOKEN / built-in token | Gitea does not inject a built-in token with container-registry push scope; PAT required           |
+| @googleapis/calendar   | googleapis (monolithic)              | Monolithic bundles 170+ clients; scoped package is Calendar-only; same typed API, fraction of size |
+| Hand-rolled CalendarProvider interface | cross-provider normalization library | No maintained library exists; hand-rolled interface stays under project control |
 
 ---
 
@@ -394,6 +738,10 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 | `mysqladmin ping` health check with MariaDB 11       | mysqladmin not shipped in mariadb:11 image; silently blocks CI    | `healthcheck.sh --connect --innodb_initialized`           |
 | `runs-on: ubuntu-latest` on Gitea self-hosted runner | Label only resolves on GitHub's hosted infrastructure             | `runs-on: self-hosted` (or the runner's registered label) |
 | Any validation library for setup wizard              | zod + mysql2 + web-push + Node 22 fetch cover all checks natively | Use existing stack                                        |
+| `googleapis` (monolithic npm package)                | Bundles 170+ API clients; ~50 MB for Calendar-only use            | `@googleapis/calendar` + `google-auth-library`            |
+| `next-themes` or any theming library                 | Adds indirection over CSS data-theme + Zustand persist (already in stack) | CSS `[data-theme="dark"]` + Zustand `persist` middleware |
+| `drizzle-kit push` in production / MariaDB 11        | Schedules destructive schema diffs; banned on MariaDB 11          | `drizzle-kit generate` + `migrate()` at runtime           |
+| FCM/Firebase for Google Calendar push                | Google Calendar push = REST polling / webhooks; unrelated to VAPID push | Use existing `web-push` for app notifications; Google Calendar webhooks are separate |
 
 ---
 
@@ -402,12 +750,17 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 | Package                      | Compatible With        | Notes                                                                                      |
 | ---------------------------- | ---------------------- | ------------------------------------------------------------------------------------------ |
 | drizzle-orm@0.45.x           | mysql2@3.x             | Use `drizzle-orm/mysql2` import path; mysql2@3.x uses Promises API by default              |
+| drizzle-orm/mysql2/migrator  | drizzle-orm@0.45.x, mysql2@3.x | Single connection required (not pool); `multipleStatements: true` for MariaDB 11  |
 | vite-plugin-pwa@1.3.x        | Vite@8.x, Workbox@7.x  | vite-plugin-pwa 0.16+ requires Node 16+; 1.x tracks Vite 6+                                |
 | @hono/oidc-auth@1.8.x        | hono@4.x, oauth4webapi | Peer-depends on hono 4.x                                                                   |
 | ical.js@2.x                  | rrule@2.8.x            | Use together: ical.js parses the RRULE string, pass to `new RRule(RRule.parseString(...))` |
 | web-push@3.6.x               | Node.js 18+            | VAPID uses Web Crypto; works in Node.js 18+ natively                                       |
 | @playwright/test@1.60.x      | Node.js 18+            | Install Chromium only in CI (`npx playwright install --with-deps chromium`)                |
 | mariadb:11 service container | GitHub/Gitea Actions   | Health check must use `healthcheck.sh`; `mysqladmin` removed in 11.x                       |
+| google-auth-library@10.7.0   | Node.js 18+, TypeScript 5.x | Ships own types; no @types/ needed; OAuth2Client auto-refreshes expired access tokens |
+| @googleapis/calendar@15.0.0  | googleapis-common@^8.0.0 | Auto-installed as transitive dep; do not pin googleapis-common separately              |
+| zustand/middleware `persist` | zustand@5.0.x          | Built-in middleware; no separate import package; works with localStorage in PWA            |
+| Schedule-X `--sx-color-*`   | tokens.css `[data-theme]` | All Schedule-X color vars already map to project tokens; dark overrides cascade automatically |
 
 ---
 
@@ -423,6 +776,10 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 
 5. **Playwright mobile tests and DEV_AUTH_BYPASS in CI:** The mobile test harness depends on `DEV_AUTH_BYPASS=true` being available in CI. This means the CI run starts the API with that flag — confirm it is only set in the test environment, never in the production image/deploy step.
 
+6. **Google OAuth2 consent screen verification:** Google requires app verification for production OAuth apps requesting Calendar scopes. For a self-hosted household app, the project must be in "testing" mode (max 100 users) or published. For a two-person household, testing mode (unverified) is sufficient; add both Google accounts as test users in Google Cloud Console. No app review needed.
+
+7. **Google Calendar webhook push vs. polling:** The Google Calendar API supports webhook push notifications (via `events.watch()`) that POST to a public URL when calendars change. This is more efficient than polling but requires a verified public HTTPS endpoint. The existing ctag-poller pattern (5-min interval) is simpler and sufficient for a two-person household — evaluate webhooks only if polling latency becomes a problem.
+
 ---
 
 ## Sources
@@ -436,6 +793,7 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 - [rrule npm](https://www.npmjs.com/package/rrule) — Version 2.8.1 confirmed
 - [Hono](https://hono.dev/) — Version 4.12.23; Node.js adapter confirmed
 - [Drizzle ORM MySQL](https://orm.drizzle.team/docs/get-started-mysql) — MariaDB via mysql2 confirmed
+- [Drizzle ORM Migrations API](https://mintlify.wiki/drizzle-team/drizzle-orm/api/core/migrations) — `migrate(db, { migrationsFolder })` with mysql2, single connection required
 - [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) — Version 1.3.0; Workbox 7 integration
 - [web-push npm](https://www.npmjs.com/package/web-push) — Version 3.6.7
 - [Meet Declarative Web Push — WebKit](https://webkit.org/blog/16535/meet-declarative-web-push/) — Safari 18.4+, iOS 18.4+ confirmed
@@ -452,8 +810,16 @@ Redis (`ioredis`) is only needed if multiple Node containers run behind a load b
 - [MariaDB 11 health check fix](https://github.com/mage-os/github-actions/issues/365) — mysqladmin removed in mariadb:11.4; healthcheck.sh required
 - [MySQL in GitHub Actions (ovirium.com)](https://ovirium.com/blog/how-to-make-mysql-work-in-your-github-actions/) — Service container pattern; ports, env, options syntax (GitHub-compatible = Gitea-compatible)
 - [DEV Community — Docker-in-Docker with Gitea Actions](https://dev.to/tmlr/the-definitive-guide-to-safe-docker-in-docker-with-gitea-actions-331l) — DinD vs socket-mount tradeoffs; socket-mount recommended for homelab
+- [@googleapis/calendar npm](https://www.npmjs.com/package/@googleapis/calendar) — Version 15.0.0, verified 2026-06-19; depends only on googleapis-common
+- [google-auth-library npm](https://www.npmjs.com/package/google-auth-library) — Version 10.7.0, verified 2026-06-19; ships own TypeScript types
+- [Google Auth Library Node.js — Context7 / googleapis GitHub](https://github.com/googleapis/google-auth-library-nodejs) — OAuth2Client.generateAuthUrl, getToken, setCredentials, tokens event
+- [Google Calendar API — Recurring Events](https://developers.google.com/workspace/calendar/api/guides/recurringevents) — RRULE recurrence array, instance fields, singleEvents param, series delete
+- [Google Calendar API — Reminders](https://developers.google.com/workspace/calendar/concepts/reminders) — overrides array, method types, useDefault=false requirement
+- [pnpm audit CLI](https://pnpm.io/cli/audit) — --fix=update (pnpm v11+) vs --fix=override default
+- [pnpm outdated CLI](https://pnpm.io/cli/outdated) — --recursive workspace support
+- [Schedule-X Theme Docs](https://schedule-x.dev/docs/calendar/theme) — --sx-color-* CSS variable list; no built-in dark mode
 
 ---
 
-_Stack research for: FamilySync — self-hosted family calendar + shared-lists PWA on Fastmail_
-_Researched: 2026-06-03 (v1.0 baseline) / 2026-06-10 (v1.1 Operability & Polish additions)_
+_Stack research for: FamilySync — self-hosted family calendar + shared-lists PWA_
+_Researched: 2026-06-03 (v1.0 baseline) / 2026-06-10 (v1.1 Operability & Polish) / 2026-06-19 (v1.2 Multi-Provider, Theming & Zero-Setup)_