chore(04): commit pattern map + session config; ignore intel/graph diff baselines

Auto-fix loop converged after 2 fix iterations + a final verifying re-review:
- Pass 1: 13/14 findings fixed (3 Critical, 6 Warning, 4 Info).
- Re-review surfaced 1 new Critical (move-path RRULE data loss) + 4 lower.
- Pass 2: 8/8 fixed, including the move-path RRULE forwarding.
- Final re-review: 0 Critical. Remaining 2 Warning / 2 Info are documented
  v1 scope cuts (recurrence-editing deferred), not defects.

Test suites green throughout: api 108, pwa 145; both tsc --noEmit clean.
Per-iteration REVIEW/REVIEW-FIX snapshots retained as audit trail.

.gitignore

@@ -42,3 +42,10 @@ gate2-*.png
 
 # Operator-only credential seed (run out-of-band; never tracked)
 apps/api/scripts/seed-credential.mjs
+
+# Graphify build cache (regenerable; committed artifacts live in .planning/graphs/)
+graphify-out/
+
+# Intel / graph diff baselines (local-only; regenerated on each refresh/build)
+.planning/intel/.last-refresh.json
+.planning/graphs/.last-build-snapshot.json

.planning/HANDOFF.json

@@ -1,46 +1,35 @@
 {
   "version": "1.0",
-  "timestamp": "2026-06-07T02:39:57.236Z",
-  "phase": "03",
-  "phase_name": "event-write-back-pwa-install",
-  "phase_dir": ".planning/phases/03-event-write-back-pwa-install",
-  "plan": "Gate 2 (Part D live verification)",
-  "task": "delete/edit join fix RESOLVED (quick 260607-l6l); Gate 2 human/device checkpoints remain",
+  "timestamp": "2026-06-08T01:52:24.365Z",
+  "phase": "4",
+  "phase_name": "Shared Lists + Live Sync",
+  "phase_dir": ".planning/phases/04-shared-lists-live-sync",
+  "plan": null,
+  "task": null,
   "total_tasks": null,
   "status": "paused",
-  "update_2026_06_07": "Quick task 260607-l6l cleared the three write-path CODE bugs (edit/delete join 503, displayName, GET events filter) on branch gsd/v1.0-milestone — build clean, 100/100 api tests pass, handler-coupled regression test added, deriveDisplayName extracted as shared helper. Remaining items are operator rebuild + human/device Gate 2 checkpoints, not code work.",
+  "stage": "discuss-complete; entry-gate-cleared; ready-to-plan",
   "completed_tasks": [
-    {"id": "tunnel", "name": "PWA loads through Pangolin/newt — newt MTU 1280→1200 (operator) fixed large-asset blackhole; API serves full ./public tree (431ab31)", "status": "done"},
-    {"id": "auth", "name": "Real Authelia OIDC login working — client_id=familysync-dev, scopes incl offline_access, /api/login route + redirect (quick 260606-tv8), fetchMe redirect:manual (1adb460)", "status": "done", "commit": "874f23d"},
-    {"id": "bringup", "name": "Stack bring-up: PWA built into API image, NODE_ENV=production, broker credential seeded (reused spike app password)", "status": "done", "commit": "b46b25b"},
-    {"id": "bug-A", "name": "BUG A timezone — events written 4h off; fixed via in-browser UTC serialization (eventDateTime.ts)", "status": "done", "commit": "a9d3de6"},
-    {"id": "bug-B", "name": "BUG B calendar identity — events attached to wrong user + duplicate calendar rows; unique(userId,url) + per-user predicates + migration applied to live DB", "status": "done", "commit": "a9d3de6"},
-    {"id": "spike-cleanup", "name": "Deleted obsolete spike user (id=1 Dev User) + calendar id=1 + cached events (DB op, operator-approved)", "status": "done"}
+    {"id": 1, "name": "discuss-phase 4 → 04-CONTEXT.md + 04-DISCUSSION-LOG.md (18 decisions D-01..D-18)", "status": "done", "commit": "05e1c9e"},
+    {"id": 2, "name": "Ran SSE-over-Pangolin smoke test live — PASS (~6 min, 35 heartbeats, buffering off, no cut)", "status": "done"},
+    {"id": 3, "name": "Recorded gate PASS via quick task 260607-u8o (01-HUMAN-UAT item 4 + 03-GATE2-RESULTS Part C)", "status": "done", "commit": "9ee5906"},
+    {"id": 4, "name": "Saved project memory: N-member expansion principle", "status": "done"}
   ],
   "remaining_tasks": [
-    {"id": "edit-delete-join", "name": "RESOLVED (quick 260607-l6l, commit 2870413): added .innerJoin(calendars,...) to PATCH /:uid/edit + DELETE /:uid lookups; handler-coupled regression test (asserts 202 + innerJoin spy, verified RED when join removed).", "status": "done", "commit": "2870413"},
-    {"id": "displayName", "name": "RESOLVED (quick 260607-l6l, commits 23c8bb3 + a99ef1d): shared deriveDisplayName helper (name→preferred_username→email→Member<sub>) used in me.ts + resolveUserId; user.ts now UPDATEs an existing blank display_name on re-upsert (so user id=2 self-corrects on next request). OPERATOR FOLLOW-UP: legend shows full name only if Authelia emits name/preferred_username — else it shows email.", "status": "done", "commit": "23c8bb3"},
-    {"id": "events-filter", "name": "RESOLVED (quick 260607-l6l, commit 00a0454): GET /api/events now filters WHERE (calendars.userId=currentUser OR calendars.isShared) AND <date-window>, correctly grouped.", "status": "done", "commit": "00a0454"},
-    {"id": "sync-toast", "name": "Syncing toast not animated / ~27s (outbox 15s drain + CalDAV) looks stalled — UI polish (backlog candidate).", "status": "not_started"},
-    {"id": "gate2-A2A3", "name": "Gate 2 Part A2 (session persists across browser restart) + A3 (2nd member distinct color) — operator verify.", "status": "not_started"},
-    {"id": "gate2-B", "name": "Gate 2 Part B — iOS standalone install + login (device-only; manifest/sw fixes now unblock it).", "status": "not_started"},
-    {"id": "gate2-C", "name": "Gate 2 Part C — 5-min SSE smoke (Phase 4 entry gate).", "status": "not_started"}
-  ],
-  "blockers": [
-    {"description": "RESOLVED — edit/delete 503 (missing calendars join) fixed in quick 260607-l6l (commit 2870413). Code on gsd/v1.0-milestone; not yet rebuilt into the running container.", "type": "technical", "workaround": "n/a — fixed; operator must rebuild to deploy"},
-    {"description": "playwright-cli daemon wedges/crashes in this WSL2 env (hangs on never-settling pages; even open/run-code fail after). Cannot drive browser verification here.", "type": "technical", "workaround": "Verify via curl + ask the operator to test in their real browser/incognito."}
+    {"id": 5, "name": "Plan Phase 4: /gsd-plan-phase 4 (reads 04-CONTEXT.md)", "status": "not_started"},
+    {"id": 6, "name": "Optionally /gsd-ui-phase 4 for the lists UI design contract (UI hint: yes)", "status": "not_started"},
+    {"id": 7, "name": "Execute Phase 4 plans", "status": "not_started"}
   ],
+  "blockers": [],
   "human_actions_pending": [
-    {"action": "Rebuild + deploy: docker compose up -d --build (newt target drops ~30s then self-recovers — not a bug).", "context": "The 3 write-path code fixes (260607-l6l) are committed but not in the running container.", "blocking": true},
-    {"action": "Browser re-test after rebuild: delete an event (dialog should close, event disappears) and edit an event (no 503). Create a NEW 9am event; the OLD wrong-time 5am test event can now be deleted.", "context": "BUG 1 (join) + earlier BUG A/B (timezone/identity) fixes.", "blocking": false},
-    {"action": "Confirm calendar legend shows a name. If it shows email instead of full name, configure Authelia to emit the name/preferred_username OIDC claim (code reads them preferentially; existing blank row self-corrects on next request).", "context": "BUG 2 — displayName helper deployed; legend content depends on Authelia claim emission.", "blocking": false}
+    {"action": "Log out / invalidate the Authelia session whose oidc-auth cookie was pasted into the transcript during the SSE test", "context": "Cookie embeds a refresh token valid until ~2026-06-08; it is now in conversation history. Non-blocking but a security hygiene follow-up.", "blocking": false}
   ],
   "decisions": [
-    {"decision": "newt -mtu 1200 (systemd drop-in)", "rationale": "newt default tunnel MTU 1280 == eth0 underlay; WireGuard overhead made encrypted packets exceed 1280 → large transfers (JS bundle) blackholed. THE root cause of the 'spinner'.", "phase": "03"},
-    {"decision": "Spike user (id=1) + its calendar/events deleted", "rationale": "Obsolete Phase 1 test identity polluting the unified view as 'Dev User'; events are re-syncable cache. Operator approved.", "phase": "03"},
-    {"decision": "fetchMe uses redirect:manual; serve full ./public; OIDC_SCOPES constrained", "rationale": "fetch followed cross-origin 302 and hung; static serving only did /assets/*; empty OIDC_SCOPES requested all scopes_supported (Authelia invalid_scope).", "phase": "03"}
+    {"decision": "Phase 4 entry gate (SSE-over-Pangolin, D-14/#1034) CLEARED", "rationale": "Live smoke test held a heartbeat stream open ~6 min through Pangolin with incremental delivery and no cut; buffering confirmed off", "phase": "4"},
+    {"decision": "All Phase 4 implementation decisions captured in 04-CONTEXT.md (D-01..D-18)", "rationale": "Discuss-phase complete; downstream planner/researcher consume CONTEXT.md", "phase": "4"},
+    {"decision": "Design member-count-agnostic (N family members, not hard-coded 2)", "rationale": "User stated future expansion; drives list_shares join table + per-list-scoped SSE fan-out", "phase": "4"}
   ],
   "uncommitted_files": [],
-  "next_action": "The three write-path code bugs are FIXED (quick 260607-l6l, on gsd/v1.0-milestone, build clean + 100/100 api tests). NEXT: operator rebuilds (docker compose up -d --build) and re-tests delete/edit + legend name in a real browser. Then resume the remaining Gate 2 checkpoints: Part A2 (session persists across browser restart) + A3 (2nd member distinct color); Part B iOS standalone install+login (device-only); Part C 5-min SSE smoke (Phase 4 entry gate). sync-toast polish is a backlog candidate. New backlog todo captured: event-creation reminder/VALARM options (.planning/todos/pending/event-creation-reminder-options.md).",
-  "context_notes": "This session went from 'paused awaiting docker decisions' to a full Gate 2 live bring-up. The big unlock was the newt MTU fix — every earlier 'spinner' symptom was the JS bundle blackholing through the tunnel, not auth. Along the way fixed 6+ real bugs (auth redirect, static serving, OIDC scopes/client_id, timezone, calendar identity) and cleaned spike data. Stack is running (docker compose production target); /health 200 through tunnel; real OIDC login works. Write path (create) works end-to-end to Fastmail. Delete/edit are the current blocker (trivial join fix). Do NOT use playwright-cli (broken here). Do NOT read/write .env via tools (permission-locked; operator applies .env changes). Every docker compose recreate drops newt's target ~30s (503) then self-recovers — not a bug. DB now: 1 user (id=2, display_name blank), calendars id=2 Calendar(509ev) + id=3 USA Holidays(32)."
+  "next_action": "/clear then /gsd-plan-phase 4 (entry gate is cleared; no infra precondition remains)",
+  "context_notes": "Phase 4 = app-native shared lists (MariaDB, NOT CalDAV) with SSE live co-edit sync. Discussion is done and committed; the SSE transport gate that was blocking the build is now verified and recorded. Nothing is mid-edit — clean stopping point between discuss and plan. Key locked choices for the planner: default-shared lists + private toggle via list_shares join table; checked items sink to completed section; optimistic UI + per-field PATCH last-write-wins (no CRDT); delete-wins; full-refetch-on-reconnect + capped-backoff + polling fallback; string fractional-index ordering; bottom tab bar + react-router. Open for planner: in-memory EventEmitter vs Redis pub/sub (single Node process today, ioredis not installed); new tables must use drizzle generate+migrate, NOT push."
 }

.planning/PROJECT.md

@@ -15,17 +15,18 @@ The household can see and co-edit one color-coded family calendar (shared + each
 <!-- Shipped and confirmed valuable. -->
 
 - [x] Unified, color-coded calendar view aggregating all Fastmail-hosted calendars (shared family + each member's personal) — **Validated in Phase 2 (calendar-display)**: read-only day/week/month/agenda views, server-side recurrence expansion (DST-correct), all-day no-shift, color routing by member/shared. Operator UAT approved. (Shared/rose lane activates once a shared calendar is marked — deferred per D-16.)
+- [x] Create / edit / delete events written back to the correct Fastmail calendar via the app's single broker token — **Validated in Phase 3 (Gate 2, live 2026-06-07)**: create (timed/all-day/weekly-recurring), edit, delete, and recurring-series delete all round-trip to caldav.fastmail.com; 412-conflict handled. Recurring repeat-bound + per-occurrence-duration UX are "create+display only in v1" gaps (backlog 999.7/999.8).
+- [x] Authelia OIDC login for every member (true SSO) — **Validated in Phase 3 (Gate 2, live 2026-06-07)**: both members log in via real Authelia OIDC over Pangolin; distinct stable colors; session carried transparently by Authelia SSO. (Full-name legend needs an Authelia ID-token `claims_policy` — operator step.)
+- [x] React PWA installable on iPhone via "Add to Home Screen" (no App Store) — **Validated in Phase 3 (Gate 2, live 2026-06-07)**: iOS install + full-screen standalone launch + standalone OIDC login (load-bearing) confirmed on the wife's iPhone. Android install walkthrough deferred (B5, not yet device-tested).
 
 ### Active
 
 <!-- v1 scope. Hypotheses until shipped and validated. -->
-- [ ] Create / edit / delete events written back to the correct Fastmail calendar via the app's single broker token
 - [ ] Shared collaborative lists (groceries, gift ideas) that both members co-edit, stored in MariaDB
 - [ ] Live list sync so co-edits appear without manual refresh (Redis optional)
-- [ ] Authelia OIDC login for every member (true SSO)
-- [ ] React PWA installable on iPhone and Android via "Add to Home Screen" (no App Store)
 - [ ] Web Push notifications for event reminders and list changes
-- [ ] Low-friction onboarding for the non-technical Apple member — visit one URL, sign in
+- [ ] Android PWA install walkthrough verified on a real Android device (iOS validated Phase 3; Android = carried Gate 2 row B5)
+- [ ] Low-friction onboarding for the non-technical Apple member — visit one URL, sign in. **Partially validated Phase 3** (wife logged in + installed unaided); the per-member Fastmail app-password provider-setup step is still missing (backlog 999.5)
 
 ### Out of Scope
 
@@ -77,6 +78,7 @@ The household can see and co-edit one color-coded family calendar (shared + each
 | **D-14:** Defer Phase 1 Gate 2 (live Authelia/Pangolin verification). SSE-over-Pangolin smoke = hard gate before Phase 4; live AUTH smoke incl. iOS standalone-PWA folded into Phase 3; full 2-member prod login verified there. Phases 2–3 develop behind a documented dev-auth bypass. | Gate 2 needs operator infra (Authelia config + tunnel) + docs that didn't exist; deferring unblocks Phase 2/3 code without rework risk, since the broker data path (CAL-01/CAL-08) is already proven live. SSE must still be verified before Phase 4 to avoid building live-sync on an unverified transport (#1034). | Tracked: `01-HUMAN-UAT.md`, `docs/deployment.md` |
 | **D-15:** Validate the real external topology via a **local Newt connector + test subdomain** through existing Pangolin (Mode A), not an Unraid deploy. Unraid (Mode B) reserved for go-live. | Authelia OIDC + SSE pass-through behaviour live in Authelia + Pangolin/Newt, not in where the origin runs — so a local Newt rig faithfully tests both, decoupling "does the topology work" from "is it in production." Newt dials outbound (no open ports). Only shared touch is an additive, reversible Authelia client. | — Pending (Gate 2) |
 | **D-16 (2026-06-05, Phase 2):** No dedicated Fastmail "broker" account. The **shared-family calendar is a calendar collection created on the operator's primary Fastmail account** (`me@lucasberger.ca`) and shared out to the wife + others via Fastmail's own calendar sharing. The app's single app password enumerates it like any other collection; the `calendars.is_shared` flag (operator-set) marks which row is the shared one. | Clarified during the Wave 2 checkpoint: "broker account" was only ever the role the primary account's app password plays. id=1 ("Calendar") is the operator's **personal** calendar, not the shared one — so it must NOT be marked `is_shared`. Aggregating each *other* member's **personal** calendar still follows the D-09 per-member app-password model (open for Phase 3 onboarding: a member may get a personal color lane, or only the shared calendar). | — Pending (shared calendar not yet created) |
+| **D-17 (2026-06-07, Phase 3):** Phase 1 Gate 2 (deferred per D-14) was executed live during Phase 3 against real Authelia OIDC over Pangolin/Newt (Mode A), clearing the load-bearing iOS-standalone-login risk. The full event write path (create/all-day/recurring/edit/delete/conflict) is verified end-to-end to Fastmail. | Live bring-up surfaced bugs the dev-bypass build could not (newt MTU blackhole, OIDC state-cookie race, write-path timezone/identity/join/cache bugs, all-day off-by-one, color collisions). All fixed; UX gaps captured as backlog 999.3–999.9. | — Validated (Gate 2, `03-GATE2-RESULTS.md`). Carried: Android install (B5), SSE smoke (Phase 4 entry gate, D-14). |
 
 ## Evolution
 
@@ -96,4 +98,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-06-03 after initialization*
+*Last updated: 2026-06-07 after Phase 3 (event-write-back-pwa-install)*

.planning/ROADMAP.md

@@ -15,9 +15,10 @@ Decimal phases appear between their surrounding integers in numeric order.
 
 - [x] **Phase 1: Foundation + Broker Spike** - Auth, Docker scaffold, CalDAV broker read path, and personal-calendar ACL spike (go/no-go gate) (completed 2026-06-04)
 - [x] **Phase 2: Calendar Display** - Read-only unified color-coded calendar (week/month/day/agenda) built on the confirmed broker (completed 2026-06-05)
-- [ ] **Phase 3: Event Write-Back + PWA Install** - Full event CRUD written back to Fastmail, PWA manifest + service worker, guided iOS install flow
+- [x] **Phase 3: Event Write-Back + PWA Install** - Full event CRUD written back to Fastmail, PWA manifest + service worker, guided iOS install flow (completed 2026-06-07)
 - [ ] **Phase 4: Shared Lists + Live Sync** - Named collaborative lists with item CRUD and real-time SSE co-edit sync
 - [ ] **Phase 5: Web Push Notifications** - VAPID push for event reminders, event changes, and list-change alerts
+- [ ] **Phase 6: UX Polish** - All-day visual distinction, event-form date/recurrence behavior, recurring-series edit, and auth-flow smoothing
 
 ## Phase Details
 
@@ -123,7 +124,7 @@ Plans:
 
 **Wave 5** *(blocked on Wave 4)*
 
-- [ ] 03-08-PLAN.md — Gate 2 live verification: real Authelia OIDC over Pangolin + iOS standalone login + end-to-end Fastmail write round-trips (success criterion 6, D-14/D-15)
+- [x] 03-08-PLAN.md — Gate 2 live verification: real Authelia OIDC over Pangolin + iOS standalone login + end-to-end Fastmail write round-trips (success criterion 6, D-14/D-15)
 
 **UI hint**: yes
 
@@ -140,7 +141,31 @@ Plans:
   2. Either member can add items to a list, check items off, reorder them by drag-and-drop, and delete individual items
   3. When one member adds or checks off an item, the other member sees the change appear in the list within a few seconds without refreshing — even if they reconnect after a brief network gap
 
-**Plans**: TBD
+**Entry gate status (2026-06-08):** CLEARED — SSE-over-Pangolin smoke test PASSED (35 heartbeats over ~6 min, buffering off, no cut). Live sync may be built directly on SSE; polling fallback (D-12) retained as belt-and-suspenders.
+
+**Plans**: 6 plans
+Plans:
+**Wave 1**
+
+- [ ] 04-01-PLAN.md — Foundation + app shell: deps install (+ legitimacy gate), list tables generate+migrate [BLOCKING], API test harness + Wave-0 RED stubs, react-router + BottomTabBar + empty ListsIndex (D-13/D-16/D-17/D-18)
+
+**Wave 2** *(blocked on Wave 1)*
+
+- [ ] 04-02-PLAN.md — TDD: scoped in-memory fan-out (listEmitter) + getAccessibleListIds access scope — the load-bearing D-04 no-leak primitive (LIST-04)
+- [ ] 04-03-PLAN.md — List CRUD slice: POST/GET/PATCH/DELETE /api/lists with scoped access + auto-share-on-create + ListsIndex/ListCard/CreateListSheet/ListDeleteDialog (LIST-01, D-01/D-02/D-06)
+
+**Wave 3** *(blocked on Wave 2)*
+
+- [ ] 04-04-PLAN.md — Item CRUD + checked-sink slice: item endpoints + fractional rank + per-field LWW PATCH + ListDetail/ItemRow/AddItemInput + optimistic UI (LIST-02, D-05/D-07/D-08/D-09)
+
+**Wave 4** *(blocked on Wave 3)*
+
+- [ ] 04-05-PLAN.md — Reorder slice: dnd-kit sortable + generateKeyBetween rank + one-row position PATCH + animate-on-remote (LIST-03, D-13/D-14/D-15)
+
+**Wave 5** *(blocked on Waves 2 + 4)*
+
+- [ ] 04-06-PLAN.md — Live-sync slice: scoped /api/sse/lists + fan-out triggers + useListSSE bounded-backoff hook + LiveSyncIndicator + polling fallback (LIST-04, D-04/D-10/D-11/D-12)
+
 **UI hint**: yes
 
 ### Phase 5: Web Push Notifications
@@ -158,19 +183,39 @@ Plans:
 
 **Plans**: TBD
 
+### Phase 6: UX Polish
+
+**Goal**: Smooth the rough edges surfaced during live use — clearer all-day events, saner event-form date/recurrence behavior, recurring-series editing, and auth-flow polish — so the app feels slick for the non-technical Apple member (hard UX constraint).
+**Mode:** mvp
+**Depends on**: Phase 3 (calendar/event-form polish); Phase 4 for any list-related polish
+**Requirements**: TBD
+**Success Criteria** (what must be TRUE):
+
+  1. All-day events are visually distinct from timed events at a glance
+  2. The event form keeps a sane duration when the start moves, all-day edits don't grow the event, and a recurrence can be bounded (repeat-until / count)
+  3. A recurring series can be edited as a whole
+  4. A session that expires mid-use redirects cleanly to sign-in instead of hanging on a generic error
+  5. Unauthenticated cold load shows a neutral "signing you in…" splash — no calendar/"sign-in required" flash before Authelia
+
+**Candidate scope** (promote via `/gsd-review-backlog` at planning): 999.2 (login flash), 999.3 (session-timeout redirect), 999.6 (all-day visual), 999.7 (form end-tracking + all-day-edit off-by-one), 999.8 (recurrence bound), 999.9 (recurring-series edit). 999.4 (reminders) and 999.5 (provider setup) are more feature than polish — decide at planning.
+
+**Plans**: TBD
+**UI hint**: yes
+
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 Note: Phase 4 depends only on Phase 1 and can begin as soon as Phase 1 is complete. It is serialized here to reduce work-in-progress.
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. Foundation + Broker Spike | 4/4 | Complete   | 2026-06-04 |
 | 2. Calendar Display | 5/5 | Complete    | 2026-06-05 |
-| 3. Event Write-Back + PWA Install | 11/12 | In Progress|  |
-| 4. Shared Lists + Live Sync | 0/? | Not started | - |
+| 3. Event Write-Back + PWA Install | 12/12 | Complete    | 2026-06-07 |
+| 4. Shared Lists + Live Sync | 0/6 | Planned | - |
 | 5. Web Push Notifications | 0/? | Not started | - |
+| 6. UX Polish | 0/? | Not started | - |
 
 ## Backlog
 
@@ -178,7 +223,7 @@ Note: Phase 4 depends only on Phase 1 and can begin as soon as Phase 1 is comple
 
 **Goal:** [Captured for future planning] Abstract the calendar backend behind a provider interface so Fastmail/CalDAV is one implementation among potentially many. Shipping with a single provider is fine, but the broker, sync, and event-expansion layers should be structured so additional providers (e.g. other CalDAV hosts, Google Calendar, generic ICS feeds) can be added without rework. Captures the "provider" seam as an explicit architectural concern.
 **Requirements:** TBD
-**Plans:** 11/12 plans executed
+**Plans:** 12/12 plans complete
 
 Plans:
 
@@ -199,3 +244,104 @@ Plans:
 Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.3: Redirect to sign-in on session timeout instead of hanging (BACKLOG)
+
+**Goal:** [Captured for future planning] When the OIDC session expires mid-use, the app hangs the action (no toast/progress) and then shows a generic "couldn't load events" — fooling the user into thinking it's broken rather than signed out. Detect session expiry (401 / opaqueredirect) from ANY query or mutation and drive a clear re-auth: top-level navigation to `/api/login`, ideally behind a brief "Your session expired — signing you back in…" interstitial, with no silent loss of an in-flight write.
+
+**Root cause** (diagnosed during Phase 03 Gate 2 live verification, 2026-06-07) — re-auth is only wired to the INITIAL `/api/me` failure and is one-shot (`familysync.loginRedirectAttempted` flag, cleared on a successful `/api/me`). `fetchEvents` uses `redirect:'follow'` so a timed-out session 302s cross-origin → the XHR rejects → `eventsQuery` just errors; write mutations hang/error with no re-auth.
+
+**Proposed fix:** Centralize expiry detection in `apps/pwa/src/api/client.ts` (typed `SessionExpiredError` on 401/opaqueredirect), apply `redirect:'manual'` consistently, and a single TanStack Query/Mutation error handler that re-arms `maybeRedirectToLogin()`. See `.planning/todos/pending/` archive for full detail.
+
+**Severity:** high — hits any long-lived tab (the wife leaving the PWA open). Tags: phase-03, auth, ux.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.4: Event-creation notification/reminder (VALARM) options (BACKLOG)
+
+**Goal:** [Captured for future planning] The event create/edit form has no UI to set a reminder ("remind me 10 min / 1 hour / 1 day before"), so the written `.ics` carries no `VALARM` and no reminder can fire — in native clients or via web push. Add a reminder selector, serialize chosen offsets as `VALARM` (TRIGGER) on write-back, parse existing `VALARM`s on read so edits preserve them. Feeds the Phase 5 web-push requirement (push needs reminder data to notify about).
+
+**Severity:** medium — feature gap surfaced during Phase 03 Gate 2 testing. Tags: phase-03, calendar, write-back, phase-05-dependency.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.5: First-login provider setup — prompt + instructions to add a Fastmail app password (BACKLOG)
+
+**Goal:** [Captured for future planning] On a member's first login there is no onboarding to connect their own calendar provider. Today the broker uses a single seeded Fastmail app password (the operator's), so a second member (e.g. the wife) who logs in sees only what that token reaches — she has no way to attach her **own** Fastmail personal calendar (the D-09 per-member app-password model). Add a first-login flow that detects a member has no `member_credentials` row and prompts them to create + paste a Fastmail app password, with clear step-by-step instructions (where to generate it in Fastmail settings, required scope: Calendars/CalDAV, that one app password covers all of that account's calendars). Store it encrypted (APP_PASSWORD_ENCRYPTION_KEY, existing crypto path), then trigger an initial sync so their personal calendar lane populates.
+
+**Context** (surfaced 2026-06-07, Gate 2 live testing): the wife logged in on her iPhone and added the PWA to her Home Screen, but there is no provider-setup step — so her personal calendar can't be connected. This is the onboarding half of the "each member's personal calendar" v1 requirement.
+
+**Scope to decide when promoted:**
+
+- Detect "no credential yet" state server-side (`GET /api/me` exposes a `needsProviderSetup` flag, or a dedicated endpoint) and gate a setup screen in the PWA.
+- App-password entry UI + validation (test the credential with a CalDAV PROPFIND before saving), encrypted storage, and triggering the first sync.
+- Non-technical-friendly instructions (the hard UX constraint) — ideally with a direct link to Fastmail's app-password page and a screenshot/walkthrough.
+- Decide the model: does every member attach their own personal calendar, or do some members only see the shared family calendar? (Open question from D-16.)
+- Security: never log/echo the app password; member-scoped; T-03-19 style scoping.
+
+**Severity:** high for true multi-member use — without it the second member has no personal calendar. Tags: phase-03, onboarding, auth, caldav, per-member-credential, D-09.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.6: All-day events should stand out visually (BACKLOG)
+
+**Goal:** [Captured for future planning] All-day events currently look identical to timed events except for the absence of a time label, so they don't read as "all-day" at a glance. Give them a distinct visual treatment (e.g. a full-width pill/bar in the all-day row, a different shape/border, or a subtle background band) so they're immediately distinguishable from timed events.
+
+**Context** (surfaced 2026-06-07, Gate 2 live testing). Tags: phase-03, ui, calendar, ux-polish.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.7: Event form — auto-advance end when start moves; keep duration sane (BACKLOG)
+
+**Goal:** [Captured for future planning] In the create/edit form, moving the start date/time into the future does NOT move the end with it, so the event keeps a stale end and can become an absurdly long event. Auto-advance the end to preserve the current duration (or snap to a sensible default, e.g. +1h timed / same-day all-day) whenever the start changes, and guard against accidentally-multi-day durations.
+
+**Context** (surfaced 2026-06-07): a "recurring event" was created with start 2026-06-11 and end 2026-08-13 — a ~2-month-long event — because the end did not track the start. Combined with a weekly RRULE this rendered as overlapping bars spanning the calendar (looked duplicated). Tags: phase-03, ui, event-form, ux.
+
+**Also fix here — all-day EDIT off-by-one (latent bug found 2026-06-07):** the write path treats the form's all-day end date as INCLUSIVE and writes an exclusive `DTEND` (+1, WR-04 in `vevent.ts`). But the edit form populates its end-date field from the raw occurrence end, which is the EXCLUSIVE `DTEND` (start+1 for a 1-day event). So editing an all-day event and saving advances `DTEND` by another day — the event grows by one day per edit. The form must convert the exclusive occurrence end back to the inclusive date (−1 day) when populating all-day edits, symmetric with the create write and the display fix (commit d4d5327, hydrateEvents).
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.8: Recurrence bound (repeat-until / count) + recurring create polish (BACKLOG)
+
+**Goal:** [Captured for future planning] The recurrence control is just a frequency preset (none/daily/weekly/…) with no way to bound the series, so users reach for the event end-date to mean "repeat until" — producing one giant multi-month event instead of N short occurrences. Add a "repeat until <date>" (or "for N occurrences") control that writes RRULE UNTIL/COUNT, keeping each occurrence's duration tied to start→end (not the recurrence span). Also verify the frequency dropdown writes the selected FREQ (a daily selection appeared to persist as weekly — confirm/fix).
+
+**Context** (surfaced 2026-06-07): stored event had `RRULE:FREQ=WEEKLY` with a 2-month DTSTART→DTEND duration; user expected daily and a bounded series. Recurring is "create + display only" in v1 (D-decision); this is the create-side UX gap. Tags: phase-03, recurrence, event-form, caldav, ux.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.9: Edit a recurring series (whole-series edit) (BACKLOG)
+
+**Goal:** [Captured for future planning] There is currently no way to edit a recurring series — opening an occurrence offers no "edit this series" path. Add whole-series editing (modify the master VEVENT: title/time/RRULE/etc.). NOTE: single-occurrence editing (RECURRENCE-ID) and "this and following" are already deferred to v1.x (see Deferred Items); this item is specifically the series-level edit, the most common case, and may be worth pulling earlier than the per-occurrence variants.
+
+**Context** (surfaced 2026-06-07, Gate 2 live testing). Tags: phase-03, recurrence, event-form, caldav.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+

.planning/STATE.md

@@ -3,40 +3,40 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: Completed 03-11-PLAN.md (gap-closure waves done; 03-08 Gate 2 human checkpoint remains)
-last_updated: "2026-06-06T00:34:09.142Z"
-last_activity: 2026-06-06 -- Phase 03 execution started
+stopped_at: Phase 4 UI-SPEC approved
+last_updated: "2026-06-09T14:25:21.889Z"
+last_activity: 2026-06-09 -- Phase 04 planning complete
 progress:
-  total_phases: 6
-  completed_phases: 2
+  total_phases: 15
+  completed_phases: 3
   total_plans: 21
-  completed_plans: 16
-  percent: 33
+  completed_plans: 21
+  percent: 20
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-06-03)
+See: .planning/PROJECT.md (updated 2026-06-07)
 
 **Core value:** One color-coded family calendar (shared + personal) and shared lists from a single low-friction PWA — cross-ecosystem, no app store
-**Current focus:** Phase 03 — event-write-back-pwa-install
+**Current focus:** Phase 04 — Shared Lists + Live Sync (entry gate: SSE-over-Pangolin smoke test, D-14)
 
 ## Current Position
 
-Phase: 03 (event-write-back-pwa-install) — EXECUTING
-Plan: 11 of 12 (gap-closure 03-09/10/11/12 complete; 03-08 Gate 2 live/iOS human checkpoint remains)
-Status: Gap-closure waves complete — write path now reachable end-to-end
-Last activity: 2026-06-06 -- Phase 03 gap-closure (03-09..03-12) executed and merged
+Phase: 4
+Plan: Not started
+Status: Ready to execute
+Last activity: 2026-06-09 -- Phase 04 planning complete
 
-Progress: [███████░░░] 65%
+Progress: [█████░░░░░] 50% (3 of 6 phases)
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 5
+- Total plans completed: 17
 - Average duration: -
 - Total execution time: 0 hours
 
@@ -45,6 +45,7 @@ Progress: [███████░░░] 65%
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 02 | 5 | - | - |
+| 03 | 12 | - | - |
 
 **Recent Trend:**
 
@@ -86,6 +87,10 @@ Recent decisions affecting current work:
 - [Phase ?]: D-02 calendar picker: hidden when writableCalendars.length === 1, shown when >1 — authoritative from GET /api/events/writable-calendars
 - [Phase ?]: T-03-15 XSS: EventForm renders all values as plain-text JSX children; no dangerouslySetInnerHTML in code
 
+### Roadmap Evolution
+
+- Phase 6 added (2026-06-07): UX Polish — all-day visual distinction, event-form date/recurrence behavior, recurring-series edit, auth-flow smoothing. Candidate scope pulls from backlog 999.2/999.3/999.6/999.7/999.8/999.9.
+
 ### Pending Todos
 
 - **Fix `docs/deployment.md` local-dev command** — the documented dev run is wrong: the API dev script (`node --watch dist/index.js`) does NOT load `.env`, and `DB_HOST` defaults to `localhost` with an empty password. Correct local-dev command is: `pnpm --filter @familysync/api build && set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev` (+ `pnpm --filter @familysync/pwa dev`). Consider adding `--env-file=.env` to the dev script so this is automatic. (Surfaced during Phase 2 UAT.)
@@ -95,7 +100,7 @@ Recent decisions affecting current work:
 ### Blockers/Concerns
 
 - ~~Phase 1: Personal-calendar CalDAV ACL~~ RESOLVED → CAL-08 GO (per-member app password; no cross-account ACL).
-- Phase 4 ENTRY GATE: Pangolin SSE pass-through (issue #1034) still unverified — deferred from Phase 1 Gate 2 (D-14). Must pass the 5-min SSE smoke (docs/deployment.md) before building live sync.
+- ~~Phase 4 ENTRY GATE: Pangolin SSE pass-through (issue #1034) unverified~~ CLEARED 2026-06-08 — SSE smoke PASS over familysync-dev.bergerhouse.net (~6 min, 35 heartbeats, buffering off, no cut). Live sync unblocked. Caveat: untested for a max total connection-duration cap; residual risk covered by Phase 4 design (D-10/D-11/D-12). See quick 260607-u8o + 03-GATE2-RESULTS.md Part C.
 - Phase 3: iOS standalone-PWA + Authelia login is load-bearing for the wife and is the first real external auth test (carried Gate 2 item, D-14). Also: iOS install guide is load-bearing — she gets no push notifications if she does not install the PWA.
 - Phase 2/3 dev: build behind a documented dev-auth bypass until Gate 2 deploy (D-14).
 - Phase 5: iOS push subscriptions silently revoked after 3 silent pushes. Subscription health-check and event.waitUntil() are mandatory from day one.
@@ -106,6 +111,7 @@ Recent decisions affecting current work:
 |---|-------------|------|--------|-----------|
 | 260606-tv8 | Fix missing sign-in redirect in the PWA (Phase 03 auth-entry gap from Gate 2): guarded /api/login → / + full-page redirect on unauthenticated fetchMe | 2026-06-07 | 7c6531f | [260606-tv8-fix-missing-sign-in-redirect-in-the-pwa-](./quick/260606-tv8-fix-missing-sign-in-redirect-in-the-pwa-/) |
 | 260607-l6l | Batch-fix Phase 03 write-path bugs: events.ts edit/delete missing calendars innerJoin (503, BLOCKING) + handler-coupled regression test; shared deriveDisplayName helper (me.ts + resolveUserId, corrects blank rows); GET /api/events userId/isShared ownership filter | 2026-06-07 | 2870413 | [260607-l6l-fix-phase-03-write-path-correctness-bugs](./quick/260607-l6l-fix-phase-03-write-path-correctness-bugs/) |
+| 260607-u8o | Record SSE-over-Pangolin smoke test PASS (Phase 4 entry gate, D-14 / issue #1034) — updated 01-HUMAN-UAT item 4 + 03-GATE2-RESULTS Part C to PASS with live evidence | 2026-06-08 | 26655cf | [260607-u8o-record-sse-over-pangolin-smoke-test-pass](./quick/260607-u8o-record-sse-over-pangolin-smoke-test-pass/) |
 
 ## Deferred Items
 
@@ -120,6 +126,6 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-06-07 — Completed quick task 260607-l6l (write-path bug batch)
-Stopped at: Edit/delete 503 blocker RESOLVED (missing calendars join), displayName + GET-events-filter fixed. Code on gsd/v1.0-milestone; build clean, 100/100 api tests pass. NEXT: operator must rebuild (docker compose up -d --build) and browser re-test delete/edit + legend name. Remaining Gate 2 items (A2/A3 session+2nd-member-color, B iOS install, C SSE smoke) are human/device checkpoints — see HANDOFF.json.
-Resume file: .planning/HANDOFF.json (updated — 3 code bugs cleared, gate-2 human checkpoints remain)
+Last session: 2026-06-09T13:44:22.701Z
+Stopped at: Phase 4 UI-SPEC approved
+Resume file: .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md

.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,322 @@
+<!-- refreshed: 2026-06-09 -->
+# Architecture
+
+**Analysis Date:** 2026-06-09
+
+## System Overview
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                   PWA Frontend (React 19)                   │
+│ CalendarShell + Schedule-X calendar + EventForm + UI state  │
+│ TanStack Query (server state) + Zustand (UI-only state)    │
+│ `apps/pwa/src/`                                             │
+└────────┬──────────────────────────────────────────────────┬─┘
+         │                                                  │
+         │ fetch (with credentials)                        │ SSE
+         │ (OIDC session cookie)                           │
+         ▼                                                  ▼
+┌──────────────────────────────────────────────────────────────┐
+│     Backend API (Hono + Node.js) — Port 3000                 │
+│ ┌──────────────────────────────────────────────────────────┐ │
+│ │ Auth Layer (OIDC + Authelia)                             │ │
+│ │ `apps/api/src/auth/middleware.ts`, `devBypass.ts`        │ │
+│ └──────────────────────────────────────────────────────────┘ │
+│ ┌──────────────────────────────────────────────────────────┐ │
+│ │ Route Handlers — Read from MariaDB cache only            │ │
+│ │ GET /api/events — windowed occurrences via expand.ts    │ │
+│ │ GET /api/me — current user profile + color              │ │
+│ │ POST /api/events/create, PATCH /:uid/edit — enqueue     │ │
+│ │ DELETE /:uid — enqueue delete to outbox                 │ │
+│ │ GET /api/sse/heartbeat — SSE smoke test                 │ │
+│ │ `apps/api/src/routes/`                                  │ │
+│ └──────────────────────────────────────────────────────────┘ │
+│ ┌──────────────────────────────────────────────────────────┐ │
+│ │ DB Layer (Drizzle ORM + mysql2)                          │ │
+│ │ Schema: users, member_credentials, calendars,           │ │
+│ │ calendar_events, calendar_outbox                         │ │
+│ │ `apps/api/src/db/`                                      │ │
+│ └──────────────────────────────────────────────────────────┘ │
+│ ┌──────────────────────────────────────────────────────────┐ │
+│ │ Background Broker (CalDAV sync & write-back)             │ │
+│ │ - Poller (5-min): PROPFIND → ctag change detect         │ │
+│ │ - Sync (per-cal): REPORT → ical.js → MariaDB upsert    │ │
+│ │ - OutboxWorker (15-sec): drain pending writes to        │ │
+│ │   Fastmail (PUT/DELETE via tsdav)                       │ │
+│ │ `apps/api/src/broker/`                                  │ │
+│ └──────────────────────────────────────────────────────────┘ │
+└────────┬──────────────────────────────────────────────────┬──┘
+         │                                                  │
+         └─ Fastmail CalDAV + app passwords ────────────────┘
+           (tsdav client, encrypted credentials)
+           (PROPFIND, REPORT, PUT, DELETE)
+         
+         MariaDB (persistent cache)
+         (read on every request, written by broker)
+```
+
+## Component Responsibilities
+
+| Component | Responsibility | File |
+|-----------|----------------|------|
+| **CalendarShell** | React entry point; wires TanStack Query + Schedule-X + Zustand + event modals | `apps/pwa/src/components/CalendarShell.tsx` |
+| **AppNav** | Navigation header/sidebar; responsive (phone/tablet layout) | `apps/pwa/src/components/AppNav.tsx` |
+| **EventDetailPopover** | Displays event details; driven by Zustand.openEventId | `apps/pwa/src/components/EventDetailPopover.tsx` |
+| **EventForm** | Create/edit event modal; builds payloads for POST/PATCH endpoints | `apps/pwa/src/components/EventForm.tsx` |
+| **SyncStateToast** | Toast polling `/api/events/sync-status?uid=` for optimistic-accept feedback | `apps/pwa/src/components/SyncStateToast.tsx` |
+| **Zustand calendarStore** | UI-only state: selectedView, openEventId, eventFormOpen, calendarRange, deleteDialog state | `apps/pwa/src/store/calendarStore.ts` |
+| **TanStack Query hooks** | Server state: fetchMe (user profile), fetchEvents (windowed occurrences), fetchSyncStatus | `apps/pwa/src/api/client.ts` + CalendarShell.tsx |
+| **hydrateEvents** | Transforms raw CalendarOccurrence[] to Schedule-X CalendarType[] with Temporal dates | `apps/pwa/src/lib/hydrateEvents.ts` |
+| **buildCalendarConfig** | Builds Schedule-X calendar configuration (views, plugins, columns) | `apps/pwa/src/lib/calendarConfig.ts` |
+| **OIDC middleware** | Protects /api/* routes; 302-redirects unauthenticated requests to Authelia | `apps/api/src/auth/middleware.ts` |
+| **devAuthBypass** | Dev-only passthrough auth for local development without Authelia | `apps/api/src/auth/devBypass.ts` |
+| **upsertUser** | Identity upsert by (oidc_iss, oidc_sub); auto-assigns color from palette | `apps/api/src/auth/user.ts` |
+| **eventsRouter** | GET /api/events (windowed reads), POST/PATCH/DELETE (enqueue outbox), GET /writable-calendars | `apps/api/src/routes/events.ts` |
+| **meRouter** | GET /api/me — returns authenticated user profile (id, displayName, color) | `apps/api/src/routes/me.ts` |
+| **sseRouter** | GET /api/sse/heartbeat — SSE smoke test for Pangolin proxy validation | `apps/api/src/routes/sse.ts` |
+| **CalDAV Broker** | Decrypts credentials, manages tsdav clients, syncs calendars, drains outbox | `apps/api/src/broker/*.ts` |
+| **Poller** | 5-min background job: PROPFIND → ctag comparison → skip or syncCalendar | `apps/api/src/broker/poller.ts` |
+| **syncCalendar** | REPORT → ical.js parse → VEVENT upsert; prunes deleted events | `apps/api/src/broker/sync.ts` |
+| **OutboxWorker** | 15-sec background job: drain pending outbox rows, build VEVENTs, PUT/DELETE to Fastmail | `apps/api/src/broker/outboxWorker.ts` |
+| **expandOccurrences** | Server-side RRULE expansion via ical.js; produces concrete occurrences for UI | `apps/api/src/broker/expand.ts` |
+
+## Pattern Overview
+
+**Overall:** Three-tier monolith (PWA frontend, Node.js backend, MariaDB), split between `apps/pwa` (React) and `apps/api` (Hono + broker). 
+
+**Request-response pattern:**
+- Frontend reads from MariaDB cache via REST endpoints (GET only)
+- Frontend enqueues writes to transactional outbox (POST/PATCH/DELETE return 202 immediately)
+- Background broker drains outbox, calls Fastmail CalDAV, updates cache
+- Real-time updates via SSE (Phase 4) and/or polling (SyncStateToast for write feedback)
+
+**Data ownership pattern:**
+- Poller owns calendar collection discovery + change detection (D-13 ctag polling)
+- syncCalendar owns per-calendar event cache (REPORT → parse → upsert)
+- OutboxWorker owns write-back to Fastmail (D-05 transactional outbox)
+- Routes own read authorization and ownership checks (T-03-06..T-03-11)
+
+**Key Characteristics:**
+- Events endpoint shares MariaDB cache — no direct Fastmail I/O from routes (T-03-02 broker boundary)
+- Write operations use optimistic-accept pattern: 202 + immediate UI response, success confirmed via polling
+- All server state in TanStack Query; UI state only in Zustand (clear separation)
+- User identity keyed on (oidc_iss, oidc_sub) not email (D-10); color auto-assigned (D-06)
+- All-day events stored as DATE, timed events as TIMESTAMP UTC (D-13 schema contract)
+- Recurring events expanded server-side (D-09); client receives concrete occurrences only
+
+## Layers
+
+**Presentation (React PWA):**
+- Purpose: Display calendar, handle user interactions, manage UI state (view selection, modals, popovers)
+- Location: `apps/pwa/src/`
+- Contains: Components (CalendarShell, EventForm, EventDetailPopover, AppNav, SyncStateToast), UI hooks (CalendarShell's useQuery for data, Zustand for view state)
+- Depends on: Schedule-X (calendar library), @tanstack/react-query (server state), Zustand (UI state), TanStack utilities
+- Used by: Browser tab (Vite dev proxy or production Pangolin tunnel)
+
+**API / Route Layer:**
+- Purpose: Validate requests, enforce authorization (T-03-06..T-03-11), read from cache, enqueue writes
+- Location: `apps/api/src/routes/`
+- Contains: Route handlers (events.ts, me.ts, health.ts, sse.ts); Zod schemas for input validation
+- Depends on: Hono framework, Drizzle ORM, @hono/zod-validator, auth middleware
+- Used by: PWA frontend (fetch with OIDC cookie), load balancer redirects
+- Architecture invariant: Routes **never** import tsdav or call Fastmail directly (T-03-02)
+
+**Database / ORM Layer:**
+- Purpose: Type-safe query building, schema definition, migrations
+- Location: `apps/api/src/db/`
+- Contains: Drizzle schema (users, member_credentials, calendars, calendar_events, calendar_outbox), mysql2 client
+- Depends on: mysql2 driver, Drizzle ORM
+- Used by: All route handlers, broker modules
+
+**Broker / Background Worker Layer:**
+- Purpose: Keep MariaDB calendar cache in sync with Fastmail; drain transactional outbox
+- Location: `apps/api/src/broker/`
+- Contains: Poller (5-min cron), syncCalendar (REPORT parse), OutboxWorker (15-sec drain), supporting utilities
+- Depends on: tsdav (CalDAV client), ical.js (VEVENT parsing), node-cron (scheduling), Drizzle ORM
+- Used by: Scheduled background jobs (started in index.ts only when module is main)
+- Data sources: member_credentials (encrypted), calendars, calendar_events (cache), calendar_outbox (pending writes)
+
+**Auth / Session Layer:**
+- Purpose: OIDC authentication via Authelia, user identity upsert, session cookies
+- Location: `apps/api/src/auth/`
+- Contains: Middleware (oidcAuthMiddleware, processOAuthCallback from @hono/oidc-auth), upsertUser color assignment, dev bypass
+- Depends on: @hono/oidc-auth, Drizzle ORM for user upsert
+- Used by: Hono middleware stack, route handlers via getAuth(c) or c.get('user')
+
+## Data Flow
+
+### Primary Request Path (GET /api/events)
+
+1. **Client request** — CalendarShell's eventsQuery fires when meQuery succeeds
+2. **OIDC guard** (`apps/api/src/auth/middleware.ts:oidcAuthMiddleware`) — 302-redirect if unauthenticated; session cookie checked
+3. **Route handler** (`apps/api/src/routes/events.ts:eventsRouter.get('/')`) — validate start/end dates, resolve userId via getAuth + upsertUser
+4. **SQL pre-filter** — Select from calendar_events JOIN calendars JOIN users; WHERE matches:
+   - Ownership: current user's own calendars OR shared-family calendar (isShared=true)
+   - Date window: recurring masters (hasRrule=1) OR non-recurring timed (dtstartUtc in range) OR all-day (dtstartDate in range)
+5. **Expansion** (`apps/api/src/broker/expand.ts:expandOccurrences`) — For each row, parse rawVevent with ical.js, expand RRULE into occurrences, emit CalendarOccurrence[] with stable IDs
+6. **Response** — JSON { occurrences: CalendarOccurrence[] }
+7. **Client hydration** (`apps/pwa/src/lib/hydrateEvents.ts`) — Convert occurrence ISO strings to Temporal.ZonedDateTime for Schedule-X
+8. **Schedule-X render** — eventsService.set() updates calendar model; re-render with color routing (isShared ? 'shared' : String(ownerUserId))
+
+**State Management:**
+- TanStack Query caches result with key ['events', start, end]; staleTime 5 min
+- Zustand calendarRange (start/end) drives query key → navigation re-fetches
+- SyncStateToast polls `/api/events/sync-status?uid=` to show write-back progress
+
+### Write Path (POST /api/events/create)
+
+1. **User interaction** — EventForm.onSubmit calls POST /api/events/create with CreateEventPayload
+2. **OIDC guard** — Session verified
+3. **Route validation** (`apps/api/src/routes/events.ts:eventsRouter.post('/create')`) — Zod validates payload (title, start, end, location, description, recurrence)
+4. **Calendar ownership check** — If calendarUrl supplied, verify it's owned by currentUser OR isShared; else default to user's first calendar
+5. **Outbox enqueue** — INSERT into calendar_outbox with status='pending', operation='create', uid=randomUUID
+6. **202 response** — Return immediately with { uid } (optimistic-accept, D-05)
+7. **UI toast** — Zustand setLastSyncedUid; SyncStateToast polls sync-status for this uid
+8. **Background drain** — OutboxWorker (15-sec cron):
+   - SELECT outbox WHERE status='pending' AND next_attempt_at <= NOW()
+   - Decrypt credential from member_credentials
+   - Call `/broker/write.ts:createCalendarEvent` — builds VEVENT from payload, PUT to Fastmail
+   - On 2xx: mark done, trigger targeted sync (syncCalendar) to refetch the calendar
+   - On 412 conflict: mark failed (no retry), trigger sync (UI sees server state)
+   - On 5xx/408/429: exponential backoff, mark dead after 5 attempts
+   - On 400/401/403: mark failed immediately
+9. **Cache update** — syncCalendar upserts calendar_events from REPORT; GET /api/events now includes the new event
+10. **Client refetch** — SyncStateToast sees status='done'; TanStack Query invalidateQueries refetches events
+
+### Calendar Sync (Background Poller → syncCalendar)
+
+1. **Poller fires** — node-cron 5-min schedule calls runPoll()
+2. **Load credentials** — SELECT member_credentials; decrypt each app password (T-03-04 — never log plaintext)
+3. **Per-credential**: Create tsdav client, PROPFIND to discover calendars
+4. **Per-calendar**:
+   - Look up known ctag from calendar_events join
+   - If ctag unchanged and not null: SKIP (no DB write, no Fastmail round-trip)
+   - If ctag changed or null: call syncCalendar
+5. **syncCalendar** (`apps/api/src/broker/sync.ts`):
+   - Upsert calendars row with new ctag/syncToken
+   - REPORT (calendar-query) → tsdav.fetchCalendarObjects() → array of { data, etag, url }
+   - For each: Parse with ICAL.parse(), extract VEVENT, build dtstartUtc/dtstartDate per schema contract (D-13)
+   - Upsert calendar_events with onDuplicateKeyUpdate (idempotency key: calendarId + uid)
+   - Prune deletes: DELETE events whose uid is no longer on server (BUG B: scope by (userId, url) for shared account)
+
+**Ownership Model (D-03, D-16):**
+- Shared Fastmail account: both members' credentials fetch the same calendar collections
+- Stored as (userId, url) composite unique key so each member caches the same calendar separately
+- eventsRouter ownership check: calendar.userId = currentUserId OR isShared=true (writable set)
+- poller lookup: AND(userId, url) to fetch the right member's cached version
+
+## Key Abstractions
+
+**CalendarOccurrence:**
+- Purpose: Single concrete event occurrence ready for UI (expanded from RRULE if needed)
+- Examples: `apps/api/src/broker/expand.ts:CalendarOccurrence`, `apps/pwa/src/api/client.ts:CalendarOccurrence`
+- Pattern: Backend expands RRULE into N occurrences; each has stable id = `${uid}::${dtstart_iso}`, allowing Schedule-X dedup and Zustand.openEventId routing
+
+**Transactional Outbox (D-05):**
+- Purpose: Decouple client request (202 response) from Fastmail write (async worker)
+- Examples: `apps/api/src/db/schema.ts:calendarOutbox`
+- Pattern: Write endpoint INSERTs pending row; worker POLLs and drains; status machine (pending → done/failed/dead) controls retry + backoff
+
+**Wrapped Schema Contract (D-13):**
+- Purpose: Guarantee correct DATE vs TIMESTAMP storage for all-day vs timed events
+- Examples: `apps/api/src/db/schema.ts` (dtstartUtc, dtstartDate, allDay); `apps/api/src/broker/sync.ts` (storage logic); `apps/api/src/routes/events.ts` (window predicate)
+- Pattern: All-day events NEVER coerce to midnight-UTC (Pitfall 2); timed events always UTC; query pre-filters both branches
+
+**RRULE Expansion (D-09):**
+- Purpose: Expand recurring masters server-side so client receives concrete occurrences only
+- Examples: `apps/api/src/broker/expand.ts:expandOccurrences`, `apps/pwa/src/lib/hydrateEvents.ts` (no expansion on client)
+- Pattern: Route calls expandOccurrences for each cached VEVENT; ical.js handles RRULE parsing, EXDATE exclusion, VTIMEZONE DST adjustment
+
+**Encrypted Credentials:**
+- Purpose: Store Fastmail app passwords at rest without exposing plaintext
+- Examples: `apps/api/src/db/schema.ts:memberCredentials.encryptedPassword`, `apps/api/src/broker/crypto.ts:decryptPassword`
+- Pattern: AES-256-GCM with per-message nonce; stored as JSON { iv, authTag, ciphertext }; decrypted only immediately before tsdav client creation (T-03-04)
+
+## Entry Points
+
+**Browser → PWA:**
+- Location: `apps/pwa/src/main.tsx` (Vite SPA entry), `apps/pwa/src/App.tsx` (root component = CalendarShell)
+- Triggers: User navigates to / (domain root) or clicks Home
+- Responsibilities: Hydrate React app, mount CalendarShell, wire TanStack Query + Zustand
+
+**PWA → API:**
+- Location: `apps/pwa/src/api/client.ts` (fetch functions)
+- Triggers: CalendarShell useQuery hooks on mount and navigation
+- Responsibilities: Fetch events, me profile, sync status; handle OIDC redirects via maybeRedirectToLogin
+
+**Unauthenticated User → OIDC:**
+- Location: `apps/api/src/auth/middleware.ts` (oidcAuthMiddleware)
+- Triggers: Unauthenticated fetch to /api/* endpoint
+- Responsibilities: 302-redirect to Authelia /authorize; await callback at /callback; set session JWT cookie
+
+**OIDC Callback → API Login:**
+- Location: `apps/api/src/index.ts:app.get('/callback')` and `apps/api/src/auth/middleware.ts:processOAuthCallback`
+- Triggers: Authelia POST to /callback after authorization-code exchange
+- Responsibilities: Exchange code for token, validate nonce, set JWT cookie with refresh token, redirect to /api/login
+
+**API Login → SPA Boot:**
+- Location: `apps/api/src/index.ts:app.get('/api/login')`
+- Triggers: Top-level navigation after callback redirects here (or direct /api/login hit by PWA)
+- Responsibilities: Verify session cookie valid, 302-redirect to / so SPA boots authenticated
+
+**Background Poller:**
+- Location: `apps/api/src/broker/poller.ts:startBrokerPoller`, called from `apps/api/src/index.ts` in isMainModule() guard
+- Triggers: 5-min node-cron schedule starting at API boot
+- Responsibilities: Load all credentials, PROPFIND calendars, compare ctag, call syncCalendar if changed
+
+**Outbox Worker:**
+- Location: `apps/api/src/broker/outboxWorker.ts:startOutboxWorker`, called from `apps/api/src/index.ts` in isMainModule() guard
+- Triggers: 15-sec node-cron schedule starting at API boot
+- Responsibilities: Poll outbox WHERE status='pending', drain to Fastmail via write.ts, update status, trigger refetch
+
+## Architectural Constraints
+
+- **Threading:** Single-threaded event loop (Node.js). Broker poller and outbox worker run in the same process; scheduled tasks do not block request handling.
+- **Global state:** None in routes (all state passed via c context). Broker modules keep DB client as singleton. tsdav clients created per-credential per-poll (not cached).
+- **Circular imports:** None detected. Routes import from routes only; broker imports from db + auth; auth imports from db; no cycles.
+- **Request handling:** Synchronous route completion (routes do not wait for broker background tasks). Writes are optimistic-accept (202); client polls for confirmation.
+- **Session cookies:** Signed JWT stored in httpOnly cookie; refresh token included in JWT payload; @hono/oidc-auth handles rotation every 15 min by default.
+- **Shared Fastmail account:** Both members' credentials fetch the same calendar collections. Ownership tracked per-user via (userId, url) composite key to avoid cross-member cache contamination (BUG B fix).
+- **Database transactions:** Explicit tx() used for edit-as-move (D-04) — delete + create pair atomic. All other operations single-statement (upserts via onDuplicateKeyUpdate).
+
+## Anti-Patterns
+
+### Direct Fastmail calls from routes
+
+**What happens:** Routes call tsdav or make fetch requests directly to Fastmail CalDAV endpoints
+**Why it's wrong:** Routes would block on network I/O; Fastmail errors would fail the request immediately instead of retrying via outbox; credential decryption happens on every request instead of once per poller cycle; no centralized write ordering (concurrent POSTs can collide)
+**Do this instead:** Routes enqueue outbox rows (202) and let broker handle Fastmail I/O. See `apps/api/src/routes/events.ts:eventsRouter.post('/create')` and `apps/api/src/routes/events.ts:eventsRouter.delete('/:uid')` — both INSERT outbox, never call tsdav.
+
+### Storing displayName as identity key
+
+**What happens:** User row lookup is by email or displayName instead of OIDC issuer+subject
+**Why it's wrong:** Email changes (user migrates providers); displayName is user-editable and can collide (two Lucases). If Authelia email claim changes mid-login, the user gets a duplicate row.
+**Do this instead:** Key by (oidc_iss, oidc_sub) composite, never email. See `apps/api/src/auth/user.ts:upsertUser` — identity lookup is always by (oidcIss, oidcSub), then displayName is updated as a display hint on re-upsert.
+
+### Caching tsdav clients across polls
+
+**What happens:** Broker reuses the same tsdav client instance for multiple credential sessions
+**Why it's wrong:** DAVClient maintains HTTP connection state; reusing across credential changes can cross-contaminate requests or leak auth headers.
+**Do this instead:** Create a fresh client per credential per poll. See `apps/api/src/broker/poller.ts:runPoll` — each credential iteration calls `createFastmailClient()` fresh.
+
+### Windowed event query without pre-filter for recurring masters
+
+**What happens:** SQL query only selects non-recurring events in the date window; recurring masters are not included
+**Why it's wrong:** A weekly meeting created 3 years ago has dtstartUtc < window start, so it's filtered out. But it has RRULE so it has occurrences in the window (RESEARCH.md Pitfall 5).
+**Do this instead:** OR-combine three sub-predicates: (1) non-recurring timed in window, (2) non-recurring all-day in window, (3) recurring masters with dtstartUtc < windowEnd. See `apps/api/src/routes/events.ts` lines 173–200 for the full predicate.
+
+### Storing all-day events as midnight-UTC datetime
+
+**What happens:** All-day event is stored as '2026-06-01T00:00:00Z' (datetime) instead of '2026-06-01' (date)
+**Why it's wrong:** When the viewer is in a different timezone (e.g., UTC-04:00), the date column renders as 2026-05-31 (one day off). Timezone conversion applies to DATETIME but not DATE.
+**Do this instead:** Store all-day events in the DATE column only; timed events in TIMESTAMP UTC. See `apps/api/src/db/schema.ts` (dtstartUtc vs dtstartDate) and `apps/api/src/broker/sync.ts` lines 100–112 for the schema contract enforcement.
+
+### Relying on 200 response to mean write success
+
+**What happens:** Route marks an event as written and notifies the client success before verifying the outbox row completed
+**Why it's wrong:** Client UI state gets out of sync with server; if the outbox worker later fails, the client never knows.
+**Do this instead:** Return 202 Accepted immediately, then client polls `/api/events/sync-status?uid=` to track the outbox status. See `apps/api/src/routes/events.ts:eventsRouter.post('/create')` returns 202, and `apps/pwa/src/components/SyncStateToast.tsx` polls until done/failed/dead.
+
+---
+
+*Architecture analysis: 2026-06-09*

.planning/codebase/CONCERNS.md

@@ -0,0 +1,258 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-06-09
+
+## Tech Debt
+
+**Drizzle-kit push unsafe on MariaDB 11:**
+- Issue: `drizzle-kit push` emits false destructive DDL on MariaDB 11 (mysql dialect) — misreads table metadata and schedules column truncation in the migration diff. This destroys production data if applied blindly.
+- Files: `apps/api/src/db/schema.ts`, `apps/api/drizzle.config.ts`, `.planning/STATE.md` (D-Task5-DDL)
+- Impact: Any schema change requires manual validation. Automated push pipelines are unsafe.
+- Current mitigation: All additive DDL hand-applied. Database migrations live in `apps/api/src/db/migrations/` (SQL files). Documented in STATE.md.
+- Fix approach: Adopt `drizzle-kit generate+migrate` workflow for all future schema changes — generate the diff, manually review the SQL, then apply via migration file. Never use `push` on MariaDB without field-by-field validation. If multi-replica deployment is needed, consider PostgreSQL migration at that point.
+
+**Dev-auth bypass lacks production guard redundancy:**
+- Issue: The `DEV_AUTH_BYPASS` environment variable is guarded by a `NODE_ENV !== 'production'` check in `index.ts` (line 19), but relies on correct deployment configuration. If `NODE_ENV` is accidentally omitted from the production Docker Compose, the bypass could activate.
+- Files: `apps/api/src/index.ts` (lines 19–26), `apps/api/src/auth/devBypass.ts`
+- Impact: Unauthenticated access to the API in production if misconfigured.
+- Current mitigation: The `docker-compose.yml` should explicitly set `NODE_ENV=production`; `.env.example` has `DEV_AUTH_BYPASS` commented out. Documented in `docs/deployment.md` (line 266–268).
+- Fix approach: Add a startup assertion that logs an error and exits if `NODE_ENV !== 'production'` and `DEV_AUTH_BYPASS=true` are both detected. Consider a secondary check in the oidcAuthMiddleware instantiation.
+
+**Event datetime serialization was timezone-naive (FIXED in Phase 3):**
+- Issue: The PWA's `EventForm` previously sent naive local wall-clock strings (no UTC offset) to the API; the outbox worker's `new Date(string)` parsed them in the container's UTC timezone, resulting in events written 4 hours early/late. Fixed in Phase 3 quick 260607-l6l.
+- Files: `apps/pwa/src/lib/eventDateTime.ts` (new), `apps/pwa/src/components/EventForm.tsx` (updated)
+- Impact: FIXED. Regression test added (`apps/pwa/src/lib/eventDateTime.test.ts`).
+- Fix status: Closed via commit 2870413 (2026-06-07). Serialization now uses `localWallClockToUtcIso()` to convert to UTC `Z` instant in the browser before sending to the API.
+
+**Calendar row deduplication cross-user bug (FIXED in Phase 3):**
+- Issue: The poller and sync used `url`-only predicates to lookup calendar rows, but the two household members share one Fastmail account — the same collection URL exists for both. This caused events to be cached under the wrong member's calendar and duplicate rows accumulated on every poll. Fixed in Phase 3 via commit 2870413 and migration `0001_calendars_user_url_unique.sql`.
+- Files: `apps/api/src/broker/poller.ts` (line 52–56), `apps/api/src/broker/sync.ts` (line 62–66), `apps/api/src/db/schema.ts` (line 84), `apps/api/src/db/migrations/0001_calendars_user_url_unique.sql`
+- Impact: FIXED. Unique constraint `uniq_calendar_user_url` enforces (userId, url) identity; all predicates scoped correctly.
+- Fix status: Closed. Migration applied to live DB; regression tests added to `poller.test.ts` and `sync.test.ts`.
+
+---
+
+## Known Bugs
+
+**GET /api/events missing userId/isShared filter (IDENTIFIED, RESOLVED via 260607-l6l):**
+- Symptoms: GET /api/events returned events from all users (including stale spike data), not just owned + shared calendars.
+- Files: `apps/api/src/routes/events.ts` (line 127–129 now filters correctly via resolveUserId)
+- Trigger: Any `/api/events` call without the ownership/isShared predicate in the JOIN.
+- Status: FIXED in commit 2870413. The route now filters: `WHERE currentUserId = userId OR isShared=1`.
+
+**Stale spike user + calendar data in production DB:**
+- Symptoms: User id=1 ("Dev User", obsolete spike identity `oidc_iss='spike://cal-08'`) remains in the DB with 508 cached events under the now-deduplicated calendar row id=1. This is stale data, not a code bug.
+- Files: Live MariaDB (data only, not source code)
+- Impact: Low — new events written by the real users go to the correct rows (id=2, id=3 calendars). The spike data is not served to the app because the route filters by currentUserId. Safe to clean via a manual DB DELETE, but non-blocking.
+- Fix approach: Post-deployment cleanup task: `DELETE FROM users WHERE oidc_iss='spike://cal-08'; DELETE FROM calendar_events WHERE calendar_id=1;` if confident no real events are under id=1. Safer: check `calendars.url` to confirm id=1 is the spike duplicate before deletion.
+
+---
+
+## Security Considerations
+
+**Fastmail app password exposure risk:**
+- Risk: The API loads and decrypts Fastmail app passwords from `member_credentials.encrypted_password`. If the encryption key is leaked or the decryption is implemented incorrectly, all calendar access is compromised.
+- Files: `apps/api/src/broker/crypto.ts`, `apps/api/src/broker/poller.ts` (line 41), `deployment.md` (Step 2 — key generation)
+- Current mitigation: AES-256-GCM encryption, key stored in `.env` (gitignored). Decrypted password never logged (T-03-04). Decryption happens only in `poller.ts` and `outboxWorker.ts`, not in HTTP routes.
+- Recommendations: (1) Ensure `.env` is marked .gitignore in CI/CD (already done). (2) Rotate encryption key monthly + re-encrypt all passwords — design a rotation mechanism before multi-replica deployment. (3) Monitor access logs for repeated failed calendar syncs (sign of credential tampering). (4) Consider a secrets manager (e.g., Docker Compose secrets) for the encryption key in production.
+
+**OIDC claim extraction fragility (Authelia defaults):**
+- Risk: Authelia v4.39+ omits `name`, `email`, `preferred_username` from the ID token by default — requires a `claims_policy` config. The app's `deriveDisplayName()` (auth/user.ts) falls back through `name` → `preferred_username` → `email` → `sub`, but if Authelia is not configured with claims, all users appear as "Member" in the legend (observed in Phase 2). This is a configuration issue, not a code bug, but fragile.
+- Files: `apps/api/src/auth/user.ts` (lines 8–19), `docs/deployment.md` (Authelia client config, line 91–92 does NOT show claims_policy)
+- Current mitigation: The identity is keyed on `iss+sub` (never email), so display name is cosmetic. The legend displays correctly after identity is established.
+- Recommendations: (1) Add a `claims_policy` block to the example Authelia configuration in `docs/deployment.md` (or a separate `authelia-familysync-claims.yml` example). (2) Document that without claims, all users show as "Member" and that's non-blocking for v1 (they still get distinct colors via their `sub`). (3) Test Authelia claim extraction before Phase 5 push notifications are built (notification titles will need displayName).
+
+**SSE heartbeat endpoint carries no secrets but could be abuse vector:**
+- Risk: `/api/sse/heartbeat` is authenticated (behind oidcAuthMiddleware) but emits only timestamps — no sensitive data. However, a malicious actor with a valid session could hold open many concurrent heartbeat streams, consuming server resources (DoS).
+- Files: `apps/api/src/routes/sse.ts`
+- Current mitigation: The endpoint is single-purpose (testing transport viability); Phase 4 will add real list-change SSE with per-user subscriptions. Resource limits are absent.
+- Recommendations: (1) For Phase 4, implement per-user connection limits (max 3 concurrent SSE streams per user). (2) Add heartbeat-timeout tracking: if a client doesn't read for 120s, close the stream. (3) Monitor stream creation rate in logs (spike = potential abuse).
+
+---
+
+## Performance Bottlenecks
+
+**Calendar windowed query without pagination (acceptable for v1, scales to ~5000 events):**
+- Problem: GET `/api/events?start=X&end=Y` returns all occurrences in the window with no pagination. The query is efficient (indexes on `dtstart_utc`, `dtstart_date`, `hasRrule`), but response size grows with window span and recurrence expansion.
+- Files: `apps/api/src/routes/events.ts` (line 126–170)
+- Cause: No pagination implemented. For a 2-person household with ~500 events/person and heavy recurring series, a month-view response is ~2–5 KB (acceptable).
+- Improvement path: (1) Monitor response time in Phase 4 (live sync will add per-user subscriptions). (2) If response >100 KB, add cursor-based pagination to the events endpoint. (3) Consider server-side caching of expansion results per (userId, window) for frequently-accessed ranges (e.g., current month).
+
+**Broker poller is full-scan every 5 minutes (acceptable for <10 members, mitigated by ctag):**
+- Problem: `poller.ts` loops all member_credentials and calls `fetchCalendars()` on each, then compares ctag. For a 2-person household with 2 Fastmail accounts (shared calendars + personal), this is ~2–4 PROPFIND/REPORT calls per cycle. Scales poorly to >10 members.
+- Files: `apps/api/src/broker/poller.ts` (line 35–77)
+- Cause: No selective polling per calendar; all calendars checked every 5 minutes.
+- Improvement path: (1) For v1 (2–4 members), current approach is fine — ~10 req/min to Fastmail. (2) For Phase 1.x (N-member expansion, per STATE.md note): track last-known ctag per calendar and skip polling if unchanged; implement WebDAV-Sync (sync-token) for delta-only fetches (RFC 6578). (3) Monitor Fastmail API rate-limit headers (`X-RateLimit-*`) in logs.
+
+**Outbox worker retries backoff reaches 30 min max (acceptable, prevents spam):**
+- Problem: The outbox retry window for a failed write is capped at ~30 min (BACKOFF_SECONDS: 15+60+300+600+1800). A transient Fastmail outage lasting >30 min will abandon the write as "dead" without user notification.
+- Files: `apps/api/src/broker/outboxWorker.ts` (line 46, MAX_ATTEMPTS=5)
+- Cause: Exponential backoff with a fixed cap to prevent infinite queuing.
+- Improvement path: (1) For v1, 30 min is acceptable (household is US-based, Fastmail SLA is high). (2) For Phase 4, add a `dead-letter-queue` processor that logs unsent writes and optionally re-queues them manually. (3) Consider extending MAX_ATTEMPTS to 7–8 for a longer retry window (2–3 hours) if outages are observed.
+
+---
+
+## Fragile Areas
+
+**CalDAV event write-back lacks conflict resolution (D-08 mitigation exists, risk remains):**
+- Files: `apps/api/src/broker/write.ts`, `apps/api/src/broker/outboxWorker.ts` (line 180–190), `docs/deployment.md` (Pitfall 14)
+- Why fragile: When a user edits an event in the app and another user edits it concurrently in the native Fastmail app, the outbox worker receives a 412 (If-Match conflict). The current behavior is to mark the outbox row as "failed" and trigger a re-sync. This is correct but provides no UI feedback to the user — they don't know their edit was rejected. If this happens repeatedly, the user will see the calendar diverge unpredictably.
+- Safe modification: (1) Add a `syncStatus` subscription in the PWA (already designed in Phase 3 Plan 03-06). The UI shows "sync conflict — your edit was rejected, event reloaded from server" in a toast. (2) If the outbox row is marked "failed", the next re-sync will pull the current server state. (3) For Phase 4+, consider implementing a "merge/overwrite" UI where the user can choose to force their edit if they're confident it's the right state. For v1, reject-and-reload is acceptable.
+
+**Recurring event expansion via rrule + EXDATE is CPU-sensitive (mitigated by window cap):**
+- Files: `apps/api/src/broker/expand.ts`, `apps/api/src/routes/events.ts` (line 45, MAX_WINDOW_DAYS=90)
+- Why fragile: Expanding a 5-year-old weekly recurring event to a 90-day window generates ~50 occurrences. Expanding to a 1-year window generates ~250. If a user requests a 365-day window (not capped), the expansion becomes CPU-bound.
+- Safe modification: The MAX_WINDOW_DAYS=90 guard is in place (T-02b-02, DoS protection). No change needed. If Phase 6 adds a "year view", re-evaluate the expansion window and consider caching expanded results per (event.uid, window).
+
+**OIDC session middleware dependency on @hono/oidc-auth (tied to Authelia version):**
+- Files: `apps/api/src/auth/middleware.ts`, package.json (@hono/oidc-auth: 1.8.3)
+- Why fragile: @hono/oidc-auth v1.8.3 assumes a specific OIDC metadata contract. If Authelia makes a breaking change in its .well-known/openid-configuration response, the middleware could fail silently (e.g., missing `token_endpoint`, `userinfo_endpoint`).
+- Safe modification: (1) Add a startup health check that fetches Authelia's OIDC metadata and logs an error if critical fields are missing. (2) Monitor Authelia release notes for OIDC spec changes. (3) Pin @hono/oidc-auth to 1.8.x in package.json (already done). (4) Test Authelia upgrades in a staging environment before deploying to production.
+
+---
+
+## Scaling Limits
+
+**Single-process deployment concurrency guard in outbox worker:**
+- Current capacity: The outbox worker's drain-concurrency guard (CR-05, line 87–100) uses a module-level boolean flag. This is safe for a single-process Docker container but breaks if scaled to multiple API replicas.
+- Limit: If the API is deployed as N replicas behind a load balancer, the drain cycles can overlap and double-dispatch the same outbox row to Fastmail, causing duplicate writes.
+- Scaling path: (1) For v1 (single Unraid container), no change needed. (2) For multi-replica or Kubernetes: replace the module-level guard with a durable DB row claim (`UPDATE calendar_outbox SET status='processing' WHERE id=? AND status='pending'`). The first replica to claim wins; others skip that row. (3) Add a "processing" timeout (5 min) to prevent dead-replica claims from blocking the queue indefinitely.
+
+**In-memory SSE fan-out via EventEmitter (Phase 4 dependency, acceptable for single process):**
+- Current capacity: Phase 4 will add live list-change SSE that broadcasts to connected clients. If implemented as a simple Node EventEmitter, each replica process maintains its own in-memory subscriptions. A member on replica A updates a list; the SSE fires on replica A but replica B's connections don't see it (if the member's browser is routed to replica B after the update).
+- Limit: Limited to single-process deployment or requires Redis Pub/Sub for fan-out across replicas.
+- Scaling path: (1) For v1 (single container), EventEmitter is fine. (2) For Phase 4+, if multi-replica is needed: design the SSE layer to use Redis Pub/Sub for cross-process broadcasts. Add ioredis to package.json (it's already recommended in CLAUDE.md). See PITFALLS.md §Pitfall 15 for sequence-number replay strategy.
+
+**Redis not yet installed (Phase 4 dependency, scheduled for list sync):**
+- Current status: The app has no Redis dependency. Phase 4 will require Redis for pub/sub (list-change broadcasts across processes/replicas).
+- Impact: v1 is single-process; live sync works fine without Redis. Phase 4+ requires it.
+- Remediation: Add Redis to docker-compose.yml in Phase 4. ioredis client already in package.json recommendations (CLAUDE.md, Table 1). Configure connection pooling (ioredis default: 8 connections).
+
+---
+
+## Dependencies at Risk
+
+**@hono/oidc-auth peer dependency on Authelia RFC compliance:**
+- Risk: @hono/oidc-auth relies on Authelia conforming to OIDC RFC 6749/6234. If Authelia introduces a non-standard endpoint or claim format, the middleware may fail.
+- Impact: OIDC login would break; users cannot access the app.
+- Migration plan: If Authelia breaks OIDC compatibility, replace @hono/oidc-auth with `openid-client` (a lower-level OIDC library). Estimated effort: 2–3 days to wire custom middleware. openid-client is already in CLAUDE.md as an escape hatch (Table 1, row 3).
+
+**tsdav maintained by single contributor (NateLinDev/tsdav):**
+- Risk: The CalDAV client library `tsdav@2.2.2` has low maintenance activity. If a Fastmail CalDAV protocol change occurs or a critical bug is found, the library may not be updated promptly.
+- Impact: Calendar sync could break (PROPFIND, REPORT, PUT all depend on tsdav).
+- Migration plan: (1) For v1, tsdav is stable and proven in this codebase. (2) If maintenance becomes a blocker, the next option is to implement CalDAV PROPFIND/REPORT directly via fetch + xml2js (Pitfall 1 explicitly warns against this, but it's doable). Estimated effort: 1 week to implement a minimal CalDAV client. (3) Monitor tsdav GitHub issues and PRs.
+
+**ical.js reference implementation (kewisch/ical.js):**
+- Risk: ical.js is the Mozilla-maintained RRULE/iCalendar reference implementation, but Mozilla does not actively develop calendar software. If a new RFC 5545 edge case is discovered (e.g., an RRULE rule that breaks ical.js), it may not be fixed quickly.
+- Impact: Recurring events could expand incorrectly (rare, but affects display).
+- Migration plan: (1) For v1, ical.js is the most reliable available. (2) If a bug is found, open an issue on GitHub; Mozilla is responsive to reference-implementation bugs. (3) Fallback: use `rrule` library only (lighter weight) if ical.js is abandoned, but rrule is less comprehensive for EXDATE/RECURRENCE-ID handling.
+
+---
+
+## Missing Critical Features
+
+**Single-occurrence recurring event override (deferred to v1.x):**
+- Problem: A user cannot edit or delete a single occurrence of a recurring event (e.g., "skip next Tuesday's meeting"). The edit-as-move write path (D-04) supports full-series edits only.
+- Blocks: Users frustrated when they want to reschedule one instance.
+- Deferred reason: Requires RECURRENCE-ID write-back (RFC 5545) and complex VCALENDAR patching. Estimated effort: 2–3 days of implementation + testing. For v1, edit-all is acceptable for a 2-person household.
+- Resolution approach: Phase 6 or v1.x — implement a "Edit this and all following" option that re-dates the RRULE UNTIL and creates a new series from the edit date onward.
+
+**Notification subscription health-check (CRITICAL for Phase 5, deferred to Phase 5 implementation):**
+- Problem: iOS silently revokes Web Push subscriptions after 3 silent push events (Pitfall 9). The app must detect this and re-subscribe automatically.
+- Blocks: Phase 5 (push notifications) cannot be considered production-ready without this.
+- Missing implementation: No subscription health-check exists in the PWA yet. The service worker needs to call `pushManager.getSubscription()` on every page open and compare the endpoint to the server's stored endpoint; if they differ, re-subscribe.
+- Resolution approach: Phase 5 must include health-check implementation as a prerequisite, not a polish task.
+
+---
+
+## Test Coverage Gaps
+
+**Events API route (GET /api/events, POST /create, PATCH /edit, DELETE /delete) has integration-level testing but lacks edge cases:**
+- What's not tested: (1) Window boundary conditions (start=end, off-by-one day shifts). (2) Recurring all-day events with complex EXDATE. (3) Concurrent edit conflict (412 handling). (4) Ownership assertions with mixed owned + shared calendars.
+- Files: `apps/api/tests/routes/events.test.ts` (126 lines, covers happy paths + 400/403 error cases)
+- Risk: Edge cases in expansion or ownership filtering could silently pass tests and break in production.
+- Priority: MEDIUM — add 10–15 test cases before Phase 4 (live sync will depend on ownership filtering being bulletproof).
+
+**Outbox worker state machine (retry backoff, edit-as-move ordering, dead-letter) has unit tests but lacks end-to-end CalDAV integration:**
+- What's not tested: (1) Outbox row with a real Fastmail endpoint (mocked in tests). (2) 412 conflict response from Fastmail + re-sync flow. (3) Concurrent outbox rows from the same list (edit+delete pair ordering under network failures). (4) Recovery after a multi-hour Fastmail outage.
+- Files: `apps/api/tests/broker/outboxWorker.test.ts` (state-machine tests only)
+- Risk: Silent data loss if outbox row ordering is wrong under failures; list sync will depend on correct write ordering.
+- Priority: HIGH — add integration tests before Phase 4. Mock Fastmail CalDAV responses (conflict, transient, success) and verify state transitions.
+
+**PWA EventForm timezone serialization (fixed in Phase 3, regression test exists but limited scope):**
+- What's not tested: (1) Daylight Saving Time transitions (create event on March 12, spring-forward boundary). (2) Cross-timezone consistency (create event in Toronto, verify UTC serialization, reload in UTC, confirm display is Toronto wall-clock). (3) All-day event edge cases (midnight boundary serialization).
+- Files: `apps/pwa/src/lib/eventDateTime.test.ts` (5 cases: timed → UTC, all-day → DATE, round-trip)
+- Risk: Similar timezone bug could reappear if eventDateTime.ts is refactored without comprehensive DST testing.
+- Priority: MEDIUM — add 5–10 DST/all-day edge cases to the test suite before Phase 6 (UX polish will touch date/time handling).
+
+**PWA service worker and offline behavior untested:**
+- What's not tested: (1) Service worker install, activation, and update lifecycle. (2) Offline calendar view (reads from cache). (3) Offline list mutation (queues for sync). (4) Cache expiration strategy.
+- Files: Service worker is auto-generated by vite-plugin-pwa; offline behavior is unimplemented in Phase 1–3.
+- Risk: Phase 4's offline queue and Phase 5's background sync depend on correct SW lifecycle. Silent failures in SW updates could leave the wife on a stale version.
+- Priority: MEDIUM — Phase 4 should include SW unit tests (simulate offline, verify cache reads, verify mutation queue behavior).
+
+**Mobile-specific behavior (iOS push, PWA standalone mode, permissions) untested by vitest:**
+- What's not tested: (1) iOS 16.4+ push subscription (requires real device). (2) Standalone PWA launch (requires Add-to-Home-Screen). (3) Permission request flow (requires user gesture). (4) Camera/location permissions (out of scope for v1, but worth listing).
+- Files: Not applicable (device-only testing).
+- Risk: High impact if broken (wife can't install, can't receive notifications). Mitigated by human UAT (Phase 3 Gate 2 item 4).
+- Priority: MEDIUM — document a manual iOS test checklist in Phase 5 (must run before ship). Playwright can test browser-side behavior; device-side requires manual verification.
+
+---
+
+## Architectural Constraints & Anti-Patterns
+
+**Single-process assumption in outbox drain guard (CR-05, documented but constrains scaling):**
+- Constraint: The module-level boolean flag `let isProcessing = false` in outboxWorker.ts assumes a single Node.js process. This is correct for the Unraid single-container deployment but breaks if scaled horizontally.
+- Consequence: Multi-replica deployments MUST implement a durable DB claim (UPDATE … WHERE status='processing') before the API is horizontally scaled.
+- Workaround: Documented in code comment (line 91–100). Clear and easy to address when scaling is needed.
+
+**No pagination on calendar events endpoint (acceptable for v1, design assumption):**
+- Constraint: GET /api/events returns all occurrences in the window with no pagination. Designed for a 90-day max window and <1000 occurrences per window (acceptable for 2-person household).
+- Consequence: Very large windows or households with hundreds of recurring events could generate multi-MB responses.
+- Workaround: MAX_WINDOW_DAYS=90 guard prevents DoS. For Phase 4+, if response size exceeds 500 KB, add cursor pagination.
+
+**Dev-auth bypass is development-only but deployment-critical (configuration risk):**
+- Constraint: The bypass is designed for local development (NODE_ENV !== 'production' + DEV_AUTH_BYPASS=true). If the bypass is accidentally enabled in production, the OIDC guard is completely bypassed.
+- Consequence: Unauthenticated API access if misconfigured.
+- Workaround: (1) .env.example has DEV_AUTH_BYPASS commented out. (2) docker-compose.yml MUST NOT include DEV_AUTH_BYPASS in env. (3) Documented in docs/deployment.md. Recommended: add a startup assertion to double-check.
+
+---
+
+## Infrastructure & Deployment Concerns
+
+**Drizzle migrations require manual SQL review (no auto-apply in Docker):**
+- Issue: The app does not auto-migrate on startup. The `drizzle-kit push` command is unsafe on MariaDB. Manual `drizzle-kit migrate` must be run once per DB version before the app starts.
+- Files: `apps/api/src/db/migrations/`, `docs/deployment.md` (Step 3: `drizzle-kit push` is the documented command, but should be `migrate` or `generate+migrate` for production safety)
+- Impact: If the operator forgets to migrate after pulling a new schema, the app will crash on startup (missing tables). The error message should be clear.
+- Fix approach: (1) Update `docs/deployment.md` Step 3 to use `migrate` instead of `push`. (2) Add a startup health check in `src/db/client.ts` that verifies all expected tables exist; fail with a clear message if any are missing. (3) Document the migration process in a DEPLOYMENT.md subsection.
+
+**Pangolin SSE idle timeout dependency (D-14, issue #1034) verified but residual risk remains:**
+- Issue: SSE streams can be cut by proxy idle-timeout. The Phase 4 entry gate smoke test PASSED (6 min without cut), but only tested on the test domain `familysync-dev.bergerhouse.net`.
+- Files: `docs/deployment.md` (line 165–170), `.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md`
+- Impact: If the production Pangolin idle-timeout is lower than the test rig, SSE will be cut during live list sync. Users will experience brief disconnects (mitigated by reconnect logic in Phase 4).
+- Current mitigation: Documented in deployment.md. The operator must set Pangolin's idle-timeout to ≥120s (recommended 300s) when deploying to production.
+- Residual risk: If Pangolin is misconfigured and SSE is cut, the fallback (D-12 polling every 5s) will maintain sync but with degraded latency (5s vs real-time). Phase 4 must implement the polling fallback.
+
+---
+
+## Known Limitations (Documented as Design Decisions)
+
+**Personal calendar sharing requires manual Fastmail setup (D-16 CAL-08 spike result):**
+- Limitation: The two household members' personal Fastmail calendars are accessed via per-member app passwords (not a shared broker token). This requires each member to generate an app password and register it in the app.
+- Impact: Acceptable. The unified view works correctly and scales to shared + personal calendars.
+- Status: GO decision (CAL-08-DECISION.md, Phase 1).
+
+**Recurring event edit supports edit-all only (single-occurrence override deferred to v1.x):**
+- Limitation: The write path does not support RECURRENCE-ID overrides. Editing a recurring event changes all future occurrences.
+- Impact: Users cannot reschedule a single meeting. For a 2-person household, edit-all is acceptable.
+- Status: Documented in STATE.md (deferred items), Phase 6 planning.
+
+**EU DMA compliance risk for EU-based households (Pitfall 11):**
+- Limitation: iOS 17.4+ in EU countries removes standalone PWA mode and push support due to Digital Markets Act. FamilySync's push notifications would not work for an EU user.
+- Impact: If the household moves to EU or uses EU Apple IDs, notifications are unavailable.
+- Status: This is a Canadian household (me@lucasberger.ca, .ca domain, Unraid self-hosted). Documented as not applicable but worth flagging for future.
+- Fix approach: Monitor for EU regulatory changes; if the household moves, switch to email or in-app notification fallback for v1.x.
+
+---
+
+*Concerns audit: 2026-06-09*

.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,330 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-06-09
+
+## Naming Patterns
+
+**Files:**
+- Backend route handlers: `camelCase.ts` — `events.ts`, `me.ts`, `health.ts` (`apps/api/src/routes/`)
+- Broker modules: `camelCase.ts` — `poller.ts`, `sync.ts`, `write.ts`, `expand.ts` (`apps/api/src/broker/`)
+- Frontend components: `PascalCase.tsx` — `EventForm.tsx`, `CalendarShell.tsx`, `InstallPrompt.tsx` (`apps/pwa/src/components/`)
+- Frontend utilities: `camelCase.ts` — `colorUtils.ts`, `hydrateEvents.ts`, `eventDateTime.ts`, `loginRedirect.ts` (`apps/pwa/src/lib/`)
+- Tests: `{filename}.test.ts` or `.test.tsx` co-located with source
+
+**Functions:**
+- Private helpers (not exported): `camelCase` — `claimStr()`, `getBreakpointGroup()`, `viewStorageKey()`, `resolveUserId()`
+- Exported async handlers: `camelCase` — `fetchMe()`, `createEvent()`, `expandOccurrences()`, `upsertUser()`
+- React hooks (Zustand): `useCalendarStore`, `useXxxx` pattern — follows React convention
+- Type guard / coercion functions: `camelCase` — `deriveDisplayName()`, `claimStr()`
+
+**Variables:**
+- Constants (module-level): `SCREAMING_SNAKE_CASE` — `MAX_WINDOW_DAYS`, `SHARED_FAMILY_COLOR`, `COLOR_PALETTE`, `FIXTURES`
+- Local state: `camelCase` — `currentUserId`, `targetCalendarUrl`, `windowStartDate`, `eventRow`
+- Zustand store methods: `camelCase` setters — `setSelectedView()`, `setEventForm()`, `setLastSyncedUid()`
+- Store state keys: `camelCase` — `selectedView`, `openEventId`, `eventFormOpen`, `deleteDialogUid`
+- Destructured auth claims: `camelCase` — `iss`, `sub`, `email`, `displayName`
+- Database column mappings: `snake_case` in schema → `camelCase` in TypeScript (Drizzle handles mapping)
+
+**Types/Interfaces:**
+- TypeScript interfaces: `PascalCase` — `MeUser`, `MeResponse`, `CalendarOccurrence`, `WritableCalendar`, `CalendarStore`, `SyncStatus`
+- Zod schemas: `camelCase` + `Schema` suffix — `eventsQuerySchema`, `eventFieldsSchema`, `syncStatusQuerySchema`
+- Union types (enums): `PascalCase` or quoted literals in types — `'create' | 'update' | 'delete'`, `'pending' | 'done' | 'failed' | 'dead'`
+- Database table names: `snake_case` — `calendar_events`, `calendar_outbox`, `member_credentials`
+- DB column names: `snake_case` — `dtstart_utc`, `dtstart_date`, `oidc_iss`, `oidc_sub`
+
+**Drizzle ORM tables:**
+- Table function: `mysqlTable('table_name', {...})`
+- Column names in schema def: use snake_case strings — `int('user_id')`, `varchar('oidc_iss', ...)`
+- TypeScript field names (destructured queries): auto-convert to camelCase via Drizzle's default mode
+- Primary keys: `id: int().primaryKey().autoincrement()` (all tables follow this)
+- Foreign keys: `references(() => targetTable.id, { onDelete: 'cascade' })` (explicit cascade behavior)
+- Indexes: named with `idx_` prefix — `idx_calendar_events_dtstart_utc`, `idx_outbox_user_status`
+- Unique constraints: named with `uniq_` prefix — `uniq_oidc_identity`, `uniq_calendar_uid`, `uniq_calendar_user_url`
+
+## Code Style
+
+**Formatting:**
+- No explicit ESLint or Prettier config files in the codebase (uses project defaults)
+- 2-space indentation (inferred from source code)
+- Single quotes for strings (`'string'`, not `"string"`)
+- Semicolons at end of statements
+- No trailing commas in function calls; trailing commas in object/array literals (modern style)
+
+**Linting:**
+- TypeScript: `strict: true` in both backend and frontend `tsconfig.json`
+- Module resolution: `NodeNext` (backend), `Bundler` (frontend)
+- No `any` types — use `Context` from Hono where typing is available
+
+**Example formatting (from `routes/events.ts` line 64):**
+```typescript
+async function resolveUserId(c: Context): Promise<number | null> {
+  const devUser = c.get('user') as { id: number } | undefined
+  if (devUser) return devUser.id
+
+  const auth = await getAuth(c)
+  if (!auth) return null
+
+  const iss = (auth.iss as string | undefined) ?? ''
+  const sub = auth.sub ?? ''
+  // ...
+}
+```
+
+## Import Organization
+
+**Order:**
+1. Node.js built-ins (`import { ... } from 'node:...'`)
+2. Third-party packages (`import { ... } from 'hono'`, `import { ... } from 'drizzle-orm'`)
+3. Local absolute imports (backend: none; frontend: none visible — no path aliases configured)
+4. Local relative imports (`import { ... } from '../dir/file.js'` or `../../...`)
+5. Side-effect imports (import without destructuring, placed last) — `import '../auth/devBypass.js'`
+
+**Path extensions:**
+- All imports use explicit `.js` extensions — `from './index.js'`, `from '../db/client.js'`
+- Applies to both backend and frontend (ESM module resolution)
+
+**Example (from `routes/events.ts` lines 24–38):**
+```typescript
+import { randomUUID } from 'node:crypto'        // Node.js built-in
+import { Hono } from 'hono'                      // Third-party
+import type { Context } from 'hono'
+import { zValidator } from '@hono/zod-validator' // Third-party (Hono ecosystem)
+import { z } from 'zod'
+import { and, or, eq, desc } from 'drizzle-orm'
+import { sql } from 'drizzle-orm'
+import { db } from '../db/client.js'              // Relative local import
+import { calendarEvents, calendars, ... } from '../db/schema.js'
+import { expandOccurrences } from '../broker/expand.js'
+import { getAuth } from '../auth/middleware.js'
+import { upsertUser, deriveDisplayName } from '../auth/user.js'
+import '../auth/devBypass.js'                     // Side-effect import (last)
+```
+
+## Error Handling
+
+**Patterns:**
+
+**Backend (Hono routes):**
+- Early return with typed `c.json(...)` on validation or auth failure — `return c.json({ error: 'message' }, statusCode)`
+- Try-catch blocks wrap DB/external I/O, catch logs error + returns 503 Service Unavailable
+- No unhandled rejections — every async operation has explicit error handling
+- Auth failures: return 401 Unauthorized; authorization failures: return 403 Forbidden; missing resource: return 404
+- Validation failures: return 400 Bad Request with error envelope
+
+**Example (from `routes/events.ts` lines 126–225):**
+```typescript
+eventsRouter.get('/', zValidator('query', eventsQuerySchema), async (c) => {
+  const currentUserId = await resolveUserId(c)
+  if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
+
+  const { start, end } = c.req.valid('query')
+
+  const spanDays = (windowEndDate.getTime() - windowStartDate.getTime()) / (1000 * 60 * 60 * 24)
+  if (spanDays > MAX_WINDOW_DAYS || spanDays <= 0) {
+    return c.json({ error: 'Date window must be between 1 and 90 days' }, 400)
+  }
+
+  try {
+    const rows = await db.select(...).from(...).where(...)
+    const allOccurrences = rows.flatMap((row) => expandOccurrences(...))
+    return c.json({ occurrences: allOccurrences })
+  } catch (err) {
+    console.error('[events] DB query or expansion failed:', err)
+    return c.json({ error: 'Service unavailable' }, 503)
+  }
+})
+```
+
+**Frontend (React + TanStack Query):**
+- Fetch client throws on non-ok response; caller handles redirect logic (`maybeRedirectToLogin()`)
+- API client checks `res.type === 'opaqueredirect'` and `res.status === 401` to detect auth failure (CORS-safe 302 handling)
+- Component state via Zustand; server state via React Query
+- No inline try-catch in components — defer to query error states
+
+**Example (from `api/client.ts` lines 28–53):**
+```typescript
+export async function fetchMe(): Promise<MeResponse> {
+  const res = await fetch('/api/me', {
+    credentials: 'include',
+    redirect: 'manual',
+  })
+
+  if (res.type === 'opaqueredirect' || res.status === 401) {
+    throw new Error('GET /api/me: authentication required')
+  }
+
+  if (!res.ok) {
+    throw new Error(`GET /api/me failed: ${res.status}`)
+  }
+
+  return res.json() as Promise<MeResponse>
+}
+```
+
+## Logging
+
+**Framework:** Console methods only (`console.log`, `console.error`, `console.warn`)
+
+**Patterns:**
+- Errors logged with context prefix in square brackets — `console.error('[events]', message)`, `console.error('[broker/sync]', message)`
+- Startup messages logged at info level — `console.log('FamilySync API running on ...')`
+- Dev-mode warnings prefixed with warning emoji-ish symbol — `console.warn('⚠ DEV_AUTH_BYPASS active ...')`
+- No structured logging (JSON); plain text OK for small household app
+- Errors include the full exception object for stack trace — `console.error('[events] DB query failed:', err)`
+
+**Example (from `index.ts` lines 23, 111):**
+```typescript
+if (devBypassActive) {
+  console.warn('⚠ DEV_AUTH_BYPASS active — OIDC guard DISABLED. Never use in production.')
+}
+// ...
+serve({ fetch: app.fetch, port: 3000 }, (info) => {
+  console.log(`FamilySync API running on http://localhost:${info.port}`)
+})
+```
+
+## Comments
+
+**When to Comment:**
+- Complex algorithms or non-obvious business logic — e.g., window date filtering in `routes/events.ts` (lines 142–151)
+- Security assertions or threat-model references — e.g., ownership checks (T-03-06), CSRF-token patterns
+- Architectural invariants — e.g., "broker boundary: this route reads ONLY from cache" (routes/events.ts:4)
+- Non-standard patterns — e.g., `isMainModule()` check to gate cron startup (index.ts:81–99)
+- Workarounds and why they exist — e.g., "WR-04: carrier/groupId for edit-as-move txn" (routes/events.ts:373)
+
+**JSDoc/TSDoc:**
+- Used for public exported functions, not for every function
+- Single-line for simple functions; multi-line with `@param` and `@returns` for complex signatures
+- Comments on types (interfaces) to document contract — e.g., `CalendarOccurrence` interface (api/client.ts:71–87)
+
+**Example (from `auth/user.ts` lines 25–32):**
+```typescript
+/**
+ * Accessible, visually-distinct palette for per-member color assignment.
+ * A new member is given the first entry not already in use (see upsertUser).
+ *
+ * Ordering matters: the shared-family calendar is reserved rose (#F25C7A, D-06),
+ * so the warm near-rose hues (coral, amber) are placed LAST. Early members get
+ * cool colors (blue, green, teal) that read clearly distinct from the shared
+ * lane — otherwise a member's coral was mistaken for the shared rose.
+ * Values are Claude's choice per D-06.
+ */
+export const COLOR_PALETTE: string[] = [...]
+```
+
+## Function Design
+
+**Size:** Prefer short, single-responsibility functions. Route handlers are the exception — they bundle validation, ownership check, and response assembly (pragmatism for Hono idiom).
+
+**Parameters:**
+- Use Hono's `Context` type rather than destructuring everything — `async (c: Context)`
+- Explicit parameters for helper functions; Hono context passed implicitly where possible
+- Zod validators return typed objects via `c.req.valid('json')` or `c.req.valid('query')`
+
+**Return Values:**
+- Async functions return typed values or throw — `Promise<T>` or `Promise<void>`
+- Error responses returned explicitly (not thrown) — callers handle 4xx/5xx in same try-catch
+- Database queries return typed Drizzle result objects; destructure as needed
+
+**Example (from `auth/user.ts` lines 79–142):**
+```typescript
+export async function upsertUser(
+  oidcIss: string,
+  oidcSub: string,
+  displayName?: string | null,
+) {
+  // 1. Look up by composite identity key...
+  const existing = await db.select().from(users).where(...).limit(1)
+  if (existing[0]) {
+    // Update displayName if changed
+    if (displayName != null && displayName !== existing[0].displayName) {
+      await db.update(users).set({ displayName }).where(...)
+      return { ...existing[0], displayName }
+    }
+    return existing[0]
+  }
+
+  // 2. Assign color from palette...
+  // 3. Insert new row...
+  // 4. Re-select and return
+}
+```
+
+## Module Design
+
+**Exports:**
+- Named exports for functions and types — `export const TABLE`, `export function handler()`, `export interface Type`
+- No default exports (exception: SPA app shell `App.tsx` uses default export)
+- Re-export from middleware modules for convenience — `auth/middleware.ts` re-exports `@hono/oidc-auth` functions
+
+**Barrel Files:**
+- No wildcard re-exports (`export * from ...`) — explicit named exports only
+- Top-level index files not used (each module imported directly)
+
+**Example (from `auth/middleware.ts` lines 24–26):**
+```typescript
+export { oidcAuthMiddleware, processOAuthCallback, getAuth } from '@hono/oidc-auth'
+```
+
+## Database Patterns
+
+**Drizzle conventions (critical):**
+- Schema definition: `mysqlTable('name', { id: int().primaryKey().autoincrement(), ... }, (t) => [...])`
+- Foreign keys: ALWAYS include `{ onDelete: 'cascade' }` to propagate deletes cleanly
+- Indexes: Explicit index names with `idx_` prefix on frequently filtered columns
+- Unique constraints: Explicit unique names with `uniq_` prefix on identity/natural keys
+- Never use `db:push` on populated MariaDB (false destructive diffs) — ALWAYS use `generate + migrate`
+
+**Query patterns:**
+- Use Drizzle's type-safe query builder: `db.select(...).from(table).where(...).limit(...)`
+- Raw SQL via `` sql`...` `` for complex predicates (e.g., multi-condition OR chains in events.ts:167–201)
+- Parameterized values via `sql` template tag prevent SQL injection
+- Joins: explicitly `innerJoin()` or `leftJoin()` with `.on(eq(...))` conditions
+
+**Example (from `db/schema.ts` lines 96–123):**
+```typescript
+export const calendarEvents = mysqlTable(
+  'calendar_events',
+  {
+    id: int().primaryKey().autoincrement(),
+    calendarId: int('calendar_id')
+      .notNull()
+      .references(() => calendars.id, { onDelete: 'cascade' }),
+    uid: varchar('uid', { length: 512 }).notNull(),
+    // ... more columns
+  },
+  (t) => [
+    index('idx_calendar_events_dtstart_utc').on(t.dtstartUtc),
+    index('idx_calendar_events_has_rrule').on(t.hasRrule),
+    unique('uniq_calendar_uid').on(t.calendarId, t.uid),
+  ],
+)
+```
+
+## Reactive State (Frontend)
+
+**TanStack Query (Server State):**
+- All calendar events, lists, user profile live in React Query
+- Queries keyed by API endpoint + windowing params — `['events', { start, end }]`
+- Mutations handle POST/PATCH/DELETE; invalidate cache on success
+- Use `useQuery` for reads, `useMutation` for writes; never mix server state into Zustand
+
+**Zustand (UI State):**
+- Owns only UI-shape state: `selectedView`, `openEventId`, `eventFormOpen`, `deleteDialogOpen`, etc.
+- Persists breakpoint-scoped `selectedView` to `localStorage`
+- Never store server data (user profile, events) — keep it in React Query
+- Setters are synchronous; no side effects (except localStorage in `setSelectedView`)
+
+**Example (from `store/calendarStore.ts` lines 1–25):**
+```typescript
+/**
+ * Zustand UI-state store for the calendar shell.
+ *
+ * Owns ONLY UI-shape state — no server data ever enters this store.
+ * Server state (events, user profile) lives in TanStack Query.
+ */
+```
+
+---
+
+*Convention analysis: 2026-06-09*

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,156 @@
+# External Integrations
+
+**Analysis Date:** 2026-06-09
+
+## APIs & External Services
+
+**CalDAV (Fastmail):**
+- Fastmail CalDAV endpoint - Calendar read/write for all household calendars
+  - SDK/Client: tsdav 2.2.2 (`apps/api/src/broker/client.ts`)
+  - Auth: Basic auth with Fastmail app password (per-member, stored encrypted in `member_credentials` table)
+  - Endpoint: `https://caldav.fastmail.com`
+  - Operations: PROPFIND (discover calendars), REPORT (fetch events), PUT (create/update), DELETE (remove events)
+  - Principal URL pattern: `https://caldav.fastmail.com/dav/principals/user/{email}/`
+  - Parse responses via ical.js; expand recurrence with rrule
+
+**OIDC (Authelia):**
+- Authelia OIDC identity provider - User authentication and session management
+  - SDK/Client: @hono/oidc-auth 1.8.3 (`apps/api/src/auth/middleware.ts`)
+  - Auth method: Authorization-code flow with PKCE (S256 challenge method)
+  - Token auth: client_secret_basic (plaintext secret, NOT pbkdf2 hash)
+  - Required env vars: OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET
+  - Session: Storage-less JWT cookies; refresh via stored refresh token every 15 min (default OIDC_AUTH_REFRESH_INTERVAL)
+  - Requested scopes: `openid profile email offline_access` (customize via OIDC_SCOPES env var)
+  - Metadata discovery: Fetches `/.well-known/openid-configuration` from issuer
+  - Callback: `/callback` route in Hono app; redirects to `/api/login` → `/` on success
+
+## Data Storage
+
+**Databases:**
+- MariaDB 11 - Primary relational database (required; PostgreSQL not available)
+  - Connection: Environment vars (DB_HOST, DB_PORT 3306, DB_USER, DB_PASSWORD, DB_NAME)
+  - Client: mysql2 3.22.4 (native driver via Drizzle ORM)
+  - Schema: `apps/api/src/db/schema.ts` (Drizzle mysqlTable definitions)
+  - Tables: users, member_credentials, calendars, calendarEvents, calendarOutbox
+  - Connection pool: 10 connections max (mysql2 createPool)
+  - Migrations: Generated by drizzle-kit; stored in `apps/api/src/db/migrations/`
+  - Local dev: Docker service `mariadb` with healthcheck; data persisted to `mariadb_data` volume
+
+**File Storage:**
+- Local filesystem only - PWA static assets built by Vite
+  - Location: Built output copied to `apps/api/dist/public` (Dockerfile pwa-builder stage)
+  - Served by Hono via serveStatic middleware on the same :3000 port
+  - No external cloud storage (S3, GCS, etc.)
+
+**Caching:**
+- Redis 7-Alpine - Declared in docker-compose.yml but unused in Phase 1
+  - Reserved for Phase 4 live list sync (pub/sub for broadcasting list-change events across Node processes)
+  - Local dev: Docker service `redis` on port 6379
+  - Client: ioredis (not yet added to dependencies; planned for Phase 4)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Authelia (self-hosted, pre-deployed on Unraid host)
+  - Implementation: RFC-compliant OIDC provider
+  - User identity: Composite key of oidc_iss + oidc_sub (never email, per D-10 in schema)
+  - Session flow: Browser top-level nav to /api/login → 302 redirect to Authelia authorize → user logs in → POST to /callback → JWT session cookie set → browser redirected to /
+  - Invalid XHR redirects: Browser blocks cross-origin redirects from fetch/XHR to external IdP; PWA handles via maybeRedirectToLogin() (top-level navigation)
+  - Claims policy: Authelia 4.39+ required for name/email/preferred_username in ID token (otherwise defaults to "Member" display name)
+
+**Dev Bypass (non-production only):**
+- DEV_AUTH_BYPASS environment variable (NODE_ENV !== 'production')
+  - When enabled: Skips @hono/oidc-auth middleware; injects DEV_USER into context
+  - Allows local development without live Authelia instance
+  - Implementation: `apps/api/src/auth/devBypass.ts`
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Not detected - Errors logged to console; no external service integration
+
+**Logs:**
+- Console-based - Events logged to stdout/stderr
+  - Backend (Hono): Startup message, CalDAV poller errors (per-credential logging, T-03-04), outbox worker status
+  - Frontend: React error boundaries catch component errors
+
+**Health Check:**
+- GET /health endpoint (unauthenticated)
+  - Endpoint: `apps/api/src/routes/health.ts`
+  - Used by Docker Compose healthcheck for mariadb service
+  - MariaDB test: `healthcheck.sh --connect --innodb_initialized`
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Docker on Unraid host (self-hosted)
+  - Container image: Single production image from Dockerfile (API + PWA on port :3000)
+  - Orchestration: Docker Compose (docker-compose.yml + docker-compose.dev.yml overrides)
+  - Environment: Split-DNS internal domain; private IPs internally; external access via Pangolin/Newt tunnel
+
+**CI Pipeline:**
+- Not detected - No GitHub Actions, GitLab CI, or similar configured
+
+**Build Output:**
+- Docker multi-stage build:
+  - API: TypeScript compiled to `apps/api/dist/` by tsc
+  - PWA: Vite bundles to `apps/pwa/dist/`; copied to `apps/api/dist/public` in production image
+  - Single container serves both layers on :3000
+
+## Environment Configuration
+
+**Required env vars (Backend):**
+- Database: DB_HOST, DB_PORT (default 3306), DB_USER, DB_PASSWORD, DB_NAME, DB_ROOT_PASSWORD
+- OIDC: OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI, OIDC_AUTH_EXTERNAL_URL (mandatory for Pangolin redirects)
+- Session: OIDC_AUTH_SECRET (32+ chars for JWT cookie signing)
+- Scopes: OIDC_SCOPES (default: `openid profile email offline_access`)
+- Encryption: APP_PASSWORD_ENCRYPTION_KEY (AES-256-GCM key for encrypting Fastmail app passwords)
+- Environment: NODE_ENV (production/development)
+- Dev override: DEV_AUTH_BYPASS (set to 'true' to disable OIDC; dev-only, NODE_ENV !== 'production')
+
+**Secrets location:**
+- `.env` file (local development) — not committed; pattern documented in docker-compose.yml
+- Docker Compose environment variables — injected at runtime from `.env` or deployment config
+- Member app passwords: Encrypted in DB (member_credentials.encryptedPassword) using APP_PASSWORD_ENCRYPTION_KEY
+- OIDC client secret: Plain text in env var (NOT the pbkdf2 hash from Authelia config)
+
+**Optional env vars:**
+- OIDC_AUTH_EXTERNAL_URL - MANDATORY behind Pangolin for correct redirect_uri construction (Pitfall 1)
+- DEV_AUTH_BYPASS - Dev-only; local testing without Authelia
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- /callback - OIDC authorization-code exchange endpoint
+  - Mounted in `apps/api/src/index.ts` before oidcAuthMiddleware
+  - Receives POST from Authelia after user login; exchanges code for tokens
+  - Sets session JWT cookie; redirects to /api/login (continues to /)
+  - Critical: Must not be intercepted by service worker (navigateFallbackDenylist in vite.config.ts)
+
+**Outgoing:**
+- None detected - No third-party webhooks triggered by the app
+- Fastmail CalDAV: Changes are POLLED (5-min cron poller), not webhook-driven
+- List sync (Phase 4): Will use SSE (server-sent events) for client push, not webhooks
+
+## Network & Transport
+
+**HTTPS/TLS:**
+- Mandatory for OIDC flows
+- Pangolin/Newt tunnel provides HTTPS reverse proxy
+- Internal domain: Split-DNS routes internal requests directly to private IP
+- External requests: Routed through Pangolin tunnel
+
+**Server-Sent Events (SSE):**
+- GET /api/sse/heartbeat - Test endpoint for Pangolin compatibility
+  - Endpoint: `apps/api/src/routes/sse.ts`
+  - Uses Hono's streamSSE helper
+  - Test procedure (D-08): `curl -N https://familysync.<domain>/api/sse/heartbeat`
+  - Phase 4 will extend this for live list sync
+
+**CORS:**
+- Credentials: 'include' for all fetch calls (session cookie sent cross-origin in dev proxy)
+- redirect: 'manual' for /api/me to detect OIDC redirect (prevents fetch hang on cross-origin 302 to Authelia)
+
+---
+
+*Integration audit: 2026-06-09*

.planning/codebase/STACK.md

@@ -0,0 +1,130 @@
+# Technology Stack
+
+**Analysis Date:** 2026-06-09
+
+## Languages
+
+**Primary:**
+- TypeScript 5.5.x - Full stack: backend (`apps/api/src`), frontend (`apps/pwa/src`), shared types
+- JavaScript - Package tooling (node-cron, vite config, drizzle config)
+
+**Secondary:**
+- CSS - Styling (imported via Vite; Schedule-X provides default theme)
+- HTML - PWA manifest generation via vite-plugin-pwa
+
+## Runtime
+
+**Environment:**
+- Node.js 22 LTS (`FROM node:22-alpine` in Dockerfile)
+- Browser: ES2023 target; iOS 16.4+ (PWA home-screen install required)
+
+**Package Manager:**
+- pnpm 11.5.1
+- Lockfile: `pnpm-lock.yaml` present
+- Workspace: `pnpm-workspace.yaml` with `apps/*` packages
+
+## Frameworks
+
+**Core (Backend):**
+- Hono 4.12.23 - HTTP framework with Web Standards API; `@hono/node-server` for Node.js runtime
+- @hono/oidc-auth 1.8.3 - OIDC session middleware (Authelia integration; storage-less JWT cookies)
+- @hono/zod-validator 0.8.0 - Request body/query validation in route handlers
+
+**Core (Frontend):**
+- React 19.x - PWA frontend with concurrent features
+- Vite 8.0.16 - Build tooling (dev server with HMR, production bundler)
+- vite-plugin-pwa 1.3.0 - Service worker registration, PWA manifest generation, Workbox 7 integration
+
+**Calendar UI:**
+- @schedule-x/react 4.1.0 - Calendar component wrapper
+- @schedule-x/calendar 4.6.0 - Core calendar rendering
+- @schedule-x/event-modal 4.6.0 - Event detail/edit modal
+- @schedule-x/events-service 4.6.0 - Event data management
+- @schedule-x/calendar-controls 4.6.0 - Month/week navigation
+- @schedule-x/theme-default 4.6.0 - Default theme (CSS overridden by `apps/pwa/src/styles/tokens.css`)
+
+**Client State:**
+- @tanstack/react-query 5.101.0 - Server state fetching, caching, background refetch, invalidation
+- zustand 5.0.14 - UI-only state (selected date range, color assignments, drawer states)
+
+**Testing (Backend):**
+- Vitest 4.1.8+ - Unit + integration test runner; config: `apps/api/vitest.config.ts` (environment: node, globals: true)
+
+**Testing (Frontend):**
+- Vitest 4.1.8+ - Unit test runner; config: `apps/pwa/vitest.config.ts` (environment: jsdom, TZ=UTC for deterministic date tests)
+- @testing-library/react 16.3.0 - Component testing utilities
+- @testing-library/jest-dom 6.6.3+ - Jest DOM matchers
+
+**Build/Dev:**
+- @vitejs/plugin-react 4.3.0+ - JSX transform, React Fast Refresh
+
+## Key Dependencies
+
+**Critical (CalDAV):**
+- tsdav 2.2.2 - CalDAV client for Fastmail integration; fetches calendars (PROPFIND) and events (REPORT); handles Basic auth
+- ical.js 2.2.1 - iCalendar (.ics) parsing on both backend (CalDAV responses) and frontend (event hydration); Mozilla-maintained reference implementation
+- rrule 2.8.1 - Not yet declared; RRULE expansion for recurring event expansion (Phase 2 calendar view)
+
+**Critical (Database):**
+- drizzle-orm 0.45.2 - Type-safe SQL ORM; MySQL dialect targeting MariaDB; zero runtime overhead
+- drizzle-kit 0.31.10 - Schema migration generator (generates SQL from `apps/api/src/db/schema.ts`)
+- mysql2 3.22.4 - Native MariaDB/MySQL driver; Promises API; used by Drizzle
+
+**Critical (Validation):**
+- zod 3.25.0+ - Schema validation (event payloads, API requests)
+
+**Supporting (Backend):**
+- node-cron 4.2.1+ - Cron scheduling for CalDAV poller (5-min), outbox worker (15-sec)
+- temporal-polyfill 0.3.2 - Temporal API polyfill for date/time operations (ISO 8601 handling)
+
+**Supporting (Frontend):**
+- temporal-polyfill 0.3.2 - Same Temporal polyfill; imported before Schedule-X at `apps/pwa/src/main.tsx:7`
+- lucide-react 1.17.0 - Icon library
+- idb 7.1.1 - IndexedDB wrapper (optional; available but not yet wired)
+
+**Development Only:**
+- @types/node 22.x - Node.js type definitions
+- @types/react 19.x - React type definitions
+- @types/react-dom 19.x - React DOM type definitions
+- jsdom 26.1.0+ - DOM simulation for frontend tests
+
+## Configuration
+
+**Environment (Backend — `apps/api`):**
+- `.env` - Local secrets (DB credentials, OIDC settings, encryption key); pattern in `docker-compose.yml`
+- `drizzle.config.ts` - Dialect: mysql; schema path: `./src/db/schema.ts`; migrations: `./src/db/migrations`
+- `tsconfig.json` - Target: ES2023; module: NodeNext; strict: true
+
+**Environment (Frontend — `apps/pwa`):**
+- `vite.config.ts` - React plugin, PWA plugin (Workbox config with navigateFallback and denylist for /callback, /api/*, /health)
+- `tsconfig.json` - Target: ES2023; lib: [ES2023, DOM, DOM.Iterable]; jsx: react-jsx; strict: true
+
+**Build (Docker):**
+- Multi-stage Dockerfile (`apps/api/Dockerfile`):
+  - `base` - Node 22 Alpine with pnpm enabled
+  - `builder` - TypeScript compilation for API only
+  - `pwa-builder` - Vite build for PWA (produces `dist/`)
+  - `dev` - Development image with hot-reload via `node --watch`
+  - `production` - Single port (:3000) serving both API and PWA static files
+
+## Platform Requirements
+
+**Development:**
+- Node.js 22 LTS
+- pnpm 11.5.1
+- Docker + Docker Compose (for local MariaDB + Redis)
+- MariaDB 11 (via `docker-compose.yml`)
+- Redis 7-Alpine (via `docker-compose.yml`, present but unused in Phase 1)
+- Vite dev server proxy: `localhost:3000` for /api, /callback, /health
+
+**Production:**
+- Node.js 22 LTS runtime in Docker container
+- Authelia OIDC provider (pre-deployed; configured via env vars)
+- MariaDB 11 database
+- Redis 7 (optional; reserved for Phase 4 live list sync pub/sub)
+- Pangolin/Newt tunnel for secure external access (no open ports)
+- Split-DNS internal domain resolution
+
+---
+
+*Stack analysis: 2026-06-09*

.planning/codebase/STRUCTURE.md

@@ -0,0 +1,273 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-06-09
+
+## Directory Layout
+
+```
+familysync/
+├── apps/
+│   ├── api/
+│   │   ├── src/
+│   │   │   ├── index.ts                     # Hono app + HTTP server + broker startup
+│   │   │   ├── auth/
+│   │   │   │   ├── middleware.ts            # OIDC guard via @hono/oidc-auth
+│   │   │   │   ├── user.ts                  # Identity upsert + color assignment
+│   │   │   │   └── devBypass.ts             # DEV_AUTH_BYPASS middleware (local dev)
+│   │   │   ├── db/
+│   │   │   │   ├── client.ts                # mysql2 + Drizzle instance
+│   │   │   │   ├── schema.ts                # Drizzle table definitions
+│   │   │   │   └── migrations/              # drizzle-kit migration files
+│   │   │   ├── routes/
+│   │   │   │   ├── events.ts                # GET /api/events (windowed), POST/PATCH/DELETE (enqueue)
+│   │   │   │   ├── me.ts                    # GET /api/me (current user)
+│   │   │   │   ├── health.ts                # GET /health (unauthenticated)
+│   │   │   │   └── sse.ts                   # GET /api/sse/heartbeat (SSE test)
+│   │   │   └── broker/
+│   │   │       ├── poller.ts                # 5-min cron: PROPFIND → ctag detect
+│   │   │       ├── sync.ts                  # REPORT → ical.js → upsert (per-calendar)
+│   │   │       ├── outboxWorker.ts          # 15-sec cron: drain pending writes to Fastmail
+│   │   │       ├── write.ts                 # PUT/DELETE builders for tsdav
+│   │   │       ├── expand.ts                # Server-side RRULE expansion
+│   │   │       ├── vevent.ts                # VEVENT builder + RRULE extraction
+│   │   │       ├── client.ts                # tsdav client factory
+│   │   │       ├── crypto.ts                # AES-256-GCM encrypt/decrypt
+│   │   │       └── spike.ts                 # Proof-of-concept (unused, historical)
+│   │   ├── tests/
+│   │   │   ├── routes/                      # Unit tests for route handlers
+│   │   │   ├── broker/                      # Unit tests for broker modules
+│   │   │   ├── auth/                        # Unit tests for auth
+│   │   │   ├── fixtures/                    # Test data factories
+│   │   │   └── helpers/                     # Test utilities (mock db, etc.)
+│   │   ├── package.json                     # Backend dependencies
+│   │   ├── tsconfig.json                    # TypeScript config (strict mode)
+│   │   └── dist/                            # Compiled JavaScript (gitignored)
+│   └── pwa/
+│       ├── src/
+│       │   ├── main.tsx                     # Vite entry point
+│       │   ├── App.tsx                      # Root component (CalendarShell)
+│       │   ├── components/
+│       │   │   ├── CalendarShell.tsx        # Schedule-X wiring + TanStack Query + Zustand
+│       │   │   ├── AppNav.tsx               # Header/sidebar navigation
+│       │   │   ├── EventDetailPopover.tsx   # Event detail display + edit/delete actions
+│       │   │   ├── EventForm.tsx            # Create/edit event modal
+│       │   │   ├── DeleteConfirmationDialog.tsx # Delete confirm modal
+│       │   │   ├── SyncStateToast.tsx       # Write-back status toast
+│       │   │   ├── ColorLegend.tsx          # Calendar color legend
+│       │   │   ├── InstallPrompt.tsx        # PWA install prompt
+│       │   │   ├── SkeletonCalendar.tsx     # Loading skeleton
+│       │   │   ├── ErrorBoundary.tsx        # Error boundary wrapper
+│       │   │   └── *.test.tsx               # Component tests
+│       │   ├── api/
+│       │   │   ├── client.ts                # Typed fetch wrappers (fetchMe, fetchEvents, fetchCreateEvent, etc.)
+│       │   │   └── client.test.ts           # API client tests
+│       │   ├── store/
+│       │   │   └── calendarStore.ts         # Zustand UI-state store
+│       │   ├── lib/
+│       │   │   ├── hydrateEvents.ts         # Occurrence[] → Schedule-X CalendarType[]
+│       │   │   ├── calendarConfig.ts        # Schedule-X config builder
+│       │   │   ├── colorUtils.ts            # Hex color utilities
+│       │   │   ├── eventDateTime.ts         # Date/time formatting + parsing
+│       │   │   ├── loginRedirect.ts         # OIDC redirect handler (maybeRedirectToLogin)
+│       │   │   └── *.test.ts                # Utility tests
+│       │   └── styles/
+│       │       └── tokens.ts                # CSS-in-JS design tokens (colors, spacing)
+│       ├── public/
+│       │   ├── index.html                   # PWA shell HTML
+│       │   ├── manifest.webmanifest         # PWA metadata
+│       │   ├── sw.js                        # Service worker entry (generated by vite-plugin-pwa)
+│       │   ├── icon-192.png                 # PWA icon (192x192)
+│       │   └── icon-512.png                 # PWA icon (512x512)
+│       ├── package.json                     # Frontend dependencies
+│       ├── tsconfig.json                    # TypeScript config
+│       ├── vite.config.ts                   # Vite + vite-plugin-pwa configuration
+│       └── dist/                            # Built PWA (gitignored)
+├── packages/
+│   └── shared/                              # Shared types (currently placeholder)
+├── package.json                             # Monorepo root (pnpm workspaces)
+├── pnpm-lock.yaml                          # Dependency lock file
+└── .planning/
+    └── codebase/                            # This document
+```
+
+## Directory Purposes
+
+**`apps/api/src/`** — Backend HTTP server and background broker
+- **Routes** respond to client requests (GET reads cache only; POST/PATCH/DELETE enqueue outbox)
+- **Broker** runs background jobs (poller syncs with Fastmail; outbox worker drains writes)
+- **Auth** handles OIDC session + user identity upsert
+- **DB** defines schema and provides Drizzle ORM client
+
+**`apps/pwa/src/`** — React PWA frontend
+- **Components** render UI and handle user interactions
+- **API** wraps typed fetch calls to backend endpoints
+- **Store** owns UI-only state (view selection, modal open/close) via Zustand
+- **Lib** provides utilities for date handling, color assignment, event hydration, login redirect
+- **Public** contains PWA manifest, service worker config, and static assets
+- **Styles** defines design tokens (colors, spacing, typography)
+
+**`apps/api/tests/`** — Unit tests for backend
+- **Routes** test endpoint validation, authorization, DB queries
+- **Broker** test CalDAV sync logic, RRULE expansion, outbox draining
+- **Auth** test user upsert, color assignment, OIDC claim handling
+- **Fixtures** provide test data factories (mock users, credentials, events)
+- **Helpers** provide test utilities (mock Drizzle, mock tsdav clients)
+
+**`packages/shared/`** — Shared types (future expansion for N-member)
+- Currently a placeholder; will contain cross-app TypeScript interfaces when multi-member features need shared definitions
+
+## Key File Locations
+
+**Entry Points:**
+
+| File | Purpose |
+|------|---------|
+| `apps/api/src/index.ts` | Hono app definition, middleware stack, route registration, broker startup |
+| `apps/pwa/src/main.tsx` | Vite entry point; React.createRoot, hydrate App |
+| `apps/pwa/src/App.tsx` | Root component; renders CalendarShell |
+
+**Configuration:**
+
+| File | Purpose |
+|------|---------|
+| `apps/api/package.json` | Backend dependencies (Hono, Drizzle, tsdav, ical.js, rrule, node-cron, zod, @hono/zod-validator, @hono/oidc-auth, mysql2) |
+| `apps/pwa/package.json` | Frontend dependencies (React 19, Vite, @tanstack/react-query, Zustand, @schedule-x/react, lucide-react, etc.) |
+| `apps/api/tsconfig.json` | strict: true; lib: es2022; module: es2022 |
+| `apps/pwa/tsconfig.json` | strict: true; jsx: react-jsx; lib: es2022, dom |
+| `apps/pwa/vite.config.ts` | Vite plugins (react, VitePWA); dev proxy to :3000; PWA manifest config |
+
+**Core Logic:**
+
+| File | Purpose |
+|------|---------|
+| `apps/api/src/db/schema.ts` | Drizzle table definitions (users, member_credentials, calendars, calendar_events, calendar_outbox) |
+| `apps/api/src/routes/events.ts` | GET /api/events (windowed + expanded), write endpoints (POST/PATCH/DELETE), sync-status polling, writable-calendars |
+| `apps/api/src/broker/poller.ts` | 5-min background job; PROPFIND → ctag change detection |
+| `apps/api/src/broker/sync.ts` | REPORT → ical.js parse → calendar_events upsert; prune deletes |
+| `apps/api/src/broker/outboxWorker.ts` | 15-sec drain pending outbox rows; PUT/DELETE to Fastmail; exponential backoff |
+| `apps/api/src/broker/expand.ts` | ical.js RecurExpansion; emit concrete occurrences (with VTIMEZONE + RRULE handled) |
+| `apps/pwa/src/components/CalendarShell.tsx` | TanStack Query (events, me), Zustand (range, view), Schedule-X wiring |
+| `apps/pwa/src/store/calendarStore.ts` | Zustand store; selectedView, openEventId, calendarRange, eventFormOpen, deleteDialogOpen |
+| `apps/pwa/src/api/client.ts` | Typed fetch wrappers; MeResponse, CalendarOccurrence, CreateEventPayload interfaces |
+| `apps/pwa/src/lib/hydrateEvents.ts` | Occurrence[] → Schedule-X CalendarEvent[] with Temporal.ZonedDateTime conversion |
+
+**Testing:**
+
+| File | Purpose |
+|------|---------|
+| `apps/api/tests/routes/events.test.ts` | Unit tests for route handlers (validation, ownership checks, SQL correctness) |
+| `apps/api/tests/broker/expand.test.ts` | Unit tests for RRULE expansion (VTIMEZONE, EXDATE, DST) |
+| `apps/pwa/src/components/CalendarShell.test.tsx` | Component integration test; mocked React Query + Zustand |
+| `apps/pwa/src/lib/hydrateEvents.test.ts` | Unit tests for Temporal conversion logic |
+
+## Naming Conventions
+
+**Files:**
+
+| Pattern | Example | Where |
+|---------|---------|-------|
+| Kebab-case for route/route groups | `events.ts`, `health.ts` | `apps/api/src/routes/` |
+| Kebab-case for modules | `poller.ts`, `sync.ts`, `outbox-worker.ts` (or camelCase `outboxWorker.ts`) | `apps/api/src/broker/` |
+| PascalCase for React components | `CalendarShell.tsx`, `EventDetailPopover.tsx` | `apps/pwa/src/components/` |
+| Kebab-case for utility functions | `hydrateEvents.ts`, `colorUtils.ts` | `apps/pwa/src/lib/` |
+| `.test.ts` / `.test.tsx` for tests | `events.test.ts`, `CalendarShell.test.tsx` | Colocated with source |
+
+**Functions:**
+
+| Pattern | Example |
+|---------|---------|
+| camelCase for functions | `fetchEvents`, `expandOccurrences`, `upsertUser`, `syncCalendar` |
+| PascalCase for React components | `CalendarShell`, `EventForm`, `SyncStateToast` |
+| UPPER_CASE for module-level constants | `MAX_WINDOW_DAYS`, `COLOR_PALETTE`, `TRANSIENT_STATUSES` |
+| Leading `$` for Drizzle special methods | `.$returningId()`, `.onDuplicateKeyUpdate()` |
+
+**Variables:**
+
+| Pattern | Example |
+|---------|---------|
+| camelCase for variables | `currentUserId`, `calendarRange`, `eventsQuery` |
+| `is`/`has` prefix for booleans | `isShared`, `hasRrule`, `eventFormOpen` |
+| Trailing `Id` for foreign keys | `userId`, `calendarId`, `groupId` |
+| Descriptive names for arrays | `seenUids`, `usedColors`, `occurrences` |
+
+**Types:**
+
+| Pattern | Example |
+|---------|---------|
+| PascalCase for interfaces | `CalendarOccurrence`, `MeResponse`, `CreateEventPayload` |
+| PascalCase for type aliases | `RecurrencePreset`, `BreakpointGroup` |
+| Trailing `Schema` for Zod/validation | `eventsQuerySchema`, `eventFieldsSchema` |
+| Trailing `Response` for API responses | `MeResponse`, `OccurrencesResponse` |
+
+## Where to Add New Code
+
+**New Feature:**
+
+| Feature Type | Primary Code | Tests | Configuration |
+|--------------|--------------|-------|---------------|
+| Calendar event operation (read-only) | `apps/api/src/routes/events.ts` (new GET endpoint) | `apps/api/tests/routes/events.test.ts` | `apps/pwa/src/api/client.ts` (new fetchFn) |
+| Calendar event operation (write) | `apps/api/src/routes/events.ts` (new POST/PATCH/DELETE) + `apps/api/src/broker/write.ts` (new builder) | Route tests + outbox drain tests | `apps/pwa/src/components/EventForm.tsx` (new field) |
+| Recurring event handling | `apps/api/src/broker/expand.ts` (expansion logic) | `apps/api/tests/broker/expand.test.ts` | N/A (no UI change needed) |
+| Shared list sync | `apps/api/src/routes/lists.ts` (new router) + `apps/api/src/broker/listsSync.ts` (if background job needed) | `apps/api/tests/routes/lists.test.ts` | `apps/pwa/src/api/client.ts` (new interfaces) |
+| UI component (calendar display) | `apps/pwa/src/components/` | `apps/pwa/src/components/*.test.tsx` | N/A |
+| UI component (modal/dialog) | `apps/pwa/src/components/` + `apps/pwa/src/store/calendarStore.ts` (add state if needed) | Component test | N/A |
+
+**New Endpoint:**
+
+1. Create router file in `apps/api/src/routes/` (or add to existing)
+2. Define Zod schema for input validation
+3. Implement handler(s): call resolveUserId, validate input, check authorization, query DB or enqueue outbox
+4. Mount in `apps/api/src/index.ts` via `app.route('/api/...', newRouter)`
+5. Export typed fetch function from `apps/pwa/src/api/client.ts`
+6. Call from CalendarShell or component via useQuery/useMutation
+7. Write unit tests in `apps/api/tests/routes/`
+
+**New Component:**
+
+1. Create `.tsx` file in `apps/pwa/src/components/`
+2. Use TanStack Query for server state (via useQuery hook)
+3. Use Zustand selectors for UI state (via useCalendarStore)
+4. Export from CalendarShell or parent component
+5. Add `.test.tsx` file with Vitest + React Testing Library
+6. Mock useQuery and useCalendarStore in tests
+
+**New Utility:**
+
+1. Create `.ts` file in `apps/pwa/src/lib/` (frontend) or `apps/api/src/broker/` (backend)
+2. Export functions with clear names and JSDoc comments
+3. Add `.test.ts` file with test cases
+4. Import where needed (no circular dependencies)
+
+## Special Directories
+
+**`apps/api/src/db/migrations/`:**
+- Purpose: drizzle-kit-generated SQL migration files
+- Generated: Yes (via `drizzle-kit generate:mysql`)
+- Committed: Yes (must be version-controlled for reproducibility)
+- How to add: Run `drizzle-kit generate:mysql` after modifying `schema.ts`; commit the `.sql` file
+- How to apply: Run `drizzle-kit migrate:mysql` to execute pending migrations against MariaDB
+
+**`apps/pwa/public/`:**
+- Purpose: PWA static assets served at root (manifest.webmanifest, service worker, icons, index.html)
+- Generated: `sw.js` and `registerSW.js` are generated by vite-plugin-pwa; others are committed
+- Committed: Yes (except dist/ and generated service worker code — PWA plugin handles registration)
+- How to add: Place assets here; vite build copies to dist/ and serves at /
+
+**`apps/api/dist/` and `apps/pwa/dist/`:**
+- Purpose: Compiled output (JavaScript, CSS, bundled PWA)
+- Generated: Yes (via build scripts)
+- Committed: No (gitignored)
+
+**`node_modules/`:**
+- Purpose: pnpm-installed dependencies
+- Generated: Yes (via `pnpm install`)
+- Committed: No (gitignored; use `pnpm-lock.yaml` for reproducibility)
+
+**`.planning/codebase/`:**
+- Purpose: Auto-generated codebase analysis documents (this file, ARCHITECTURE.md, TESTING.md, etc.)
+- Generated: Yes (by `/gsd-map-codebase` orchestrator)
+- Committed: Yes (reference documentation for future phases)
+
+---
+
+*Structure analysis: 2026-06-09*

.planning/codebase/TESTING.md

@@ -0,0 +1,400 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-06-09
+
+## Test Framework
+
+**Runner:**
+- Backend: Vitest 4.1.8, Node environment
+- Frontend: Vitest 4.1.8, jsdom environment
+- Config: `apps/api/vitest.config.ts`, `apps/pwa/vitest.config.ts`
+
+**Assertion Library:**
+- Vitest built-in `expect()`
+- Testing Library (`@testing-library/react`, `@testing-library/jest-dom`) for component DOM assertions
+- `jest-dom` matchers extended via `apps/pwa/src/test-setup.ts`
+
+**Run Commands:**
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm --filter @familysync/api test:watch
+pnpm --filter @familysync/pwa test:watch
+
+# Run with coverage (not configured yet)
+vitest run --coverage
+```
+
+## Test File Organization
+
+**Location:**
+- Backend: `apps/api/tests/` parallel to `apps/api/src/` — mirrors source structure
+- Frontend: Co-located with source files — `src/components/Foo.tsx` → `src/components/Foo.test.tsx`
+
+**Naming:**
+- Test files: `{module}.test.ts` or `.test.tsx`
+- Fixtures: `apps/api/tests/fixtures/` — fixture files (e.g., `weekly-dst.ics`) loaded by test helpers
+
+**Structure:**
+```
+apps/api/tests/
+├── health.test.ts                 # End-to-end test for GET /health
+├── auth/
+│   ├── devBypass.test.ts
+│   └── user.test.ts
+├── broker/
+│   ├── expand.test.ts             # expandOccurrences() unit tests
+│   ├── poller.test.ts
+│   ├── outboxWorker.test.ts
+│   ├── sync.test.ts
+│   ├── vevent.test.ts
+│   ├── write.test.ts
+│   └── crypto.test.ts
+├── routes/                        # Route handler tests TBD
+├── helpers/                       # Test utility functions
+└── fixtures/
+    ├── weekly-dst.ics             # DST test fixture (weekly recurrence)
+    └── allday-birthday.ics        # All-day recurrence fixture
+
+apps/pwa/src/
+├── api/client.test.ts
+├── lib/
+│   ├── colorUtils.test.ts
+│   ├── eventDateTime.test.ts
+│   ├── hydrateEvents.test.ts
+│   ├── loginRedirect.test.ts
+│   └── calendarConfig.test.ts
+├── components/
+│   ├── InstallPrompt.test.tsx
+│   └── ...
+└── store/
+    └── (Zustand store tested via client.test.ts)
+```
+
+## Test Structure
+
+**Suite Organization:**
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+describe('GET /health', () => {
+  it('returns 200 with { ok: true, db: "up" } when DB round-trip succeeds', async () => {
+    // Arrange
+    const { app } = await import('../src/index.js')
+    
+    // Act
+    const res = await app.request('/health')
+    
+    // Assert
+    expect(res.status).toBe(200)
+    const body = await res.json() as { ok: boolean; db: string }
+    expect(body.ok).toBe(true)
+  })
+
+  it('returns 503 when DB round-trip throws', async () => {
+    // Arrange
+    const { db } = await import('../src/db/client.js')
+    vi.mocked(db.execute).mockRejectedValueOnce(new Error('DB connection failed'))
+
+    // Act
+    const { app } = await import('../src/index.js')
+    const res = await app.request('/health')
+
+    // Assert
+    expect(res.status).toBe(503)
+  })
+})
+```
+
+**Patterns:**
+- Async test functions with full await chain
+- Hono request testing: `app.request(path)` returns a Response object
+- Mock setup in `beforeEach`; cleanup in `afterEach` with `vi.unstubAllGlobals()` or `vi.clearAllMocks()`
+- Descriptive test names following "should [action] when [condition]" or "[verb] [noun]" pattern
+- Arrange-Act-Assert (AAA) comment structure for multi-step tests
+
+## Mocking
+
+**Framework:** Vitest `vi` object (`vi.mock`, `vi.mocked`, `vi.fn`, `vi.stubGlobal`)
+
+**Module Mocking:**
+```typescript
+// Hoist vi.mock() calls to the top of the module (Vitest requirement)
+vi.mock('../src/db/client.js', () => ({
+  db: {
+    execute: vi.fn().mockResolvedValue([[{ '1': 1 }]]),
+  },
+}))
+```
+
+**Function Mocking:**
+```typescript
+const mockFetch = vi.mocked(fetch)
+mockFetch.mockResolvedValueOnce({
+  ok: true,
+  json: async () => ({ uid: 'test-uid' }),
+} as Response)
+
+// Call the function under test
+await createEvent(payload)
+
+// Assert the mock was called correctly
+expect(mockFetch).toHaveBeenCalledWith(
+  '/api/events/create',
+  expect.objectContaining({
+    method: 'POST',
+    credentials: 'include',
+  }),
+)
+```
+
+**Global Stubs (Frontend):**
+```typescript
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn())
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+```
+
+**What to Mock:**
+- External I/O: database (via `vi.mock` on `src/db/client.js`)
+- Network calls: `fetch` (via `vi.stubGlobal('fetch', ...)`)
+- Environment-dependent code: `window.matchMedia` (jsdom polyfill, see test-setup.ts)
+- Time-dependent code: `Date`, `setTimeout` (if needed; not used currently)
+
+**What NOT to Mock:**
+- Pure utility functions — test them directly (colorUtils, eventDateTime, hydrateEvents)
+- Zod validation schemas — test with real payloads
+- Zustand stores — instantiate real store, call real methods
+- Hono app logic — use `app.request()` to test end-to-end
+- iCalendar parsing (ical.js) — test with real .ics fixtures, not mocks
+
+## Fixtures and Factories
+
+**Test Data (Backend):**
+Fixture files are `.ics` (iCalendar) strings stored in `apps/api/tests/fixtures/`:
+
+```typescript
+// Load fixture file
+const rawVevent = readFileSync(join(FIXTURES, 'weekly-dst.ics'), 'utf8')
+
+// Use in test
+const occurrences = expandOccurrences(
+  rawVevent,
+  new Date('2026-03-01T00:00:00Z'),
+  new Date('2026-04-01T00:00:00Z'),
+  1,
+  'My Calendar',
+  1,
+  'Alice',
+  '#4A90D9',
+  false,
+)
+```
+
+**Test Data (Frontend):**
+Inline mock objects in test files (no factory pattern needed yet):
+
+```typescript
+vi.mocked(fetch).mockResolvedValueOnce({
+  ok: true,
+  json: async () => ({
+    calendars: [
+      { url: 'https://caldav.fastmail.com/cal1', displayName: 'My Calendar', color: '#4A90D9', isShared: false },
+      { url: 'https://caldav.fastmail.com/cal2', displayName: 'Family', color: '#F25C7A', isShared: true },
+    ],
+  }),
+} as Response)
+```
+
+**Location:**
+- Fixture files: `apps/api/tests/fixtures/` — raw .ics strings for iCalendar tests
+- Mock payloads: inline in test files (`api/client.test.ts`, etc.)
+
+## Coverage
+
+**Requirements:** None enforced (no coverage thresholds in vitest.config.ts)
+
+**Current State:**
+- Backend: Partial coverage — broker modules (expand, sync, write, crypto, vevent) tested; route handlers mostly untested
+- Frontend: Good coverage of utility functions (colorUtils, eventDateTime, hydrateEvents, calendarConfig) and API client
+
+**View Coverage:**
+```bash
+# Generate coverage report (requires @vitest/coverage-v8)
+vitest run --coverage
+```
+
+## Test Types
+
+**Unit Tests:**
+- Scope: Single function or small module in isolation (mocks external dependencies)
+- Approach: Test input → output contracts, edge cases, error conditions
+- Examples: `lib/colorUtils.test.ts`, `broker/crypto.test.ts`, `api/client.test.ts`
+
+**Integration Tests:**
+- Scope: Multi-module behavior (e.g., route handler + DB + auth middleware)
+- Approach: Test realistic user flows using `app.request()` for HTTP semantics
+- Examples: `health.test.ts` (GET /health with mocked DB)
+- No external API calls (Fastmail, Authelia mocked)
+
+**E2E Tests:**
+- Not implemented; would require running a real server + browser
+- Currently using `playwright-cli` skill for browser-based smoke tests of UI (per project CLAUDE.md)
+
+## Common Patterns
+
+**Async Testing:**
+```typescript
+it('returns { uid } on success', async () => {
+  vi.mocked(fetch).mockResolvedValueOnce({
+    ok: true,
+    json: async () => ({ uid: 'returned-uid' }),
+  } as Response)
+
+  const { createEvent } = await import('./client.js')
+  const result = await createEvent(payload)
+
+  expect(result).toEqual({ uid: 'returned-uid' })
+})
+```
+
+**Error Testing:**
+```typescript
+it('throws on non-ok response', async () => {
+  vi.mocked(fetch).mockResolvedValueOnce({
+    ok: false,
+    status: 400,
+    json: async () => ({ error: 'Bad Request' }),
+  } as Response)
+
+  const { createEvent } = await import('./client.js')
+  
+  await expect(
+    createEvent({ title: '', ... })
+  ).rejects.toThrow()
+})
+```
+
+**Status Code Testing:**
+```typescript
+it('returns 503 when DB round-trip throws', async () => {
+  const { db } = await import('../src/db/client.js')
+  vi.mocked(db.execute).mockRejectedValueOnce(new Error('DB connection failed'))
+
+  const { app } = await import('../src/index.js')
+  const res = await app.request('/health')
+
+  expect(res.status).toBe(503)
+})
+```
+
+**Fixture-Based Testing:**
+```typescript
+describe('expandOccurrences — DST correctness', () => {
+  it('returns 10:00 America/New_York wall-clock time on BOTH sides of March 2026 DST boundary', () => {
+    const rawVevent = loadFixture('weekly-dst.ics')
+    const windowStart = new Date('2026-03-01T00:00:00Z')
+    const windowEnd = new Date('2026-04-01T00:00:00Z')
+
+    const occurrences = expandOccurrences(
+      rawVevent,
+      windowStart,
+      windowEnd,
+      1, 'My Calendar', 1, 'Alice', '#4A90D9', false,
+    )
+
+    // Check DST correctness: all occurrences must show hour === 10 local time
+    for (const occ of occurrences) {
+      expect(occ.start).toMatch(/T10:00:00/)
+      expect(occ.start).toContain('[America/New_York]')
+    }
+
+    // Explicitly check pre- and post-transition occurrences
+    const preTransition = occurrences.find(o => o.start.includes('2026-03-01'))
+    const postTransition = occurrences.find(o => o.start.includes('2026-03-15'))
+
+    expect(preTransition!.start).toContain('-05:00[America/New_York]')   // EST
+    expect(postTransition!.start).toContain('-04:00[America/New_York]')  // EDT
+  })
+})
+```
+
+**Zustand Store Testing:**
+```typescript
+describe('calendarStore', () => {
+  it('setEventForm(true, edit, some-uid) updates all three keys', async () => {
+    const { useCalendarStore } = await import('../store/calendarStore.js')
+    useCalendarStore.getState().setEventForm(true, 'edit', 'some-uid')
+    const state = useCalendarStore.getState()
+
+    expect(state.eventFormOpen).toBe(true)
+    expect(state.eventFormMode).toBe('edit')
+    expect(state.eventFormUid).toBe('some-uid')
+  })
+})
+```
+
+## Test Setup
+
+**Backend (Node environment):**
+- `vitest.config.ts` specifies `environment: 'node'` with `globals: true`
+- No test-setup file needed (Node has built-in globals)
+- Modules imported via `await import(...)` to enable per-test mocking
+
+**Frontend (jsdom environment):**
+- `vitest.config.ts` specifies `environment: 'jsdom'` with `globals: true` and `setupFiles: ['./src/test-setup.ts']`
+- `test-setup.ts` polyfills `window.matchMedia` (jsdom doesn't implement CSSOM MediaQueryList)
+- `test-setup.ts` extends `expect` with `jest-dom` matchers
+- Timezone pinned to UTC via `env: { TZ: 'UTC' }` for deterministic date tests (WR-05)
+
+**Example (from `apps/pwa/vitest.config.ts`):**
+```typescript
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test-setup.ts'],
+    env: { TZ: 'UTC' },
+  },
+})
+```
+
+**Example (from `apps/pwa/src/test-setup.ts`):**
+```typescript
+import '@testing-library/jest-dom'
+
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    // ... other MediaQueryList methods
+  }),
+})
+```
+
+## Known Testing Gaps
+
+**Backend Route Handlers:**
+- GET /api/events, POST /api/events/create, PATCH /api/events/:uid/edit, DELETE /api/events/:uid — no route tests yet (in scope for Phase 5 / Plan 05)
+- GET /api/events/writable-calendars, GET /api/events/sync-status — no route tests
+- SSE route (`/api/sse`) — not tested
+- Auth flow tests (dev-bypass, OIDC session) partially covered; integration tests with Authelia not applicable
+
+**Frontend Components:**
+- EventForm, DeleteConfirmationDialog, CalendarShell — no component tests yet
+- SSE event listener integration (real-time list updates) — not tested
+
+**Integration:**
+- Full end-to-end flow (login → fetch events → create event → poll sync-status) — not covered
+- Database transaction rollback on error — not explicitly tested
+
+---
+
+*Testing analysis: 2026-06-09*

.planning/config.json

@@ -18,7 +18,7 @@
     "plan_check": true,
     "verifier": true,
     "nyquist_validation": true,
-    "auto_advance": true,
+    "auto_advance": false,
     "node_repair": true,
     "node_repair_budget": 2,
     "ui_phase": true,
@@ -27,7 +27,7 @@
     "tdd_mode": true,
     "human_verify_mode": "end-of-phase",
     "text_mode": false,
-    "research_before_questions": false,
+    "research_before_questions": true,
     "discuss_mode": "discuss",
     "skip_discuss": false,
     "code_review": true,
@@ -42,7 +42,9 @@
     "security_enforcement": true,
     "security_asvs_level": 1,
     "security_block_on": "high",
-    "_auto_chain_active": false
+    "_auto_chain_active": false,
+    "ui_review": true,
+    "use_worktrees": true
   },
   "ship": {
     "pr_body_sections": [
@@ -83,5 +85,11 @@
     "source_grounding_authority": "grep"
   },
   "mode": "interactive",
-  "granularity": "standard"
+  "granularity": "standard",
+  "intel": {
+    "enabled": true
+  },
+  "graphify": {
+    "enabled": true
+  }
 }

.planning/graphs/GRAPH_REPORT.md

@@ -0,0 +1,973 @@
+# Graph Report - familysync  (2026-06-09)
+
+## Corpus Check
+- 205 files · ~256,858 words
+- Verdict: corpus is large enough that graph structure adds value.
+
+## Summary
+- 2182 nodes · 2228 edges · 210 communities (185 shown, 25 thin omitted)
+- Extraction: 100% EXTRACTED · 0% INFERRED · 0% AMBIGUOUS · INFERRED: 5 edges (avg confidence: 0.8)
+- Token cost: 0 input · 0 output
+
+## Graph Freshness
+- Built from commit: `00cbbb41`
+- Run `git rev-parse HEAD` and compare to check if the graph is stale.
+- Run `graphify update .` after code changes (no API cost).
+
+## Community Hubs (Navigation)
+- [[_COMMUNITY_Community 0|Community 0]]
+- [[_COMMUNITY_Community 1|Community 1]]
+- [[_COMMUNITY_Community 2|Community 2]]
+- [[_COMMUNITY_Community 3|Community 3]]
+- [[_COMMUNITY_Community 4|Community 4]]
+- [[_COMMUNITY_Community 5|Community 5]]
+- [[_COMMUNITY_Community 6|Community 6]]
+- [[_COMMUNITY_Community 7|Community 7]]
+- [[_COMMUNITY_Community 8|Community 8]]
+- [[_COMMUNITY_Community 9|Community 9]]
+- [[_COMMUNITY_Community 10|Community 10]]
+- [[_COMMUNITY_Community 11|Community 11]]
+- [[_COMMUNITY_Community 12|Community 12]]
+- [[_COMMUNITY_Community 13|Community 13]]
+- [[_COMMUNITY_Community 14|Community 14]]
+- [[_COMMUNITY_Community 15|Community 15]]
+- [[_COMMUNITY_Community 16|Community 16]]
+- [[_COMMUNITY_Community 17|Community 17]]
+- [[_COMMUNITY_Community 18|Community 18]]
+- [[_COMMUNITY_Community 19|Community 19]]
+- [[_COMMUNITY_Community 20|Community 20]]
+- [[_COMMUNITY_Community 21|Community 21]]
+- [[_COMMUNITY_Community 22|Community 22]]
+- [[_COMMUNITY_Community 23|Community 23]]
+- [[_COMMUNITY_Community 24|Community 24]]
+- [[_COMMUNITY_Community 25|Community 25]]
+- [[_COMMUNITY_Community 26|Community 26]]
+- [[_COMMUNITY_Community 27|Community 27]]
+- [[_COMMUNITY_Community 28|Community 28]]
+- [[_COMMUNITY_Community 29|Community 29]]
+- [[_COMMUNITY_Community 30|Community 30]]
+- [[_COMMUNITY_Community 31|Community 31]]
+- [[_COMMUNITY_Community 32|Community 32]]
+- [[_COMMUNITY_Community 33|Community 33]]
+- [[_COMMUNITY_Community 34|Community 34]]
+- [[_COMMUNITY_Community 35|Community 35]]
+- [[_COMMUNITY_Community 36|Community 36]]
+- [[_COMMUNITY_Community 37|Community 37]]
+- [[_COMMUNITY_Community 38|Community 38]]
+- [[_COMMUNITY_Community 39|Community 39]]
+- [[_COMMUNITY_Community 40|Community 40]]
+- [[_COMMUNITY_Community 41|Community 41]]
+- [[_COMMUNITY_Community 42|Community 42]]
+- [[_COMMUNITY_Community 43|Community 43]]
+- [[_COMMUNITY_Community 44|Community 44]]
+- [[_COMMUNITY_Community 45|Community 45]]
+- [[_COMMUNITY_Community 46|Community 46]]
+- [[_COMMUNITY_Community 47|Community 47]]
+- [[_COMMUNITY_Community 48|Community 48]]
+- [[_COMMUNITY_Community 49|Community 49]]
+- [[_COMMUNITY_Community 50|Community 50]]
+- [[_COMMUNITY_Community 51|Community 51]]
+- [[_COMMUNITY_Community 52|Community 52]]
+- [[_COMMUNITY_Community 53|Community 53]]
+- [[_COMMUNITY_Community 54|Community 54]]
+- [[_COMMUNITY_Community 55|Community 55]]
+- [[_COMMUNITY_Community 56|Community 56]]
+- [[_COMMUNITY_Community 57|Community 57]]
+- [[_COMMUNITY_Community 58|Community 58]]
+- [[_COMMUNITY_Community 59|Community 59]]
+- [[_COMMUNITY_Community 60|Community 60]]
+- [[_COMMUNITY_Community 61|Community 61]]
+- [[_COMMUNITY_Community 62|Community 62]]
+- [[_COMMUNITY_Community 63|Community 63]]
+- [[_COMMUNITY_Community 64|Community 64]]
+- [[_COMMUNITY_Community 65|Community 65]]
+- [[_COMMUNITY_Community 66|Community 66]]
+- [[_COMMUNITY_Community 67|Community 67]]
+- [[_COMMUNITY_Community 68|Community 68]]
+- [[_COMMUNITY_Community 69|Community 69]]
+- [[_COMMUNITY_Community 70|Community 70]]
+- [[_COMMUNITY_Community 71|Community 71]]
+- [[_COMMUNITY_Community 72|Community 72]]
+- [[_COMMUNITY_Community 73|Community 73]]
+- [[_COMMUNITY_Community 74|Community 74]]
+- [[_COMMUNITY_Community 75|Community 75]]
+- [[_COMMUNITY_Community 76|Community 76]]
+- [[_COMMUNITY_Community 77|Community 77]]
+- [[_COMMUNITY_Community 78|Community 78]]
+- [[_COMMUNITY_Community 79|Community 79]]
+- [[_COMMUNITY_Community 80|Community 80]]
+- [[_COMMUNITY_Community 81|Community 81]]
+- [[_COMMUNITY_Community 82|Community 82]]
+- [[_COMMUNITY_Community 83|Community 83]]
+- [[_COMMUNITY_Community 84|Community 84]]
+- [[_COMMUNITY_Community 85|Community 85]]
+- [[_COMMUNITY_Community 86|Community 86]]
+- [[_COMMUNITY_Community 87|Community 87]]
+- [[_COMMUNITY_Community 88|Community 88]]
+- [[_COMMUNITY_Community 89|Community 89]]
+- [[_COMMUNITY_Community 90|Community 90]]
+- [[_COMMUNITY_Community 91|Community 91]]
+- [[_COMMUNITY_Community 92|Community 92]]
+- [[_COMMUNITY_Community 93|Community 93]]
+- [[_COMMUNITY_Community 94|Community 94]]
+- [[_COMMUNITY_Community 95|Community 95]]
+- [[_COMMUNITY_Community 96|Community 96]]
+- [[_COMMUNITY_Community 97|Community 97]]
+- [[_COMMUNITY_Community 98|Community 98]]
+- [[_COMMUNITY_Community 99|Community 99]]
+- [[_COMMUNITY_Community 100|Community 100]]
+- [[_COMMUNITY_Community 101|Community 101]]
+- [[_COMMUNITY_Community 102|Community 102]]
+- [[_COMMUNITY_Community 103|Community 103]]
+- [[_COMMUNITY_Community 104|Community 104]]
+- [[_COMMUNITY_Community 105|Community 105]]
+- [[_COMMUNITY_Community 106|Community 106]]
+- [[_COMMUNITY_Community 107|Community 107]]
+- [[_COMMUNITY_Community 108|Community 108]]
+- [[_COMMUNITY_Community 109|Community 109]]
+- [[_COMMUNITY_Community 110|Community 110]]
+- [[_COMMUNITY_Community 111|Community 111]]
+- [[_COMMUNITY_Community 112|Community 112]]
+- [[_COMMUNITY_Community 113|Community 113]]
+- [[_COMMUNITY_Community 114|Community 114]]
+- [[_COMMUNITY_Community 115|Community 115]]
+- [[_COMMUNITY_Community 116|Community 116]]
+- [[_COMMUNITY_Community 117|Community 117]]
+- [[_COMMUNITY_Community 118|Community 118]]
+- [[_COMMUNITY_Community 119|Community 119]]
+- [[_COMMUNITY_Community 120|Community 120]]
+- [[_COMMUNITY_Community 121|Community 121]]
+- [[_COMMUNITY_Community 122|Community 122]]
+- [[_COMMUNITY_Community 123|Community 123]]
+- [[_COMMUNITY_Community 124|Community 124]]
+- [[_COMMUNITY_Community 125|Community 125]]
+- [[_COMMUNITY_Community 126|Community 126]]
+- [[_COMMUNITY_Community 127|Community 127]]
+- [[_COMMUNITY_Community 128|Community 128]]
+- [[_COMMUNITY_Community 129|Community 129]]
+- [[_COMMUNITY_Community 130|Community 130]]
+- [[_COMMUNITY_Community 131|Community 131]]
+- [[_COMMUNITY_Community 132|Community 132]]
+- [[_COMMUNITY_Community 133|Community 133]]
+- [[_COMMUNITY_Community 134|Community 134]]
+- [[_COMMUNITY_Community 135|Community 135]]
+- [[_COMMUNITY_Community 136|Community 136]]
+- [[_COMMUNITY_Community 137|Community 137]]
+- [[_COMMUNITY_Community 138|Community 138]]
+- [[_COMMUNITY_Community 139|Community 139]]
+- [[_COMMUNITY_Community 140|Community 140]]
+- [[_COMMUNITY_Community 141|Community 141]]
+- [[_COMMUNITY_Community 142|Community 142]]
+- [[_COMMUNITY_Community 143|Community 143]]
+- [[_COMMUNITY_Community 144|Community 144]]
+- [[_COMMUNITY_Community 145|Community 145]]
+- [[_COMMUNITY_Community 146|Community 146]]
+- [[_COMMUNITY_Community 147|Community 147]]
+- [[_COMMUNITY_Community 148|Community 148]]
+- [[_COMMUNITY_Community 149|Community 149]]
+- [[_COMMUNITY_Community 150|Community 150]]
+- [[_COMMUNITY_Community 151|Community 151]]
+- [[_COMMUNITY_Community 152|Community 152]]
+- [[_COMMUNITY_Community 153|Community 153]]
+- [[_COMMUNITY_Community 154|Community 154]]
+- [[_COMMUNITY_Community 155|Community 155]]
+- [[_COMMUNITY_Community 156|Community 156]]
+- [[_COMMUNITY_Community 157|Community 157]]
+- [[_COMMUNITY_Community 158|Community 158]]
+- [[_COMMUNITY_Community 159|Community 159]]
+- [[_COMMUNITY_Community 160|Community 160]]
+- [[_COMMUNITY_Community 161|Community 161]]
+- [[_COMMUNITY_Community 162|Community 162]]
+- [[_COMMUNITY_Community 163|Community 163]]
+- [[_COMMUNITY_Community 164|Community 164]]
+- [[_COMMUNITY_Community 165|Community 165]]
+- [[_COMMUNITY_Community 166|Community 166]]
+- [[_COMMUNITY_Community 167|Community 167]]
+- [[_COMMUNITY_Community 168|Community 168]]
+- [[_COMMUNITY_Community 169|Community 169]]
+- [[_COMMUNITY_Community 170|Community 170]]
+- [[_COMMUNITY_Community 171|Community 171]]
+- [[_COMMUNITY_Community 172|Community 172]]
+- [[_COMMUNITY_Community 173|Community 173]]
+- [[_COMMUNITY_Community 174|Community 174]]
+- [[_COMMUNITY_Community 175|Community 175]]
+- [[_COMMUNITY_Community 176|Community 176]]
+- [[_COMMUNITY_Community 177|Community 177]]
+- [[_COMMUNITY_Community 178|Community 178]]
+- [[_COMMUNITY_Community 179|Community 179]]
+- [[_COMMUNITY_Community 180|Community 180]]
+- [[_COMMUNITY_Community 181|Community 181]]
+- [[_COMMUNITY_Community 182|Community 182]]
+- [[_COMMUNITY_Community 183|Community 183]]
+- [[_COMMUNITY_Community 184|Community 184]]
+- [[_COMMUNITY_Community 185|Community 185]]
+- [[_COMMUNITY_Community 186|Community 186]]
+- [[_COMMUNITY_Community 187|Community 187]]
+- [[_COMMUNITY_Community 188|Community 188]]
+- [[_COMMUNITY_Community 189|Community 189]]
+- [[_COMMUNITY_Community 190|Community 190]]
+- [[_COMMUNITY_Community 191|Community 191]]
+- [[_COMMUNITY_Community 193|Community 193]]
+- [[_COMMUNITY_Community 194|Community 194]]
+- [[_COMMUNITY_Community 195|Community 195]]
+
+## God Nodes (most connected - your core abstractions)
+1. `workflow` - 32 edges
+2. `Phase 4: Shared Lists + Live Sync — Research` - 29 edges
+3. `Phase 3: Event Write-Back + PWA Install — Research` - 27 edges
+4. `Phase 2: Calendar Display - Research` - 20 edges
+5. `Phase 1: Foundation + Broker Spike — Research` - 19 edges
+6. `Critical Pitfalls` - 19 edges
+7. `Pattern Assignments` - 18 edges
+8. `Phase 2 — UI Design Contract` - 18 edges
+9. `Dev` - 16 edges
+10. `compilerOptions` - 15 edges
+
+## Surprising Connections (you probably didn't know these)
+- `loadClientForUser()` --calls--> `createFastmailClient()`  [EXTRACTED]
+  apps/api/src/broker/outboxWorker.ts → apps/api/src/broker/client.ts
+- `main()` --calls--> `createFastmailClient()`  [EXTRACTED]
+  apps/api/src/broker/spike.ts → apps/api/src/broker/client.ts
+- `loadClientForUser()` --calls--> `decryptPassword()`  [EXTRACTED]
+  apps/api/src/broker/outboxWorker.ts → apps/api/src/broker/crypto.ts
+- `runPoll()` --calls--> `decryptPassword()`  [EXTRACTED]
+  apps/api/src/broker/poller.ts → apps/api/src/broker/crypto.ts
+- `triggerTargetedResync()` --calls--> `syncCalendar()`  [EXTRACTED]
+  apps/api/src/broker/outboxWorker.ts → apps/api/src/broker/sync.ts
+
+## Import Cycles
+- None detected.
+
+## Communities (210 total, 25 thin omitted)
+
+### Community 0 - "Community 0"
+Cohesion: 0.05
+Nodes (43): 60 / 30 / 10 split, Agenda view (default: phone), AgendaRow, AppNav, Base palette, Breakpoints, Calendar config constant, Calendar Display (+35 more)
+
+### Community 1 - "Community 1"
+Cohesion: 0.06
+Nodes (35): dependencies, ical.js, lucide-react, react, react-dom, @schedule-x/calendar, @schedule-x/calendar-controls, @schedule-x/event-modal (+27 more)
+
+### Community 2 - "Community 2"
+Cohesion: 0.06
+Nodes (35): Advanced: Multiple Cookies or Custom Options, Advanced: Multiple Operations, Authentication State Reuse, Clear All Cookies, Clear All localStorage, Clear sessionStorage, Common Patterns, Cookies (+27 more)
+
+### Community 3 - "Community 3"
+Cohesion: 0.06
+Nodes (34): Accessibility Baseline, `AddItemInput`, Bottom Tab Bar (phone, ≤767px), `BottomTabBar`, Checked-Off Sink Behavior (D-05), Checker Sign-Off, Color, Component Inventory (+26 more)
+
+### Community 4 - "Community 4"
+Cohesion: 0.06
+Nodes (31): Android install, CalendarPicker (within EventForm — conditional, D-02), Checker Sign-Off, Color, Component Inventory, Copywriting Contract, Delete interaction, DeleteConfirmationDialog (new component) (+23 more)
+
+### Community 5 - "Community 5"
+Cohesion: 0.06
+Nodes (31): dependencies, drizzle-orm, hono, @hono/node-server, @hono/oidc-auth, @hono/zod-validator, ical.js, mysql2 (+23 more)
+
+### Community 6 - "Community 6"
+Cohesion: 0.06
+Nodes (32): workflow, ai_integration_phase, auto_advance, _auto_chain_active, auto_prune_state, code_review, code_review_command, code_review_depth (+24 more)
+
+### Community 7 - "Community 7"
+Cohesion: 0.06
+Nodes (31): Anti-Pattern 1: Fetching from Fastmail on Every Calendar Request, Anti-Pattern 2: Using Email as the App User Key, Anti-Pattern 3: Storing Recurring Events Only as Expanded Instances, Anti-Pattern 4: Separate Microservices for Broker, Lists, Push, Anti-Pattern 5: Per-User CalDAV Credentials in the PWA, Anti-Patterns, Architectural Patterns, Architecture Research (+23 more)
+
+### Community 8 - "Community 8"
+Cohesion: 0.06
+Nodes (30): `apps/api/src/auth/devBypass.ts` (middleware — new file), `apps/api/src/broker/expand.ts` (utility, transform — new file), `apps/api/src/db/schema.ts` (model — modify existing), `apps/api/src/index.ts` (config — modify existing), `apps/api/src/routes/events.ts` (route, request-response — modify existing), `apps/api/tests/broker/expand.test.ts` (test — new file), `apps/api/tests/routes/events.test.ts` (test — new file), `apps/pwa/src/api/client.ts` (utility, request-response — modify existing) (+22 more)
+
+### Community 9 - "Community 9"
+Cohesion: 0.07
+Nodes (29): 401 Guard Pattern, `apps/api/src/db/schema.ts` (model, CRUD — append new tables), `apps/api/src/index.ts` (config, modify), `apps/api/src/lib/listEmitter.ts` (utility, event-driven), `apps/api/src/routes/lists.ts` (route, CRUD), `apps/api/src/routes/sse.ts` (route, streaming — extend existing), `apps/pwa/src/api/listsClient.ts` (utility, request-response), `apps/pwa/src/App.tsx` (component, modify) (+21 more)
+
+### Community 10 - "Community 10"
+Cohesion: 0.07
+Nodes (29): Critical Pitfalls, Integration Gotchas, "Looks Done But Isn't" Checklist, Performance Traps, Pitfall 10: Declarative Web Push vs Standard Web Push — Choose the Right Target, Pitfall 11: EU Digital Markets Act Breaks iOS PWA Entirely for EU Users, Pitfall 12: Service Worker Caching Serves Stale Calendar Data, Pitfall 13: Service Worker Update Staleness — App Never Updates for the Wife (+21 more)
+
+### Community 11 - "Community 11"
+Cohesion: 0.07
+Nodes (27): Alternatives Considered, Architecture, Authelia OIDC Integration, Backend, Backend Framework, Browser-based verification, Calendar Integration: CalDAV, Not JMAP, Constraints (+19 more)
+
+### Community 12 - "Community 12"
+Cohesion: 0.14
+Nodes (19): BACKOFF_SECONDS, DispatchResult, dispatchRow(), HARD_FAIL_STATUSES, loadClientForUser(), OutboxPayloadFields, outboxPayloadSchema, OutboxRow (+11 more)
+
+### Community 13 - "Community 13"
+Cohesion: 0.08
+Nodes (23): `apps/api/src/broker/outboxWorker.ts` — new file, outbox drain loop, `apps/api/src/broker/vevent.ts` — new file, ical.js VEVENT builder, `apps/api/src/broker/write.ts` — new file, tsdav PUT/DELETE wrapper, `apps/api/src/db/schema.ts` — add `calendarOutbox` table + `objectUrl` column on `calendarEvents`, `apps/api/src/routes/events.ts` — extend with write endpoints + sync-status, `apps/pwa/src/api/client.ts` — add write calls + sync-status poll, `apps/pwa/src/components/EventDetailPopover.tsx` — add edit/delete to reserved footer, `apps/pwa/src/components/EventForm.tsx` — new file, create/edit form (+15 more)
+
+### Community 14 - "Community 14"
+Cohesion: 0.08
+Nodes (23): Browser Automation with playwright-cli, Browser Sessions, Commands, Core, DevTools, Example: Debugging with DevTools, Example: Form submission, Example: Interactive session (+15 more)
+
+### Community 15 - "Community 15"
+Cohesion: 0.09
+Nodes (22): Canonical References, Claude's Discretion (deferred to research/planner), Deferred Ideas, Entry gate & transport, Established Patterns, Existing Code Insights, Implementation Decisions, Integration Points (+14 more)
+
+### Community 16 - "Community 16"
+Cohesion: 0.14
+Nodes (18): createEvent(), CreateEventPayload, CreateEventResponse, fetchSyncStatus(), fetchWritableCalendars(), MeResponse, MeUser, OccurrencesResponse (+10 more)
+
+### Community 17 - "Community 17"
+Cohesion: 0.16
+Nodes (14): ContextVariableMap, DEV_USER, devAuthBypass(), claimStr(), deriveDisplayName(), upsertUser(), eventFieldsSchema, eventsQuerySchema (+6 more)
+
+### Community 18 - "Community 18"
+Cohesion: 0.09
+Nodes (21): Backlog, Overview, Phase 1: Foundation + Broker Spike, Phase 2: Calendar Display, Phase 3: Event Write-Back + PWA Install, Phase 4: Shared Lists + Live Sync, Phase 5: Web Push Notifications, Phase 6: UX Polish (+13 more)
+
+### Community 19 - "Community 19"
+Cohesion: 0.09
+Nodes (21): Architecture Approach, Confidence Assessment, Critical Pitfalls, Executive Summary, Expected Features, Gaps to Address, Implications for Roadmap, Key Findings (+13 more)
+
+### Community 20 - "Community 20"
+Cohesion: 0.10
+Nodes (20): Canonical References, Claude's Discretion, Color & ownership legibility, Deferred Ideas, Dev-auth bypass (from D-14, project-level), Established Patterns, Event detail density, Existing Code Insights (+12 more)
+
+### Community 21 - "Community 21"
+Cohesion: 0.10
+Nodes (20): CR-01: Event edit/delete ownership check resolves an arbitrary member's row (uid-only lookup), CR-02: Outbox WR-02 "freshest etag" re-read also queries uid-only — can pick the wrong member's etag, CR-03: All-day end date is exclusive on write but inclusive on edit pre-fill — span grows one day per re-edit, Critical Issues, IN-01: `triggerTargetedResync` re-loads and re-decrypts the credential per row, IN-02: Unknown-status responses retried for the full backoff window before giving up, IN-03: `InstallPrompt` reads `localStorage` synchronously in `useState` initializer without try/catch, IN-04: `resolveUserId` typed as `any` (+12 more)
+
+### Community 22 - "Community 22"
+Cohesion: 0.10
+Nodes (20): 1. Name Browser Sessions Semantically, 2. Always Clean Up, 3. Delete Stale Browser Data, A/B Testing Sessions, Attach by channel name, Attach via browser extension, Attach via CDP endpoint, Attaching to a Running Browser (+12 more)
+
+### Community 23 - "Community 23"
+Cohesion: 0.10
+Nodes (19): Canonical References, Claude's Discretion, Deferred Ideas, Established Patterns, Existing Code Insights, External docs (authoritative), Implementation Decisions, Infrastructure & Deployment Scope (+11 more)
+
+### Community 24 - "Community 24"
+Cohesion: 0.10
+Nodes (19): Architectural Responsibility Map, Assumptions Log, Don't Hand-Roll, Environment Availability, Metadata, Open Questions (RESOLVED), Package Legitimacy Audit, Pattern 1: Building a VEVENT with ical.js (new file: `broker/vevent.ts`) (+11 more)
+
+### Community 25 - "Community 25"
+Cohesion: 0.10
+Nodes (19): Anti-Patterns, Architectural Constraints, Architecture, Caching tsdav clients across polls, Calendar Sync (Background Poller → syncCalendar), Component Responsibilities, Data Flow, Direct Fastmail calls from routes (+11 more)
+
+### Community 26 - "Community 26"
+Cohesion: 0.10
+Nodes (19): agent_skills, brave_search, claude_md_path, commit_docs, exa_search, firecrawl, granularity, hooks (+11 more)
+
+### Community 27 - "Community 27"
+Cohesion: 0.11
+Nodes (18): blockers, completed_tasks, context_notes, decisions, human_actions_pending, next_action, phase, phase_dir (+10 more)
+
+### Community 28 - "Community 28"
+Cohesion: 0.11
+Nodes (18): 1.1 Prerequisite: workspace, 1.2 Prerequisite: seed test, 1.3 Explore the app, 1.4 Write the spec file, 1. Planning, 2.1 Inputs, 2.2 Generate one scenario, 2.3 Generate multiple scenarios (+10 more)
+
+### Community 29 - "Community 29"
+Cohesion: 0.11
+Nodes (17): Accomplishments, Auto-fixed Issues, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Issues Encountered, Known Stubs (+9 more)
+
+### Community 30 - "Community 30"
+Cohesion: 0.11
+Nodes (17): 1. Color-coded event rendering, 2. All four views render events correctly, 3. Recurring events — DST boundary (CAL-07), 4. All-day events — no date shift (CAL-07), Anti-Patterns Found, Behavioral Spot-Checks, Data-Flow Trace (Level 4), Deferred Items (+9 more)
+
+### Community 31 - "Community 31"
+Cohesion: 0.11
+Nodes (17): Canonical References, Carried forward — locked, NOT re-discussed, Claude's Discretion (researcher / planner decide), Code this phase extends, Deferred Ideas, Established Patterns, Existing Code Insights, Implementation Decisions (+9 more)
+
+### Community 32 - "Community 32"
+Cohesion: 0.11
+Nodes (17): CR-01: Event edit/delete ownership check resolves an arbitrary member's row (uid-only lookup), CR-02: Outbox WR-02 "freshest etag" re-read also queries uid-only, CR-03: All-day end date exclusive on write but inclusive on edit pre-fill, Fixed Issues, IN-01: `triggerTargetedResync` re-loads and re-decrypts the credential per row, IN-02: Unknown-status responses retried for the full backoff window before giving up, IN-03: `InstallPrompt` reads `localStorage` synchronously without try/catch, IN-04: `resolveUserId` typed as `any` (+9 more)
+
+### Community 33 - "Community 33"
+Cohesion: 0.11
+Nodes (17): compilerOptions, declaration, declarationMap, esModuleInterop, forceConsistentCasingInFileNames, lib, module, moduleResolution (+9 more)
+
+### Community 34 - "Community 34"
+Cohesion: 0.12
+Nodes (16): Accomplishments, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Issues Encountered, Known Stubs, Metrics (+8 more)
+
+### Community 35 - "Community 35"
+Cohesion: 0.12
+Nodes (16): Accomplishments, Dependency graph, Deviations from Plan, Files Created/Modified, Known Stubs, Live Verification Pending (Tasks 2 + 3), Metrics, Performance (+8 more)
+
+### Community 36 - "Community 36"
+Cohesion: 0.12
+Nodes (16): 1. AUTH-01 — Authelia OIDC Login (Member 1: Lucas), 2. AUTH-02 — Session Persistence Across Browser Restart, 3. AUTH-03 — Cross-Member Distinct Color (Member 2: Wife), 4. SSE Smoke Test — Pangolin Pass-Through (D-08), Anti-Patterns Found, Behavioral Spot-Checks, Data-Flow Trace (Level 4), Gaps Summary (+8 more)
+
+### Community 37 - "Community 37"
+Cohesion: 0.12
+Nodes (16): Accomplishments, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Known Stubs, Metrics, Performance (+8 more)
+
+### Community 38 - "Community 38"
+Cohesion: 0.12
+Nodes (16): Architectural Responsibility Map, Assumptions Log, Don't Hand-Roll, Entry Gate Status: CLEARED, Environment Availability, Metadata, Open Questions, Package Legitimacy Audit (+8 more)
+
+### Community 39 - "Community 39"
+Cohesion: 0.12
+Nodes (16): 1. Start Tracing Before the Problem, 2. Clean Up Old Traces, Analyzing Performance, Basic Usage, Best Practices, Capturing Evidence, Debugging Failed Actions, Limitations (+8 more)
+
+### Community 40 - "Community 40"
+Cohesion: 0.12
+Nodes (16): Alternatives Considered, Authelia OIDC Integration, Backend Framework, Calendar Integration: CalDAV, Not JMAP, Core Technologies, Development Tools, Installation, Live List Sync (+8 more)
+
+### Community 41 - "Community 41"
+Cohesion: 0.12
+Nodes (15): Accomplishments, Auto-fixed Issues, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Known Stubs, Metrics (+7 more)
+
+### Community 42 - "Community 42"
+Cohesion: 0.12
+Nodes (15): 1. Register FamilySync as an Authelia OIDC confidential client, 2. Set OIDC_AUTH_EXTERNAL_URL in the app's .env, 3. Expose via Pangolin / Newt (Mode A local rig), 4. Apply database schema (first deploy only), 5. Bring up the app and confirm /health over the tunnel, Gate 2 Checklist, Header, /health Tunnel Verification (+7 more)
+
+### Community 43 - "Community 43"
+Cohesion: 0.23
+Nodes (11): createFastmailClient(), FastmailClient, runPoll(), startBrokerPoller(), main(), syncCalendar(), calendarEvents, calendarOutbox (+3 more)
+
+### Community 44 - "Community 44"
+Cohesion: 0.13
+Nodes (14): Accomplishments, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Known Stubs, Metrics, Operator Setup Required (Authelia Client Registration) (+6 more)
+
+### Community 45 - "Community 45"
+Cohesion: 0.13
+Nodes (14): Accomplishments, Decisions Made, Dependency graph, Deviations from Plan, Files Created/Modified, Issues Encountered, Metrics, Next Phase Readiness (+6 more)
+
+### Community 46 - "Community 46"
+Cohesion: 0.13
+Nodes (14): Accomplishments, Auto-fixed Issues, Decisions Made, Dependency graph, Deviations from Plan, Files Created, Known Stubs, Metrics (+6 more)
+
+### Community 47 - "Community 47"
+Cohesion: 0.13
+Nodes (14): Accomplishments, Auto-fixed Issues, Decisions Made, Deviations from Plan, Files Created/Modified, Issues Encountered, Known Stubs, Next Phase Readiness (+6 more)
+
+### Community 48 - "Community 48"
+Cohesion: 0.13
+Nodes (14): Accomplishments, Auto-fixed Issues, Decisions Made, Deviations from Plan, Files Created/Modified, Issues Closed, Issues Encountered, Known Stubs (+6 more)
+
+### Community 49 - "Community 49"
+Cohesion: 0.13
+Nodes (14): Auto-fixed Issues, Deviations from Plan, IN-03: todayIso exported from calendarStore, Issues Closed, Phase 03 Plan 12: EventForm Gap Closure — Edit Mode, Focus Trap, PWA Assets Summary, PWA-01/PWA-02: Install assets confirmed present (IN-04), Self-Check: PASSED, Tasks Completed (+6 more)
+
+### Community 50 - "Community 50"
+Cohesion: 0.13
+Nodes (14): Behavior when the CalDAV write fails, Calendar selector visibility, Claude's Discretion, Default target calendar for a new event, Deferred Ideas, Edit-conflict (etag mismatch / 412) handling, How the member sees their own change after save (poll-based cache), Move event between calendars on edit (+6 more)
+
+### Community 51 - "Community 51"
+Cohesion: 0.13
+Nodes (14): Auto-fixed Issues, BUG 1 — Missing join on PATCH/:uid/edit and DELETE/:uid (BLOCKING), BUG 2 — Blank displayName from weak OIDC claim reading, BUG 3 — GET /api/events returning all users' events, Bug Details, Deviations from Plan, Known Stubs, Operator Actions Required (+6 more)
+
+### Community 52 - "Community 52"
+Cohesion: 0.16
+Nodes (11): fetchEvents(), fetchMe(), ALLDAY_OCCURRENCE, makeQueryClient(), mockEventsServiceSet, renderWithClient(), TIMED_OCCURRENCE, CalendarOccurrence (+3 more)
+
+### Community 53 - "Community 53"
+Cohesion: 0.13
+Nodes (14): Dev-auth bypass (Phase 2+ local development), FamilySync — Deployment & Live-Verification Runbook, Gate 2 — Live verification checklist (`01-HUMAN-UAT.md`), Newt connector, Prerequisites (both modes), ⚠️ Same-parent-domain requirement (Pitfall 1), ⚠️ SSE idle timeout (Phase 4 dependency, issue #1034), Step 1 — Register the OIDC client in Authelia (+6 more)
+
+### Community 54 - "Community 54"
+Cohesion: 0.13
+Nodes (14): compilerOptions, esModuleInterop, forceConsistentCasingInFileNames, jsx, lib, module, moduleResolution, noEmit (+6 more)
+
+### Community 55 - "Community 55"
+Cohesion: 0.13
+Nodes (14): Add After Validation (v1.x), Anti-Features (Deliberately Exclude), Competitor Feature Analysis, Dependency Notes, Differentiators (Competitive Advantage for This Product), Feature Dependencies, Feature Landscape, Feature Prioritization Matrix (+6 more)
+
+### Community 56 - "Community 56"
+Cohesion: 0.14
+Nodes (13): Area Selection, Broker access model, Claude's Discretion, Credential storage, Deferred Ideas, Deployment scope, Infra validation scope, Member color assignment (+5 more)
+
+### Community 57 - "Community 57"
+Cohesion: 0.14
+Nodes (13): CR-01: Edit-as-move silently strips a recurring series' RRULE, Critical Issues, IN-01: `RRULE_PRESETS` round-trip is lossy for any parameterized RRULE, IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00, IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields, Info, Phase 3: Code Review Report (Re-Review, Iteration 2), Summary (+5 more)
+
+### Community 58 - "Community 58"
+Cohesion: 0.14
+Nodes (13): Architectural Constraints & Anti-Patterns, Codebase Concerns, Dependencies at Risk, Fragile Areas, Infrastructure & Deployment Concerns, Known Bugs, Known Limitations (Documented as Design Decisions), Missing Critical Features (+5 more)
+
+### Community 59 - "Community 59"
+Cohesion: 0.18
+Nodes (6): BeforeInstallPromptEvent, InstallPrompt(), IOS_STEPS, isIOSSafariNonStandalone(), useAndroidInstallPrompt(), WalkthroughSheetProps
+
+### Community 60 - "Community 60"
+Cohesion: 0.14
+Nodes (13): BUG A — Event times written 4 hours off (local serialized as UTC), BUG A — write-path timezone serialization, BUG B — Created events attach to the wrong user's calendar; poller creates duplicate calendar rows, BUG B — wrong-calendar attach + duplicate calendar rows, Current Focus, Debug Session: write-path-event-bugs, Eliminated, Environment (+5 more)
+
+### Community 61 - "Community 61"
+Cohesion: 0.27
+Nodes (9): buildCalendarConfig(), CalendarConfig, MemberCalendarConfig, ScheduleXCalendarEntry, deriveScheduleXColors(), hexToContainer(), hexToOnContainer(), hexToRgb() (+1 more)
+
+### Community 62 - "Community 62"
+Cohesion: 0.14
+Nodes (13): Calendar → Fastmail (NOT self-hosted), Display + aggregation → custom app (the actual product), FamilySync Architecture Decisions, Frontend → React PWA, Household, Infrastructure, Lists → custom app backend (MariaDB), Net result (+5 more)
+
+### Community 63 - "Community 63"
+Cohesion: 0.14
+Nodes (13): Authentication & Onboarding, Calendar, Calendar, Display, Lists, Notifications, Out of Scope, PWA & Install (+5 more)
+
+### Community 64 - "Community 64"
+Cohesion: 0.14
+Nodes (13): Clipboard, Complex Workflows, Error Handling, File Downloads, Frames and Iframes, Geolocation, JavaScript Execution, Media Emulation (+5 more)
+
+### Community 65 - "Community 65"
+Cohesion: 0.15
+Nodes (12): Auto-fixed Issues, Dev-Auth Bypass (Task 2), Deviations from Plan, ICS Fixtures (Task 1), Known Stubs, Phase 02 Plan 01: Foundation — Schema Columns, Test Harness, Dev-Auth Bypass Summary, PWA Test Harness (Task 1), RED Test Stubs (Task 1) (+4 more)
+
+### Community 66 - "Community 66"
+Cohesion: 0.15
+Nodes (12): Auto-fixed Issues, Deviations from Plan, Human Verify Checkpoint (Task 3 — awaiting operator), Known Stubs, Phase 02 Plan 05: Calendar UX — Popover, Chrome, States Summary, Self-Check: PASSED, Task 1: EventDetailPopover + CalendarShell wiring (TDD), Task 2: Chrome components, state branches, EventProof retired (+4 more)
+
+### Community 67 - "Community 67"
+Cohesion: 0.15
+Nodes (12): Auto-fixed Issues, Deviations from Plan, Known Stubs, Phase 03 Plan 06: Edit/Delete + SyncStateToast Summary, Self-Check: PASSED, Task 1 — Client calls + Zustand keys (RED: `8357cf9`, GREEN: `8aeacc8`), Task 2 — SyncStateToast (RED: `6874e1a`, GREEN: `aa7c4c3`), Task 3 — EventDetailPopover footer + DeleteConfirmationDialog (RED: `2fbeffe`, GREEN: `40322e1`) (+4 more)
+
+### Community 68 - "Community 68"
+Cohesion: 0.15
+Nodes (12): Auto-fixed Issues, Decisions Made, Deviations from Plan, Infrastructure, Issues Closed, Known Stubs, Phase 03 Plan 10: Outbox Worker ICS Builder Wiring Summary, Self-Check: PASSED (+4 more)
+
+### Community 69 - "Community 69"
+Cohesion: 0.15
+Nodes (9): mockDelete, mockDeleteWhere, mockFrom, mockInsert, mockLimit, mockOnDuplicateKeyUpdate, mockSelect, mockValues (+1 more)
+
+### Community 70 - "Community 70"
+Cohesion: 0.15
+Nodes (12): Accumulated Context, Blockers/Concerns, Current Position, Decisions, Deferred Items, Pending Todos, Performance Metrics, Project Reference (+4 more)
+
+### Community 71 - "Community 71"
+Cohesion: 0.17
+Nodes (11): Architectural Responsibility Map, Assumptions Log, Don't Hand-Roll, Environment Availability, Metadata, Open Questions (DEFERRED TO SPIKE — resolved empirically in Plan 01-04), Package Legitimacy Audit, Phase 1: Foundation + Broker Spike — Research (+3 more)
+
+### Community 72 - "Community 72"
+Cohesion: 0.17
+Nodes (11): Auto-fixed Issues, Deviations from Plan, Known Stubs, Phase 02 Plan 03: PWA Foundation — Token Layer, Color Utils, Calendar Config, Hydration, Store Summary, Self-Check: PASSED, Task 1: Schedule-X Stack + Token Layer + main.tsx Import Order, Task 2: colorUtils + calendarConfig — RED Stubs Turned GREEN, Task 3: hydrateEvents + calendarStore + windowed fetchEvents — RED Stubs Turned GREEN (+3 more)
+
+### Community 73 - "Community 73"
+Cohesion: 0.17
+Nodes (11): Architectural Responsibility Map, Assumptions Log, Don't Hand-Roll, Environment Availability, Metadata, Open Questions, Package Legitimacy Audit, Phase 2: Calendar Display - Research (+3 more)
+
+### Community 74 - "Community 74"
+Cohesion: 0.17
+Nodes (11): Auto-fixed Issues, Deviations from Plan, Known Stubs, Phase 03 Plan 05: Event Write UI (EventForm + Client Calls) Summary, Self-Check: PASSED, Task 1: Typed write client calls + Zustand form-state keys, Task 2: EventForm modal, Task 3: Mount EventForm + "New Event" FAB/toolbar in CalendarShell (+3 more)
+
+### Community 75 - "Community 75"
+Cohesion: 0.17
+Nodes (11): Auto-fixed Issues, Decisions Made, Deviations from Plan, Known Stubs, Phase 03 Plan 09: Route Schema + OIDC Resolution Fix Summary, Self-Check: PASSED, Tasks Completed, TDD Gate Compliance (+3 more)
+
+### Community 76 - "Community 76"
+Cohesion: 0.17
+Nodes (11): Code Style, Coding Conventions, Comments, Database Patterns, Error Handling, Function Design, Import Organization, Logging (+3 more)
+
+### Community 77 - "Community 77"
+Cohesion: 0.17
+Nodes (11): Common Patterns, Coverage, Fixtures and Factories, Known Testing Gaps, Mocking, Test File Organization, Test Framework, Test Setup (+3 more)
+
+### Community 78 - "Community 78"
+Cohesion: 0.17
+Nodes (11): Active, Constraints, Context, Core Value, Evolution, FamilySync, Key Decisions, Out of Scope (+3 more)
+
+### Community 79 - "Community 79"
+Cohesion: 0.18
+Nodes (10): Auto-fixed Issues, Deviations from Plan, Known Stubs, Phase 02 Plan 02: Windowed /api/events — Recurrence Expansion + Color Join Summary, Self-Check: PASSED, Task 1: expandOccurrences() — apps/api/src/broker/expand.ts, Task 2: Windowed /api/events — apps/api/src/routes/events.ts, Task 3: Shared-Family Calendar Marking — RESOLVED BY DEFERRAL (+2 more)
+
+### Community 80 - "Community 80"
+Cohesion: 0.18
+Nodes (10): Auto-fixed Issues, Deviations from Plan, Known Stubs, Phase 02 Plan 04: CalendarShell — Schedule-X Mounted, Wired to Data Pipeline Summary, Self-Check: PASSED, Task 1: CalendarShell + App.tsx, Task 2: CalendarShell Render Smoke Test (CAL-03), Threat Flags (+2 more)
+
+### Community 81 - "Community 81"
+Cohesion: 0.18
+Nodes (10): CR-01: Edit-as-move silently strips a recurring series' RRULE, Fixed Issues, IN-01: `RRULE_PRESETS` round-trip is lossy for parameterized RRULEs, IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00, IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields, Phase 3: Code Review Fix Report (Iteration 2), WR-01: Edit form provides no indication recurrence is locked, WR-02: `handleAllDayToggle` can leave end-date inconsistent (+2 more)
+
+### Community 82 - "Community 82"
+Cohesion: 0.18
+Nodes (10): CR-01: Edit-as-move silently strips a recurring series' RRULE, Fixed Issues, IN-01: `RRULE_PRESETS` round-trip is lossy for parameterized RRULEs, IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00, IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields, Phase 3: Code Review Fix Report (Iteration 2), WR-01: Edit form provides no indication recurrence is locked, WR-02: `handleAllDayToggle` can leave end-date inconsistent (+2 more)
+
+### Community 83 - "Community 83"
+Cohesion: 0.18
+Nodes (10): Claude's Discretion, Deferred Ideas, List & item behavior — Checked items & delete guard, List & item behavior — Privacy (refined), List & item behavior — Sharing, Lists navigation, Live feel & conflicts, Phase 4: Shared Lists + Live Sync - Discussion Log (+2 more)
+
+### Community 84 - "Community 84"
+Cohesion: 0.18
+Nodes (10): Deviations from Plan, Known Stubs, Quick Task 260606-tv8: Fix Missing Sign-in Redirect in the PWA — Summary, Self-Check: PASSED, Task 1: GET /api/login backend route + tests (commit 237ec49), Task 2: One-shot login-redirect helper + tests (commit 6dc9ccd), Task 3: CalendarShell meQuery wiring (commit c2e0ab1), Threat Flags (+2 more)
+
+### Community 85 - "Community 85"
+Cohesion: 0.25
+Nodes (9): CalendarOccurrence, EventDetailPopover(), formatDateTime(), ScheduleXEventModalProps, ALLDAY_OCCURRENCE, {
+  mockSetOpenEventId,
+  mockSetEventForm,
+  mockSetDeleteDialog,
+}, OCCURRENCE_WITH_HTML, TIMED_OCCURRENCE (+1 more)
+
+### Community 86 - "Community 86"
+Cohesion: 0.25
+Nodes (8): CalendarOccurrence, expandOccurrences(), formatUtcOffset(), makeOccurrenceId(), OccurrenceMeta, serializeTime(), __dirname, FIXTURES
+
+### Community 87 - "Community 87"
+Cohesion: 0.29
+Nodes (6): CalendarShell(), isPhone(), resolveDefaultView(), clearLoginRedirect(), maybeRedirectToLogin(), locationStub
+
+### Community 88 - "Community 88"
+Cohesion: 0.18
+Nodes (10): name, packageManager, private, scripts, build, dev:api, dev:pwa, lint (+2 more)
+
+### Community 89 - "Community 89"
+Cohesion: 0.20
+Nodes (10): Anti-Patterns to Avoid, Architecture Patterns, Pattern 1: @hono/oidc-auth Middleware Wiring, Pattern 2: Drizzle/MariaDB Schema, Pattern 3: CalDAV Broker (tsdav), Pattern 4: AES-GCM App-Password Encryption, Pattern 5: Pangolin SSE Smoke Test, Pattern 6: Docker Compose Layout (+2 more)
+
+### Community 90 - "Community 90"
+Cohesion: 0.20
+Nodes (9): IN-01: `RRULE_PRESETS` round-trip is lossy for any parameterized RRULE, IN-02: Move-path RRULE preservation depends silently on `rawVevent` being non-empty, Info, Iteration-2 fixes — verified, Phase 3: Code Review Report (Re-Review, Iteration 3 — final --auto pass), Summary, Warnings, WR-01: Missing cached etag still produces an unconditional PUT/DELETE (D-08 gap) (+1 more)
+
+### Community 91 - "Community 91"
+Cohesion: 0.24
+Nodes (5): COLOR_PALETTE, mockDb, db, pool, healthRouter
+
+### Community 92 - "Community 92"
+Cohesion: 0.20
+Nodes (9): mockCalendarsSelectResult, mockCreateFastmailClient, mockCredentialsSelectResult, mockFetchCalendars, mockSelect, mockSelectFrom, mockSelectLimit, mockSelectWhere (+1 more)
+
+### Community 93 - "Community 93"
+Cohesion: 0.20
+Nodes (9): APIs & External Services, Authentication & Identity, CI/CD & Deployment, Data Storage, Environment Configuration, External Integrations, Monitoring & Observability, Network & Transport (+1 more)
+
+### Community 94 - "Community 94"
+Cohesion: 0.22
+Nodes (5): AppNav(), AppNavProps, ColorLegend(), ColorLegendProps, LegendMember
+
+### Community 95 - "Community 95"
+Cohesion: 0.22
+Nodes (8): 1. AUTH-01 — Live Authelia OIDC login over the public Pangolin URL, 2. AUTH-02 — Session persists across browser restart, 3. AUTH-03 — Second member gets a distinct color, 4. SSE-over-Pangolin smoke test (de-risks Phase 4), Current Test, Gaps, Summary, Tests
+
+### Community 96 - "Community 96"
+Cohesion: 0.22
+Nodes (8): CAL-08: Personal Calendar ACL Spike — Decision Record, Calendars Discovered, Decision, How to Run the Spike, Notes, Questions Resolved, Results, Status
+
+### Community 97 - "Community 97"
+Cohesion: 0.22
+Nodes (8): 1. Color-coded rendering, 2. All four views render + grid scrolls, 3. Recurring events across DST, 4. All-day banners — no date shift, Current Test, Gaps, Summary, Tests
+
+### Community 98 - "Community 98"
+Cohesion: 0.22
+Nodes (9): Anti-Patterns to Avoid, Architecture Patterns, Pattern 1: `/api/events` Windowed Query with Expansion, Pattern 2: Schedule-X Event Format (Temporal, not ISO strings), Pattern 3: Schedule-X Calendar Configuration, Pattern 4: TanStack Query + onRangeUpdate Wiring, Pattern 5: Dev-Auth Bypass Middleware, Recommended Project Structure (+1 more)
+
+### Community 99 - "Community 99"
+Cohesion: 0.22
+Nodes (8): Blocker bugs found + fixed live (all committed + deployed), Deferred / carried forward, Dependency graph, Outcome, Phase 03 Plan 08: Gate 2 Live Verification — Summary, Self-Check, Tech tracking, Verification method
+
+### Community 100 - "Community 100"
+Cohesion: 0.22
+Nodes (8): Advanced Mocking with run-code, CLI Route Commands, Conditional Response Based on Request, Delayed Response, Modify Real Response, Request Mocking, Simulate Network Failures, URL Patterns
+
+### Community 101 - "Community 101"
+Cohesion: 0.22
+Nodes (8): 1. Use Semantic Locators, 2. Explore Before Recording, 3. Add Assertions Manually, Best Practices, Building a Test File, Example Workflow, How It Works, Test Generation
+
+### Community 102 - "Community 102"
+Cohesion: 0.22
+Nodes (8): 1. Use Descriptive Filenames, 2. Record entire hero scripts., Basic Recording, Best Practices, Limitations, Overlay API Summary, Tracing vs Video, Video Recording
+
+### Community 103 - "Community 103"
+Cohesion: 0.22
+Nodes (8): Calendar host decision — RESOLVED, Email scope — RESOLVED, Open, Research Questions, Resolved, RQ-001 — Vikunja MariaDB compatibility — SUPERSEDED, RQ-002 — CalDAV server: Radicale vs Baikal — SUPERSEDED, RQ-003 — Fastmail calendar API: JMAP vs CalDAV
+
+### Community 104 - "Community 104"
+Cohesion: 0.25
+Nodes (8): Common Pitfalls, Pitfall 1: OIDC_AUTH_EXTERNAL_URL Missing Behind Pangolin, Pitfall 2: All-Day Event DATE Stored as DATETIME, Pitfall 3: tsdav createDAVClient Requires Account Discovery Round-Trip, Pitfall 4: node-cron v4 vs v3 API Change, Pitfall 5: Drizzle `onDuplicateKeyUpdate` Requires MariaDB 10.3+, Pitfall 6: Fastmail ctag vs syncToken Field Availability, Pitfall 7: Authelia Client Secret — Plain vs Hashed
+
+### Community 105 - "Community 105"
+Cohesion: 0.25
+Nodes (7): Manual-Only Verifications, Per-Task Verification Map, Phase 1 — Validation Strategy, Sampling Rate, Test Infrastructure, Validation Sign-Off, Wave 0 Requirements (created in Plan 01 Task 1)
+
+### Community 106 - "Community 106"
+Cohesion: 0.25
+Nodes (7): Claude's Discretion, Color & shared-vs-personal, Default view & per-device, Deferred Ideas, Event detail density, Phase 2: Calendar Display - Discussion Log, Visual model → Theming architecture
+
+### Community 107 - "Community 107"
+Cohesion: 0.25
+Nodes (8): Common Pitfalls, Pitfall 1: `firstDayOfWeek` Temporal Numbering Mismatch, Pitfall 2: All-Day Events Shifting by One Day, Pitfall 3: Missing VTIMEZONE Registration Causes DST-Shifted Occurrences, Pitfall 4: Schedule-X ISO String Events Silently Fail, Pitfall 5: Unwindowed `/api/events` Endpoint, Pitfall 6: `@schedule-x/react` Version Behind `@schedule-x/calendar`, Pitfall 7: Dev-Auth Bypass Active in Production
+
+### Community 108 - "Community 108"
+Cohesion: 0.25
+Nodes (7): Manual-Only Verifications, Per-Task Verification Map, Phase 02 — Validation Strategy, Sampling Rate, Test Infrastructure, Validation Sign-Off, Wave 0 Requirements
+
+### Community 109 - "Community 109"
+Cohesion: 0.25
+Nodes (8): Common Pitfalls, Pitfall 1: Service Worker intercepts `/callback` and breaks OIDC login, Pitfall 2: iOS standalone mode breaks on OIDC redirect to auth.DOMAIN, Pitfall 3: D-13 DATE vs DATETIME coercion in VEVENT building, Pitfall 4: ETag not returned after PUT on Fastmail, Pitfall 5: Edit-as-move (D-04) partial-failure, Pitfall 6: `navigateFallbackDenylist` not respected in dev mode, Pitfall 7: Outbox worker runs without a valid DAVCalendar object for re-sync
+
+### Community 110 - "Community 110"
+Cohesion: 0.25
+Nodes (7): Manual-Only Verifications, Per-Task Verification Map, Phase 3 — Validation Strategy, Sampling Rate, Test Infrastructure, Validation Sign-Off, Wave 0 Requirements
+
+### Community 111 - "Community 111"
+Cohesion: 0.25
+Nodes (8): Common Pitfalls, Pitfall 1: SSE fan-out leaking private list events to all clients, Pitfall 2: Float-based positions exhausting precision, Pitfall 3: Raw EventSource reconnect storm, Pitfall 4: `drizzle-kit push` on populated MariaDB, Pitfall 5: dnd-kit drag handle with touch — accidental drags, Pitfall 6: React Router + vite-plugin-pwa navigation fallback, Pitfall 7: SSE auth with `withCredentials`
+
+### Community 112 - "Community 112"
+Cohesion: 0.25
+Nodes (7): Manual-Only Verifications, Per-Task Verification Map, Phase 4 — Validation Strategy, Sampling Rate, Test Infrastructure, Validation Sign-Off, Wave 0 Requirements
+
+### Community 113 - "Community 113"
+Cohesion: 0.25
+Nodes (7): Commits, Deviations from Plan, Evidence Recorded (verbatim), Quick Task 260607-u8o: Record SSE-over-Pangolin Smoke Test PASS Summary, Self-Check: PASSED, Verification, What Was Done
+
+### Community 114 - "Community 114"
+Cohesion: 0.25
+Nodes (7): WritableCalendar, EDIT_OCCURRENCE, LATE_OCCURRENCE, {
+  mockSetEventForm,
+  mockSetLastSyncedUid,
+  mockCreateEvent,
+  mockUpdateEvent,
+  mockFetchWritableCalendars,
+}, ONE_CALENDAR, RECURRING_OCCURRENCE, TWO_CALENDARS
+
+### Community 115 - "Community 115"
+Cohesion: 0.25
+Nodes (4): DEFAULT_FORM_PAYLOAD, FAKE_CRED_ROW, mockPendingRows, {
+  mockUpdateSet,
+  mockUpdate,
+  mockWherePending,
+  mockWhereCalEvents,
+  mockFromFn,
+  mockSelectFn,
+  mockDecryptPassword,
+}
+
+### Community 116 - "Community 116"
+Cohesion: 0.25
+Nodes (7): Configuration, Frameworks, Key Dependencies, Languages, Platform Requirements, Runtime, Technology Stack
+
+### Community 117 - "Community 117"
+Cohesion: 0.25
+Nodes (7): Codebase Structure, Directory Layout, Directory Purposes, Key File Locations, Naming Conventions, Special Directories, Where to Add New Code
+
+### Community 118 - "Community 118"
+Cohesion: 0.25
+Nodes (4): ErrorBoundary, ErrorBoundaryProps, ErrorBoundaryState, queryClient
+
+### Community 119 - "Community 119"
+Cohesion: 0.25
+Nodes (5): renderPopover(), renderForm(), SyncStateToast(), {
+  mockLastSyncedUid,
+  mockSetLastSyncedUid,
+  mockFetchSyncStatus,
+}, renderToast()
+
+### Community 120 - "Community 120"
+Cohesion: 0.29
+Nodes (6): Architectural Decisions, Capability Proven End-to-End, Out of Scope (Deferred to Later Slices), Stack Touched in Phase 1, Subsequent Slice Plan, Walking Skeleton — FamilySync
+
+### Community 121 - "Community 121"
+Cohesion: 0.33
+Nodes (5): deleteEvent(), DeleteConfirmationDialog(), makeQueryClient(), {
+  mockDeleteEvent,
+  mockSetDeleteDialog,
+  mockSetLastSyncedUid,
+  mockSetOpenEventId,
+  mockDeleteDialogOpen,
+  mockDeleteDialogUid,
+}, renderDialog()
+
+### Community 122 - "Community 122"
+Cohesion: 0.38
+Nodes (5): decryptPassword(), EncryptedPayload, encryptPassword(), getKey(), getCrypto()
+
+### Community 123 - "Community 123"
+Cohesion: 0.29
+Nodes (4): shimmerStyle, SkeletonCalendar(), SkeletonCalendarProps, SkeletonVariant
+
+### Community 124 - "Community 124"
+Cohesion: 0.38
+Nodes (5): BreakpointGroup, CalendarStore, getBreakpointGroup(), readPersistedView(), viewStorageKey()
+
+### Community 125 - "Community 125"
+Cohesion: 0.33
+Nodes (6): Fixture ICS Files (test corpus), Phase Requirements → Test Map, Sampling Rate, Test Framework, Validation Architecture, Wave 0 Gaps
+
+### Community 126 - "Community 126"
+Cohesion: 0.33
+Nodes (5): .from(calendarEvents).innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id)), Reference idioms already in events.ts:, .where(or(eq(calendars.userId, currentUserId), eq(calendars.isShared, true))), - Working join: GET / at ~line 142-183 uses, - Working ownership predicate: /writable-calendars at ~line 501-509 uses
+
+### Community 127 - "Community 127"
+Cohesion: 0.33
+Nodes (6): git, branching_strategy, create_tag, milestone_branch_template, phase_branch_template, quick_branch_template
+
+### Community 128 - "Community 128"
+Cohesion: 0.40
+Nodes (5): Phase Requirements → Test Map, Sampling Rate, Test Framework, Validation Architecture, Wave 0 Gaps (must create before implementation)
+
+### Community 129 - "Community 129"
+Cohesion: 0.40
+Nodes (5): Core (already installed — no new installs for write-back), Installation, New Installs (PWA layer only), rrule — NOT needed for Phase 3, Standard Stack
+
+### Community 130 - "Community 130"
+Cohesion: 0.40
+Nodes (5): Phase Requirements → Test Map, Sampling Rate, Test Framework, Validation Architecture, Wave 0 Gaps
+
+### Community 131 - "Community 131"
+Cohesion: 0.40
+Nodes (5): Code Examples, Verified Pattern: Drizzle schema conventions (existing schema.ts), Verified Pattern: Hono streamSSE (existing sse.ts), Verified Pattern: NavLink with active styling, Verified Pattern: React Query optimistic update
+
+### Community 132 - "Community 132"
+Cohesion: 0.40
+Nodes (5): Primary (HIGH confidence — VERIFIED from codebase), Primary (HIGH confidence — VERIFIED via npm registry + Context7), Secondary (MEDIUM confidence — CITED from official docs), Sources, Tertiary (LOW confidence — ASSUMED)
+
+### Community 133 - "Community 133"
+Cohesion: 0.40
+Nodes (4): browser, browserName, launchOptions, channel
+
+### Community 134 - "Community 134"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 01), STRIDE Threat Register, Trust Boundaries
+
+### Community 135 - "Community 135"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 02), STRIDE Threat Register, Trust Boundaries
+
+### Community 136 - "Community 136"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 03), STRIDE Threat Register, Trust Boundaries
+
+### Community 137 - "Community 137"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 04), STRIDE Threat Register, Trust Boundaries
+
+### Community 138 - "Community 138"
+Cohesion: 0.50
+Nodes (4): Claude's Discretion, Deferred Ideas (OUT OF SCOPE), Locked Decisions, User Constraints (from CONTEXT.md)
+
+### Community 139 - "Community 139"
+Cohesion: 0.50
+Nodes (4): Code Examples, Hono app bootstrap with all middleware, Serving PWA static files from Hono, User upsert with color assignment
+
+### Community 140 - "Community 140"
+Cohesion: 0.50
+Nodes (4): Core (Phase 1 scope), Phase 1 backend install, Phase 1 frontend install, Standard Stack
+
+### Community 141 - "Community 141"
+Cohesion: 0.50
+Nodes (4): Primary (HIGH confidence), Secondary (MEDIUM confidence), Sources, Tertiary (LOW confidence)
+
+### Community 142 - "Community 142"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 01), STRIDE Threat Register, Trust Boundaries
+
+### Community 143 - "Community 143"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 02), STRIDE Threat Register, Trust Boundaries
+
+### Community 144 - "Community 144"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 03), STRIDE Threat Register, Trust Boundaries
+
+### Community 145 - "Community 145"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 04), STRIDE Threat Register, Trust Boundaries
+
+### Community 146 - "Community 146"
+Cohesion: 0.50
+Nodes (3): Artifacts this phase produces (Plan 05), STRIDE Threat Register, Trust Boundaries
+
+### Community 147 - "Community 147"
+Cohesion: 0.50
+Nodes (4): All-Day Event: Server Format to Schedule-X PlainDate, Code Examples, Schedule-X CSS Token Override Pattern, VTIMEZONE Registration + ICAL.RecurExpansion (complete pattern)
+
+### Community 148 - "Community 148"
+Cohesion: 0.50
+Nodes (4): Claude's Discretion, Deferred Ideas (OUT OF SCOPE), Locked Decisions, User Constraints (from CONTEXT.md)
+
+### Community 149 - "Community 149"
+Cohesion: 0.50
+Nodes (4): Core (all versions verified against npm registry 2026-06-04), Installation (PWA only), No New Backend Dependencies Needed, Standard Stack
+
+### Community 150 - "Community 150"
+Cohesion: 0.50
+Nodes (4): Primary (HIGH confidence), Secondary (MEDIUM confidence), Sources, Tertiary (LOW confidence)
+
+### Community 151 - "Community 151"
+Cohesion: 0.50
+Nodes (3): Critical Anti-Patterns (do NOT repeat these), Infrastructure State, Required Reading (in order)
+
+### Community 152 - "Community 152"
+Cohesion: 0.50
+Nodes (4): Claude's Discretion, Deferred Ideas (OUT OF SCOPE), Locked Decisions, User Constraints (from CONTEXT.md)
+
+### Community 153 - "Community 153"
+Cohesion: 0.50
+Nodes (4): Code Examples, Create a recurring event (whole-series RRULE presets), Detect installed state (for hiding install prompts), Sync-state poll with TanStack Query
+
+### Community 154 - "Community 154"
+Cohesion: 0.50
+Nodes (4): Primary (HIGH confidence), Secondary (MEDIUM confidence), Sources, Tertiary (LOW confidence / ASSUMED)
+
+### Community 155 - "Community 155"
+Cohesion: 0.50
+Nodes (3): Phase Goal, STRIDE Threat Register, Trust Boundaries
+
+### Community 156 - "Community 156"
+Cohesion: 0.50
+Nodes (4): Claude's Discretion, Deferred Ideas (OUT OF SCOPE), Locked Decisions, User Constraints (from CONTEXT.md)
+
+### Community 157 - "Community 157"
+Cohesion: 0.50
+Nodes (4): Phase Requirements → Test Map, Test Framework, Validation Architecture, Wave 0 Gaps
+
+### Community 158 - "Community 158"
+Cohesion: 0.50
+Nodes (3): Infrastructure State, Open Decisions for the Planner (intentionally NOT pre-decided), Required Reading (in order)
+
+### Community 160 - "Community 160"
+Cohesion: 0.50
+Nodes (3): Adopt drizzle generate+migrate workflow (retire db:push on MariaDB), Goal, Tasks
+
+### Community 161 - "Community 161"
+Cohesion: 0.50
+Nodes (3): Context to bring into the session, Kick off FamilySync with /gsd:new-project, Pre-work before running
+
+### Community 162 - "Community 162"
+Cohesion: 0.67
+Nodes (3): Applicable ASVS Categories (Level 1), Known Threat Patterns for This Stack, Security Domain
+
+### Community 163 - "Community 163"
+Cohesion: 0.67
+Nodes (3): Applicable ASVS Categories, Known Threat Patterns for This Phase, Security Domain
+
+### Community 164 - "Community 164"
+Cohesion: 0.67
+Nodes (3): Backend: `/api/events` Evolution, Current state (Phase 1), Target state (Phase 2)
+
+### Community 173 - "Community 173"
+Cohesion: 0.67
+Nodes (3): Applicable ASVS Categories, Known Threat Patterns, Security Domain
+
+### Community 174 - "Community 174"
+Cohesion: 0.67
+Nodes (3): Architecture Patterns, Recommended Project Structure Additions, System Architecture Diagram
+
+### Community 180 - "Community 180"
+Cohesion: 0.67
+Nodes (3): Applicable ASVS Categories, Known Threat Patterns for This Phase, Security Domain
+
+### Community 181 - "Community 181"
+Cohesion: 0.67
+Nodes (3): Architecture Patterns, Recommended Project Structure, System Architecture Diagram
+
+### Community 182 - "Community 182"
+Cohesion: 0.67
+Nodes (3): Core (already installed — no new installs needed), New Dependencies (must install), Standard Stack
+
+### Community 184 - "Community 184"
+Cohesion: 0.67
+Nodes (3): plan_review, source_grounding, source_grounding_authority
+
+## Knowledge Gaps
+- **1565 isolated node(s):** `allow`, `version`, `timestamp`, `phase`, `phase_name` (+1560 more)
+  These have ≤1 connection - possible missing edges or undocumented components.
+- **25 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
+
+## Suggested Questions
+_Questions this graph is uniquely positioned to answer:_
+
+- **Why does `InstallPrompt()` connect `Community 59` to `Community 87`?**
+  _High betweenness centrality (0.001) - this node is a cross-community bridge._
+- **Why does `ErrorBoundary` connect `Community 118` to `Community 119`?**
+  _High betweenness centrality (0.001) - this node is a cross-community bridge._
+- **Why does `useCalendarStore` connect `Community 85` to `Community 16`, `Community 114`, `Community 87`, `Community 119`, `Community 121`, `Community 124`?**
+  _High betweenness centrality (0.001) - this node is a cross-community bridge._
+- **What connects `allow`, `version`, `timestamp` to the rest of the system?**
+  _1565 weakly-connected nodes found - possible documentation gaps or missing edges._
+- **Should `Community 0` be split into smaller, more focused modules?**
+  _Cohesion score 0.045454545454545456 - nodes in this community are weakly interconnected._
+- **Should `Community 1` be split into smaller, more focused modules?**
+  _Cohesion score 0.05555555555555555 - nodes in this community are weakly interconnected._
+- **Should `Community 2` be split into smaller, more focused modules?**
+  _Cohesion score 0.05555555555555555 - nodes in this community are weakly interconnected._

.planning/intel/API-SURFACE.md

@@ -0,0 +1,105 @@
+# API Surface
+
+> Generated from `.planning/intel/api-map.json`. Do not edit by hand.
+
+## `GET /health`
+
+- **method:** GET
+- **path:** /health
+- **auth:** none
+- **file:** apps/api/src/routes/health.ts
+- **description:** DB liveness probe. Returns { ok: true, db: 'up' } or 503.
+
+## `GET /callback`
+
+- **method:** GET
+- **path:** /callback
+- **auth:** none (OIDC callback — must be before auth guard)
+- **file:** apps/api/src/index.ts
+- **description:** OIDC authorization-code callback. Processed by @hono/oidc-auth processOAuthCallback.
+
+## `GET /api/login`
+
+- **method:** GET
+- **path:** /api/login
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/index.ts
+- **description:** Auth entry point. Redirects to / after successful OIDC login. PWA navigates here for re-auth.
+
+## `GET /api/me`
+
+- **method:** GET
+- **path:** /api/me
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/routes/me.ts
+- **response:** { user: { id: number, displayName: string|null, color: string } }
+- **description:** Returns authenticated member's identity and assigned color. Upserts user row on first call.
+
+## `GET /api/events`
+
+- **method:** GET
+- **path:** /api/events
+- **auth:** oidcAuthMiddleware
+- **params:** start (YYYY-MM-DD, required), end (YYYY-MM-DD, required)
+- **file:** apps/api/src/routes/events.ts
+- **response:** { occurrences: CalendarOccurrence[] }
+- **description:** Windowed calendar events. Max 90-day window. Reads only from MariaDB cache; never hits Fastmail. Expands RRULEs server-side.
+
+## `POST /api/events/create`
+
+- **method:** POST
+- **path:** /api/events/create
+- **auth:** oidcAuthMiddleware
+- **body:** CreateEventPayload (title, allDay, start, end, recurrence?, location?, description?, calendarUrl?)
+- **file:** apps/api/src/routes/events.ts
+- **response:** 202 { uid: string }
+- **description:** Enqueues create to calendarOutbox. Async CalDAV write-back via outbox worker. Returns uid immediately.
+
+## `PATCH /api/events/:uid/edit`
+
+- **method:** PATCH
+- **path:** /api/events/:uid/edit
+- **auth:** oidcAuthMiddleware
+- **params:** uid (path)
+- **body:** CreateEventPayload
+- **file:** apps/api/src/routes/events.ts
+- **response:** 202 { uid: string }
+- **description:** Enqueues update (or delete+create pair for calendar-move) to calendarOutbox. Async write-back.
+
+## `DELETE /api/events/:uid`
+
+- **method:** DELETE
+- **path:** /api/events/:uid
+- **auth:** oidcAuthMiddleware
+- **params:** uid (path)
+- **file:** apps/api/src/routes/events.ts
+- **response:** 202 { uid: string }
+- **description:** Enqueues delete to calendarOutbox with cached etag (If-Match). Async write-back.
+
+## `GET /api/events/sync-status`
+
+- **method:** GET
+- **path:** /api/events/sync-status
+- **auth:** oidcAuthMiddleware
+- **params:** uid (query, required)
+- **file:** apps/api/src/routes/events.ts
+- **response:** { uid: string, status: 'pending'|'done'|'failed'|'dead', error?: string }
+- **description:** Outbox status poll for a given event UID, scoped to current member. Used by SyncStateToast.
+
+## `GET /api/events/writable-calendars`
+
+- **method:** GET
+- **path:** /api/events/writable-calendars
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/routes/events.ts
+- **response:** { calendars: [{ url, displayName, color, isShared }] }
+- **description:** Authoritative D-03 writable set: member's own calendars + shared Family calendar. Client never derives this itself.
+
+## `GET /api/sse/heartbeat`
+
+- **method:** GET
+- **path:** /api/sse/heartbeat
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/routes/sse.ts
+- **response:** text/event-stream — event: heartbeat, data: { ts, id } every 10s
+- **description:** SSE smoke-test endpoint for Pangolin tunnel validation. Phase 4 list-sync events not yet wired.

.planning/intel/api-map.json

@@ -0,0 +1,100 @@
+{
+  "_meta": {
+    "updated_at": "2026-06-09T00:00:00Z",
+    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
+    "version": 1
+  },
+  "entries": {
+    "GET /health": {
+      "method": "GET",
+      "path": "/health",
+      "auth": "none",
+      "file": "apps/api/src/routes/health.ts",
+      "description": "DB liveness probe. Returns { ok: true, db: 'up' } or 503."
+    },
+    "GET /callback": {
+      "method": "GET",
+      "path": "/callback",
+      "auth": "none (OIDC callback — must be before auth guard)",
+      "file": "apps/api/src/index.ts",
+      "description": "OIDC authorization-code callback. Processed by @hono/oidc-auth processOAuthCallback."
+    },
+    "GET /api/login": {
+      "method": "GET",
+      "path": "/api/login",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/index.ts",
+      "description": "Auth entry point. Redirects to / after successful OIDC login. PWA navigates here for re-auth."
+    },
+    "GET /api/me": {
+      "method": "GET",
+      "path": "/api/me",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/routes/me.ts",
+      "response": "{ user: { id: number, displayName: string|null, color: string } }",
+      "description": "Returns authenticated member's identity and assigned color. Upserts user row on first call."
+    },
+    "GET /api/events": {
+      "method": "GET",
+      "path": "/api/events",
+      "auth": "oidcAuthMiddleware",
+      "params": ["start (YYYY-MM-DD, required)", "end (YYYY-MM-DD, required)"],
+      "file": "apps/api/src/routes/events.ts",
+      "response": "{ occurrences: CalendarOccurrence[] }",
+      "description": "Windowed calendar events. Max 90-day window. Reads only from MariaDB cache; never hits Fastmail. Expands RRULEs server-side."
+    },
+    "POST /api/events/create": {
+      "method": "POST",
+      "path": "/api/events/create",
+      "auth": "oidcAuthMiddleware",
+      "body": "CreateEventPayload (title, allDay, start, end, recurrence?, location?, description?, calendarUrl?)",
+      "file": "apps/api/src/routes/events.ts",
+      "response": "202 { uid: string }",
+      "description": "Enqueues create to calendarOutbox. Async CalDAV write-back via outbox worker. Returns uid immediately."
+    },
+    "PATCH /api/events/:uid/edit": {
+      "method": "PATCH",
+      "path": "/api/events/:uid/edit",
+      "auth": "oidcAuthMiddleware",
+      "params": ["uid (path)"],
+      "body": "CreateEventPayload",
+      "file": "apps/api/src/routes/events.ts",
+      "response": "202 { uid: string }",
+      "description": "Enqueues update (or delete+create pair for calendar-move) to calendarOutbox. Async write-back."
+    },
+    "DELETE /api/events/:uid": {
+      "method": "DELETE",
+      "path": "/api/events/:uid",
+      "auth": "oidcAuthMiddleware",
+      "params": ["uid (path)"],
+      "file": "apps/api/src/routes/events.ts",
+      "response": "202 { uid: string }",
+      "description": "Enqueues delete to calendarOutbox with cached etag (If-Match). Async write-back."
+    },
+    "GET /api/events/sync-status": {
+      "method": "GET",
+      "path": "/api/events/sync-status",
+      "auth": "oidcAuthMiddleware",
+      "params": ["uid (query, required)"],
+      "file": "apps/api/src/routes/events.ts",
+      "response": "{ uid: string, status: 'pending'|'done'|'failed'|'dead', error?: string }",
+      "description": "Outbox status poll for a given event UID, scoped to current member. Used by SyncStateToast."
+    },
+    "GET /api/events/writable-calendars": {
+      "method": "GET",
+      "path": "/api/events/writable-calendars",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/routes/events.ts",
+      "response": "{ calendars: [{ url, displayName, color, isShared }] }",
+      "description": "Authoritative D-03 writable set: member's own calendars + shared Family calendar. Client never derives this itself."
+    },
+    "GET /api/sse/heartbeat": {
+      "method": "GET",
+      "path": "/api/sse/heartbeat",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/routes/sse.ts",
+      "response": "text/event-stream — event: heartbeat, data: { ts, id } every 10s",
+      "description": "SSE smoke-test endpoint for Pangolin tunnel validation. Phase 4 list-sync events not yet wired."
+    }
+  }
+}

.planning/intel/arch-decisions.json

@@ -0,0 +1,69 @@
+{
+  "_meta": {
+    "updated_at": "2026-06-09T00:00:00Z",
+    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
+    "version": 1
+  },
+  "entries": {
+    "broker-cache-api-pattern": {
+      "title": "Broker-Cache-API pattern (two planes never cross)",
+      "decision": "Backend split into a broker plane (apps/api/src/broker/) that owns all Fastmail I/O and an API plane (apps/api/src/routes/) that reads only from MariaDB. Broker crons are not reachable from the HTTP layer.",
+      "files": ["apps/api/src/broker/poller.ts", "apps/api/src/broker/outboxWorker.ts", "apps/api/src/routes/"]
+    },
+    "write-broker-boundary": {
+      "title": "Write-broker boundary invariant",
+      "decision": "No route file imports tsdav or createFastmailClient; no broker file handles HTTP requests. Routes enqueue calendar_outbox rows and return 202 (optimistic-accept); the outbox worker performs the Fastmail write asynchronously.",
+      "files": ["apps/api/src/routes/events.ts", "apps/api/src/broker/write.ts"]
+    },
+    "identity-keying": {
+      "title": "Identity keyed on oidc_iss + oidc_sub",
+      "decision": "Users are keyed on oidc_iss + oidc_sub (never email). A hex color from the palette is auto-assigned on first login.",
+      "files": ["apps/api/src/routes/me.ts", "apps/api/src/auth/middleware.ts"]
+    },
+    "D-03-writable-set": {
+      "title": "D-03 calendar ownership / writable-set predicate",
+      "decision": "Every writable-set query uses WHERE userId = currentUser.id OR isShared = true. Another member's personal calendar is a read-only overlay.",
+      "files": ["apps/api/src/routes/events.ts"]
+    },
+    "D-13-dual-field-dtstart": {
+      "title": "D-13 all-day vs timed events (dual dtstart fields)",
+      "decision": "dtstart_utc is NULL for all-day events; dtstart_date is NULL for timed events. Never coerce DATE to DATETIME.",
+      "files": ["apps/api/src/db/schema.ts"]
+    },
+    "D-16-shared-fastmail-account": {
+      "title": "D-16 shared Fastmail account, per-member credentials",
+      "decision": "Both members share one Fastmail account. Calendar identity in DB is (userId, url) — the same collection URL appears once per member credential. CalDAV credential per member is stored AES-256-GCM encrypted in member_credentials.",
+      "files": ["apps/api/src/db/schema.ts", "apps/api/src/broker/poller.ts"]
+    },
+    "outbox-status-machine": {
+      "title": "Outbox status machine",
+      "decision": "calendar_outbox rows transition pending -> done | failed | dead. failed rows retry up to a limit; dead is terminal. The sync-status endpoint surfaces worst-status-first per uid.",
+      "files": ["apps/api/src/broker/outboxWorker.ts", "apps/api/src/routes/events.ts"]
+    },
+    "oidc-behind-pangolin": {
+      "title": "OIDC behind Pangolin requires OIDC_AUTH_EXTERNAL_URL",
+      "decision": "OIDC_AUTH_EXTERNAL_URL must be set to the public HTTPS URL to construct a correct redirect_uri; without it the callback resolves to the internal container address.",
+      "files": ["apps/api/src/auth/middleware.ts", "apps/api/src/index.ts"]
+    },
+    "dev-auth-bypass": {
+      "title": "Dev auth bypass",
+      "decision": "DEV_AUTH_BYPASS=true with NODE_ENV!=production injects DEV_USER via Hono context; OIDC middleware is never mounted in this mode.",
+      "files": ["apps/api/src/auth/devBypass.js", "apps/api/src/index.ts"]
+    },
+    "pwa-static-serving": {
+      "title": "PWA static serving + SPA fallback",
+      "decision": "Hono serveStatic serves ./public (Vite build output); SPA routes fall through to an index.html catch-all registered after /health, /api/*, and /callback so those win.",
+      "files": ["apps/api/src/index.ts"]
+    },
+    "schedule-x-routing": {
+      "title": "Schedule-X calendar routing",
+      "decision": "Events are routed to Schedule-X calendars by isShared ? 'shared' : String(ownerUserId) — never by calendarId. hydrateEvents.ts enforces this.",
+      "files": ["apps/pwa/src/hydrateEvents.ts", "apps/pwa/src/components/CalendarShell.tsx"]
+    },
+    "state-ownership": {
+      "title": "Client state ownership split",
+      "decision": "Server state is owned by TanStack Query; UI-only state (selected range, color map, drawer) by Zustand. Schedule-X renders the calendar UI.",
+      "files": ["apps/pwa/src/store/calendarStore.ts", "apps/pwa/src/components/CalendarShell.tsx"]
+    }
+  }
+}

.planning/intel/dependency-graph.json

@@ -0,0 +1,156 @@
+{
+  "_meta": {
+    "updated_at": "2026-06-09T00:00:00Z",
+    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
+    "version": 1
+  },
+  "entries": {
+    "hono": {
+      "version": "4.12.23",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/index.ts", "apps/api/src/routes/"]
+    },
+    "@hono/node-server": {
+      "version": "2.0.4",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/index.ts"]
+    },
+    "@hono/oidc-auth": {
+      "version": "1.8.3",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/auth/middleware.ts"]
+    },
+    "@hono/zod-validator": {
+      "version": "0.8.0",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/routes/events.ts"]
+    },
+    "drizzle-orm": {
+      "version": "0.45.2",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/db/client.ts", "apps/api/src/db/schema.ts", "apps/api/src/routes/"]
+    },
+    "mysql2": {
+      "version": "3.22.4",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/db/client.ts"]
+    },
+    "tsdav": {
+      "version": "2.2.2",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/broker/client.ts", "apps/api/src/broker/write.ts"]
+    },
+    "ical.js": {
+      "version": "2.2.1",
+      "type": "production",
+      "workspace": "both (@familysync/api + @familysync/pwa)",
+      "invocation": "require",
+      "used_by": ["apps/api/src/broker/expand.ts", "apps/api/src/broker/vevent.ts", "apps/api/src/broker/sync.ts"]
+    },
+    "zod": {
+      "version": "^3.25.0",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/routes/events.ts"]
+    },
+    "node-cron": {
+      "version": "^4.2.1",
+      "type": "production",
+      "workspace": "@familysync/api",
+      "invocation": "require",
+      "used_by": ["apps/api/src/broker/poller.ts", "apps/api/src/broker/outboxWorker.ts"]
+    },
+    "drizzle-kit": {
+      "version": "0.31.10",
+      "type": "development",
+      "workspace": "@familysync/api",
+      "invocation": "npm run db:generate / npm run db:migrate",
+      "used_by": ["npm run db:generate", "npm run db:migrate", "npm run db:push"]
+    },
+    "temporal-polyfill": {
+      "version": "0.3.2",
+      "type": "production",
+      "workspace": "both",
+      "invocation": "require",
+      "used_by": ["apps/api/src/broker/expand.ts", "apps/pwa/src/lib/eventDateTime.ts"]
+    },
+    "react": {
+      "version": "^19.0.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/"]
+    },
+    "vite": {
+      "version": "8.0.16",
+      "type": "development",
+      "workspace": "@familysync/pwa",
+      "invocation": "npm run dev / npm run build",
+      "used_by": ["npm run dev", "npm run build"]
+    },
+    "vite-plugin-pwa": {
+      "version": "^1.3.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "implicit",
+      "used_by": ["apps/pwa/vite.config.ts"]
+    },
+    "@tanstack/react-query": {
+      "version": "5.101.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/App.tsx", "apps/pwa/src/components/"]
+    },
+    "zustand": {
+      "version": "5.0.14",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/store/calendarStore.ts"]
+    },
+    "@schedule-x/calendar": {
+      "version": "4.6.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/components/CalendarShell.tsx", "apps/pwa/src/lib/calendarConfig.ts"]
+    },
+    "@schedule-x/react": {
+      "version": "4.1.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/components/CalendarShell.tsx"]
+    },
+    "lucide-react": {
+      "version": "1.17.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/components/"]
+    },
+    "vitest": {
+      "version": "^4.1.8",
+      "type": "development",
+      "workspace": "both",
+      "invocation": "npm test",
+      "used_by": ["npm test", "npm run test:watch"]
+    }
+  }
+}

.planning/intel/file-roles.json

@@ -0,0 +1,259 @@
+{
+  "_meta": {
+    "updated_at": "2026-06-09T00:00:00Z",
+    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
+    "version": 1
+  },
+  "entries": {
+    "apps/api/src/index.ts": {
+      "exports": ["app"],
+      "imports": [
+        "@hono/node-server",
+        "@hono/node-server/serve-static",
+        "hono",
+        "./routes/health.js",
+        "./routes/me.js",
+        "./routes/events.js",
+        "./routes/sse.js",
+        "./auth/middleware.js",
+        "./auth/devBypass.js",
+        "./broker/poller.js",
+        "./broker/outboxWorker.js"
+      ],
+      "type": "entry-point",
+      "notes": "Hono app factory + HTTP server; mounts routes, OIDC guard, static PWA assets. Broker workers started only when isMainModule()."
+    },
+    "apps/api/src/routes/events.ts": {
+      "exports": ["eventsRouter"],
+      "imports": [
+        "node:crypto",
+        "hono",
+        "@hono/zod-validator",
+        "zod",
+        "drizzle-orm",
+        "../db/client.js",
+        "../db/schema.js",
+        "../broker/expand.js",
+        "../broker/vevent.js",
+        "../auth/middleware.js",
+        "../auth/user.js",
+        "../auth/devBypass.js"
+      ],
+      "type": "module",
+      "notes": "GET /api/events (windowed), POST /api/events/create, PATCH /api/events/:uid/edit, DELETE /api/events/:uid, GET /api/events/sync-status, GET /api/events/writable-calendars. Writes enqueue to calendarOutbox only — never calls Fastmail directly."
+    },
+    "apps/api/src/routes/me.ts": {
+      "exports": ["meRouter"],
+      "imports": [
+        "hono",
+        "../auth/middleware.js",
+        "../auth/user.js",
+        "../auth/devBypass.js"
+      ],
+      "type": "module",
+      "notes": "GET /api/me — returns { user: { id, displayName, color } }. Upserts user on first login."
+    },
+    "apps/api/src/routes/sse.ts": {
+      "exports": ["sseRouter"],
+      "imports": ["hono", "hono/streaming"],
+      "type": "module",
+      "notes": "GET /api/sse/heartbeat — server-sent events smoke-test; 10s interval heartbeat. Phase 4 SSE fan-out to be added."
+    },
+    "apps/api/src/routes/health.ts": {
+      "exports": ["healthRouter"],
+      "imports": ["hono", "../db/client.js", "drizzle-orm"],
+      "type": "module",
+      "notes": "GET /health — unauthenticated. Runs SELECT 1 against DB; returns { ok, db }."
+    },
+    "apps/api/src/db/schema.ts": {
+      "exports": ["users", "memberCredentials", "calendars", "calendarEvents", "calendarOutbox"],
+      "imports": ["drizzle-orm/mysql-core"],
+      "type": "config",
+      "notes": "Drizzle schema for all 5 MariaDB tables. calendarOutbox status enum: pending|done|failed|dead. calendarEvents dual-field dtstart (dtstartUtc / dtstartDate) for timed vs all-day."
+    },
+    "apps/api/src/db/client.ts": {
+      "exports": ["db"],
+      "imports": ["drizzle-orm/mysql2", "mysql2/promise"],
+      "type": "module",
+      "notes": "Drizzle client bound to mysql2 pool. Reads DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME from env."
+    },
+    "apps/api/src/auth/middleware.ts": {
+      "exports": ["oidcAuthMiddleware", "processOAuthCallback", "getAuth"],
+      "imports": ["@hono/oidc-auth", "hono"],
+      "type": "module",
+      "notes": "OIDC middleware for Hono. Reads OIDC_AUTH_EXTERNAL_URL (mandatory behind Pangolin), OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER from env."
+    },
+    "apps/api/src/auth/devBypass.ts": {
+      "exports": ["devAuthBypass", "DEV_USER"],
+      "imports": ["hono"],
+      "type": "module",
+      "notes": "Dev-only auth bypass middleware. Active only when DEV_AUTH_BYPASS=true AND NODE_ENV!=production. Augments Hono ContextVariableMap with 'user' key."
+    },
+    "apps/api/src/auth/user.ts": {
+      "exports": ["upsertUser", "deriveDisplayName"],
+      "imports": ["../db/client.js", "../db/schema.js", "drizzle-orm"],
+      "type": "module",
+      "notes": "User upsert keyed on oidc_iss + oidc_sub. deriveDisplayName: name → preferred_username → email → sub."
+    },
+    "apps/api/src/broker/poller.ts": {
+      "exports": ["startBrokerPoller"],
+      "imports": ["node-cron", "./sync.js", "../db/client.js", "../db/schema.js"],
+      "type": "module",
+      "notes": "5-minute cron that polls Fastmail CalDAV for each member credential. ctag change-detection (D-13)."
+    },
+    "apps/api/src/broker/outboxWorker.ts": {
+      "exports": ["startOutboxWorker"],
+      "imports": ["node-cron", "./write.js", "../db/client.js", "../db/schema.js"],
+      "type": "module",
+      "notes": "15-second cron that drains pending calendarOutbox rows. Dispatches create/update/delete to Fastmail. Status machine: pending → done|failed|dead."
+    },
+    "apps/api/src/broker/sync.ts": {
+      "exports": ["syncCalendarsForCredential"],
+      "imports": ["./client.js", "./expand.js", "../db/client.js", "../db/schema.js", "ical.js"],
+      "type": "module",
+      "notes": "CalDAV PROPFIND + REPORT → upserts calendars and calendarEvents rows."
+    },
+    "apps/api/src/broker/write.ts": {
+      "exports": ["executeOutboxRow"],
+      "imports": ["./client.js", "./vevent.js", "../db/client.js", "../db/schema.js"],
+      "type": "module",
+      "notes": "Executes a single outbox row: builds VEVENT, calls tsdav PUT/DELETE with If-Match etag."
+    },
+    "apps/api/src/broker/client.ts": {
+      "exports": ["createFastmailClient"],
+      "imports": ["tsdav", "./crypto.js", "../db/client.js", "../db/schema.js"],
+      "type": "module",
+      "notes": "Creates a tsdav DAVClient per member credential (decrypted AES-256-GCM)."
+    },
+    "apps/api/src/broker/crypto.ts": {
+      "exports": ["encrypt", "decrypt"],
+      "imports": ["node:crypto"],
+      "type": "module",
+      "notes": "AES-256-GCM encrypt/decrypt for Fastmail app passwords stored in memberCredentials."
+    },
+    "apps/api/src/broker/expand.ts": {
+      "exports": ["expandOccurrences"],
+      "imports": ["ical.js", "temporal-polyfill"],
+      "type": "module",
+      "notes": "Expands raw VCALENDAR string into CalendarOccurrence[] for a [start, end) window. Handles RRULE, EXDATE, DST via ical.js + Temporal."
+    },
+    "apps/api/src/broker/vevent.ts": {
+      "exports": ["buildVevent", "extractRruleString"],
+      "imports": ["ical.js"],
+      "type": "module",
+      "notes": "Builds VCALENDAR/VEVENT strings from CreateEventPayload. extractRruleString preserves RRULE on calendar-move edits."
+    },
+    "apps/pwa/src/main.tsx": {
+      "exports": [],
+      "imports": ["react-dom/client", "./App.tsx"],
+      "type": "entry-point",
+      "notes": "React root mount."
+    },
+    "apps/pwa/src/App.tsx": {
+      "exports": ["default"],
+      "imports": [
+        "react",
+        "@tanstack/react-query",
+        "./components/CalendarShell.tsx",
+        "./components/InstallPrompt.tsx"
+      ],
+      "type": "entry-point",
+      "notes": "Root component. Sets up QueryClient, renders CalendarShell + InstallPrompt."
+    },
+    "apps/pwa/src/api/client.ts": {
+      "exports": [
+        "fetchMe",
+        "fetchEvents",
+        "createEvent",
+        "updateEvent",
+        "deleteEvent",
+        "fetchSyncStatus",
+        "fetchWritableCalendars"
+      ],
+      "imports": [],
+      "type": "module",
+      "notes": "Typed fetch wrappers for all API endpoints. Uses credentials: 'include' + redirect: 'manual' for OIDC opaqueredirect detection."
+    },
+    "apps/pwa/src/components/CalendarShell.tsx": {
+      "exports": ["CalendarShell"],
+      "imports": [
+        "react",
+        "@tanstack/react-query",
+        "@schedule-x/react",
+        "../api/client.ts",
+        "../lib/calendarConfig.ts",
+        "../lib/hydrateEvents.ts",
+        "../lib/loginRedirect.ts",
+        "../store/calendarStore.ts",
+        "./EventDetailPopover.tsx",
+        "./EventForm.tsx",
+        "./SyncStateToast.tsx",
+        "./ColorLegend.tsx",
+        "./SkeletonCalendar.tsx",
+        "./ErrorBoundary.tsx"
+      ],
+      "type": "module",
+      "notes": "Top-level calendar view. Orchestrates TanStack Query fetches, Schedule-X calendar, event create/edit/delete flows, sync toasts."
+    },
+    "apps/pwa/src/components/EventForm.tsx": {
+      "exports": ["EventForm"],
+      "imports": ["react", "../api/client.ts"],
+      "type": "module",
+      "notes": "Create/edit event form. Posts to createEvent/updateEvent. Supports recurrence presets, allDay toggle, calendar picker."
+    },
+    "apps/pwa/src/components/EventDetailPopover.tsx": {
+      "exports": ["EventDetailPopover"],
+      "imports": ["react", "../api/client.ts"],
+      "type": "module",
+      "notes": "Popover shown on event click. Shows title/time/location/description, edit/delete actions."
+    },
+    "apps/pwa/src/components/SyncStateToast.tsx": {
+      "exports": ["SyncStateToast"],
+      "imports": ["react", "@tanstack/react-query", "../api/client.ts"],
+      "type": "module",
+      "notes": "Polls /api/events/sync-status to show pending → done | failed toast for async CalDAV writes."
+    },
+    "apps/pwa/src/components/ColorLegend.tsx": {
+      "exports": ["ColorLegend"],
+      "imports": ["react", "../store/calendarStore.ts"],
+      "type": "module",
+      "notes": "Displays per-member color swatches from calendarStore."
+    },
+    "apps/pwa/src/store/calendarStore.ts": {
+      "exports": ["useCalendarStore"],
+      "imports": ["zustand"],
+      "type": "module",
+      "notes": "Zustand store for UI-only state: selectedDateRange, calendarId→color map, drawer open/closed. No server state."
+    },
+    "apps/pwa/src/lib/calendarConfig.ts": {
+      "exports": ["buildCalendarConfig"],
+      "imports": [],
+      "type": "module",
+      "notes": "Builds Schedule-X calendar config from member color map and MeUser."
+    },
+    "apps/pwa/src/lib/hydrateEvents.ts": {
+      "exports": ["hydrateEvents"],
+      "imports": ["../api/client.ts"],
+      "type": "module",
+      "notes": "Maps CalendarOccurrence[] → Schedule-X event objects. Routes by isShared/ownerUserId (never calendarId)."
+    },
+    "apps/pwa/src/lib/eventDateTime.ts": {
+      "exports": ["formatEventDateTime", "toScheduleXDateTime"],
+      "imports": ["temporal-polyfill"],
+      "type": "module",
+      "notes": "Date/time formatting helpers for Schedule-X event start/end fields."
+    },
+    "apps/pwa/src/lib/loginRedirect.ts": {
+      "exports": ["maybeRedirectToLogin"],
+      "imports": [],
+      "type": "module",
+      "notes": "Top-level navigation to /api/login when OIDC 302/opaqueredirect detected. CORS-bypass strategy."
+    },
+    "apps/pwa/src/lib/colorUtils.ts": {
+      "exports": ["assignMemberColors"],
+      "imports": [],
+      "type": "module",
+      "notes": "Assigns hex colors from palette to members deterministically."
+    }
+  }
+}

.planning/intel/stack.json

@@ -0,0 +1,43 @@
+{
+  "_meta": {
+    "updated_at": "2026-06-09T00:00:00Z",
+    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
+    "version": 1
+  },
+  "languages": ["TypeScript", "SQL"],
+  "frameworks": ["Hono 4.12.23", "React 19", "Drizzle ORM 0.45.2"],
+  "tools": [
+    "Vite 8.0.16",
+    "vite-plugin-pwa 1.3.0",
+    "Vitest",
+    "drizzle-kit 0.31.10",
+    "ESLint",
+    "node-cron"
+  ],
+  "build_system": "pnpm workspaces + tsc (api) + vite build (pwa)",
+  "test_framework": "Vitest",
+  "package_manager": "pnpm 11.5.1",
+  "runtime": "Node.js 22 LTS",
+  "database": "MariaDB via mysql2 3.22.4",
+  "cache": "Redis (ioredis — planned for Phase 4 list sync; not yet wired)",
+  "auth": "Authelia OIDC — authorization_code + PKCE via @hono/oidc-auth 1.8.3",
+  "calendar_backend": "Fastmail CalDAV via tsdav 2.2.2 + ical.js 2.2.1",
+  "calendar_ui": "@schedule-x/calendar 4.6.0",
+  "server_state": "@tanstack/react-query 5.101.0",
+  "client_state": "zustand 5.0.14",
+  "content_formats": [
+    "TypeScript (source)",
+    "SQL (Drizzle migrations)",
+    "iCalendar / VCALENDAR (CalDAV payloads)",
+    "Markdown (planning docs)"
+  ],
+  "infra": {
+    "hosting": "Unraid + Docker Compose",
+    "networking": "Pangolin/Newt tunnel (no open ports), split-DNS"
+  },
+  "workspaces": {
+    "root": "familysync (pnpm workspace root)",
+    "api": "@familysync/api — apps/api",
+    "pwa": "@familysync/pwa — apps/pwa"
+  }
+}

.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md

@@ -27,14 +27,14 @@ result: [pending]
 
 ### 4. SSE-over-Pangolin smoke test (de-risks Phase 4)
 expected: With a valid session cookie, `curl -N -H "Cookie: oidc-auth=<value>" https://familysync.<domain>/api/sse/heartbeat` streams a `heartbeat` event roughly every 10s and stays open for 5+ minutes without Pangolin cutting the stream. PASS = continuous heartbeats; FAIL = stream cut early (investigate Pangolin idle-timeout; note as Phase 4 constraint, ref issue #1034).
-result: [pending]
+result: PASS (2026-06-08) — GET /api/sse/heartbeat over familysync-dev.bergerhouse.net (Pangolin→Newt→api) with a valid session cookie held open ~6 min (01:37:53Z→01:43:54Z), 35 heartbeat events id 0→34 at ~10s cadence; response bytes grew 71→2535 (incremental delivery → Pangolin buffering OFF); no early cut. Phase 4 entry gate (D-14 / issue #1034) CLEARED. Caveat: proves no idle-timeout/buffering over ~6 min, not the absence of a max total connection-duration cap — residual risk covered by Phase 4 design (D-10/D-11/D-12 in 04-CONTEXT.md).
 
 ## Summary
 
 total: 4
-passed: 0
+passed: 1
 issues: 0
-pending: 4
+pending: 3
 skipped: 0
 blocked: 0
 

.planning/phases/03-event-write-back-pwa-install/.continue-here.md

@@ -1,75 +0,0 @@
----
-context: phase
-phase: 03-event-write-back-pwa-install
-task: "Gate 2 Part D — edit/delete join fix (diagnosed, not started)"
-total_tasks: null
-status: in_progress
-last_updated: 2026-06-07T02:39:57.236Z
----
-
-# Critical Anti-Patterns
-
-| Pattern | Description | Severity | Prevention Mechanism |
-|---------|-------------|----------|---------------------|
-| playwright-cli wedges in this WSL2 env | After loading a never-settling page (e.g. the infinite-spinner state), the playwright-cli daemon hangs and even `open`/`run-code` fail afterward. Burned a lot of effort on it. | blocking | Do NOT use playwright-cli for verification here. Verify via `curl` against the tunnel + ask the operator to test in their real browser/incognito. |
-| Drizzle: referencing joined-table columns without the join | `events.ts` edit + delete handlers select `calendars.url`/`calendars.userId` from `.from(calendarEvents)` with no `.innerJoin(calendars,...)` → runtime 503 "table calendars is not part of the query". Unit tests mock `db.select()` so they DON'T catch it. | blocking | Any handler selecting another table's columns MUST `.innerJoin` it. Regression tests for write endpoints must exercise the REAL query builder (test DB), not a mocked `db.select()`. |
-| `.env` is permission-locked | The Read/Edit/Bash tools are denied on `.env` (and `.env.spike`). | advisory | Hand the operator exact `.env` lines to apply via the `!` prefix; never assume you can read/write it. |
-| docker compose recreate drops the newt target ~30s | Every `docker compose up -d` recreates the api container, resetting newt's held TCP connection → tunnel returns 503 "no available server" for ~30s, then self-recovers. | advisory | After any recreate, poll `/health` through the tunnel until 200 before testing. Not a bug — do not chase it. |
-
-<current_state>
-Phase 03 **Gate 2 live verification is largely working.** The PWA now loads through Pangolin/newt, real Authelia OIDC login works, and create-event round-trips to Fastmail correctly (right time, right user) after this session's fixes. Working tree is clean (all committed).
-
-**Immediate blocker:** deleting (and latently editing) an event 503s — the `events.ts` edit/delete handlers are missing a `calendars` join. Diagnosed, fix NOT yet applied. The operator paused right as I asked how to land the fix.
-</current_state>
-
-<completed_work>
-This session (commits b46b25b → bdbb9b8):
-- **Tunnel works** — operator set `newt -mtu 1200` (was 1280 == eth0 underlay; WireGuard overhead blackholed large packets). THIS was the real cause of every "spinner" — the 510KB JS bundle never downloaded. Plus API now serves the full `./public` tree (431ab31), so manifest/sw/icons stop returning HTML.
-- **Auth works** — `/api/login` route + redirect (quick task 260606-tv8), `fetchMe` uses `redirect:'manual'` (1adb460), `OIDC_CLIENT_ID=familysync-dev`, `OIDC_SCOPES=openid profile email offline_access`, redirect URI corrected. Operator added `offline_access` to the Authelia client.
-- **Bring-up** (b46b25b) — PWA built into the API image (single port :3000), `NODE_ENV=production`, broker credential seeded (reused the spike app password).
-- **BUG A (timezone)** + **BUG B (calendar identity)** fixed via /gsd-debug (a9d3de6, session `.planning/debug/write-path-event-bugs.md`). Migration `0001_calendars_user_url_unique.sql` applied to the live DB.
-- **Spike cleanup** — deleted obsolete user id=1 ("Dev User") + calendar id=1 + cached events (operator-approved DB op).
-- **Backlog 999.2** added — slick unauthenticated-entry (no login flash).
-</completed_work>
-
-<remaining_work>
-1. **BLOCKING — edit/delete join fix.** `apps/api/src/routes/events.ts`: the `PATCH /:uid/edit` lookup (~line 295) and `DELETE /:uid` lookup (~line 392) select `calendarUrl: calendars.url` + `userId: calendars.userId` from `.from(calendarEvents).where(eq(calendarEvents.uid, uid))` with NO join. Add `.innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))` to both (mirror the working `GET /api/events` query at ~line 153). Add a regression test that runs the real query builder.
-2. `me.ts` blank displayName — passes the (missing) `email` claim as displayName, never reads `name`/`preferred_username`; `oidc_iss` also blank. Legend name is blank (user id=2 `display_name=''`). May also need Authelia to include name/email in the ID token, or call userinfo.
-3. `GET /api/events` has no `userId`/`isShared` filter (returns all users' events) — latent now (1 real user), real bug for a 2nd member.
-4. "Syncing" toast not animated / ~27s — UI polish (backlog candidate).
-5. Gate 2 remaining: A2 (session persistence), A3 (2nd-member color), B (iOS standalone install+login — device-only), C (5-min SSE smoke — Phase 4 entry gate).
-
-The operator was choosing how to land #1: **(a)** batch #1+#2+#3 in one /gsd-quick, **(b)** /gsd-quick just #1, or **(c)** fix #1 inline. Re-offer that.
-</remaining_work>
-
-<decisions_made>
-- `newt -mtu 1200` — fixes large-asset blackhole through the WireGuard tunnel.
-- Deleted the spike user (id=1) + its calendar/events — obsolete test identity, re-syncable cache.
-- `fetchMe` `redirect:'manual'`, serve full `./public`, constrained `OIDC_SCOPES` — see HANDOFF.json.
-</decisions_made>
-
-<blockers>
-- Delete/edit events 503 (missing calendars join) — trivial fix, not yet applied.
-- playwright-cli broken in this env — verify via curl + operator's browser.
-</blockers>
-
-## Required Reading (in order)
-1. `.planning/HANDOFF.json` — machine-readable mirror of this state.
-2. `apps/api/src/routes/events.ts` — the edit (~line 295) + delete (~line 392) handlers missing the `calendars` join; compare to the working GET query (~line 153).
-3. `.planning/debug/write-path-event-bugs.md` — the resolved timezone + calendar-identity debug session (context for the write path).
-4. `.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md` — the Gate 2 checklist (still needs updating with what now passes).
-
-## Infrastructure State
-- Stack: `docker compose` (production target) — api + mariadb (healthy) + redis up. `/health` 200 locally AND through `https://familysync-dev.bergerhouse.net`.
-- newt: systemd service, `-mtu 1200` drop-in applied by operator; WireGuard tunnel carries large transfers now.
-- DB: 1 user (id=2, real OIDC, `display_name=''`, color #E8734A); calendars id=2 "Calendar" (509 ev) + id=3 "USA Holidays" (32). `uniq_calendar_user_url(user_id,url)` present.
-- OIDC: `client_id=familysync-dev` registered in Authelia with `offline_access`; redirect `https://familysync-dev.bergerhouse.net/callback`.
-- An old test event (uid `92dd5a80…`) exists in Fastmail at the WRONG time (written pre-BUG-A-fix) — operator should delete it via the app once delete works.
-
-<context>
-The whole session was a Gate 2 bring-up that turned into a bug hunt. The keystone was the newt MTU fix — until then the JS bundle couldn't traverse the tunnel, so the app showed a perpetual spinner that looked like (and got misdiagnosed as) auth problems. After that unlocked, live testing surfaced a cascade of real write-path bugs, most now fixed. Remaining work is small and well-understood; the edit/delete join is a 2-line fix gated only on the operator's choice of how to land it.
-</context>
-
-<next_action>
-Start with: re-offer the operator the landing choice for the edit/delete join fix (batch #1+#2+#3 / quick-only #1 / inline). Then apply `.innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))` to the edit (~line 295) and delete (~line 392) handlers in `apps/api/src/routes/events.ts`, add a real-query regression test, `docker compose up -d --build`, wait for tunnel `/health` 200, and have the operator re-test delete in the browser.
-</next_action>

.planning/phases/03-event-write-back-pwa-install/03-08-SUMMARY.md

@@ -0,0 +1,79 @@
+---
+phase: 03-event-write-back-pwa-install
+plan: 08
+subsystem: gate, live-verification, auth, broker, pwa
+tags: [gate-2, live-verification, authelia, oidc, pangolin, ios-pwa, caldav, write-back]
+
+# Dependency graph
+requires:
+  - phase: 03-event-write-back-pwa-install
+    plan: 04
+    provides: write endpoints (create/edit/delete) + outbox
+  - phase: 03-event-write-back-pwa-install
+    plan: 06
+    provides: EventDetailPopover + DeleteConfirmationDialog + SyncStateToast
+  - phase: 03-event-write-back-pwa-install
+    plan: 07
+    provides: PWA manifest + service worker + InstallPrompt
+
+provides:
+  - Gate 2 live-verification results against the real Authelia + Pangolin deploy
+  - Confirmed end-to-end write path (create/all-day/recurring/edit/delete/conflict) to Fastmail
+  - Confirmed iOS standalone install + OIDC login (load-bearing)
+
+affects: [phase-04]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Live Mode-A topology: local origin + Newt connector + Authelia OIDC through Pangolin"
+    - "Operator-driven verification (playwright-cli unavailable in WSL2); evidence via DB/outbox + browser"
+
+key-files:
+  created:
+    - .planning/phases/03-event-write-back-pwa-install/03-08-SUMMARY.md
+  modified:
+    - .planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+---
+
+# Phase 03 Plan 08: Gate 2 Live Verification — Summary
+
+**One-liner:** Took FamilySync live (real Authelia OIDC over Pangolin/Newt) and verified the full event write-back path end-to-end to Fastmail on desktop and iOS, fixing a long string of blocker bugs found only under live conditions.
+
+## Outcome
+
+Gate 2 is **complete for Phase 03 scope**. See `03-GATE2-RESULTS.md` for the per-row record. Summary:
+
+- **A — Auth/session/colors:** A1 (OIDC login → app) ✅, A2 (session — transparent via Authelia SSO) ✅, A3 (distinct member colors) ✅ after fixing a color-collision bug.
+- **B — iOS standalone (load-bearing):** B1–B4 ✅ — install to Home Screen, full-screen standalone launch, and **OIDC login completed from standalone without dropping to Safari**. B5 (Android install) deferred.
+- **C — SSE smoke:** deferred by design — this is the Phase 4 *entry* gate (D-14), verified at the start of Phase 4.
+- **D — write round-trips:** D1–D6 ✅ — create (timed), all-day, weekly recurring, edit, delete, 412-conflict, plus recurring-series delete, all round-tripping to caldav.fastmail.com.
+
+## Blocker bugs found + fixed live (all committed + deployed)
+
+Live bring-up surfaced bugs the dev-bypass build could not:
+
+- **Tunnel:** newt MTU 1280→1200 (operator) — encrypted WireGuard packets exceeded the underlay MTU, blackholing the JS bundle (the original "spinner"). API now serves the full `./public` tree.
+- **Auth:** `/api/login` route + `fetchMe` `redirect:'manual'`; OIDC scopes/client_id; and the OIDC **state-cookie churn** (events query racing the login flow → `OAUTH_INVALID_RESPONSE`) — fixed by gating the events query on auth.
+- **Write path:** event timezone (UTC serialization), per-user calendar identity (unique(userId,url) + per-user predicates), missing `calendars` join in edit/delete (503), delete **cache reconciliation** (deletes lingered as ghosts), and the post-write **refetch race** (resync now precedes marking the outbox row done).
+- **UI:** calendar **remount flash** (nested component rendered as `<CalendarContent/>`), all-day **display off-by-one** (exclusive DTEND vs Schedule-X inclusive), member **color collision** and member-vs-shared **color clash**.
+- **Identity:** displayName now derived from OIDC claims with self-heal (Authelia ID-token `claims_policy` documented as the operator step for full names).
+
+## Deferred / carried forward
+
+- **B5** — Android install walkthrough (device check).
+- **C** — SSE 5-min smoke (Phase 4 entry gate, D-14).
+- **Backlog 999.3–999.9** — session-timeout sign-in redirect; event reminder/VALARM options; first-login Fastmail app-password provider setup; all-day visual distinction; event-form end-tracking + all-day edit off-by-one; recurrence repeat-until/count bound; edit recurring series.
+
+## Verification method
+
+Operator-driven browser testing (desktop + the wife's iPhone) + backend evidence (`calendar_outbox` rows reaching `done`, `calendar_events` cache, stored VEVENTs). `playwright-cli` is unavailable in this WSL2 env, so desktop rows were operator-driven rather than automated.
+
+## Self-Check
+
+- [x] Gate 2 results recorded in `03-GATE2-RESULTS.md`
+- [x] Write path (create/all-day/recurring/edit/delete/conflict) verified live to Fastmail
+- [x] iOS standalone install + login (load-bearing) verified
+- [x] All live blocker bugs fixed, committed, and deployed
+- [x] UX gaps captured as backlog (999.3–999.9); B5/C deferred by design

.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md

@@ -4,11 +4,20 @@
 
 | Field        | Value                                                   |
 |--------------|---------------------------------------------------------|
-| Deploy URL   | TBD — operator must configure (see Operator Setup below)|
-| Build SHA    | 40dfbb4                                                 |
-| Build date   | 2026-06-05T22:50:16Z                                    |
-| PWA build    | CLEAN — 1818 modules, dist/sw.js + workbox generated    |
-| API build    | CLEAN — tsc passed, no errors                           |
+| Deploy URL   | LIVE via Pangolin/Newt (operator domain) — confirmed reachable; real Authelia OIDC login working 2026-06-07 |
+| Build SHA    | 86069b8 (2026-06-07 live bring-up + write-path fixes)   |
+| Build date   | 2026-06-07                                              |
+| PWA build    | CLEAN — dist/sw.js + workbox generated; 140/140 tests   |
+| API build    | CLEAN — tsc passed; 102/102 tests                       |
+
+> **2026-06-07 live verification note.** Gate 2 was executed live against the running
+> Docker stack through Pangolin/Newt (Mode A). Several blocker bugs were found and fixed
+> during this session (see commits): newt MTU blackhole, OIDC state-cookie churn, event
+> write-path timezone + calendar identity, missing calendars join (edit/delete 503),
+> delete cache-reconciliation, post-write refetch race, and a calendar remount flash.
+> Rows verified below were confirmed via operator browser testing + backend evidence
+> (calendar_outbox rows reaching `done` against caldav.fastmail.com). playwright-cli is
+> unavailable in this WSL2 env, so desktop rows were operator-driven, not automated.
 
 ---
 
@@ -118,9 +127,9 @@ Mark each row PASS or FAIL and add notes. On failure, apply the indicated remedy
 
 | # | Ref | Check | Result | Notes |
 |---|-----|-------|--------|-------|
-| A1 | AUTH-01 | Open `https://familysync-dev.DOMAIN` → redirects to Authelia → login completes → land on the app with name, color, and at least one cached event | [ ] PENDING — operator | |
-| A2 | AUTH-02 | Fully close + reopen browser → revisit the URL → no re-login prompted (session persists) | [ ] PENDING — operator | |
-| A3 | AUTH-03 | Second member logs in on a separate device → distinct stable color assigned (different from first member's color) | [ ] PENDING — operator/device | |
+| A1 | AUTH-01 | Open `https://familysync-dev.DOMAIN` → redirects to Authelia → login completes → land on the app with name, color, and at least one cached event | ✅ PASS (2026-06-07) | Real Authelia OIDC login lands on the calendar; name (email claim), assigned color, and cached events render. Name self-heals to full name once Authelia emits name/preferred_username (see backlog/memory). |
+| A2 | AUTH-02 | Fully close + reopen browser → revisit the URL → no re-login prompted (session persists) | 🟡 PASS (transparent) | Confirmed (desktop + iPhone): cold open bounces through Authelia but its SSO carries the session, so NO credential prompt — user lands straight on the app. Note: the app's own oidc-auth cookie is session-scoped (dropped on browser close), so each cold open does a redirect round-trip. Acceptable for v1; making the app cookie persistent (skip the bounce) is a minor follow-up. |
+| A3 | AUTH-03 | Second member logs in on a separate device → distinct stable color assigned (different from first member's color) | ✅ PASS (2026-06-07) | Second member (amelia, id=3) logged in on her iPhone. Found + fixed a collision bug (both members were #E8734A — COUNT%palette reused a slot after a deletion); now luc=#E8734A, amelia=#4A90D9 (distinct, stable). Fix: first-unused-palette-color (commit f700182). |
 
 ### Part B — iOS PWA Standalone Login (Task 2) — LOAD-BEARING CHECK
 
@@ -134,17 +143,17 @@ Mark each row PASS or FAIL and add notes. On failure, apply the indicated remedy
 
 | # | Ref | Check | Result | Notes |
 |---|-----|-------|--------|-------|
-| B1 | iOS PWA | Open `https://familysync-dev.DOMAIN` in Safari on iPhone → in-app install walkthrough appears → tap "Add to Home Screen" | [ ] PENDING — device | |
-| B2 | iOS PWA | Launch FamilySync from Home Screen → opens full-screen with no Safari browser chrome (standalone mode) | [ ] PENDING — device | |
-| B3 | iOS PWA (Pitfall 2) | Complete Authelia OIDC login from standalone mode → redirect does NOT break out of standalone (user stays in the app, not dropped to Safari) | [ ] PENDING — device | **Load-bearing check** |
-| B4 | PWA-01 | Installed PWA on iOS opens full-screen with no browser chrome | [ ] PENDING — device | |
-| B5 | PWA-02 | Installed PWA on Android opens full-screen with no browser chrome | [ ] PENDING — device | |
+| B1 | iOS PWA | Open `https://familysync-dev.DOMAIN` in Safari on iPhone → in-app install walkthrough appears → tap "Add to Home Screen" | ✅ PASS (2026-06-07) | Wife added FamilySync to her iPhone Home Screen and logged in (user id=3 created). |
+| B2 | iOS PWA | Launch FamilySync from Home Screen → opens full-screen with no Safari browser chrome (standalone mode) | ✅ PASS (2026-06-07) | Confirmed: launches full-screen standalone from Home Screen. |
+| B3 | iOS PWA (Pitfall 2) | Complete Authelia OIDC login from standalone mode → redirect does NOT break out of standalone (user stays in the app, not dropped to Safari) | ✅ PASS (2026-06-07) | Confirmed working — OIDC login from standalone stays in the app, no drop to Safari. **Load-bearing check cleared.** |
+| B4 | PWA-01 | Installed PWA on iOS opens full-screen with no browser chrome | ✅ PASS (2026-06-07) | Confirmed (same as B2). |
+| B5 | PWA-02 | Installed PWA on Android opens full-screen with no browser chrome | [ ] PENDING — device | Android install not yet exercised. |
 
 ### Part C — SSE Smoke Test (Gate before Phase 4)
 
 | # | Ref | Check | Result | Notes |
 |---|-----|-------|--------|-------|
-| C1 | SSE | Hold stream open 5+ min without it being cut (see curl command below) | [ ] PENDING — operator | |
+| C1 | SSE | Hold stream open 5+ min without it being cut (see curl command below) | ✅ PASS (2026-06-08) | Held GET /api/sse/heartbeat open ~6 min over familysync-dev.bergerhouse.net (Pangolin→Newt→api) with a valid session cookie (01:37:53Z→01:43:54Z); 35 heartbeat events id 0→34 at ~10s cadence; response bytes grew 71→2535 (incremental → Pangolin buffering OFF); no early cut. Phase 4 entry gate (D-14 / issue #1034) CLEARED. Caveat: proves no idle-timeout/buffering over ~6 min, not the absence of a max total connection-duration cap — residual risk covered by Phase 4 design (D-10/D-11/D-12 in 04-CONTEXT.md). |
 
 ```bash
 # Get the session cookie from browser DevTools → Application → Cookies (oidc-auth=<value>)
@@ -157,12 +166,12 @@ curl -N -H "Cookie: oidc-auth=<value>" https://familysync-dev.DOMAIN/api/sse/hea
 
 | # | Ref | Check | Result | Notes |
 |---|-----|-------|--------|-------|
-| D1 | CAL-04 | Create a timed event → "Syncing…" toast → "Saved" toast → event appears in native Fastmail app on next sync | [ ] PENDING — operator | |
-| D2 | CAL-07 | Create an all-day event → same Syncing→Saved flow → appears in Fastmail | [ ] PENDING — operator | |
-| D3 | CAL-04 | Create a weekly recurring event → appears in Fastmail | [ ] PENDING — operator | |
-| D4 | CAL-05 | Edit an existing event's title and time → Syncing→Saved → change persists in Fastmail | [ ] PENDING — operator | |
-| D5 | CAL-06 | Delete an event via the two-tap confirmation dialog → Syncing→Saved → event disappears from all views on next sync | [ ] PENDING — operator | |
-| D6 | D-08 | (Optional) Trigger a 412 conflict by editing the same event in Fastmail first → conflict toast appears in the app → calendar re-fetches | [ ] PENDING — operator | Optional |
+| D1 | CAL-04 | Create a timed event → "Syncing…" toast → "Saved" toast → event appears in native Fastmail app on next sync | ✅ PASS (2026-06-07) | Timed create round-trips to caldav.fastmail.com (outbox rows reach `done`); appears in the app. Timezone fix applied (was 4h off). |
+| D2 | CAL-07 | Create an all-day event → same Syncing→Saved flow → appears in Fastmail | ✅ PASS (2026-06-07) | All-day create round-trips to Fastmail (verified VEVENT: DTSTART/DTEND VALUE=DATE, exclusive end). Found + fixed a display off-by-one (single-day showed across 2 days — Schedule-X inclusive vs iCal exclusive end; commit d4d5327). Reload to confirm 1-day rendering. |
+| D3 | CAL-04 | Create a weekly recurring event → appears in Fastmail | ✅ PASS — write correct; UX gaps backlogged | A weekly event was created and recurred in Fastmail with a valid `RRULE:FREQ=WEEKLY`. Two UX gaps surfaced (NOT write-correctness): no "repeat until/count" bound (series is unbounded → recurs into 2028+) and the end-date is the per-occurrence duration (a 2-month end made each occurrence 63 days → overlapping every day). Backlogged 999.7/999.8. Deleting the recurring series cleared the master + all occurrences from Fastmail in one delete (recurring-series delete verified). |
+| D4 | CAL-05 | Edit an existing event's title and time → Syncing→Saved → change persists in Fastmail | ✅ PASS (2026-06-07) | Edit/move confirmed working; update outbox rows reach `done`; post-write refetch race fixed so the change shows without manual refresh. |
+| D5 | CAL-06 | Delete an event via the two-tap confirmation dialog → Syncing→Saved → event disappears from all views on next sync | ✅ PASS (2026-06-07) | Delete confirmed working; delete cache-reconciliation fix means the event leaves the cache/UI (was lingering as a ghost). |
+| D6 | D-08 | (Optional) Trigger a 412 conflict by editing the same event in Fastmail first → conflict toast appears in the app → calendar re-fetches | ✅ PASS (2026-06-07) | Observed live: a stale-etag update produced `412 conflict` (outbox id=7) and the "This event changed elsewhere" conflict toast; calendar re-syncs. |
 
 ---
 
@@ -171,9 +180,9 @@ curl -N -H "Cookie: oidc-auth=<value>" https://familysync-dev.DOMAIN/api/sse/hea
 Record the curl result through the public URL here:
 
 ```
-URL tested:    https://familysync-dev.DOMAIN/health
-Result:        [ ] PENDING — operator
-Response body: <fill in>
+URL tested:    https://<operator-domain>/health (via Pangolin/Newt) + http://localhost:3000/health
+Result:        ✅ PASS (2026-06-07) — app reachable through the tunnel; real OIDC login completed
+Response body: {"ok":true,"db":"up"}
 ```
 
 ---
@@ -182,13 +191,19 @@ Response body: <fill in>
 
 | Section | Status |
 |---------|--------|
-| Production builds (PWA + API) | CLEAN (automated, 2026-06-05) |
-| Operator infra setup | PENDING |
-| A — Auth / session / colors | PENDING |
-| B — iOS standalone login (load-bearing) | PENDING |
-| C — SSE smoke test | PENDING |
-| D — Fastmail write round-trips | PENDING |
+| Production builds (PWA + API) | ✅ CLEAN (2026-06-07; 102 API + 140 PWA tests) |
+| Operator infra setup | ✅ DONE (Authelia client + Pangolin/Newt live; OIDC login working) |
+| A — Auth / session / colors | ✅ A1, A2 (transparent SSO), A3 all PASS |
+| B — iOS standalone login (load-bearing) | ✅ B1–B4 PASS (install + standalone launch + standalone login); B5 (Android) deferred |
+| C — SSE smoke test | ✅ PASS (2026-06-08) — Phase 4 ENTRY gate (D-14 / issue #1034) CLEARED; held ~6 min, 35 heartbeats, incremental delivery, no proxy cut |
+| D — Fastmail write round-trips | ✅ D1–D6 PASS (create/all-day/recurring/edit/delete/conflict); recurring-series delete also verified |
 
 Gate 2 is complete when all rows are PASS. Record final status here:
 
-**Gate 2 outcome:** [ ] PENDING
+**Gate 2 outcome:** ✅ COMPLETE for Phase 03 scope (2026-06-07) — auth, session, distinct member
+colors, iOS install + standalone login (load-bearing), and all write round-trips (create / all-day /
+weekly recurring / edit / delete / 412-conflict, incl. recurring-series delete) verified live.
+Many blocker bugs found + fixed this session (see git log). Recurring create writes valid RRULE;
+its repeat-bound + per-occurrence-duration UX are tracked as backlog 999.7/999.8 (within the v1
+"recurring create+display only" scope). Deferred by design: B5 (Android install) and C (SSE smoke —
+Phase 4 entry gate per D-14). Phase 03 is code-complete and live-verified.

.planning/phases/03-event-write-back-pwa-install/03-REVIEW-FIX.iter2.md

@@ -0,0 +1,189 @@
+---
+phase: 03-event-write-back-pwa-install
+fixed_at: 2026-06-09T00:00:00Z
+review_path: .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+iteration: 1
+findings_in_scope: 14
+fixed: 13
+skipped: 1
+status: partial
+---
+
+# Phase 3: Code Review Fix Report
+
+**Fixed at:** 2026-06-09
+**Source review:** .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+**Iteration:** 1
+
+**Summary:**
+- Findings in scope: 14 (fix_scope: all — Critical + Warning + Info)
+- Fixed: 13
+- Skipped: 1
+
+**Note on recovery:** a prior `--fix` run was interrupted (orphan worktree
+`/tmp/sv-03-reviewfix-uxjhc1` + branch `gsd-reviewfix/03-53993` + recovery sentinel).
+That run's 3 commits had mismatched finding labels and its branch had diverged from the
+current branch tip (which had advanced with docs commits, making a fast-forward
+impossible). Per the recovery protocol the orphan worktree/branch/sentinel were cleaned
+up and all fixes were re-applied fresh from the current branch tip. All 13 commits below
+are new.
+
+**Verification environment:** the isolated worktree had no `node_modules` (gitignored,
+not carried into a fresh worktree). `node_modules` from the main repo were symlinked in
+so `tsc --noEmit` could resolve dependencies for Tier-2 syntax/type checks. The symlinks
+are gitignored and were never committed. Every fix was Tier-2 verified (full
+`tsc --noEmit` per affected package, clean).
+
+## Fixed Issues
+
+### CR-01: Event edit/delete ownership check resolves an arbitrary member's row (uid-only lookup)
+
+**Files modified:** `apps/api/src/routes/events.ts`
+**Commit:** 54addb1
+**Status:** fixed: requires human verification (ownership/authorization logic)
+**Applied fix:** Both the PATCH `/:uid/edit` and DELETE `/:uid` lookups now scope the
+`calendarEvents` → `calendars` join to the acting member's writable set
+(`or(calendars.userId = currentUserId, calendars.isShared)`), add
+`orderBy(sql\`(calendars.userId = currentUserId) desc\`)` so the user's own row ranks
+ahead of a shared/other copy, and `limit(1)` for determinism. This stops `[0]` from
+resolving to another member's calendar row for a shared-account uid (D-16).
+
+### CR-02: Outbox WR-02 "freshest etag" re-read also queries uid-only
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`
+**Commit:** a596f52
+**Status:** fixed: requires human verification (etag-selection logic)
+**Applied fix:** The pre-PUT freshest-etag re-read now joins through `calendars` and
+filters on the outbox row's own `userId` + `calendarUrl` with `limit(1)`, so the etag
+used in `If-Match` belongs to the writing member's calendar instead of an arbitrary
+shared-account row. `calendars` added to the schema import.
+
+### CR-03: All-day end date exclusive on write but inclusive on edit pre-fill
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`
+**Commit:** f645644
+**Status:** fixed: requires human verification (date-arithmetic / data-correctness)
+**Applied fix:** Added `exclusiveEndToInclusiveDate()` (DST-safe UTC-component
+subtraction) and apply it when pre-filling the end-date input for all-day occurrences —
+both in the initial `useState` and the open/reset effect. Keeps `occurrence.end`
+exclusive everywhere (reviewer option a); `buildVeventString` still rolls forward to
+exclusive at the ICS boundary, so a re-edit no longer grows the span by a day.
+**Note:** the reviewer also suggested a regression test (edit an all-day multi-day event
+twice, assert the span is stable). Not added — flagged for the developer.
+
+### WR-01: Recurrence silently reset to `none` on every edit — data loss
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`, `apps/api/src/broker/vevent.ts`, `apps/pwa/src/api/client.ts`, `apps/pwa/src/components/EventForm.tsx`
+**Commit:** 02aa407
+**Status:** fixed: requires human verification (data-loss-prevention logic)
+**Applied fix:** Coordinated change so an edit no longer strips a recurring series:
+- `vevent.ts`: new `extractRruleString()` parses the existing RRULE from a stored VEVENT.
+- `outboxWorker.ts` (update path): when the payload carries no explicit `recurrence`, the
+  freshest-etag query also reads `rawVevent` and preserves the existing RRULE; an explicit
+  recurrence value (including `'none'`) still overrides.
+- `client.ts`: `CreateEventPayload.recurrence` made optional (matches the API Zod schema,
+  which already had it optional).
+- `EventForm.tsx`: on edit, `recurrence` is omitted from the payload (signals "unchanged")
+  and the recurrence `<select>` is disabled — editing recurrence is deferred until the
+  occurrence contract exposes it.
+
+### WR-02: Default-calendar selection on create is non-deterministic
+
+**Files modified:** `apps/api/src/routes/events.ts`
+**Commit:** 5499f83
+**Applied fix:** Added `.orderBy(calendars.id).limit(1)` to the default-calendar query in
+POST `/create`, giving a stable insertion-order default instead of an arbitrary `[0]`.
+
+### WR-03: `parseDateTime` all-day check uses the raw `iso`, not the cleaned string
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`
+**Commit:** d34edec
+**Applied fix:** The all-day regex test and early return now use `clean` (IANA-suffix
+stripped) instead of the raw `iso`, matching the documented strip intent.
+
+### WR-04: Worker cron schedules start on bare module import — pollutes the test process
+
+**Files modified:** `apps/api/src/index.ts`
+**Commit:** 7bc129f
+**Applied fix:** `startBrokerPoller()` and `startOutboxWorker()` moved out of top level
+into the `isMainModule()` entrypoint guard, so importing `./index.js` in route tests no
+longer registers real `node-cron` schedules or leaks open handles.
+
+### WR-05: `index.ts` direct-run guard is fragile and can mis-fire
+
+**Files modified:** `apps/api/src/index.ts`
+**Commit:** 22d1bc2
+**Applied fix:** Replaced the basename-tail `endsWith` heuristic with
+`isMainModule()` comparing `fileURLToPath(import.meta.url)` against
+`realpathSync(process.argv[1])` (symlink-resolved), guarded by try/catch.
+
+### WR-06: Edit-as-move create-412 dead-ends the move with no retry path
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`, `apps/pwa/src/components/SyncStateToast.tsx`
+**Commit:** 1c71f8c
+**Status:** fixed: requires human verification (UX/conflict-flow logic)
+**Applied fix:** When a create row carrying a `groupId` (edit-as-move) hits 412, the
+worker now writes a distinct `move-failed:` `lastError` (no `'412'` substring).
+`SyncStateToast` detects it (`error.startsWith('move-failed')`), routes it away from the
+etag-conflict copy, and shows "Couldn't move the event. Open it and save again." No
+contract change — surfaced via the existing `sync-status` `error` field.
+
+### IN-01: `triggerTargetedResync` re-loads and re-decrypts the credential per row
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`
+**Commit:** 95f9d8c
+**Applied fix:** `triggerTargetedResync` accepts an optional per-drain-cycle
+`Map<number, FastmailClient>` cache; `runOutboxDrain` creates one per cycle and passes it
+to both call sites, so each member's credential is decrypted at most once per cycle
+(narrows the decrypted-password-in-memory window, T-03-13). Cache is discarded when the
+drain returns.
+
+### IN-02: Unknown-status responses retried for the full backoff window before giving up
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`
+**Commit:** e29d6c1
+**Status:** fixed: requires human verification (error-classification logic)
+**Applied fix:** `dispatchRow` now classifies any unmapped 4xx (status 400–499, after the
+explicit 408/429 transient set and 400/401/403 hard-fail set are handled) as a hard fail,
+so permanent client errors (405/409/422) settle immediately instead of burning the retry
+budget. 5xx, network, and truly unknown statuses still fall through to transient.
+
+### IN-03: `InstallPrompt` reads `localStorage` synchronously without try/catch
+
+**Files modified:** `apps/pwa/src/components/InstallPrompt.tsx`
+**Commit:** 7e4ea71
+**Applied fix:** Added guarded `readDismissed()` / `persistDismissed()` helpers
+(try/catch, mirroring `calendarStore.ts`) used by the `useState` initializer and
+`dismiss()`, so a throwing `localStorage` (private mode / SSR) degrades to "not dismissed"
+instead of crashing the component on mount.
+
+### IN-04: `resolveUserId` typed as `any`
+
+**Files modified:** `apps/api/src/routes/events.ts`
+**Commit:** 6d2fd79
+**Applied fix:** Parameter typed as Hono's `Context` (imported as a type) instead of
+`any`, removing the eslint-disable. `c.get('user')` resolves through the existing
+`ContextVariableMap` augmentation in `auth/devBypass.ts` and `getAuth(c)` accepts a
+`Context`. Used `Context` rather than the reviewer's literal
+`Context<{ Variables: { user?: { id: number } } }>` because the latter would conflict
+with the global `ContextVariableMap` augmentation (which types `user` non-optionally as
+the DEV_USER shape).
+
+## Skipped Issues
+
+### IN-05: `deleteCalendarEvent` relies on tsdav ignoring `data: ''`
+
+**File:** `apps/api/src/broker/write.ts:93`
+**Reason:** skipped: reviewer specifies "None required for v1; note on the tsdav upgrade
+checklist." No source change is warranted — the finding asks for a process/checklist note,
+not a code fix. The existing inline comment already documents the dependency on tsdav
+internals. Flagged here so the developer can add a tsdav-upgrade-checklist entry.
+**Original issue:** Passes an empty `data` placeholder because tsdav requires the
+`DAVCalendarObject` shape. Relies on tsdav internals; a future version validating `data`
+would break this silently.
+
+---
+
+_Fixed: 2026-06-09_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 1_

.planning/phases/03-event-write-back-pwa-install/03-REVIEW-FIX.iter3.md

@@ -0,0 +1,84 @@
+---
+phase: 03-event-write-back-pwa-install
+fixed_at: 2026-06-09T15:06:11Z
+review_path: .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+iteration: 2
+findings_in_scope: 8
+fixed: 8
+skipped: 0
+status: all_fixed
+---
+
+# Phase 3: Code Review Fix Report (Iteration 2)
+
+**Fixed at:** 2026-06-09T15:06:11Z
+**Source review:** .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+**Iteration:** 2
+
+**Summary:**
+- Findings in scope: 8 (fix_scope: all — Critical + Warning + Info)
+- Fixed: 8
+- Skipped: 0
+
+All fixes verified with `tsc --noEmit` AND the full vitest suite in BOTH apps:
+- `apps/api`: 108 tests pass (was 103 baseline; +5 new regression tests)
+- `apps/pwa`: 145 tests pass (was 141 baseline; +4 new regression tests)
+- Typecheck clean in both packages.
+
+## Fixed Issues
+
+### CR-01: Edit-as-move silently strips a recurring series' RRULE
+
+**Files modified:** `apps/api/src/routes/events.ts`, `apps/api/src/broker/outboxWorker.ts`, `apps/api/tests/routes/events.test.ts`, `apps/api/tests/broker/outboxWorker.test.ts`
+**Commit:** 5168920
+**Applied fix:** Used the review's approach 1 (forward the RRULE from the route). The PATCH edit lookup now also selects `calendarEvents.rawVevent`. In the edit-as-move branch, when the edit payload carries no explicit `recurrence`, the route extracts the source RRULE via `extractRruleString()` and stashes it on the create outbox payload as `_preservedRrule`. The worker's `create` branch now mirrors the `update` branch's recurrence logic: it re-applies `_preservedRrule` when the payload omits `recurrence`, while an explicit `recurrence` (including `'none'`) still wins. Added two worker regression tests (moved event → emitted ICS contains `RRULE:`; explicit `recurrence:'none'` suppresses RRULE even when `_preservedRrule` present) and one route regression test (move stashes the source `FREQ=WEEKLY;BYDAY=MO` on the create row).
+**Note:** Logic-sensitive fix. Backed by direct regression tests asserting the RRULE survives the move on both the route side (payload stash) and the worker side (ICS re-apply), so behavior is locked rather than relying on syntax verification alone.
+
+### WR-01: Edit form provides no indication recurrence is locked
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** Additive helper text only (no logic change). In edit mode, explanatory copy renders beneath the disabled recurrence select: "Repeat can't be changed yet — edits keep the existing schedule." Added two tests (text present in edit mode; absent in create mode).
+
+### WR-02: `handleAllDayToggle` can leave end-date inconsistent
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** On toggle-on, `endDate` is clamped to `max(startDate, endDate)` deterministically (snaps a behind-end up to the start day) and any stale end-time error from the timed view is cleared. Added a test toggling all-day ON with end behind start, asserting the clamp and clean validation. Per the review's prescribed `max(startDate, endDate)` fix, a genuinely midnight-spanning event (end day after start day) still yields a 2-day all-day span — the clamp only repairs the behind-case, matching the review's suggested fix exactly.
+
+### WR-03: Missing cached etag becomes an unconditional PUT/DELETE
+
+**Files modified:** `apps/api/src/broker/write.ts`
+**Commit:** 5b720ff
+**Applied fix:** Took the review's minimum (observability). `updateCalendarEvent` and `deleteCalendarEvent` now `console.warn` when dispatched with a null/empty etag, making the unconditional-write (conflict-detection-disabled) path observable instead of silent. The write is not blocked (blocking would strand the user's edit).
+
+### WR-04: `sync-status` masks an earlier failure behind the newest row
+
+**Files modified:** `apps/api/src/routes/events.ts`, `apps/api/tests/routes/events.test.ts`
+**Commit:** fd13852
+**Applied fix:** The `sync-status` query now orders by a status-priority CASE (`failed`/`dead` rank 0, `pending` rank 1, `done` rank 2) before `createdAt DESC`, so any failed/dead row for the uid is surfaced ahead of a later `done` row. Added a test seeding a dead row, asserting the handler returns `dead` + its error and that the ORDER BY contains the priority CASE expression (scanned via the Drizzle sql `queryChunks` to avoid the circular-structure JSON.stringify pitfall).
+
+### IN-01: `RRULE_PRESETS` round-trip is lossy for parameterized RRULEs
+
+**Files modified:** `apps/api/src/broker/vevent.ts`
+**Commit:** f95760e
+**Applied fix:** Documentation only. Added a v1-limitation note at `RRULE_PRESETS` explaining that applying a bare preset to a previously-rich rule drops BYDAY/INTERVAL/UNTIL/COUNT, and that recurrence editing must modify the parsed RECUR in place rather than replacing it with a preset.
+
+### IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** `parseDateTime` now returns an `ok` flag. A new `initFormDateTime()` helper falls back to today/09:00 only on the CREATE path (benign default for a new event); in EDIT mode a parse failure leaves the field blank. `validate()` blocks submit when start/end (or time for non-all-day) is blank, surfacing "Couldn't read this event's date — re-open it from the calendar." Added a test: edit mode with an unparseable start leaves the date blank and blocks `updateEvent`.
+**Note:** Logic-sensitive (changes validation flow). Backed by a regression test asserting the blank field + blocked submit; CREATE-mode defaults remain covered by existing tests.
+
+### IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`, `apps/api/tests/broker/outboxWorker.test.ts`
+**Commit:** b8c1864
+**Applied fix:** Added a worker-local zod schema (`outboxPayloadSchema`, mirroring `eventFieldsSchema` and `.passthrough()`-ing the CR-01 `_preservedRrule` field). Both the `update` and `create` branches now `safeParse` the JSON payload after parsing and hard-fail the row (no retry) on validation error, so a schema-invalid row can never dispatch `SUMMARY:undefined`/Invalid Date. Added a test: a create row missing `title` is hard-failed and never dispatched.
+
+---
+
+_Fixed: 2026-06-09T15:06:11Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 2_

.planning/phases/03-event-write-back-pwa-install/03-REVIEW-FIX.md

@@ -0,0 +1,84 @@
+---
+phase: 03-event-write-back-pwa-install
+fixed_at: 2026-06-09T15:06:11Z
+review_path: .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+iteration: 2
+findings_in_scope: 8
+fixed: 8
+skipped: 0
+status: all_fixed
+---
+
+# Phase 3: Code Review Fix Report (Iteration 2)
+
+**Fixed at:** 2026-06-09T15:06:11Z
+**Source review:** .planning/phases/03-event-write-back-pwa-install/03-REVIEW.md
+**Iteration:** 2
+
+**Summary:**
+- Findings in scope: 8 (fix_scope: all — Critical + Warning + Info)
+- Fixed: 8
+- Skipped: 0
+
+All fixes verified with `tsc --noEmit` AND the full vitest suite in BOTH apps:
+- `apps/api`: 108 tests pass (was 103 baseline; +5 new regression tests)
+- `apps/pwa`: 145 tests pass (was 141 baseline; +4 new regression tests)
+- Typecheck clean in both packages.
+
+## Fixed Issues
+
+### CR-01: Edit-as-move silently strips a recurring series' RRULE
+
+**Files modified:** `apps/api/src/routes/events.ts`, `apps/api/src/broker/outboxWorker.ts`, `apps/api/tests/routes/events.test.ts`, `apps/api/tests/broker/outboxWorker.test.ts`
+**Commit:** 5168920
+**Applied fix:** Used the review's approach 1 (forward the RRULE from the route). The PATCH edit lookup now also selects `calendarEvents.rawVevent`. In the edit-as-move branch, when the edit payload carries no explicit `recurrence`, the route extracts the source RRULE via `extractRruleString()` and stashes it on the create outbox payload as `_preservedRrule`. The worker's `create` branch now mirrors the `update` branch's recurrence logic: it re-applies `_preservedRrule` when the payload omits `recurrence`, while an explicit `recurrence` (including `'none'`) still wins. Added two worker regression tests (moved event → emitted ICS contains `RRULE:`; explicit `recurrence:'none'` suppresses RRULE even when `_preservedRrule` present) and one route regression test (move stashes the source `FREQ=WEEKLY;BYDAY=MO` on the create row).
+**Note:** Logic-sensitive fix. Backed by direct regression tests asserting the RRULE survives the move on both the route side (payload stash) and the worker side (ICS re-apply), so behavior is locked rather than relying on syntax verification alone.
+
+### WR-01: Edit form provides no indication recurrence is locked
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** Additive helper text only (no logic change). In edit mode, explanatory copy renders beneath the disabled recurrence select: "Repeat can't be changed yet — edits keep the existing schedule." Added two tests (text present in edit mode; absent in create mode).
+
+### WR-02: `handleAllDayToggle` can leave end-date inconsistent
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** On toggle-on, `endDate` is clamped to `max(startDate, endDate)` deterministically (snaps a behind-end up to the start day) and any stale end-time error from the timed view is cleared. Added a test toggling all-day ON with end behind start, asserting the clamp and clean validation. Per the review's prescribed `max(startDate, endDate)` fix, a genuinely midnight-spanning event (end day after start day) still yields a 2-day all-day span — the clamp only repairs the behind-case, matching the review's suggested fix exactly.
+
+### WR-03: Missing cached etag becomes an unconditional PUT/DELETE
+
+**Files modified:** `apps/api/src/broker/write.ts`
+**Commit:** 5b720ff
+**Applied fix:** Took the review's minimum (observability). `updateCalendarEvent` and `deleteCalendarEvent` now `console.warn` when dispatched with a null/empty etag, making the unconditional-write (conflict-detection-disabled) path observable instead of silent. The write is not blocked (blocking would strand the user's edit).
+
+### WR-04: `sync-status` masks an earlier failure behind the newest row
+
+**Files modified:** `apps/api/src/routes/events.ts`, `apps/api/tests/routes/events.test.ts`
+**Commit:** fd13852
+**Applied fix:** The `sync-status` query now orders by a status-priority CASE (`failed`/`dead` rank 0, `pending` rank 1, `done` rank 2) before `createdAt DESC`, so any failed/dead row for the uid is surfaced ahead of a later `done` row. Added a test seeding a dead row, asserting the handler returns `dead` + its error and that the ORDER BY contains the priority CASE expression (scanned via the Drizzle sql `queryChunks` to avoid the circular-structure JSON.stringify pitfall).
+
+### IN-01: `RRULE_PRESETS` round-trip is lossy for parameterized RRULEs
+
+**Files modified:** `apps/api/src/broker/vevent.ts`
+**Commit:** f95760e
+**Applied fix:** Documentation only. Added a v1-limitation note at `RRULE_PRESETS` explaining that applying a bare preset to a previously-rich rule drops BYDAY/INTERVAL/UNTIL/COUNT, and that recurrence editing must modify the parsed RECUR in place rather than replacing it with a preset.
+
+### IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00
+
+**Files modified:** `apps/pwa/src/components/EventForm.tsx`, `apps/pwa/src/components/EventForm.test.tsx`
+**Commit:** eed178f
+**Applied fix:** `parseDateTime` now returns an `ok` flag. A new `initFormDateTime()` helper falls back to today/09:00 only on the CREATE path (benign default for a new event); in EDIT mode a parse failure leaves the field blank. `validate()` blocks submit when start/end (or time for non-all-day) is blank, surfacing "Couldn't read this event's date — re-open it from the calendar." Added a test: edit mode with an unparseable start leaves the date blank and blocks `updateEvent`.
+**Note:** Logic-sensitive (changes validation flow). Backed by a regression test asserting the blank field + blocked submit; CREATE-mode defaults remain covered by existing tests.
+
+### IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields
+
+**Files modified:** `apps/api/src/broker/outboxWorker.ts`, `apps/api/tests/broker/outboxWorker.test.ts`
+**Commit:** b8c1864
+**Applied fix:** Added a worker-local zod schema (`outboxPayloadSchema`, mirroring `eventFieldsSchema` and `.passthrough()`-ing the CR-01 `_preservedRrule` field). Both the `update` and `create` branches now `safeParse` the JSON payload after parsing and hard-fail the row (no retry) on validation error, so a schema-invalid row can never dispatch `SUMMARY:undefined`/Invalid Date. Added a test: a create row missing `title` is hard-failed and never dispatched.
+
+---
+
+_Fixed: 2026-06-09T15:06:11Z_
+_Fixer: Claude (gsd-code-fixer)_
+_Iteration: 2_

.planning/phases/03-event-write-back-pwa-install/03-REVIEW.iter2.md

@@ -0,0 +1,181 @@
+---
+phase: 03-event-write-back-pwa-install
+reviewed: 2026-06-09T00:00:00Z
+depth: standard
+files_reviewed: 29
+files_reviewed_list:
+  - apps/api/src/broker/outboxWorker.ts
+  - apps/api/src/broker/sync.ts
+  - apps/api/src/broker/vevent.ts
+  - apps/api/src/broker/write.ts
+  - apps/api/src/db/schema.ts
+  - apps/api/src/index.ts
+  - apps/api/src/routes/events.ts
+  - apps/api/tests/broker/outboxWorker.test.ts
+  - apps/api/tests/broker/vevent.test.ts
+  - apps/api/tests/broker/write.test.ts
+  - apps/api/tests/routes/events.test.ts
+  - apps/pwa/index.html
+  - apps/pwa/package.json
+  - apps/pwa/src/api/client.test.ts
+  - apps/pwa/src/api/client.ts
+  - apps/pwa/src/components/CalendarShell.tsx
+  - apps/pwa/src/components/DeleteConfirmationDialog.test.tsx
+  - apps/pwa/src/components/DeleteConfirmationDialog.tsx
+  - apps/pwa/src/components/EventDetailPopover.test.tsx
+  - apps/pwa/src/components/EventDetailPopover.tsx
+  - apps/pwa/src/components/EventForm.test.tsx
+  - apps/pwa/src/components/EventForm.tsx
+  - apps/pwa/src/components/InstallPrompt.test.tsx
+  - apps/pwa/src/components/InstallPrompt.tsx
+  - apps/pwa/src/components/SyncStateToast.test.tsx
+  - apps/pwa/src/components/SyncStateToast.tsx
+  - apps/pwa/src/store/calendarStore.ts
+  - apps/pwa/vite.config.ts
+  - apps/pwa/vitest.config.ts
+findings:
+  critical: 3
+  warning: 6
+  info: 5
+  total: 14
+status: issues_found
+---
+
+# Phase 3: Code Review Report
+
+**Reviewed:** 2026-06-09
+**Depth:** standard
+**Files Reviewed:** 29
+**Status:** issues_found
+
+## Summary
+
+The phase-3 write-back path (events router → outbox → outboxWorker → CalDAV write wrappers) and the PWA write/install UI are generally well-structured, with thorough comments documenting prior fixes (BUG A/B, CR-xx, WR-xx). However the adversarial pass surfaced a recurring class of defect the comments missed: **`calendar_events` is keyed `(calendarId, uid)`, not `uid` alone, yet several lookups query by `uid` only.** Because both household members share one Fastmail account (D-16) and each member gets their own `calendars`/`calendar_events` rows for the same collection URL, a single UID exists in MULTIPLE rows. Three query sites take an arbitrary `[0]` row from that set, producing wrong-member ownership checks, wrong etag selection, and cross-member writes. This is the same `(userId, url)` scoping bug class that schema.ts comment "BUG B" already documents for `calendars` — it was not propagated to the event-row lookups.
+
+Additional findings: an all-day end-date inclusivity inconsistency that compounds on re-edit, a recurrence silently reset to `none` on every edit (data loss), a non-deterministic default-calendar pick, and worker cron schedules that fire on bare module import.
+
+## Narrative Findings (AI reviewer)
+
+## Critical Issues
+
+### CR-01: Event edit/delete ownership check resolves an arbitrary member's row (uid-only lookup)
+
+**File:** `apps/api/src/routes/events.ts:311-322` (edit) and `:411-422` (delete)
+**Issue:** Both handlers look up the event with `.where(eq(calendarEvents.uid, uid))` and destructure `const [eventRow]`. The unique key is `(calendarId, uid)` (`schema.ts:121`), and with a shared Fastmail account (D-16) the SAME uid is cached once per member's calendar — so this query returns 2+ rows and `[0]` is whichever the DB returns first (lowest id = typically the OTHER member). Consequences:
+- The ownership check `eventRow.userId !== currentUserId` can compare against the wrong member's calendar row, then fall through to the `isShared` branch and either wrongly 403 a legitimate owner or wrongly authorize against a different calendar.
+- The enqueued outbox row carries `eventRow.calendarUrl / objectUrl / etag` from the arbitrary row, so the write can target the wrong member's object URL / etag.
+
+The `GET /` handler correctly scopes by `or(eq(calendars.userId, currentUserId), eq(calendars.isShared, true))`; the write lookups do not. This is the exact bug class schema.ts "BUG B" warns about, un-propagated to the event lookups.
+**Fix:** Scope the lookup to the current user's writable set and disambiguate deterministically:
+```ts
+const [eventRow] = await db
+  .select({ /* …same cols… */ })
+  .from(calendarEvents)
+  .innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))
+  .where(and(
+    eq(calendarEvents.uid, uid),
+    or(eq(calendars.userId, currentUserId), eq(calendars.isShared, true)),
+  ))
+  .limit(1)
+```
+Prefer the current user's own row over a shared/other row if both match (e.g. order so `calendars.userId = currentUserId` ranks first), so the etag/objectUrl chosen belongs to the acting member.
+
+### CR-02: Outbox WR-02 "freshest etag" re-read also queries uid-only — can pick the wrong member's etag
+
+**File:** `apps/api/src/broker/outboxWorker.ts:205-211`
+**Issue:** Before a PUT, the worker re-reads the freshest etag with `db.select({ etag }).from(calendarEvents).where(eq(calendarEvents.uid, row.uid))` and takes `freshEtagRows[0].etag`. Same uid-collision problem as CR-01: for a shared-account uid this returns multiple rows and `[0]` may be the OTHER member's etag. Using a foreign etag in `If-Match` will either spuriously 412 (false conflict → the edit is marked `failed` with no retry, D-08, user sees the conflict toast and the edit is dropped) or, worse, match by coincidence and overwrite. The intended WR-02 behavior (avoid stale-etag 412 on rapid edits) is undermined.
+**Fix:** Scope the re-read to the row's own calendar. The outbox row knows `calendarUrl` and `userId`; join through `calendars`:
+```ts
+const freshEtagRows = await db
+  .select({ etag: calendarEvents.etag })
+  .from(calendarEvents)
+  .innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))
+  .where(and(
+    eq(calendarEvents.uid, row.uid),
+    eq(calendars.userId, row.userId),
+    eq(calendars.url, row.calendarUrl),
+  ))
+  .limit(1)
+```
+
+### CR-03: All-day end date is exclusive on write but inclusive on edit pre-fill — span grows one day per re-edit
+
+**File:** `apps/api/src/broker/vevent.ts:83-90` vs `apps/pwa/src/components/EventForm.tsx:178-187` / `apps/api/src/broker/expand.ts`
+**Issue:** `buildVeventString` advances the all-day DTEND by one calendar day to satisfy RFC-5545's exclusive-end rule (`vevent.ts:86-87`), treating the form's `end` as the inclusive last day. But on **edit**, the form pre-populates `endDate` from `occurrence.end` (`EventForm.tsx:181,187`), and `occurrence.end` for an all-day event coming back from sync/expand is the **exclusive** DTEND ('YYYY-MM-DD') that Fastmail stored. Round-tripping an edit therefore re-advances the already-exclusive end by another day on each save, silently growing multi-day all-day events by one day per edit. Even a no-op title edit corrupts the date span.
+**Fix:** Make the inclusive/exclusive contract explicit and symmetric. Either (a) keep `occurrence.end` exclusive everywhere and subtract one day before pre-filling the all-day end-date input in `EventForm`, or (b) expose an inclusive end on the occurrence and convert to exclusive only at the ICS boundary. Add a regression test that edits an all-day multi-day event twice and asserts the span is stable.
+
+## Warnings
+
+### WR-01: Recurrence is silently reset to `none` on every edit — data loss on recurring events
+
+**File:** `apps/pwa/src/components/EventForm.tsx:188-196`
+**Issue:** `occurrence.recurrence` is not part of the `CalendarOccurrence` contract, so the edit form casts to `any`, reads `undefined`, and defaults `recurrence` to `'none'` (comment acknowledges this). Saving an edit to a recurring event then enqueues `recurrence: 'none'`, and `outboxWorker` builds a VEVENT with no RRULE — converting a weekly series into a single event on Fastmail. Any edit to a recurring event (e.g. fixing a typo) destroys the recurrence. Flagged WARNING only because v1 may not yet expose editing recurring events through this surface — confirm; otherwise promote to BLOCKER.
+**Fix:** Either expose recurrence on the occurrence/expand contract and pre-fill it, or disable the recurrence `<select>` and omit `recurrence` from the update payload (so the worker preserves the existing RRULE) when editing a known-recurring event.
+
+### WR-02: Default-calendar selection on create is non-deterministic (no ORDER BY)
+
+**File:** `apps/api/src/routes/events.ts:260-268`
+**Issue:** When `calendarUrl` is omitted, the handler picks `const [calRow] = await db.select(...).where(eq(calendars.userId, currentUserId))` with no `orderBy` and no `limit(1)`. A member with multiple personal calendars gets an arbitrary "first" calendar that can change between requests. D-01 intends a stable default. The PWA mitigates by sending `calendarUrl` when `writableCalendars.length > 1`, but the result is undefined-ordered whenever this path is reached.
+**Fix:** Add deterministic order and limit: `.orderBy(calendars.id).limit(1)`, or prefer a calendar flagged as default.
+
+### WR-03: `parseDateTime` all-day check uses the raw `iso`, not the cleaned string
+
+**File:** `apps/pwa/src/components/EventForm.tsx:88-93`
+**Issue:** `clean` strips the `[IANA]` suffix, but the all-day regex test runs against the original `iso` and the early return returns `{ date: iso }` (raw). For a true all-day 'YYYY-MM-DD' this is fine, but a date-only value carrying a bracket suffix would skip the all-day branch and fall through to `new Date(clean)`. The variable used contradicts the "Strip IANA bracket suffix" intent documented one line above.
+**Fix:** Test and return `clean`: `if (/^\d{4}-\d{2}-\d{2}$/.test(clean)) return { date: clean, time: '09:00' }`.
+
+### WR-04: Worker cron schedules start on bare module import — pollutes the test process
+
+**File:** `apps/api/src/index.ts:63-67`
+**Issue:** `startBrokerPoller()` and `startOutboxWorker()` are called at top level, so importing `./index.js` (the route tests import `app` from here) registers real `node-cron` schedules. They will fire drains/polls during the test run, touch the mocked DB/CalDAV layers nondeterministically, and keep open handles that prevent clean process exit.
+**Fix:** Move worker startup inside the direct-run guard (see WR-05) or gate it behind `if (process.env.NODE_ENV !== 'test')`.
+
+### WR-05: `index.ts` direct-run guard is fragile and can mis-fire
+
+**File:** `apps/api/src/index.ts:79`
+**Issue:** `import.meta.url.endsWith(process.argv[1].replace(/^.*\//, ''))` compares the module URL tail to the basename of argv[1]. A symlinked entrypoint or a differently-located file with the same basename can make this either fail to start the server in production or start it during an unrelated import.
+**Fix:** Use a robust check, e.g. `fileURLToPath(import.meta.url) === realpathSync(process.argv[1])`.
+
+### WR-06: Edit-as-move create-412 dead-ends the move with no retry path
+
+**File:** `apps/api/src/broker/outboxWorker.ts:401-411` + `:361-396`
+**Issue:** For edit-as-move the create runs first; on 412 it is marked `failed`, the durable gate later marks the paired delete `failed` ("original preserved"). No data is lost (original event survives), but the PWA set `lastSyncedUid` to the NEW uid (`EventForm.tsx:373`), whose only outbox row is `failed` — so the toast shows a conflict and there is no path to retry the move; the move is silently abandoned.
+**Fix:** Surface that the move did not apply (distinct from a same-calendar conflict) and guide the user to re-open and re-save.
+
+## Info
+
+### IN-01: `triggerTargetedResync` re-loads and re-decrypts the credential per row
+
+**File:** `apps/api/src/broker/outboxWorker.ts:108-111`
+**Issue:** Each successful/conflicted row independently calls `loadClientForUser` (DB read + AES-GCM decrypt) inside the drain loop, widening the window the decrypted password is held in memory.
+**Fix:** Optionally cache the client per userId within a single drain cycle.
+
+### IN-02: Unknown-status responses retried for the full backoff window before giving up
+
+**File:** `apps/api/src/broker/outboxWorker.ts:288-295`
+**Issue:** Any unmapped non-ok status (e.g. 405, 409, 422) is classified `transient` and retried to MAX_ATTEMPTS then dead-lettered. Safe (no data loss) but slow to settle for a permanent 4xx.
+**Fix:** Treat unmapped 4xx (except 408/429) as hard fail; keep transient only for 5xx/network/unknown.
+
+### IN-03: `InstallPrompt` reads `localStorage` synchronously in `useState` initializer without try/catch
+
+**File:** `apps/pwa/src/components/InstallPrompt.tsx:282-284`
+**Issue:** Unlike `calendarStore.ts`, this access is unguarded; in private-mode/SSR contexts where `localStorage` throws it crashes the component on mount. `dismiss()` (`:298`) is likewise unguarded.
+**Fix:** Wrap in try/catch returning `false`, mirroring the store's pattern.
+
+### IN-04: `resolveUserId` typed as `any`
+
+**File:** `apps/api/src/routes/events.ts:59`
+**Issue:** The Hono context is `any` (eslint-disabled), losing type safety on `c.get('user')` and `getAuth`.
+**Fix:** Type as `Context<{ Variables: { user?: { id: number } } }>`.
+
+### IN-05: `deleteCalendarEvent` relies on tsdav ignoring `data: ''`
+
+**File:** `apps/api/src/broker/write.ts:93`
+**Issue:** Passes an empty `data` placeholder because tsdav requires the `DAVCalendarObject` shape. Relies on tsdav internals; a future version validating `data` would break this silently.
+**Fix:** None required for v1; note on the tsdav upgrade checklist.
+
+---
+
+_Reviewed: 2026-06-09_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: standard_

.planning/phases/03-event-write-back-pwa-install/03-REVIEW.iter3.md

@@ -0,0 +1,160 @@
+---
+phase: 03-event-write-back-pwa-install
+reviewed: 2026-06-09T00:00:00Z
+depth: standard
+files_reviewed: 29
+files_reviewed_list:
+  - apps/api/src/broker/outboxWorker.ts
+  - apps/api/src/broker/sync.ts
+  - apps/api/src/broker/vevent.ts
+  - apps/api/src/broker/write.ts
+  - apps/api/src/db/schema.ts
+  - apps/api/src/index.ts
+  - apps/api/src/routes/events.ts
+  - apps/api/tests/broker/outboxWorker.test.ts
+  - apps/api/tests/broker/vevent.test.ts
+  - apps/api/tests/broker/write.test.ts
+  - apps/api/tests/routes/events.test.ts
+  - apps/pwa/index.html
+  - apps/pwa/package.json
+  - apps/pwa/src/api/client.test.ts
+  - apps/pwa/src/api/client.ts
+  - apps/pwa/src/components/CalendarShell.tsx
+  - apps/pwa/src/components/DeleteConfirmationDialog.test.tsx
+  - apps/pwa/src/components/DeleteConfirmationDialog.tsx
+  - apps/pwa/src/components/EventDetailPopover.test.tsx
+  - apps/pwa/src/components/EventDetailPopover.tsx
+  - apps/pwa/src/components/EventForm.test.tsx
+  - apps/pwa/src/components/EventForm.tsx
+  - apps/pwa/src/components/InstallPrompt.test.tsx
+  - apps/pwa/src/components/InstallPrompt.tsx
+  - apps/pwa/src/components/SyncStateToast.test.tsx
+  - apps/pwa/src/components/SyncStateToast.tsx
+  - apps/pwa/src/store/calendarStore.ts
+  - apps/pwa/vite.config.ts
+  - apps/pwa/vitest.config.ts
+findings:
+  critical: 1
+  warning: 4
+  info: 3
+  total: 8
+status: issues_found
+---
+
+# Phase 3: Code Review Report (Re-Review, Iteration 2)
+
+**Reviewed:** 2026-06-09
+**Depth:** standard
+**Files Reviewed:** 29
+**Status:** issues_found
+
+## Summary
+
+This is a re-review of the event write-back + PWA-install phase after a 13-item fix pass. I verified each of the previously flagged fixes the orchestrator called out:
+
+- **CR-01 / CR-02 member-scoped lookups** — VERIFIED FIXED. `events.ts` PATCH/DELETE now scope the `calendarEvents` lookup to the acting member's writable set and add a deterministic `ORDER BY (calendars.userId = currentUserId) DESC LIMIT 1` (events.ts:340-347, 453-460). `outboxWorker.ts`'s fresh-etag re-read now joins `calendars` and filters on `calendars.userId = row.userId AND calendars.url = row.calendarUrl` (outboxWorker.ts:228-239), so a shared-account duplicate uid can no longer resolve to the wrong member's etag.
+- **CR-03 all-day inclusive/exclusive DTEND** — VERIFIED FIXED and now symmetric. `vevent.ts:106-118` advances the inclusive end by one UTC day on write; `EventForm.tsx:86-96` `exclusiveEndToInclusiveDate()` rolls it back on pre-fill. The round-trip no longer grows multi-day all-day spans. `vevent.test.ts:140-160` asserts DTEND = DTSTART + 1.
+- **WR-01 RRULE preserve-on-edit** — PARTIALLY FIXED. The same-calendar `update` path correctly preserves the stored RRULE (`outboxWorker.ts:244-248` reads `rawVevent`, extracts the RRULE, re-applies when the payload omits `recurrence`). **The edit-as-move path (D-04) still silently strips recurrence** — see CR-01. This is a real, demonstrable correctness regression of exactly the class WR-01 set out to prevent, so it is filed as a BLOCKER.
+
+Other fixes (backoff index `outboxWorker.ts:533-535`, fail-closed credentials `outboxWorker.ts:163-167`, durable create-before-delete `outboxWorker.ts:427-464`, move-failed toast copy `SyncStateToast.tsx:53-58`, localStorage guards `InstallPrompt.tsx:284-298`) are present and correct.
+
+## Critical Issues
+
+### CR-01: Edit-as-move silently strips a recurring series' RRULE
+
+**File:** `apps/api/src/broker/outboxWorker.ts:267-297`, `apps/api/src/routes/events.ts:371-401`
+
+**Issue:** WR-01 was fixed only for the same-calendar `update` branch. When a recurring event is edited *and moved to a different calendar*, the PATCH handler (`events.ts:371-398`) enqueues a `delete` of the old object plus a `create` with a brand-new `newUid` and the edit payload. The edit payload omits `recurrence` by design (`EventForm.tsx:323`; the recurrence picker is disabled in edit mode). The worker's `create` branch then builds the VEVENT with:
+
+```ts
+rruleString: fields.recurrence && fields.recurrence !== 'none'
+  ? RRULE_PRESETS[fields.recurrence as string]
+  : undefined,   // ← recurrence absent → undefined → no RRULE
+```
+
+Unlike the `update` branch, the `create` branch performs **no** `rawVevent` read and **no** `extractRruleString` fallback. The original event's RRULE lives in `calendar_events` under the OLD uid/calendar; the create uses `newUid` and never reads it. Net effect: moving any recurring event to another calendar converts the whole series into a single one-off occurrence on Fastmail — silent data loss — and the original series is deleted once the paired delete runs. This is the identical failure mode WR-01 was meant to eliminate, on a different code path.
+
+**Fix:** Carry the existing RRULE through the move. Two viable approaches:
+
+1. In `events.ts`, have the edit lookup also select `rawVevent`, extract the RRULE, and stash it on the create outbox row so the worker re-applies it:
+
+```ts
+// events.ts — add rawVevent to the eventRow select, then in the move branch:
+const preservedRrule = extractRruleString(eventRow.rawVevent ?? '')
+await tx.insert(calendarOutbox).values({
+  /* ...create row... */
+  payload: JSON.stringify({ ...payload, _preservedRrule: preservedRrule }),
+  groupId,
+})
+```
+…and in the worker `create` branch, fall back to `fields._preservedRrule` when `recurrence` is absent.
+
+2. Or, in the worker `create` branch, when the row has a `groupId` (move) and the payload lacks `recurrence`, look up the RRULE from the sibling delete row's original uid/calendar via `calendarEvents.rawVevent` and feed it to `buildVeventString`, mirroring `outboxWorker.ts:244-248`.
+
+Add a regression test: move a recurring event → assert the created ICS contains `RRULE:`.
+
+## Warnings
+
+### WR-01: Edit form cannot edit recurrence and provides no way to remove an RRULE
+
+**File:** `apps/pwa/src/components/EventForm.tsx:311-327, 715-742`
+
+**Issue:** The recurrence `<select>` is hard-disabled in edit mode and the payload always omits `recurrence` on edit. Combined with server-side preservation, a user can never (a) change a recurring event's frequency, nor (b) intentionally make a recurring event non-recurring — the worker treats "no recurrence field" as "keep the existing RRULE," so there is no way to express "remove the RRULE." For v1 this is an accepted scope cut (documented in comments), but it is a silent usability trap: a user who opens a weekly event, changes the title, and saves gets no indication the schedule is locked. The disabled control has `opacity: 0.6` and no explanatory text.
+
+**Fix:** Acceptable to defer full edit-recurrence, but surface the constraint: when `eventFormMode === 'edit'`, render helper text near the disabled select (e.g. "Repeat can't be changed yet — edits keep the existing schedule"). Additive copy only; no logic change.
+
+### WR-02: `handleAllDayToggle` can leave end-date inconsistent with the discarded time inputs
+
+**File:** `apps/pwa/src/components/EventForm.tsx:259-271, 287-289`
+
+**Issue:** `validate()` for all-day uses strict `endDate < startDate`. `handleAllDayToggle` only advances `endDate` to `startDate` when toggling all-day ON *and* `endDate < startDate`. When a timed event spans midnight (start 2026-06-10 23:00, end 2026-06-11 01:00) and the user toggles all-day ON, the time inputs are discarded but `endDate` is left at 06-11, producing a 2-day all-day event the user likely did not intend; conversely, toggle paths that leave `endDate === startDate` validate as a 1-day event silently. Not data loss, but the toggle can change the event span without a clear signal.
+
+**Fix:** On toggle-on, clamp `endDate` to `max(startDate, endDate)` deterministically and clear time errors. Add a test covering toggle-on across a midnight-spanning timed event.
+
+### WR-03: Missing cached etag becomes an unconditional PUT/DELETE, defeating D-08 conflict detection
+
+**File:** `apps/api/src/routes/events.ts:385, 411, 486`; `apps/api/src/broker/write.ts:62-75, 85-97`
+
+**Issue:** When `eventRow.etag` is null (event cached before an etag was captured, or Fastmail omitted it), the outbox row's `etag` is `undefined`, and `write.ts` maps null/`''` to "no If-Match header" — an **unconditional** PUT/DELETE. That defeats conflict detection for exactly the rows most likely to be stale: a concurrent external edit is silently overwritten with no 412. Only triggers when the cached etag is missing, so Warning rather than Blocker.
+
+**Fix:** Make the no-etag policy explicit. Safer: when no etag is available, fetch the current etag (REPORT/GET) before writing, or skip the write and force a re-sync. At minimum, log a warning when an update/delete dispatches with an empty If-Match so the unconditional-write path is observable.
+
+### WR-04: `sync-status` reports only the newest outbox row per uid, masking an earlier failure
+
+**File:** `apps/api/src/routes/events.ts:511-532`; `apps/pwa/src/components/SyncStateToast.tsx:39-70`
+
+**Issue:** `sync-status` selects `ORDER BY createdAt DESC LIMIT 1` for `(userId, uid)`. For rapid successive same-uid edits (two `update` rows enqueued before the worker drains), the toast reports only the newest row's status. If the newest succeeds but an older row dead-letters, the user sees "Saved" while a queued write silently failed. Window is small (single-process 15s drain) but real under burst edits.
+
+**Fix:** Prefer a non-terminal/`failed`/`dead` row over a `done` row when reporting status for a uid (order so `pending`/`failed`/`dead` outranks `done`), or report `failed`/`dead` if ANY row for the uid is in that state. Add a test with two update rows where the older is `dead`.
+
+## Info
+
+### IN-01: `RRULE_PRESETS` round-trip is lossy for any parameterized RRULE
+
+**File:** `apps/api/src/broker/vevent.ts:39-44, 53-67`; `apps/api/src/broker/outboxWorker.ts:208-211`
+
+**Issue:** `RRULE_PRESETS` maps only to bare `FREQ=DAILY|WEEKLY|MONTHLY|YEARLY`. `extractRruleString` returns the full stored RECUR (which may include `BYDAY`, `INTERVAL`, `COUNT`, `UNTIL`). The preserve path keeps the rich rule (good), but if a `recurrence` value is ever set on a previously-rich rule, it collapses to the bare preset — dropping `BYDAY`/`UNTIL`. Acceptable for v1 (picker offers only the four bare presets and is disabled on edit), but a latent foot-gun once recurrence editing ships.
+
+**Fix:** Document the v1 limitation at the `RRULE_PRESETS` definition; when recurrence editing lands, modify the parsed RECUR rather than replacing it with a preset.
+
+### IN-02: `parseDateTime` silently rewrites a malformed edit value to today/09:00
+
+**File:** `apps/pwa/src/components/EventForm.tsx:107-131`
+
+**Issue:** On an unparseable occurrence start/end the form falls back to `todayIso()`/09:00 with no user signal. In edit mode a corrupt cached value silently rewrites the event to today at 09:00 if the user saves without noticing. Low probability (the API produces well-formed ISO), but a silent data-changing default in an edit form is worth a guard.
+
+**Fix:** In edit mode, on parse failure, leave the field blank and block submit rather than substituting today/09:00.
+
+### IN-03: Unchecked `as` casts on JSON-parsed outbox payload fields
+
+**File:** `apps/api/src/broker/outboxWorker.ts:251-258, 285-293`
+
+**Issue:** `fields.title as string`, `fields.allDay as boolean`, `fields.start as string`, etc. are unchecked casts on a `Record<string, unknown>` parsed from stored JSON. The payload is zod-validated at enqueue, so low-risk, but schema drift or a manually-inserted row would pass `undefined`/wrong types into `buildVeventString`, producing `SUMMARY:undefined` or an `Invalid Date`.
+
+**Fix:** Re-validate the parsed payload with `eventFieldsSchema` (or a worker-local zod schema) before building the VEVENT, and hard-fail the row on validation error (it can never succeed). Cheap insurance against enqueue→drain schema drift.
+
+---
+
+_Reviewed: 2026-06-09_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: standard_

.planning/phases/03-event-write-back-pwa-install/03-REVIEW.md

@@ -1,8 +1,8 @@
 ---
 phase: 03-event-write-back-pwa-install
-reviewed: 2026-06-05T00:00:00Z
+reviewed: 2026-06-09T00:00:00Z
 depth: standard
-files_reviewed: 18
+files_reviewed: 29
 files_reviewed_list:
   - apps/api/src/broker/outboxWorker.ts
   - apps/api/src/broker/sync.ts
@@ -11,199 +11,99 @@ files_reviewed_list:
   - apps/api/src/db/schema.ts
   - apps/api/src/index.ts
   - apps/api/src/routes/events.ts
+  - apps/api/tests/broker/outboxWorker.test.ts
+  - apps/api/tests/broker/vevent.test.ts
+  - apps/api/tests/broker/write.test.ts
+  - apps/api/tests/routes/events.test.ts
   - apps/pwa/index.html
+  - apps/pwa/package.json
+  - apps/pwa/src/api/client.test.ts
   - apps/pwa/src/api/client.ts
   - apps/pwa/src/components/CalendarShell.tsx
+  - apps/pwa/src/components/DeleteConfirmationDialog.test.tsx
   - apps/pwa/src/components/DeleteConfirmationDialog.tsx
+  - apps/pwa/src/components/EventDetailPopover.test.tsx
   - apps/pwa/src/components/EventDetailPopover.tsx
+  - apps/pwa/src/components/EventForm.test.tsx
   - apps/pwa/src/components/EventForm.tsx
+  - apps/pwa/src/components/InstallPrompt.test.tsx
   - apps/pwa/src/components/InstallPrompt.tsx
+  - apps/pwa/src/components/SyncStateToast.test.tsx
   - apps/pwa/src/components/SyncStateToast.tsx
   - apps/pwa/src/store/calendarStore.ts
   - apps/pwa/vite.config.ts
-  - apps/pwa/package.json
+  - apps/pwa/vitest.config.ts
 findings:
-  critical: 6
-  warning: 8
-  info: 5
-  total: 19
+  critical: 0
+  warning: 2
+  info: 2
+  total: 4
 status: issues_found
 ---
 
-# Phase 3: Code Review Report
+# Phase 3: Code Review Report (Re-Review, Iteration 3 — final --auto pass)
 
-**Reviewed:** 2026-06-05
+**Reviewed:** 2026-06-09
 **Depth:** standard
-**Files Reviewed:** 18
-**Status:** issues_found
+**Files Reviewed:** 29
+**Status:** issues_found (no blockers — remaining items are accepted v1 limitations)
 
 ## Summary
 
-This phase is the CalDAV write-back + outbox + PWA-install slice, about to undergo its first live Gate 2 write test. The review found that **the write path is fundamentally broken end-to-end** and will fail at multiple independent points before any event ever reaches Fastmail:
+Final re-review of the event write-back + PWA-install phase after the iteration-2 fix pass. I traced each iteration-2 fix end-to-end against its implementation and tests. All iteration-2 fixes are correct and introduce no regressions. The prior BLOCKER (CR-01: edit-as-move strips the RRULE) is now **resolved and correct**.
 
-1. The PWA sends `title/start/end`, but the server's zod schema requires `summary/dtstart/dtend` — **every create and update is rejected with 400 at the route boundary.** The write path cannot succeed today.
-2. Even if a row reaches the outbox, the worker PUTs the **raw JSON form payload** to Fastmail as if it were an iCalendar string. `buildVeventString` (the entire `vevent.ts` file, the D-13 DATE/DATETIME contract) is **never called** — it is dead code. Fastmail will reject the body or store a corrupt object.
-3. The edit-as-move create row and the `update` row reuse the form-fields JSON as `payload`, so recurrence, all-day handling, and field mapping are all lost regardless.
+### Iteration-2 fixes — verified
 
-Because of (1) and (2), the core acceptance criterion of this phase (write an event to Fastmail) cannot pass. These must be fixed before Gate 2.
+- **Move-path RRULE forwarding (CR-01) — VERIFIED FIXED.** `events.ts` now selects `rawVevent` in the edit lookup (events.ts:338) and, in the move branch, extracts the source RRULE and stashes it as `_preservedRrule` on the create payload **only when the edit carried no explicit recurrence** (events.ts:388-395). The worker create branch reads it back: `hasExplicitRecurrence` is computed via `hasOwnProperty(fields,'recurrence')` (outboxWorker.ts:336), and `rruleString` resolves to `preservedRrule ?? rruleFromPayload` only when there is no explicit recurrence (outboxWorker.ts:341-353). The two sides agree: an EDIT omits `recurrence`, so `hasExplicitRecurrence=false` and the stashed RRULE is applied; an explicit `recurrence` (including `'none'`) still wins. `JSON.stringify` on the move payload drops the absent `recurrence` key, so `hasOwnProperty` is correctly `false` after the round-trip. Covered by events.test.ts:422-469 (route stashes RRULE) and outboxWorker.test.ts:311-358 (worker re-applies; explicit `'none'` still emits no RRULE). No regression to the same-calendar `update` preserve path (outboxWorker.ts:281-285).
 
-Secondary but serious: a production fallback in `dispatchRow` can silently authenticate with empty credentials on a transient DB error; the backoff schedule skips its first delay; and several outbox/ordering edge cases can drop or double-apply writes across drain batches.
+- **Outbox payload re-validation (IN-03) — VERIFIED FIXED.** Both the `update` and `create` branches parse the stored JSON, then `outboxPayloadSchema.safeParse` it (outboxWorker.ts:231-235, 323-327). A schema-invalid row is hard-failed (no retry, no CalDAV dispatch). The schema mirrors `eventFieldsSchema` and uses `.passthrough()` so `_preservedRrule` survives validation (outboxWorker.ts:70-82). Covered by outboxWorker.test.ts:288-306 (missing title → hard-fail, never dispatched).
 
-## Critical Issues
+- **Sync-status failed-row ranking (WR-04) — VERIFIED FIXED.** `sync-status` orders by a status-priority CASE (`failed`/`dead`=0, `pending`=1, else=2) then `createdAt DESC` (events.ts:549-552), so an earlier failed/dead row for a uid outranks a later `done` row. Covered by events.test.ts:556-589, which also asserts the CASE expression is present in the ORDER BY chunks.
 
-### CR-01: API contract mismatch — every create/update rejected with 400
+- **Helper-text / all-day toggle clamp (WR-01/WR-02 UI) — VERIFIED FIXED.** The recurrence `<select>` is disabled in edit mode with explanatory helper text (EventForm.tsx:789-800), and `handleAllDayToggle` clamps `endDate` to `max(startDate,endDate)` on toggle-on and clears stale time errors (EventForm.tsx:296-305).
 
-**File:** `apps/api/src/routes/events.ts:68-77`, `apps/pwa/src/api/client.ts:119-128`, `apps/pwa/src/components/EventForm.tsx:247-256`
-**Issue:** The server `eventFieldsSchema` requires `summary`, `dtstart`, `dtend`. The client `CreateEventPayload` and `EventForm.handleSubmit` send `title`, `start`, `end`. `@hono/zod-validator` rejects the body before the handler runs, so `POST /api/events/create` and `PATCH /api/events/:uid/edit` return 400 for every well-formed client request. The write path is dead on arrival. (`recurrence` is also `required` on the client type but `.optional()` on the server — a lesser instance of the same drift.)
-**Fix:** Make the two ends agree on one field contract. Either rename the client payload to `summary/dtstart/dtend`, or accept `title/start/end` server-side and map internally:
-```ts
-const eventFieldsSchema = z.object({
-  title: z.string().min(1).max(255),
-  allDay: z.boolean(),
-  start: z.string().min(1).max(64),
-  end: z.string().min(1).max(64),
-  location: z.string().max(2000).optional(),
-  description: z.string().max(2000).optional(),
-  recurrence: z.enum(['none','daily','weekly','monthly','yearly']).optional(),
-  calendarUrl: z.string().url().max(1024).optional(),
-})
-```
-Add a contract test that round-trips the exact `CreateEventPayload` shape through the schema.
+- **All-day inclusive/exclusive DTEND symmetry (CR-03) — STILL CORRECT.** `vevent.ts:116-123` rolls the inclusive end forward one UTC day on write; `EventForm.tsx:86-96` rolls it back on pre-fill. Symmetric; covered by vevent.test.ts:140-160.
 
-### CR-02: Outbox worker PUTs raw form JSON to Fastmail — `buildVeventString` is dead code
-
-**File:** `apps/api/src/broker/outboxWorker.ts:168-187`, `apps/api/src/routes/events.ts:250`, `apps/api/src/broker/vevent.ts` (entire file)
-**Issue:** The route stores `payload: JSON.stringify(payload)` — the raw form fields. The worker passes `row.payload` directly as the `iCalString`/`data` to `createCalendarEvent`/`updateCalendarEvent`. `buildVeventString` is never imported or called anywhere in the codebase (`grep` confirms zero call sites outside its own file). The body sent to Fastmail is therefore `{"title":"...","start":"..."}` — not a VCALENDAR. Fastmail will reject it (or, worse, store a corrupt object). The entire D-13 DATE-vs-DATETIME contract, RRULE serialization, escaping, and DTSTAMP logic in `vevent.ts` is bypassed.
-**Fix:** The worker must parse the stored form JSON and build the ICS before PUT:
-```ts
-// in dispatchRow, for create/update:
-const fields = JSON.parse(row.payload) as NewEventParams-equivalent
-const { icsString } = buildVeventString({
-  uid: row.uid,
-  summary: fields.title,
-  allDay: fields.allDay,
-  dtstart: fields.allDay ? fields.start : new Date(fields.start),
-  dtend: fields.allDay ? fields.end : new Date(fields.end),
-  location: fields.location,
-  description: fields.description,
-  rruleString: fields.recurrence && fields.recurrence !== 'none'
-    ? RRULE_PRESETS[fields.recurrence] : undefined,
-})
-response = await createCalendarEvent(client, davCalendar, row.uid, icsString)
-```
-Wrap `JSON.parse` in try/catch and treat a parse failure as a hard fail (no retry). Add an integration test asserting the PUT body begins with `BEGIN:VCALENDAR`.
-
-### CR-03: Production fallback authenticates to Fastmail with empty credentials
-
-**File:** `apps/api/src/broker/outboxWorker.ts:135-143`
-**Issue:** `dispatchRow` wraps `loadClientForUser` in a `try/catch` and, on **any** throw, falls back to `createFastmailClient('', '')`. The comment claims this branch is "never taken" in production, but `loadClientForUser` can throw in production for real reasons: a transient DB error on the `memberCredentials` select, a decryption failure (`decryptPassword` throws on a tampered/rotated key), or a missing credential row. When that happens in production, the worker proceeds to issue a real PUT/DELETE to `caldav.fastmail.com` with empty Basic-auth credentials. At best this is a 401 (correctly classified hard-fail, marking the row `failed` and dropping the write permanently — no retry); at worst it masks a recoverable transient DB error as a permanent failure. Either way a write is silently lost on a condition that should have been retried.
-**Fix:** Remove the production fallback. Let `loadClientForUser` failures propagate to the per-row `catch` in `runOutboxDrain` (line 343), which logs and leaves the row `pending` for the next drain — the correct transient behavior. Gate the empty-credential client strictly behind a test-only flag, never on a generic `catch`:
-```ts
-const client = await loadClientForUser(row.userId) // let it throw → outer catch retries
-```
-
-### CR-04: 412 conflict on a `create` move-pair does not block the paired `delete` reliably across batches
-
-**File:** `apps/api/src/broker/outboxWorker.ts:247-281`, `292-296`
-**Issue:** `failedCreateGroups` is a `Set` local to a single `runOutboxDrain` call. The create-before-delete guarantee only holds when both rows are fetched in the **same** drain batch. The fetch is capped at "up to 10" pending rows (and ordered only by the default DB order, not by `groupId`/`createdAt`). If a move pair straddles a batch boundary — or the create is retried into a later cycle (transient) while the delete is already eligible — the delete can run in a cycle where the create is absent from `sorted`, so `failedCreateGroups` is empty and the delete proceeds. Result: the original event is deleted before the new copy is confirmed created — exactly the "lost event" D-04 is meant to prevent. The in-memory set cannot enforce a cross-batch ordering invariant.
-**Fix:** Make the dependency durable. Options: (a) do not enqueue the `delete` row as `pending`; enqueue it `blocked` and have the worker flip it to `pending` only after the paired create row reaches `done`; or (b) when dispatching a `delete` with a `groupId`, query the DB for the paired create row's status and skip/defer unless it is `done`. Do not rely on both rows co-occurring in one in-memory batch.
-
-### CR-05: No drain concurrency guard — overlapping cycles double-dispatch the same row
-
-**File:** `apps/api/src/broker/outboxWorker.ts:247-259`, `359-365`
-**Issue:** The scheduler fires `runOutboxDrain` every 15s. A drain that issues several network PUTs plus targeted re-syncs (each `triggerTargetedResync` does a full `fetchCalendars` + `syncCalendar`) can easily exceed 15s. The selection query reads `status='pending'` but nothing marks a row "in-flight" before dispatch, and the row is only updated to `done`/`failed` **after** the network call returns. Two overlapping cycles will both select the same still-`pending` row and both issue the write. For a `create` (PUT with `If-None-Match: *`) the second attempt may 412 and get marked `failed`, masking a successful first write; for a `delete` the second DELETE re-runs the If-Match against a now-changed etag and can mis-classify. This is a double-apply / lost-confirmation hazard.
-**Fix:** Add a concurrency guard. Simplest: a module-level `isDraining` boolean that the scheduler checks and skips if a drain is still running. More robust: atomically claim rows by updating `status='pending' → status='processing'` (with a `WHERE status='pending'` guard and `LIMIT`) inside a transaction before dispatch, and only the claiming cycle processes them.
-
-### CR-06: OIDC write path is a hard 401 stub — authenticated users cannot write in production
-
-**File:** `apps/api/src/routes/events.ts:191-201`, `268-274`, `372-378`, `437-443`, `490-496`
-**Issue:** Every write/status/writable-calendars handler resolves the user via `resolveUserId`, which only returns the dev-bypass `c.get('user')`. When that is null (the real OIDC production path), the code calls `getAuth(c)` and then **unconditionally returns 401** even when `auth` is truthy ("For now return 401 if OIDC auth is not backed by a DB user here."). In production (`devBypassActive=false`), `resolveUserId` is always null, so authenticated Authelia users get 401 on every write and on `sync-status`/`writable-calendars`. The phase is described as about to undergo its first live external-auth write test (Gate 2) — this path is a stub that cannot pass. (The OIDC guard mounting in `index.ts` is correct; the issue is the unimplemented iss/sub → user-row lookup.)
-**Fix:** Implement the OIDC→user resolution: from `getAuth(c)` extract `iss`+`sub`, look up the `users` row by the `uniq_oidc_identity` key, and use that `id` as `currentUserId`. Return 401 only when no session exists; return 403/422 (not 401) when a valid session has no provisioned user row.
+The two findings below are **carried-forward, deliberately-accepted v1 limitations** (documented in code), not regressions; they are recorded for completeness. There are no blockers in this phase.
 
 ## Warnings
 
-### WR-01: Backoff schedule skips its first (15s) delay; off-by-one on dead-letter count
+### WR-01: Missing cached etag still produces an unconditional PUT/DELETE (D-08 gap)
 
-**File:** `apps/api/src/broker/outboxWorker.ts:38-44, 316-341`
-**Issue:** `attemptCount` starts at 0. On the first transient failure `nextAttemptCount = 1`, and the delay is read as `BACKOFF_SECONDS[1]` = 60s — so `BACKOFF_SECONDS[0]` (15s) is never used; the documented "15+60+300+600+1800 ≈ 30 min" window is actually 60+300+600+1800. Also `MAX_ATTEMPTS=5` with `nextAttemptCount >= MAX_ATTEMPTS` dead-letters after the 5th attempt's increment reaches 5 — the comment "~30 min" and the indexing should be reconciled.
-**Fix:** Index by `row.attemptCount` (the attempt that just failed) rather than `nextAttemptCount`: `const backoffMs = (BACKOFF_SECONDS[row.attemptCount] ?? 1800) * 1000`. Add a unit test asserting the exact delay sequence.
+**File:** `apps/api/src/broker/write.ts:74-78, 103-107`; `apps/api/src/routes/events.ts:406, 432, 507`
 
-### WR-02: Edit (same-calendar update) reuses old etag but a successful prior update changes it — guaranteed 412 on second edit
+**Issue:** When `eventRow.etag` is null (event cached before an etag was captured, or Fastmail omitted it), the outbox row's `etag` is `undefined`, and `write.ts` maps null/`''` to "no If-Match header" — an **unconditional** PUT/DELETE. That defeats D-08 conflict detection for exactly the rows most likely to be stale: a concurrent external edit is silently overwritten with no 412. The iteration-1 fix added a `console.warn` so the path is observable (write.ts:75-77, 104-106), but the unconditional write itself is unchanged — observability is not prevention. Only triggers when the cached etag is missing, so Warning, not Blocker.
 
-**File:** `apps/api/src/routes/events.ts:348-357`, `apps/api/src/broker/outboxWorker.ts:297-303`
-**Issue:** On a successful update the worker marks the row `done` and triggers a re-sync, which updates `calendarEvents.etag`. That is correct. But the route reads `eventRow.etag` from the cache at enqueue time. If a user edits twice in quick succession (or the poller has not yet refreshed the etag), the second update row carries a stale etag and will 412 even though the user is the only editor. The conflict toast then fires spuriously. This is an interaction between optimistic-accept latency and If-Match.
-**Fix:** Accept that rapid successive edits to the same object should coalesce or chain: either collapse pending update rows for the same uid before enqueueing, or re-read the freshest etag in the worker just before PUT rather than trusting the enqueue-time snapshot.
+**Fix:** When no etag is available, fetch the current etag (REPORT/GET) before writing, or skip the write and force a targeted re-sync so the next attempt carries a real etag. At minimum, document that the no-etag path is an accepted unconditional-write window for v1.
 
-### WR-03: Stale `occurrence` snapshot in EventForm — edits open with empty/old fields
+### WR-02: Edit cannot change or remove an RRULE; "no recurrence field" is overloaded as "keep existing"
 
-**File:** `apps/pwa/src/components/EventForm.tsx:113-181`
-**Issue:** `occurrence` is resolved once via an IIFE during render from the TanStack cache. The initial `useState` values capture it, but the reset `useEffect` depends on `[eventFormOpen, eventFormMode, eventFormUid]` — not on `occurrence`. If the form opens (in edit mode) before the `['events']` query has the occurrence cached, `occurrence` is null at mount and the effect never re-runs when the data later arrives, so the form stays blank. `recurrence` is also hard-reset to `'none'` on every open, so editing a recurring event silently drops its recurrence.
-**Fix:** Include `occurrence` (or `occurrence?.uid`) in the reset effect deps, and derive the initial `recurrence` from the occurrence instead of always `'none'`. Guard against opening edit mode before the cache is populated.
+**File:** `apps/pwa/src/components/EventForm.tsx:361-371, 768-800`; `apps/api/src/broker/outboxWorker.ts:281-285, 336-353`
 
-### WR-04: All-day end-date is exclusive in iCalendar but UI treats it as inclusive
+**Issue:** The recurrence `<select>` is hard-disabled on edit and the payload always omits `recurrence` on edit (EventForm.tsx:367). The server treats an absent `recurrence` as "preserve the stored RRULE" (both the same-calendar update and the move path). The consequence is that a user can never (a) change a recurring event's frequency, nor (b) intentionally make a recurring event non-recurring — there is no way to express "remove the RRULE" through the edit form, because "omit recurrence" is reserved to mean "unchanged." Helper text now surfaces the constraint (EventForm.tsx:789-800), which is the iteration-2 mitigation, so this is a documented v1 scope cut rather than a silent trap. Recorded because the overloaded semantics will need disentangling when recurrence editing ships (a sentinel distinct from "omitted" will be required to express "remove").
 
-**File:** `apps/pwa/src/components/EventForm.tsx:215-238, 250-251`, `apps/api/src/broker/vevent.ts:75-88`
-**Issue:** For all-day events the form sends `end = endDate` and validates `endDate < startDate` as the only error (so a single-day event has `start === end`). iCalendar DTEND for a DATE value is **exclusive** — a one-day all-day event must have DTEND = start + 1 day. As written, a single-day all-day event would produce DTSTART=DTEND, which is invalid/zero-length per RFC 5545. (Currently moot because CR-02 means no VEVENT is built at all, but it must be fixed alongside CR-02.)
-**Fix:** When building the all-day VEVENT, add one day to the end DATE (or normalize in the form). Add a test for the single-day all-day case.
-
-### WR-05: `parseDateTime` uses local-time getters on a UTC-parsed Date — wrong time in edit form
-
-**File:** `apps/pwa/src/components/EventForm.tsx:84-101`
-**Issue:** For timed events `new Date(clean)` parses the offset-aware ISO into an instant, then `d.toISOString().slice(0,10)` takes the **UTC** date while `d.getHours()/getMinutes()` take the **local** time. Mixing UTC date with local clock components can yield a date/time pair that is off by a day at the edges, and the time shown will be the viewer's local wall-clock rather than the event's original zone. For a family spanning Toronto/Edmonton zones this misrepresents the edited event.
-**Fix:** Derive both date and time consistently in one zone (use the same Temporal-based conversion the calendar render path uses, or compute local date with `getFullYear/getMonth/getDate`).
-
-### WR-06: `triggerTargetedResync` calls `fetchCalendars` on every successful row — N+1 round-trips and re-load of credentials
-
-**File:** `apps/api/src/broker/outboxWorker.ts:89-117, 297-303`
-**Issue:** Each successful/conflicted row triggers a full `loadClientForUser` (DB select + decrypt) plus `fetchCalendars()` (network) plus `syncCalendar` (REPORT of the whole collection). A drain of 10 rows for one user does this 10 times against the same calendar. Beyond load, this re-decrypts the app password 10x and multiplies the window during which overlapping drains (CR-05) can interfere. Out of strict v1 perf scope, but it is also a correctness amplifier for the concurrency and etag-staleness issues above.
-**Fix:** Batch re-syncs: collect the distinct `(userId, calendarUrl)` pairs touched during a drain and re-sync each once at the end of the cycle.
-
-### WR-07: `EventForm` and dialogs implement no real focus trap despite claiming one
-
-**File:** `apps/pwa/src/components/EventForm.tsx:274-278`, `DeleteConfirmationDialog.tsx:42-46`, `EventDetailPopover.tsx:157-161`
-**Issue:** The docblocks state "Focus trap while open," but the implementation only calls `.focus()` once on open. Tab can move focus out of the modal to background content (the calendar grid, FAB). For a modal `aria-modal="true"` dialog this is an accessibility defect and, combined with the always-mounted backdrop, lets keyboard users interact with obscured controls.
-**Fix:** Implement an actual focus trap (cycle Tab/Shift+Tab within the dialog) or use a vetted primitive. At minimum, document honestly that it is focus-on-open only.
-
-### WR-08: `crypto.randomUUID()` used without importing `crypto` in the route module
-
-**File:** `apps/api/src/routes/events.ts:241, 317, 318`
-**Issue:** The route relies on a global `crypto.randomUUID()`. This is available on Node 20+/22 globals, so it likely works at runtime, but there is no `import { randomUUID } from 'crypto'` and no explicit reference to `globalThis.crypto` — it depends entirely on the ambient global being present and typed. `vevent.ts` imports `randomUUID` from `'crypto'` explicitly; the inconsistency is a latent footgun if the runtime or tsconfig `lib` changes.
-**Fix:** Import explicitly (`import { randomUUID } from 'node:crypto'`) and use `randomUUID()` for consistency with `vevent.ts`.
+**Fix:** When recurrence editing lands, introduce an explicit "remove recurrence" signal distinct from an omitted field (e.g. `recurrence: 'none'` already overrides — wire the edit form to send it when the user clears the schedule), and parse-and-modify the stored RECUR in place rather than replacing it with a bare preset (see IN-01).
 
 ## Info
 
-### IN-01: `vevent.ts` is entirely unreachable dead code
+### IN-01: `RRULE_PRESETS` round-trip is lossy for any parameterized RRULE
 
-**File:** `apps/api/src/broker/vevent.ts:1-119`
-**Issue:** As established in CR-02, nothing imports `buildVeventString` or `RRULE_PRESETS`. Once CR-02 is fixed this becomes live; until then the whole file (and its D-13 logic) is untested dead weight that gives false confidence the contract is honored.
-**Fix:** Wire it in per CR-02; add a unit test so it cannot silently fall out of the call graph again.
+**File:** `apps/api/src/broker/vevent.ts:49-54`; `apps/api/src/broker/outboxWorker.ts:245-248, 337-340`
 
-### IN-02: `resolveDefaultView` ignores its own SSR guard return value
+**Issue:** `RRULE_PRESETS` maps only to bare `FREQ=DAILY|WEEKLY|MONTHLY|YEARLY`. `extractRruleString` correctly preserves the full stored RECUR (which may carry `BYDAY`/`INTERVAL`/`COUNT`/`UNTIL`), and both preserve paths keep that rich rule. But if a `recurrence` preset value is ever applied to a previously-rich rule, it collapses the rule to the bare preset — silently dropping qualifiers. This cannot happen in v1 (the picker offers only the four bare presets and is disabled on edit), so it is latent, not active. The limitation is now documented at the `RRULE_PRESETS` definition (vevent.ts:39-48).
 
-**File:** `apps/pwa/src/components/CalendarShell.tsx:63-66`
-**Issue:** `resolveDefaultView` returns `'month-grid'` when `window === undefined` else `persistedView` — it never uses a phone/desktop branch, so the JSDoc ("phone defaults to month-agenda") is misleading; the actual default already comes from the Zustand store. The helper is effectively an identity function on the client.
-**Fix:** Remove the redundant helper or align the comment with what it does.
+**Fix:** When recurrence editing ships, parse the existing RECUR and modify it in place instead of replacing it with a preset.
 
-### IN-03: `getDefaultStartDate`/`getDefaultEndDate` are identical
+### IN-02: Move-path RRULE preservation depends silently on `rawVevent` being non-empty
 
-**File:** `apps/pwa/src/components/EventForm.tsx:47-53`
-**Issue:** Both return today's date; the naming implies different defaults (the time defaults differ, but those are hardcoded separately at the call sites as `'09:00'`/`'10:00'`). Two functions with identical bodies invite drift.
-**Fix:** Collapse to a single `todayIso()` helper (one already exists in `calendarStore.ts`).
+**File:** `apps/api/src/routes/events.ts:388-391`
 
-### IN-04: `manifest.json`/icons referenced but `apple-touch-icon.png` and PWA icons not verified in scope
+**Issue:** In the move branch, `preservedRrule = payload.recurrence === undefined ? extractRruleString(eventRow.rawVevent ?? '') : undefined`. If `eventRow.rawVevent` is ever null/empty (it is selected at events.ts:338 and `calendar_events.rawVevent` is `notNull` per schema.ts:106, so this is not currently reachable), `extractRruleString('')` returns `undefined` and the move silently drops the RRULE with no diagnostic. The schema NOT NULL constraint makes this safe today; the fragility is that the preserve path has no observability if that invariant ever changes (unlike write.ts:75-77 which logs the analogous no-etag gap).
 
-**File:** `apps/pwa/index.html:7`, `apps/pwa/vite.config.ts:33-37`
-**Issue:** The manifest references `/icon-192.png`, `/icon-512.png`, and `index.html` references `/apple-touch-icon.png`. These assets are outside the reviewed file set; if missing, the iOS Add-to-Home-Screen flow (the other half of this phase) will install with a broken icon. Flagging for Gate 2 verification, not a code defect in the reviewed files.
-**Fix:** Confirm the icon assets exist in `public/` before the install test.
-
-### IN-05: Outbox `done`/`failed`/`dead` rows are never pruned
-
-**File:** `apps/api/src/db/schema.ts:125-154`, `apps/api/src/broker/outboxWorker.ts`
-**Issue:** Terminal rows accumulate indefinitely. `sync-status` reads the latest row per uid (ordered by `createdAt desc`), so correctness is preserved, but the table grows unbounded and the `idx_outbox_next_attempt` scan includes ever-more terminal rows over time (the `WHERE status='pending'` filters them, but only after index narrowing). Low urgency for a two-user household.
-**Fix:** Add a periodic prune of `done` rows older than N days; keep `failed`/`dead` for audit or prune separately.
+**Fix:** Optional — log a warning when a move with no explicit recurrence finds no extractable RRULE on a recurring-looking source, so a future schema/contract change that empties `rawVevent` is diagnosable rather than silent.
 
 ---
 
-_Reviewed: 2026-06-05_
+_Reviewed: 2026-06-09_
 _Reviewer: Claude (gsd-code-reviewer)_
 _Depth: standard_

.planning/phases/03-event-write-back-pwa-install/03-SECURITY.md

@@ -0,0 +1,99 @@
+---
+phase: 03
+slug: event-write-back-pwa-install
+status: verified
+threats_open: 0
+asvs_level: 1
+created: 2026-06-09
+---
+
+# Phase 03 — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+> Verified against the CURRENT implementation, i.e. after the code-review fix cycle
+> (CR-01/CR-02 member-scoped lookups, CR-01 move-path RRULE forwarding, IN-03 worker
+> payload re-validation, WR-04 worker-startup gate) — not the as-executed SUMMARY claims.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| Browser ↔ API | PWA calls Hono API over HTTPS (Pangolin/Newt tunnel) | Event field JSON, session cookie; no etag/credentials from client |
+| OIDC (Authelia) ↔ API | Authorization-code + PKCE; storage-less JWT session cookie | iss/sub identity claims |
+| Dev-bypass ↔ API | `DEV_AUTH_BYPASS=true` AND `NODE_ENV!=production` injects a fixed dev user | Local dev only; hard-OFF in production |
+| API ↔ MariaDB | Drizzle/mysql2 parameterized queries | Event cache, outbox rows, encrypted app passwords |
+| Outbox worker ↔ Fastmail CalDAV | Background worker PUT/DELETE with server-sourced etag (If-Match) | VEVENT payloads; decrypted app password (never logged) |
+| Service Worker ↔ network | Workbox SW; `/callback`, `/api`, `/health` on navigateFallbackDenylist; `runtimeCaching: []` | No authenticated API responses cached; OIDC callback never SW-served |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-03-01 | Tampering | drizzle-kit push | mitigate | Human checkpoint + hand-applied additive DDL; runtime CMD is `node dist/index.js` (Dockerfile:46); `db:push` manual-only npm script | closed |
+| T-03-02 | Info Disclosure | calendar_outbox payload/etag | accept | Outbox rows are server-side only; never returned to the frontend | closed |
+| T-03-03 | Tampering | VEVENT field serialization | mitigate | ical.js `ICAL.Component/Property/Recur` for all serialization; no hand-rolled ICS (vevent.ts:89-148) | closed |
+| T-03-04 | Spoofing | etag forgery to bypass conflict | mitigate | etag sourced server-side from `calendarEvents.etag`; never read from request body (write.ts:62-86, outboxWorker.ts:264-279) | closed |
+| T-03-05 | EoP | write.ts called w/ another member's calendar | accept | Low-level primitive; ownership enforced at the route layer (T-03-06) | closed |
+| T-03-06 | EoP | write to another member's personal calendar | mitigate | Route lookup scoped `and(eq(uid), or(eq(userId,current), eq(isShared,true)))` + 403 on miss; CR-01 deterministic `orderBy(...desc).limit(1)` closes shared-account IDOR (events.ts:251-260,342-368,474-497) | closed |
+| T-03-07 | Info Disclosure | sync-status leaks another member's row | mitigate | `WHERE and(eq(userId,current), eq(uid))` (events.ts:547) | closed |
+| T-03-08 | Tampering | XSS/oversized payload via title/location/description | mitigate | zod bounds (title 255, loc/desc 2000); IN-03 worker re-validates outbox payload + hard-fails invalid rows before VEVENT build (events.ts:100-109, outboxWorker.ts:70-82,231-234,323-326) | closed |
+| T-03-09 | Tampering | SQLi via uid/calendarUrl | mitigate | Drizzle parameterized queries incl. bound `sql\`\`` params; no string interpolation (events.ts:181-198) | closed |
+| T-03-10 | Spoofing | client-supplied etag bypass | mitigate | etag read server-side at enqueue; client never supplies it (events.ts:407,432,507) | closed |
+| T-03-11a | EoP | writable-calendars surfaces another member's personal calendar | mitigate | `WHERE or(eq(userId,current), eq(isShared,true))` (events.ts:600) | closed |
+| T-03-11b | Repudiation | silent last-write-wins on concurrent edit | mitigate | 412→`conflict:true`→mark failed, no overwrite + targeted resync; CR-02 fresh-etag re-read joins calendars on (userId,url)+limit(1) (outboxWorker.ts:265-279,362-370,543-548) | closed |
+| T-03-12 | DoS | poison row retrying forever | mitigate | `MAX_ATTEMPTS=5` + bounded backoff + dead-letter (outboxWorker.ts:40,46,578-587) | closed |
+| T-03-13 | Info Disclosure | logging decrypted app password | mitigate | Decrypt local-only; per-item catches log `err.message` only (outboxWorker.ts:127,174-177,608-611; poller.ts:70-74) | closed |
+| T-03-14 | Tampering | partial-failure data loss on edit-as-move | mitigate | create-before-delete + durable sibling-status gate + create-fail skips delete; CR-01 `_preservedRrule` re-applied via validated passthrough (outboxWorker.ts:336-353,462-524) | closed |
+| T-03-15 | Tampering | XSS via form title/location/description | mitigate | All fields plain-text JSX children; no `dangerouslySetInnerHTML` in `apps/pwa/src` (EventForm.tsx:557,591,729,752,798) | closed |
+| T-03-16 | EoP | client offers non-writable calendar in picker | mitigate | Picker only from authoritative `fetchWritableCalendars`; server re-enforces (client.ts:273-284, EventForm.tsx:182-187) | closed |
+| T-03-17 | Tampering | accidental/irreversible delete | mitigate | Mandatory two-tap dialog; no single-tap; no "don't ask again" (DeleteConfirmationDialog.tsx:78-81) | closed |
+| T-03-18 | Repudiation | silent data loss on failed delete sync | mitigate | failed/dead toast persists until dismiss; invalidates `['events']` so server refetch restores (SyncStateToast.tsx:59,201-222) | closed |
+| T-03-19 | Info Disclosure | another member's sync-status in toast | mitigate | Toast queries own `lastSyncedUid`; server scopes by member (SyncStateToast.tsx:41, events.ts:547) | closed |
+| T-03-20 | Spoofing | SW caches shell for /callback, breaks OIDC | mitigate | `navigateFallbackDenylist: [/^\/callback/, /^\/api\//, /^\/health/]` (vite.config.ts:16-20) | closed |
+| T-03-21 | Tampering | SW caches authenticated API responses | mitigate | `runtimeCaching: []` (vite.config.ts:22) | closed |
+| T-03-22 | Info Disclosure | manifest/icons leak secrets | accept | Static public assets only; no secrets in manifest | closed |
+| T-03-23 | Spoofing | dev-auth bypass active in live deploy | mitigate | First guard `NODE_ENV==='production'`→no-op; prod mounts OIDC unconditionally; WR-04 moved worker startup into `isMainModule()` gate without altering middleware mount order (devBypass.ts:61, index.ts:38,46-48,104-114) | closed |
+| T-03-24 | Info Disclosure | OIDC redirect_uri mismatch leaks codes | mitigate | `OIDC_AUTH_EXTERNAL_URL` MANDATORY = public URL (middleware.ts:12, index.ts:44-45); deployment-config responsibility, no code gap | closed |
+| T-03-25 | Tampering | SW intercepts /callback in live build | mitigate | Same denylist verified vs production build (vite.config.ts:16-20); Gate 2 row 4 confirmed standalone login | closed |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+| AR-03-01 | T-03-02 | Outbox payload/etag are server-side-only rows, never exposed to the frontend; payload is the member's own VEVENT | Lucas Berger | 2026-06-09 |
+| AR-03-02 | T-03-05 | `write.ts` is a low-level CalDAV primitive with no auth context; ownership is enforced one layer up at the route (T-03-06) | Lucas Berger | 2026-06-09 |
+| AR-03-03 | T-03-22 | PWA manifest and icons are static public assets; contain no secrets | Lucas Berger | 2026-06-09 |
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| 2026-06-09 | 25 | 25 | 0 | gsd-security-auditor (opus) |
+
+Notes: Verified against the post code-review-fix implementation. The five fix areas
+(CR-01 member-scoped lookups, CR-01 move-path RRULE forwarding, CR-02 fresh-etag re-read,
+IN-03 worker payload re-validation, WR-04 worker-startup gate) were each re-verified as
+present and non-regressing. T-03-24 is a deployment-config control (no code gap). No
+unregistered threat flags surfaced across the Phase 03 summaries.
+
+---
+
+## Sign-Off
+
+- [x] All threats have a disposition (mitigate / accept / transfer)
+- [x] Accepted risks documented in Accepted Risks Log
+- [x] `threats_open: 0` confirmed
+- [x] `status: verified` set in frontmatter
+
+**Approval:** verified 2026-06-09

.planning/phases/03-event-write-back-pwa-install/03-UAT.md

@@ -0,0 +1,104 @@
+---
+status: complete
+phase: 03-event-write-back-pwa-install
+mode: mvp
+source:
+  - 03-05-SUMMARY.md (Event Write UI)
+  - 03-06-SUMMARY.md (Edit/Delete + SyncStateToast)
+  - 03-07-SUMMARY.md (PWA Install)
+  - 03-08-SUMMARY.md (Gate 2 Live Verification)
+  - 03-12-SUMMARY.md (EventForm gap closure)
+  - 03-REVIEW.md / 03-REVIEW-FIX.md (code-review fix cycle, this session)
+scope: regression-focused (post code-review-fix)
+method: playwright-cli desktop drive (local dev-bypass stack, no real Fastmail writes) + green test suites + Gate 2 record
+started: 2026-06-09T15:20:00Z
+updated: 2026-06-09T15:30:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Context
+
+Gate 2 (Plan 03-08) already operator-verified the full event write-back + iOS-install user
+story **live** against real Authelia/Fastmail on desktop and the wife's iPhone (A1–A3, B1–B4,
+D1–D6). This UAT pass is **regression-focused**: it re-confirms the behaviours touched by the
+code-review fix cycle run this session (CR-01/CR-02 member-scoped lookups, CR-03 all-day
+inclusive/exclusive, WR-01/move-path RRULE preservation, WR-04 sync-status ranking, IN-03
+payload re-validation), which landed *after* Gate 2.
+
+Browser drive used a local dev-bypass stack (MariaDB + API + PWA) as the credential-less dev
+user, so no event ever reached a real Fastmail calendar. Seeded test data (one dev user, one
+`uat.local` calendar, one recurring event) was removed after the run; DB restored to original
+state (real users 2/3 and their 538 events untouched).
+
+## Tests
+
+### 1. Cold-start smoke — app boots and renders after the fixes
+expected: PWA loads, calendar shell renders (nav, Calendars legend, New Event control), no real console errors.
+result: pass
+evidence: Loaded http://localhost:5173 in real Chromium. Title "FamilySync"; nav + "New Event" + Schedule-X month grid (June 2026) rendered; legend showed **distinct** member colours (Dev User #4A90D9, Family #F25C7A). Only console error was a benign favicon.ico 404.
+
+### 2. Create-event UI flow → enqueue → sync feedback
+expected: New Event → fill form → Save → event enqueues (202) and SyncStateToast shows pending state.
+result: pass
+evidence: Opened EventForm (all UI-SPEC fields, focus on Title). Filled title, clicked "Create Event"; dialog closed, `calendar_outbox` row id=20 created (operation=create, pending), and SyncStateToast rendered `role="status"` "Syncing…". (Dispatch intentionally cannot complete — dev user has no Fastmail credential — so nothing hit a real calendar; the done/Saved transition is covered by outboxWorker tests + Gate 2 D1.)
+
+### 3. All-day toggle hides time inputs
+expected: Toggling All day on removes the start/end time fields; off restores them.
+result: pass
+evidence: Toggled the all-day switch → `[checked]`; the 09:00 / 10:00 time textboxes disappeared, Start/End showed date-only.
+
+### 4. Edit mode pre-fill + recurrence preserved (WR-01 / WR-02 fix)
+expected: Editing an event pre-populates fields; recurrence picker is disabled in edit mode with copy explaining the schedule is kept.
+result: pass
+evidence: Clicked a recurring occurrence → EventDetailPopover (live Edit/Delete footer) → Edit. "Edit Event" dialog pre-populated (title, dates 2026-06-10, times 10:00/11:00). Recurrence combobox rendered **`[disabled]`** with helper text **"Repeat can't be changed yet — edits keep the existing schedule."** — the exact preserve-on-edit guidance the WR-01/WR-02 fix added. Footer button correctly labelled "Save Changes".
+
+### 5. Member-scoped read (CR-01 GET path)
+expected: A member sees only events from calendars in their writable set.
+result: pass
+evidence: As dev user 1 (owns only the seeded UAT calendar), GET /api/events returned only that calendar's occurrences and `writable-calendars` returned only it — never the 538 events on user 2's calendars. Confirms the member-scoped query.
+
+### 6. CR-01/CR-02 member-scoped edit/delete + freshest-etag (byte/SQL level)
+expected: Edit/delete resolve the acting member's row (not an arbitrary shared-account duplicate); worker re-reads the writing member's etag.
+result: pass
+evidence: Certified by green API integration tests re-run this session (events.test.ts member-scoping + 503-join regression; outboxWorker freshest-etag WR-02 cases) — api 108 passed. Live-verified at Gate 2 D4/D5. Not UI-observable without a two-member shared-account dataset.
+
+### 7. CR-03 all-day inclusive/exclusive round-trip (byte level)
+expected: All-day events write exclusive DTEND, pre-fill inclusive on edit; span does not grow on re-edit.
+result: pass
+evidence: Certified by vevent.test.ts (inclusive→exclusive write) + EventForm.test.tsx (exclusive→inclusive pre-fill) — green. The all-day off-by-one was also fixed and confirmed live at Gate 2.
+
+### 8. WR-01 + move-path RRULE preservation (byte level)
+expected: Editing a recurring event keeps its RRULE, including edit-as-move to another calendar (worker create branch re-applies the source rule).
+result: pass
+evidence: Certified by the iteration-2 regression tests (events.test.ts _preservedRrule forwarding + outboxWorker create-branch RRULE re-apply) — green. UI half (disabled picker + helper) browser-verified in Test 4. Recurring round-trip live-verified at Gate 2 D3.
+
+### 9. WR-04 sync-status ranking + IN-03 payload re-validation
+expected: sync-status ranks a failed/dead row above an older done row; worker hard-fails malformed outbox payloads before any CalDAV call.
+result: pass
+evidence: Certified by green API integration tests (sync-status priority CASE; outbox payload safeParse hard-fail) re-run this session.
+
+### 10. Coverage check (goal-backward against the phase user story)
+expected: Members can create/edit/delete events written to the correct Fastmail calendar; app installable to iPhone & Android home screens with guided onboarding.
+result: pass (with documented deferrals)
+evidence: Create/edit/delete → correct Fastmail calendar: Gate 2 D1–D6 (live). iPhone install + standalone OIDC login + onboarding walkthrough: Gate 2 B1–B4 (live, load-bearing). Code paths present: EventForm/Edit/Delete + outbox worker, VitePWA manifest/SW + InstallPrompt walkthrough. **Deferred (not failures):** B5 Android install walkthrough (device check), C SSE smoke (Phase 4 entry gate per D-14).
+
+## Summary
+
+total: 10
+passed: 10
+issues: 0
+pending: 0
+skipped: 0
+
+## Gaps
+
+[none — 0 UAT issues]
+
+## Accepted limitations (carried forward, not UAT failures)
+
+- **WR-01 (code-review Warning):** a missing cached etag still produces an unconditional PUT/DELETE; has a `console.warn`, but true conflict prevention needs a deeper D-08 change. v1-accepted.
+- **WR-02 (code-review Warning):** edit cannot *change/remove* an RRULE — "omitted recurrence" means "keep existing"; surfaced to the user via the helper text verified in Test 4. Deferred to the recurrence-editing milestone.
+- **Gate 2 deferrals:** B5 Android install walkthrough (device-only human check); C SSE 5-min smoke (Phase 4 entry gate); backlog 999.3–999.9 (session-timeout redirect, VALARM reminders, first-login app-password setup, all-day visual distinction, recurrence bound, edit-recurring-series).

.planning/phases/04-shared-lists-live-sync/.continue-here.md

@@ -0,0 +1,89 @@
+---
+context: phase
+phase: 04-shared-lists-live-sync
+task: null
+total_tasks: null
+status: ready_to_plan
+last_updated: 2026-06-08T01:52:24.365Z
+---
+
+<current_state>
+Phase 4 (Shared Lists + Live Sync) — **discussion complete, entry gate cleared, ready to plan.**
+Nothing is mid-edit. The working tree is clean and this is a deliberate stopping point between
+discuss-phase and plan-phase.
+
+- `04-CONTEXT.md` is written and committed (18 decisions, D-01..D-18).
+- The Phase 4 **entry gate** (SSE-over-Pangolin smoke test, D-14 / issue #1034) is **CLEARED** —
+  verified live this session and recorded in the gate docs. No infra precondition remains.
+- No PLAN.md exists yet for Phase 4.
+</current_state>
+
+<completed_work>
+
+This session:
+- Ran `/gsd-discuss-phase 4` → `04-CONTEXT.md` + `04-DISCUSSION-LOG.md` (commit 05e1c9e).
+- Executed the SSE-over-Pangolin smoke test live over `familysync-dev.bergerhouse.net`:
+  ~6 min hold, 35 heartbeats (id 0→34) at ~10s, incremental delivery (buffering off), no cut → PASS.
+- Recorded the PASS via quick task 260607-u8o: updated `01-HUMAN-UAT.md` item 4 and
+  `03-GATE2-RESULTS.md` Part C to PASS; struck the entry-gate blocker in STATE.md (commit 9ee5906).
+- Saved project memory: design for N family members (not hard-coded two).
+</completed_work>
+
+<remaining_work>
+
+- **Next:** `/gsd-plan-phase 4` (consumes `04-CONTEXT.md`).
+- Optional before/after planning: `/gsd-ui-phase 4` — lists UI design contract (ROADMAP UI hint: yes).
+- Then execute Phase 4 plans.
+</remaining_work>
+
+<decisions_made>
+
+All locked in `04-CONTEXT.md` (read it before planning). Highlights for the planner:
+- **Sharing:** default-shared lists with a per-list private toggle; `list_shares` join table
+  (member-count-agnostic, N-member-ready); SSE fan-out **scoped to who can see a list** (private
+  lists must NOT broadcast to everyone).
+- **Items:** checked items sink to a completed section; confirm-on-delete for lists only
+  (reuse `DeleteConfirmationDialog`).
+- **Live feel/conflicts:** optimistic UI; per-field PATCH + per-field last-write-wins (bounded —
+  NO CRDT); delete-wins.
+- **Reconnect:** full refetch on reconnect; capped-backoff then a "updates paused" indicator;
+  React Query `refetchInterval` polling fallback.
+- **Ordering:** string-based fractional index (NOT raw floats, NOT integer-renumber); animate
+  remote reorders; last-write-wins settle.
+- **Nav:** bottom tab bar + react-router (real URLs, for Phase 5 push deep-links). No router today.
+- **Project principle:** design for N family members, not hard-coded two.
+- **Deferred (out of scope):** anonymous public-URL list sharing; per-recipient picker UI.
+</decisions_made>
+
+<blockers>
+- None. The entry gate that previously blocked the build is cleared.
+</blockers>
+
+## Required Reading (in order)
+1. `.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md` — locked implementation decisions; the contract for planning.
+2. `apps/api/src/db/schema.ts` — Drizzle table conventions for the new `lists` / `list_items` / `list_shares` tables.
+3. `apps/api/src/routes/sse.ts` — existing Hono `streamSSE` heartbeat pattern; the live-list stream extends it.
+4. `.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md` Part C — recorded SSE smoke PASS evidence.
+
+## Open Decisions for the Planner (intentionally NOT pre-decided)
+- **Fan-out mechanism:** in-memory EventEmitter vs Redis pub/sub. API runs as a single Node process
+  today (no replicas); `ioredis` is NOT installed; `redis` IS in docker-compose. In-memory is the
+  YAGNI default — planner must justify the choice against the N-member future (D-18).
+- Position-rank column type, SSE auth/middleware wiring, React Query cache-key structure.
+
+## Infrastructure State
+- Pangolin route already configured (buffering off, idle/read timeout ≥120s) and verified for SSE.
+- `redis` service present in docker-compose; `ioredis` not yet a dependency.
+- New DB tables MUST use `drizzle-kit generate` + `migrate` — **never `push`** (unsafe on populated MariaDB).
+- No background processes were left running.
+
+<context>
+Clean handoff. The hard part (verifying SSE survives the tunnel) is done and recorded, so Phase 4
+can be planned and built without an infra gate hanging over it. The planner should treat
+04-CONTEXT.md as authoritative and focus its remaining judgment on the fan-out mechanism and the
+new schema (lists, list_items, list_shares) using generate+migrate.
+</context>
+
+<next_action>
+Start with: `/clear` then `/gsd-plan-phase 4`.
+</next_action>

.planning/phases/04-shared-lists-live-sync/04-01-PLAN.md

@@ -0,0 +1,260 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - apps/pwa/package.json
+  - apps/api/package.json
+  - apps/api/src/db/schema.ts
+  - apps/api/src/db/migrations/0002_lists_schema.sql
+  - apps/api/test/setup.ts
+  - apps/api/vitest.config.ts
+  - apps/api/src/routes/lists.test.ts
+  - apps/api/src/lib/listEmitter.test.ts
+  - apps/pwa/src/hooks/useListSSE.test.ts
+  - apps/pwa/src/routes/ListDetail.test.tsx
+  - apps/pwa/src/App.tsx
+  - apps/pwa/src/components/BottomTabBar.tsx
+  - apps/pwa/src/routes/ListsIndex.tsx
+  - apps/pwa/src/store/listsStore.ts
+autonomous: false
+requirements: [LIST-01, LIST-02, LIST-03, LIST-04]
+user_setup: []
+
+must_haves:
+  truths:
+    - "User can tap a 'Lists' tab in a bottom tab bar (D-16) and land on a /lists route served by react-router (D-17)"
+    - "The /lists route renders an empty state when no lists exist"
+    - "The new lists/list_items/list_shares tables exist in MariaDB after migration"
+    - "API test harness runs and the Phase 4 RED test stubs execute (failing, not erroring on import)"
+  artifacts:
+    - path: "apps/api/src/db/schema.ts"
+      provides: "lists, listShares, listItems Drizzle tables"
+      contains: "export const lists"
+    - path: "apps/api/src/db/migrations/0002_lists_schema.sql"
+      provides: "additive CREATE TABLE migration for the three list tables"
+      contains: "CREATE TABLE"
+    - path: "apps/pwa/src/components/BottomTabBar.tsx"
+      provides: "Calendar | Lists bottom tab navigation"
+      min_lines: 25
+    - path: "apps/pwa/src/routes/ListsIndex.tsx"
+      provides: "Lists surface with empty state"
+      min_lines: 20
+    - path: "apps/api/src/routes/lists.test.ts"
+      provides: "RED test stubs for LIST-01/02/03/04 API behavior"
+      contains: "describe"
+  key_links:
+    - from: "apps/pwa/src/App.tsx"
+      to: "/lists"
+      via: "react-router Route + BottomTabBar NavLink"
+      pattern: "lists"
+    - from: "apps/api/src/db/schema.ts"
+      to: "MariaDB"
+      via: "drizzle-kit generate + migrate"
+      pattern: "mysqlTable\\('lists'"
+---
+
+<objective>
+Establish the Phase 4 foundation as a thin, runnable end-to-end shell: install the four new npm dependencies, add the three list tables to the Drizzle schema and apply them via a generated migration, scaffold the API test harness with the Phase 4 Wave-0 RED test stubs, and add react-router + a bottom tab bar so the user can navigate to a (currently empty) Lists surface.
+
+This is the MVP first slice: after this plan a real user can tap "Lists" and see the Lists surface render (empty state). No list data yet — later slices fill it in. Wave 0 test stubs are created here so every downstream task has an `<automated>` target per 04-VALIDATION.md.
+
+Purpose: De-risk the transport/routing/schema/test plumbing before any list feature is built, and satisfy the [BLOCKING] generate+migrate schema constraint once for all later DB-dependent work.
+Output: New deps installed; three tables migrated; API vitest harness + 4 RED stub test files; router + BottomTabBar + ListsIndex empty state; listsStore (UI-only).
+
+## Phase Goal
+
+**As a** household member, **I want to** create and manage shared named lists with real-time co-edit sync, **so that** my partner and I see each other's list edits appear within seconds without refreshing. (This plan delivers the navigable shell; later plans fill in CRUD, reorder, and live sync.)
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking-human">
+  <name>Task 1: Package legitimacy gate for the SUS-flagged react-router</name>
+  <files>apps/pwa/package.json</files>
+  <read_first>
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Package Legitimacy Audit"
+  </read_first>
+  <what-built>Nothing yet — this gate precedes the install in Task 2.</what-built>
+  <action>
+    Per the Package Legitimacy Audit, three packages (@dnd-kit/core, @dnd-kit/sortable, fractional-indexing) are verdict OK and auto-approved. `react-router` is flagged SUS only because version 7.17.0 was published 2026-06-04 (version-recency false positive); the package is the canonical React Router (remix-run, ~12 yrs, 47.5M/wk). Surface this to the operator for a one-time confirm before installing, since legitimacy checkpoints are never auto-approvable.
+  </action>
+  <how-to-verify>
+    1. Open https://www.npmjs.com/package/react-router and confirm publisher is `remix-run`/`react-router` org with multi-year history and ~47M weekly downloads.
+    2. Confirm version 7.x is the current major.
+  </how-to-verify>
+  <acceptance_criteria>
+    - Operator types "approved" (or names a pinned version) before Task 2 runs.
+  </acceptance_criteria>
+  <resume-signal>Type "approved" to proceed with the install, or specify an alternate version.</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Task 2: Install new dependencies + scaffold API test harness with Wave-0 RED stubs</name>
+  <files>apps/pwa/package.json, apps/api/package.json, apps/api/test/setup.ts, apps/api/vitest.config.ts, apps/api/src/routes/lists.test.ts, apps/api/src/lib/listEmitter.test.ts, apps/pwa/src/hooks/useListSSE.test.ts, apps/pwa/src/routes/ListDetail.test.tsx</files>
+  <read_first>
+    - apps/api/vitest.config.ts
+    - apps/api/src/db/client.ts
+    - apps/pwa/src/api/client.test.ts (existing PWA test convention)
+    - .planning/phases/04-shared-lists-live-sync/04-VALIDATION.md §"Wave 0 Requirements" and §"Per-Task Verification Map"
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Standard Stack" → "New Dependencies"
+  </read_first>
+  <action>
+    Install PWA deps: react-router@7, @dnd-kit/core, @dnd-kit/sortable, fractional-indexing via `pnpm --filter @familysync/pwa add`. Install API dep fractional-indexing via `pnpm --filter @familysync/api add` (needed server-side for rank generation). Do NOT install ioredis — fan-out is in-memory EventEmitter per RESEARCH discretion (justified in Plan 02).
+
+    Scaffold the API test harness: the API currently has zero test files. Create `apps/api/test/setup.ts` and reference it from `apps/api/vitest.config.ts` (`test.setupFiles`). The setup file must establish how DB-backed route tests connect — point at the local MariaDB via the existing `apps/api/src/db/client.ts` pool (DB_HOST/DB_NAME from env), and provide a per-test cleanup (truncate lists/list_items/list_shares between tests). Pure-logic tests (listEmitter, fractional rank) do NOT need the DB.
+
+    Create the four Wave-0 RED stub test files listed in 04-VALIDATION.md, each with `describe`/`it.todo` or `it(... )` blocks that compile and FAIL (red) rather than error on import — they import the not-yet-existing modules behind a guard or use `it.todo` placeholders that downstream plans convert to real assertions:
+    - apps/api/src/routes/lists.test.ts — LIST-01/02/03/04 API behavior stubs
+    - apps/api/src/lib/listEmitter.test.ts — scoped fan-out correctness (D-04) stubs
+    - apps/pwa/src/hooks/useListSSE.test.ts — D-11 bounded backoff (mock EventSource) stubs
+    - apps/pwa/src/routes/ListDetail.test.tsx — D-07 optimistic update + rollback stubs
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/api test 2>&1 | grep -Eiq 'todo|fail|no tests|passed' && pnpm --filter @familysync/pwa exec vitest run src/hooks/useListSSE.test.ts src/routes/ListDetail.test.tsx 2>&1 | grep -Eiq 'todo|fail|passed'</automated>
+  </verify>
+  <acceptance_criteria>
+    - `react-router`, `@dnd-kit/core`, `@dnd-kit/sortable`, `fractional-indexing` appear in apps/pwa/package.json dependencies.
+    - `fractional-indexing` appears in apps/api/package.json dependencies.
+    - `ioredis` is NOT added to either package.json.
+    - `apps/api/test/setup.ts` exists and is referenced by `setupFiles` in apps/api/vitest.config.ts.
+    - All four Wave-0 test files exist and run (todo/red), not import-error.
+  </acceptance_criteria>
+  <done>New deps installed (no ioredis), API test harness runs, four RED/todo stub files present and executing.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Add list tables to schema and apply via generate+migrate [BLOCKING]</name>
+  <files>apps/api/src/db/schema.ts, apps/api/src/db/migrations/0002_lists_schema.sql</files>
+  <read_first>
+    - apps/api/src/db/schema.ts (full file — table conventions)
+    - apps/api/src/db/migrations/0001_calendars_user_url_unique.sql (prior migration shape)
+    - apps/api/drizzle.config.ts
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Database Schema Design"
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/db/schema.ts"
+    - $HOME/.claude/projects/-home-luc-Projects-familysync/memory/drizzle-mariadb-push-unsafe.md
+  </read_first>
+  <action>
+    Append three tables to apps/api/src/db/schema.ts following the exact conventions in 04-RESEARCH §Database Schema Design and the analog patterns in 04-PATTERNS:
+    - `lists`: int autoincrement PK, `ownerId` int('owner_id') references users.id onDelete cascade notNull, `name` varchar(255) notNull, `isShared` boolean('is_shared') default true notNull (D-01), `createdAt` timestamp defaultNow notNull, `updatedAt` timestamp defaultNow onUpdateNow; index idx_lists_owner_id on ownerId.
+    - `listShares` (D-02, member-count-agnostic join table): int PK, `listId` int('list_id') references lists.id onDelete cascade notNull, `userId` int('user_id') references users.id onDelete cascade notNull, `createdAt` timestamp defaultNow notNull; unique('uniq_list_share') on (listId, userId), index idx_list_shares_user_id on userId.
+    - `listItems`: int PK, `listId` int('list_id') references lists.id onDelete cascade notNull, `text` varchar(500) notNull, `checked` boolean default false notNull, `rank` varchar(255) notNull (D-13 fractional-indexing string), `createdAt`, `updatedAt`; index idx_list_items_list_id_rank on (listId, rank), index idx_list_items_list_id_checked on (listId, checked).
+
+    Then generate and apply the migration. This is [BLOCKING]: run `pnpm --filter @familysync/api db:generate` to produce `apps/api/src/db/migrations/0002_lists_schema.sql` (+ journal/snapshot). REVIEW the generated SQL — it MUST be additive (CREATE TABLE only, NO DROP/TRUNCATE of existing tables). Then run `pnpm --filter @familysync/api db:migrate` to apply. NEVER run `db:push` / `drizzle-kit push` — it emits a false destructive diff on populated MariaDB (hard project constraint). Build/type checks pass without the live migration, so this task is mandatory and must complete before any DB-dependent verification in later plans.
+  </action>
+  <verify>
+    <automated>grep -q "mysqlTable('lists'" apps/api/src/db/schema.ts && grep -q "mysqlTable('list_shares'" apps/api/src/db/schema.ts && grep -q "mysqlTable('list_items'" apps/api/src/db/schema.ts && test -f apps/api/src/db/migrations/0002_lists_schema.sql && grep -iq 'CREATE TABLE' apps/api/src/db/migrations/0002_lists_schema.sql && ! grep -iE 'DROP TABLE `?(users|calendars|calendar_events|calendar_outbox|member_credentials)' apps/api/src/db/migrations/0002_lists_schema.sql && pnpm --filter @familysync/api typecheck</automated>
+  </verify>
+  <acceptance_criteria>
+    - Three tables present in schema.ts with the column/index/FK shapes above.
+    - 0002_lists_schema.sql exists, contains CREATE TABLE for lists/list_items/list_shares, and contains NO DROP/TRUNCATE of any pre-existing table.
+    - `db:migrate` applied successfully (migration recorded in drizzle journal).
+    - `pnpm --filter @familysync/api typecheck` passes.
+  </acceptance_criteria>
+  <done>list/list_items/list_shares tables exist in MariaDB via additive generate+migrate; typecheck green; no push used.</done>
+</task>
+
+<task type="auto">
+  <name>Task 4: Add react-router + BottomTabBar + empty ListsIndex shell</name>
+  <files>apps/pwa/src/App.tsx, apps/pwa/src/components/BottomTabBar.tsx, apps/pwa/src/routes/ListsIndex.tsx, apps/pwa/src/store/listsStore.ts</files>
+  <read_first>
+    - apps/pwa/src/App.tsx (current one-liner)
+    - apps/pwa/src/components/CalendarShell.tsx (state-branch + data-fetch conventions)
+    - apps/pwa/src/components/AppNav.tsx (nav/active-state + CSS token conventions)
+    - apps/pwa/src/store/calendarStore.ts (Zustand shape convention)
+    - apps/pwa/vite.config.ts (confirm navigateFallback already covers /lists/*)
+    - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"Layout: App Shell Changes", §"BottomTabBar", §"ListsIndex", §"ListsEmptyState"
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/pwa/src/App.tsx", §"BottomTabBar.tsx", §"ListsIndex.tsx", §"listsStore.ts"
+  </read_first>
+  <action>
+    Transform App.tsx into a BrowserRouter shell (react-router declarative mode, NO data router/loaders): routes `/` → Navigate replace to `/calendar`, `/calendar` → CalendarShell, `/lists` → ListsIndex, `/lists/:listId` → ListDetail. ListDetail does not exist yet — for this plan render a temporary placeholder route element (a stub component that says the list view is coming) so the route resolves; Plan 04 replaces it. Render BottomTabBar as a sibling of `<Routes>`.
+
+    Create BottomTabBar.tsx: fixed-bottom 56px + env(safe-area-inset-bottom), background var(--color-surface-dim), border-top var(--color-border), two equal NavLink tabs (CalendarDays→/calendar, List→/lists) with isActive callback applying accent var(--color-member-0) to icon+label and a 2px active indicator; inactive var(--color-text-muted); 13px label; ≥44px touch target; z-index 200. On desktop (≥768px) the existing AppNav sidebar remains; per UI-SPEC add a "Lists" NavLink there too (sidebar) — do this without breaking the existing AppNav signature.
+
+    Create ListsIndex.tsx: full-height scrollable column, "Lists" heading, useQuery(['lists'], fetchLists) where fetchLists is imported from a minimal listsClient (create only the fetchLists function + List type here if listsClient does not yet exist; Plan 03 expands it). Render ListsEmptyState ("No lists yet" / "Tap + to create your first shared list…") when there are zero lists; render a placeholder card stack otherwise. Wire isLoading/isError/success branches mirroring CalendarShell. Include the "+ New List" FAB affordance (non-functional placeholder is acceptable here; Plan 03 wires CreateListSheet).
+
+    Create listsStore.ts (Zustand, UI-only): activeTab and createListSheetOpen state with setters, following calendarStore conventions (no persist, no immer).
+
+    Confirm vite.config.ts navigateFallback ('/index.html') + denylist already cover SPA deep-links to /lists/* (it does per Phase 3 config) — if a denylist entry would block /lists, fix it; otherwise leave unchanged and note in SUMMARY.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/pwa exec vitest run src/components/CalendarShell.test.tsx 2>&1 | grep -Eiq 'passed' && pnpm --filter @familysync/pwa exec tsc --noEmit && grep -q "BrowserRouter" apps/pwa/src/App.tsx && grep -q "to=\"/lists\"" apps/pwa/src/components/BottomTabBar.tsx</automated>
+  </verify>
+  <acceptance_criteria>
+    - App.tsx wraps the app in BrowserRouter with /calendar, /lists, /lists/:listId routes; existing CalendarShell still mounts at /calendar.
+    - BottomTabBar renders Calendar and Lists NavLinks with active-state accent and ≥44px targets.
+    - ListsIndex renders the empty state copy from UI-SPEC when no lists exist.
+    - listsStore exports activeTab/createListSheetOpen with setters (no server data).
+    - PWA typecheck passes; existing CalendarShell test still green.
+    - Browser check (project convention): `playwright-cli` navigates to /lists and observes the "No lists yet" empty state and the bottom tab bar with an active "Lists" tab. Record the observation in SUMMARY.
+  </acceptance_criteria>
+  <done>User can tap the Lists tab and land on the empty Lists surface; calendar still works; router + tab bar in place.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| browser → /api/* | All list/SSE requests cross here; untrusted client input |
+| API → MariaDB | Drizzle parameterized queries only |
+| drizzle-kit → MariaDB (migration) | DDL applied to a populated production-shaped DB |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-01 | Tampering | drizzle-kit push truncating populated tables | mitigate | generate+migrate ONLY; verify 0002 SQL has no DROP/TRUNCATE of existing tables before applying (Task 3 gate) |
+| T-04-02 | Information Disclosure | scoped-fan-out leak (D-04) — foundational | mitigate | Schema models access via list_shares join table + owner_id (this plan); enforcement lands in Plans 02/03/06; negative test seeded in lists.test.ts here |
+| T-04-SC | Tampering | npm installs (react-router SUS, dnd-kit, fractional-indexing) | mitigate | Legitimacy audit in RESEARCH; blocking human checkpoint (Task 1) for the SUS react-router before install |
+</threat_model>
+
+<verification>
+- `pnpm --filter @familysync/api typecheck` and `pnpm --filter @familysync/pwa exec tsc --noEmit` both pass.
+- `pnpm --filter @familysync/api test` runs (Wave-0 stubs red/todo, not erroring).
+- 0002_lists_schema.sql is additive; migration applied; three tables queryable.
+- `playwright-cli` confirms /lists renders the empty state with the bottom tab bar.
+</verification>
+
+<success_criteria>
+- New deps installed (no ioredis); API test harness operational.
+- Three list tables migrated additively (no push).
+- Router + BottomTabBar live; Lists tab navigates to an empty Lists surface.
+- Four Wave-0 RED stub test files exist and execute.
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification — they are new):**
+- Tables: `lists`, `list_shares`, `list_items` (apps/api/src/db/schema.ts)
+- Migration: `apps/api/src/db/migrations/0002_lists_schema.sql` (+ journal/snapshot)
+- API test harness: `apps/api/test/setup.ts`; setupFiles wiring in `apps/api/vitest.config.ts`
+- RED stub tests: `apps/api/src/routes/lists.test.ts`, `apps/api/src/lib/listEmitter.test.ts`, `apps/pwa/src/hooks/useListSSE.test.ts`, `apps/pwa/src/routes/ListDetail.test.tsx`
+- Components: `BottomTabBar` (apps/pwa/src/components/BottomTabBar.tsx), `ListsIndex` (apps/pwa/src/routes/ListsIndex.tsx), temporary ListDetail placeholder route element
+- Store: `useListsStore` (apps/pwa/src/store/listsStore.ts) with activeTab/createListSheetOpen
+- App.tsx now exports a BrowserRouter-wrapped App + AppShell
+- (Possibly) initial `apps/pwa/src/api/listsClient.ts` with `fetchLists` + `List` type
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-01-SUMMARY.md` when done.
+</output>

.planning/phases/04-shared-lists-live-sync/04-02-PLAN.md

@@ -0,0 +1,139 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 02
+type: tdd
+wave: 2
+depends_on: ["04-01"]
+files_modified:
+  - apps/api/src/lib/listEmitter.ts
+  - apps/api/src/lib/listEmitter.test.ts
+  - apps/api/src/lib/listAccess.ts
+  - apps/api/src/lib/listAccess.test.ts
+autonomous: true
+requirements: [LIST-04]
+user_setup: []
+
+must_haves:
+  truths:
+    - "An event published for a list is delivered only to subscribers of that list's channel"
+    - "A subscriber to list A receives no events published for list B"
+    - "getAccessibleListIds(userId) returns owned list ids plus list ids shared via list_shares, and nothing else"
+    - "Unsubscribing stops further delivery to that handler"
+  artifacts:
+    - path: "apps/api/src/lib/listEmitter.ts"
+      provides: "in-memory scoped pub/sub: publishListEvent, subscribeListEvents"
+      exports: ["publishListEvent", "subscribeListEvents", "ListEvent"]
+    - path: "apps/api/src/lib/listAccess.ts"
+      provides: "getAccessibleListIds(userId) access-scope query"
+      exports: ["getAccessibleListIds"]
+    - path: "apps/api/src/lib/listEmitter.test.ts"
+      provides: "scoped fan-out correctness tests (D-04)"
+      contains: "describe"
+  key_links:
+    - from: "apps/api/src/lib/listEmitter.ts"
+      to: "node:events EventEmitter"
+      via: "module-level singleton keyed by list:${listId}"
+      pattern: "emit\\(`list:"
+    - from: "apps/api/src/lib/listAccess.ts"
+      to: "lists + list_shares tables"
+      via: "owner_id OR list_shares.user_id query"
+      pattern: "listShares"
+---
+
+<objective>
+Build and test-first the load-bearing live-sync primitive: an in-memory, per-list-scoped event emitter (`listEmitter.ts`) plus the access-scope query (`listAccess.ts`) that together guarantee D-04 — a list's change events reach ONLY members with access to that list, never all connected clients and never non-shared members.
+
+This is a dedicated TDD plan because it is pure, testable business logic (`expect(deliveredEvents).toEqual([...])`) and it is the single highest-correctness-risk seam in the phase (private-list leakage). The SSE endpoint (Plan 06) and the route fan-out triggers (Plans 03–06) consume these two functions.
+
+Purpose: Get scoped fan-out provably correct in isolation before any SSE wiring, with the negative test ("private-list events NOT delivered to a non-owner") proven green.
+Output: `publishListEvent`/`subscribeListEvents` (in-memory EventEmitter singleton) and `getAccessibleListIds(userId)`, both fully unit-tested.
+
+**Fan-out mechanism justification (D-18):** In-memory EventEmitter, not Redis. The API runs as a single Node process (no replicas), so Redis pub/sub adds a network hop, an ioredis dependency, and operational overhead for zero benefit. D-18 (N-member / multi-process-agnostic design) is satisfied by the abstraction boundary: callers use `publishListEvent`/`subscribeListEvents` and never touch the EventEmitter directly, so a future Redis swap is mechanical inside `listEmitter.ts`. ioredis is intentionally NOT installed in Phase 4.
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+@apps/api/src/db/schema.ts
+@apps/api/src/db/client.ts
+</context>
+
+<feature>
+  <name>Scoped in-memory list event fan-out + access-scope query (D-04)</name>
+  <files>
+    apps/api/src/lib/listEmitter.ts, apps/api/src/lib/listEmitter.test.ts,
+    apps/api/src/lib/listAccess.ts, apps/api/src/lib/listAccess.test.ts
+  </files>
+  <read_first>
+    - apps/api/src/lib/listEmitter.test.ts (RED stub from Plan 01 — convert to real assertions)
+    - apps/api/src/db/schema.ts (lists, listShares tables created in Plan 01)
+    - apps/api/src/routes/events.ts lines 1-110 (db query + drizzle and/or/eq conventions)
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 1 + Finding 3 (verbatim patterns)
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/lib/listEmitter.ts"
+  </read_first>
+  <behavior>
+    listEmitter (pure, no DB):
+    - Test 1 (RED first): publishListEvent(1, ev) delivers ev to a handler subscribed via subscribeListEvents(1, h); handler called exactly once with ev.
+    - Test 2 (the D-04 negative, critical): a handler subscribed to list 1 receives NOTHING when publishListEvent(2, ev) is called. This is the "private-list events NOT emitted to a non-owner subscriber" assertion from 04-VALIDATION.md.
+    - Test 3: the unsubscribe function returned by subscribeListEvents stops delivery — after calling it, a subsequent publish to that list does not invoke the handler.
+    - Test 4: multiple handlers on the same list channel all receive the event.
+    - ListEvent type union: 'item:added' | 'item:updated' | 'item:deleted' | 'list:updated' | 'list:deleted', shape { type, listId, payload }.
+
+    listAccess (DB-backed, uses the test DB harness from Plan 01):
+    - Test 5: getAccessibleListIds returns ids of lists the user OWNS.
+    - Test 6: getAccessibleListIds returns ids of lists shared to the user via list_shares.
+    - Test 7 (D-04): getAccessibleListIds does NOT return another user's private (non-shared, non-owned) list id.
+    - Test 8: result has no duplicates when a list is both owned and (erroneously) shared.
+  </behavior>
+  <implementation>
+    listEmitter.ts: module-level `new EventEmitter()` with setMaxListeners(200); channel key `list:${listId}`; publishListEvent emits, subscribeListEvents registers on() and returns an off() closure. Use the RESEARCH Finding 1 pattern verbatim.
+
+    listAccess.ts: `getAccessibleListIds(userId: number): Promise<number[]>` — select lists.id where lists.ownerId = userId, union select listShares.listId where listShares.userId = userId, dedupe into a number[]. Use drizzle eq from the events.ts pattern. (Implementation choice: either two selects merged in JS per RESEARCH Finding 3, or a single OR query joined to list_shares — either is acceptable; the tests assert behavior, not query shape.)
+
+    Follow RED → GREEN → REFACTOR: write the failing tests first (convert the Plan 01 stub), confirm they fail, implement minimally to green, refactor only if obvious.
+  </implementation>
+</feature>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| publisher (route handler) → subscriber (SSE stream) | A leak here exposes one member's private list to another |
+| API → MariaDB | access-scope query must not over-return list ids |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-02 | Information Disclosure | scoped fan-out leak (D-04) — load-bearing | mitigate | Per-list channel keying (`list:${listId}`) + getAccessibleListIds scoped to owner_id OR list_shares; proven by Test 2 (cross-list isolation) and Test 7 (private list excluded) |
+| T-04-03 | Information Disclosure | getAccessibleListIds over-returning ids | mitigate | Test 7 asserts a non-owned, non-shared list id is absent; Test 8 asserts dedupe |
+| T-04-04 | Denial of Service | EventEmitter max-listeners warning under many SSE connections | accept | setMaxListeners(200) headroom (100 members × 2 devices); single-process scale is bounded for a household app |
+</threat_model>
+
+<verification>
+<automated>pnpm --filter @familysync/api exec vitest run src/lib/listEmitter.test.ts src/lib/listAccess.test.ts</automated>
+- Test 2 (cross-list isolation) and Test 7 (private list excluded) MUST be present and green.
+</verification>
+
+<success_criteria>
+- RED commit: failing listEmitter/listAccess tests (incl. the D-04 negative).
+- GREEN commit: implementation passes all tests.
+- REFACTOR commit (if any): tests still green.
+- ioredis NOT introduced.
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification):**
+- `apps/api/src/lib/listEmitter.ts` exporting `publishListEvent(listId, event)`, `subscribeListEvents(listId, handler): () => void`, type `ListEvent`
+- `apps/api/src/lib/listAccess.ts` exporting `getAccessibleListIds(userId): Promise<number[]>`
+- Tests: `apps/api/src/lib/listEmitter.test.ts`, `apps/api/src/lib/listAccess.test.ts`
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-02-SUMMARY.md` with RED/GREEN/REFACTOR notes and commit list.
+</output>

.planning/phases/04-shared-lists-live-sync/04-03-PLAN.md

@@ -0,0 +1,201 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 03
+type: execute
+wave: 2
+depends_on: ["04-01"]
+files_modified:
+  - apps/api/src/routes/lists.ts
+  - apps/api/src/routes/lists.test.ts
+  - apps/api/src/index.ts
+  - apps/pwa/src/api/listsClient.ts
+  - apps/pwa/src/routes/ListsIndex.tsx
+  - apps/pwa/src/components/ListCard.tsx
+  - apps/pwa/src/components/CreateListSheet.tsx
+  - apps/pwa/src/components/ListDeleteDialog.tsx
+  - apps/pwa/src/components/ListsEmptyState.tsx
+autonomous: true
+requirements: [LIST-01]
+user_setup: []
+
+must_haves:
+  truths:
+    - "A member can create a named list and it appears in their lists"
+    - "A new shared list auto-populates list_shares rows for the other household members (D-01/D-02)"
+    - "GET /api/lists returns only lists the member owns or that are shared with them (D-04)"
+    - "A member can delete a list (with confirmation) and its items/shares cascade-delete (D-06)"
+  artifacts:
+    - path: "apps/api/src/routes/lists.ts"
+      provides: "POST/GET/PATCH/DELETE /api/lists with scoped access + zod validation"
+      exports: ["listsRouter"]
+    - path: "apps/pwa/src/components/CreateListSheet.tsx"
+      provides: "new-list form with shared/private toggle (default shared)"
+      min_lines: 30
+    - path: "apps/pwa/src/components/ListCard.tsx"
+      provides: "list summary card navigating to /lists/:id"
+      min_lines: 25
+    - path: "apps/pwa/src/components/ListDeleteDialog.tsx"
+      provides: "list-delete confirmation (D-06)"
+      min_lines: 25
+  key_links:
+    - from: "apps/pwa/src/routes/ListsIndex.tsx"
+      to: "/api/lists"
+      via: "useQuery + useMutation in listsClient"
+      pattern: "fetchLists|createList"
+    - from: "apps/api/src/routes/lists.ts"
+      to: "list_shares"
+      via: "auto-insert shares on create + scoped GET"
+      pattern: "listShares"
+    - from: "apps/api/src/index.ts"
+      to: "listsRouter"
+      via: "app.route('/api/lists', listsRouter)"
+      pattern: "api/lists"
+---
+
+<objective>
+Deliver the list-CRUD vertical slice end to end (LIST-01): a member can create a named list (defaulting to Shared), see it in their list index, and delete it with confirmation. The slice spans UI (ListsIndex/ListCard/CreateListSheet/ListDeleteDialog) → API (POST/GET/PATCH/DELETE /api/lists) → DB (lists + list_shares), with server-enforced scoped access (D-04) so a member only ever sees their own and shared lists.
+
+MVP slice: after this plan a real user can create and delete lists — a capability they did not have after Plan 01's empty shell.
+
+Purpose: Establish the lists router (the analog every later list/item endpoint extends) with correct access control and the auto-share-on-create behavior, plus the lists-index UI.
+Output: listsRouter mounted at /api/lists; ListsIndex wired to real data; CreateListSheet + ListCard + ListDeleteDialog; listsClient typed functions.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Lists router — POST/GET/PATCH/DELETE /api/lists with scoped access (LIST-01, D-01/D-02/D-04/D-06)</name>
+  <files>apps/api/src/routes/lists.ts, apps/api/src/routes/lists.test.ts, apps/api/src/index.ts</files>
+  <read_first>
+    - apps/api/src/routes/events.ts (full — resolveUserId, zod schemas, handler/try-catch/401 conventions)
+    - apps/api/src/routes/lists.test.ts (RED stub from Plan 01)
+    - apps/api/src/index.ts (route mount order)
+    - apps/api/src/auth/user.ts (upsertUser, deriveDisplayName signatures)
+    - apps/api/src/db/schema.ts (lists, listShares, listItems, users)
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/routes/lists.ts" + §"Shared Patterns"
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Open Questions" item 3 (auto-populate list_shares)
+  </read_first>
+  <behavior>
+    - Test: POST /api/lists { name, isShared:true } inserts a lists row owned by the caller AND inserts list_shares rows for every other user (not the creator). (LIST-01, D-01, Open Question 3)
+    - Test: POST /api/lists { name, isShared:false } inserts the list with NO list_shares rows.
+    - Test: GET /api/lists returns lists where owner_id = caller OR caller is in list_shares; does NOT return another member's private list (D-04 security-critical).
+    - Test: GET /api/lists includes an item-count summary per list (active/done) for the card badge; assert the field is present.
+    - Test: DELETE /api/lists/:id by the owner removes the list and cascades items + shares; a non-owner/non-sharee gets 403; unknown id gets 404.
+    - Test: PATCH /api/lists/:id updates name and/or isShared by an authorized member; toggling isShared false→true (re)populates shares, true→false removes non-owner shares.
+    - Test: zod rejects name > 255 or empty.
+  </behavior>
+  <action>
+    Create apps/api/src/routes/lists.ts exporting `listsRouter` (Hono). Copy the `resolveUserId` helper verbatim from events.ts (per project convention it is duplicated per router, not extracted). Apply the 401 guard + try/catch-503 conventions on every handler. Define zod schemas: createListSchema (name 1..255, isShared default true), patchListSchema (name?/isShared?, at least one).
+
+    Implement handlers: POST / (create list; if isShared, query users for all member ids except creator and insert list_shares rows — YAGNI auto-share per Open Question 3); GET / (scoped select: owner_id = caller OR id IN list_shares.userId = caller, returning id/name/isShared/ownerId + per-list item counts); PATCH /:id (authorized update of name/isShared, reconciling list_shares on visibility change); DELETE /:id (owner-only delete is the safe default; cascade handles items/shares). Verify list access with the ownership/share-check pattern from 04-PATTERNS before any mutation.
+
+    Mount in index.ts: `import { listsRouter }` and `app.route('/api/lists', listsRouter)` after the sseRouter mount (so it sits behind the OIDC/dev-bypass guard). Do NOT add fan-out emit calls here yet — Plan 06 adds publishListEvent triggers once the SSE endpoint exists (leave a commented seam, note it in SUMMARY). NOTE: per-field item PATCH and item endpoints are Plan 04; this plan is lists only.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts && grep -q "app.route('/api/lists'" apps/api/src/index.ts && pnpm --filter @familysync/api typecheck</automated>
+  </verify>
+  <acceptance_criteria>
+    - lists.test.ts: all create/get/delete/patch/scope tests green, including the D-04 "private list of another member is NOT returned by GET /api/lists" assertion.
+    - Shared-create auto-inserts list_shares for other members; private-create inserts none.
+    - listsRouter mounted at /api/lists in index.ts; typecheck passes.
+  </acceptance_criteria>
+  <done>POST/GET/PATCH/DELETE /api/lists work with server-enforced scoped access and auto-share-on-create; tests green.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: ListsIndex wired to real data + ListCard + CreateListSheet + ListDeleteDialog (LIST-01, D-01/D-06)</name>
+  <files>apps/pwa/src/api/listsClient.ts, apps/pwa/src/routes/ListsIndex.tsx, apps/pwa/src/components/ListCard.tsx, apps/pwa/src/components/CreateListSheet.tsx, apps/pwa/src/components/ListDeleteDialog.tsx, apps/pwa/src/components/ListsEmptyState.tsx</files>
+  <read_first>
+    - apps/pwa/src/routes/ListsIndex.tsx (placeholder shell from Plan 01)
+    - apps/pwa/src/api/client.ts (credentials:'include' fetch convention)
+    - apps/pwa/src/api/listsClient.ts (fetchLists/List from Plan 01, if present)
+    - apps/pwa/src/components/DeleteConfirmationDialog.tsx (modal/focus-trap/CSS-token pattern to mirror)
+    - apps/pwa/src/store/listsStore.ts (createListSheetOpen)
+    - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"ListsIndex", §"ListCard", §"CreateListSheet", §"ListsEmptyState", §"Sharing Toggle", §"Copywriting Contract", §"List Delete"
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"ListsIndex.tsx", §"listsClient.ts", §"DeleteConfirmationDialog reuse"
+  </read_first>
+  <action>
+    Expand apps/pwa/src/api/listsClient.ts with credentials:'include' typed functions: fetchLists, createList({name,isShared}), patchList(id, {...}), deleteList(id), plus List/ListItem types (ListItem used by Plan 04). Follow the client.ts apiFetch wrapper convention.
+
+    Build CreateListSheet.tsx per UI-SPEC: bottom sheet (mobile) / centered modal (desktop), heading "New list", auto-focused name input (placeholder "e.g. Groceries"), Shared/Private toggle defaulting to Shared (D-01), "Create" button (accent var(--color-member-0), disabled while name empty, destructive border on blank-submit attempt), "Cancel". On create: useMutation(createList) with optimistic insert into ['lists'] + onError rollback + onSettled invalidate; close sheet on success. Open/close driven by listsStore.createListSheetOpen.
+
+    Build ListCard.tsx per UI-SPEC: rounded card, list name (heading), "N items / N active · M done" badge, "Shared" pill for shared lists (nothing for private), ChevronRight; whole card taps through to /lists/:id via react-router navigate/Link; swipe/long-press (phone) or hover X (desktop) reveals Delete which opens ListDeleteDialog. All user text as plain-text JSX (XSS guard).
+
+    Build ListDeleteDialog.tsx by mirroring DeleteConfirmationDialog structure (do NOT modify the existing one — it is wired to calendarStore): same modal layout, backdrop, role="dialog"/aria-modal, Escape-to-close, focus-on-open, CSS tokens; heading "Delete list?", body '"{name}" and all its items will be permanently removed.', Cancel + destructive Delete (D-06). On confirm: useMutation(deleteList) optimistic removal from ['lists'] + navigate back to /lists; failure toast "Couldn't delete. Try again."
+
+    Replace the ListsIndex placeholder card stack with real ListCard rendering from useQuery(['lists']); ListsEmptyState when zero lists; FAB ("+ New List") opens CreateListSheet.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/pwa exec tsc --noEmit && pnpm --filter @familysync/pwa exec vitest run src/components/DeleteConfirmationDialog.test.tsx 2>&1 | grep -Eiq 'passed' && grep -q "createList" apps/pwa/src/api/listsClient.ts</automated>
+  </verify>
+  <acceptance_criteria>
+    - listsClient exports fetchLists/createList/patchList/deleteList + List/ListItem types.
+    - CreateListSheet defaults to Shared, disables Create on empty name, creates via optimistic mutation.
+    - ListCard shows name + count badge + "Shared" pill (shared only) and navigates to /lists/:id.
+    - ListDeleteDialog confirms before delete and does not modify DeleteConfirmationDialog.tsx.
+    - PWA typecheck passes; existing DeleteConfirmationDialog test still green.
+    - Browser check (`playwright-cli`): create a list named "Groceries" → it appears as a card with a "Shared" pill; open delete dialog → confirm → card disappears. Record in SUMMARY.
+  </acceptance_criteria>
+  <done>User can create (shared by default) and delete named lists through the UI, backed by scoped API; counts and sharing badge render.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| browser → /api/lists | client supplies name/isShared/list id — all untrusted |
+| API → MariaDB | scoped queries enforce who can see/mutate a list |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-05 | Elevation of Privilege | accessing another member's private list via direct id (GET/DELETE/PATCH /api/lists/:id) | mitigate | Every handler resolves caller via resolveUserId and verifies owner_id OR list_shares before returning/mutating; 403 otherwise; tested |
+| T-04-02 | Information Disclosure | GET /api/lists leaking non-shared lists | mitigate | Scoped WHERE owner_id = caller OR id IN list_shares; negative test asserts another member's private list is absent (D-04) |
+| T-04-06 | Tampering | XSS via list name | mitigate | List names rendered as plain-text JSX children only; no dangerouslySetInnerHTML (T-03-15 pattern) |
+| T-04-07 | Tampering | overposting on PATCH (fields beyond name/isShared) | mitigate | zod patchListSchema whitelists name/isShared only |
+| T-04-08 | Elevation of Privilege | self-adding to list_shares | mitigate | Shares are server-managed only (auto-populated on create/visibility change); no client-writable shares endpoint exposed in Phase 4 |
+</threat_model>
+
+<verification>
+<automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts && pnpm --filter @familysync/pwa exec tsc --noEmit</automated>
+- `playwright-cli`: create + delete a list end to end.
+- D-04 negative test green.
+</verification>
+
+<success_criteria>
+- LIST-01 satisfied: create + delete named lists end to end.
+- Shared-by-default with server-managed list_shares; scoped GET enforced.
+- listsRouter is the analog later item/SSE plans extend.
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification):**
+- `apps/api/src/routes/lists.ts` exporting `listsRouter` (POST/GET/PATCH/DELETE /api/lists); local `resolveUserId` copy
+- `app.route('/api/lists', listsRouter)` mount in apps/api/src/index.ts
+- `apps/pwa/src/api/listsClient.ts`: `fetchLists`, `createList`, `patchList`, `deleteList`, types `List`, `ListItem`
+- Components: `CreateListSheet`, `ListCard`, `ListDeleteDialog`, `ListsEmptyState`
+- Real-data `ListsIndex` (replaces Plan 01 placeholder)
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-03-SUMMARY.md` when done.
+</output>

.planning/phases/04-shared-lists-live-sync/04-04-PLAN.md

@@ -0,0 +1,196 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 04
+type: execute
+wave: 3
+depends_on: ["04-03"]
+files_modified:
+  - apps/api/src/routes/lists.ts
+  - apps/api/src/routes/lists.test.ts
+  - apps/api/src/lib/rank.ts
+  - apps/api/src/lib/rank.test.ts
+  - apps/pwa/src/api/listsClient.ts
+  - apps/pwa/src/routes/ListDetail.tsx
+  - apps/pwa/src/routes/ListDetail.test.tsx
+  - apps/pwa/src/components/ItemRow.tsx
+  - apps/pwa/src/components/AddItemInput.tsx
+  - apps/pwa/src/App.tsx
+autonomous: true
+requirements: [LIST-02]
+user_setup: []
+
+must_haves:
+  truths:
+    - "A member can add an item to a list and it appears at the bottom of the active section"
+    - "A member can check an item off and it sinks to the Completed section (D-05)"
+    - "A member can delete an individual item instantly with no confirmation (D-06)"
+    - "Adding an item assigns a fractional rank so order is stable; PATCH updates exactly one field (D-08)"
+  artifacts:
+    - path: "apps/api/src/lib/rank.ts"
+      provides: "fractional rank helpers (append-to-end, between, move-to-active-bottom)"
+      exports: ["rankForAppend", "rankBetween"]
+    - path: "apps/pwa/src/routes/ListDetail.tsx"
+      provides: "list detail with active/completed split + add/check/delete"
+      min_lines: 60
+    - path: "apps/pwa/src/components/ItemRow.tsx"
+      provides: "item row with checkbox, text, delete"
+      min_lines: 30
+    - path: "apps/pwa/src/components/AddItemInput.tsx"
+      provides: "sticky add-item input"
+      min_lines: 20
+  key_links:
+    - from: "apps/pwa/src/routes/ListDetail.tsx"
+      to: "/api/lists/:id/items + /api/list-items/:id"
+      via: "useQuery(['list', listId]) + optimistic mutations"
+      pattern: "list-items|/items"
+    - from: "apps/api/src/routes/lists.ts"
+      to: "fractional-indexing"
+      via: "rankForAppend on item create / uncheck"
+      pattern: "generateKeyBetween|rankForAppend"
+---
+
+<objective>
+Deliver the item-CRUD + checked-sink vertical slice (LIST-02): inside a list, a member can add items, check them off (sinking to a Completed section per D-05), and delete individual items instantly (D-06). Items get a stable fractional rank on creation (D-13 foundation, reused by Plan 05 reorder), and updates use per-field PATCH with single-field last-write-wins (D-08). Optimistic UI is wired here for add/check/delete (D-07/D-09).
+
+MVP slice: after this plan a real user can fully manage the contents of a list — the core grocery/gift-ideas use case — replacing the temporary ListDetail placeholder from Plan 01.
+
+Purpose: Build the item data layer (endpoints + rank assignment) and the ListDetail surface that consumes it, leaving live-sync (Plan 06) and drag-reorder (Plan 05) to layer on top.
+Output: item endpoints on listsRouter (POST items, per-field PATCH, DELETE); rank helpers; ListDetail/ItemRow/AddItemInput; App.tsx route points at the real ListDetail.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Item endpoints + fractional-rank assignment (LIST-02, D-05/D-08/D-09)</name>
+  <files>apps/api/src/routes/lists.ts, apps/api/src/routes/lists.test.ts, apps/api/src/lib/rank.ts, apps/api/src/lib/rank.test.ts</files>
+  <read_first>
+    - apps/api/src/routes/lists.ts (listsRouter from Plan 03 — extend; access-check pattern)
+    - apps/api/src/routes/lists.test.ts (item stubs)
+    - apps/api/src/db/schema.ts (listItems)
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 2 (fractional-indexing API), Finding 6 (per-field PATCH zod), §"Open Questions" item 2 (uncheck rank)
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/routes/lists.ts" (zod patchItemSchema, ownership verification)
+  </read_first>
+  <behavior>
+    - Test: POST /api/lists/:id/items { text } inserts an item with a fractional rank placed AFTER the last active item (generateKeyBetween(lastActiveRank, null)); first item in an empty list gets generateKeyBetween(null,null) → "a0". (LIST-02, D-13)
+    - Test: GET /api/lists/:id/items returns items access-gated by list membership; shape includes id/listId/text/checked/rank.
+    - Test: PATCH /api/list-items/:id { checked:true } updates ONLY checked (per-field); body with two fields is rejected by zod .refine (D-08).
+    - Test: PATCH /api/list-items/:id { checked:false } (uncheck) recomputes rank to append to the bottom of the active section (Open Question 2), in the same write.
+    - Test: PATCH /api/list-items/:id { text } updates only text; updatedAt advances (LWW basis, D-08).
+    - Test: DELETE /api/list-items/:id removes the item; a member without list access gets 403 (delete-wins semantics, D-09 — no resurrection path).
+    - Test (rank.ts pure unit): rankForAppend(lastRank|null) and rankBetween(a,b) return valid fractional-indexing strings producing the expected ASC ordering.
+  </behavior>
+  <action>
+    Create apps/api/src/lib/rank.ts wrapping fractional-indexing: `rankForAppend(lastRank: string | null): string` = generateKeyBetween(lastRank, null); `rankBetween(prev: string | null, next: string | null): string` = generateKeyBetween(prev, next). Pure functions; unit-tested.
+
+    Extend listsRouter (lists.ts) with item routes, each behind resolveUserId 401 + the list-access verification pattern from 04-PATTERNS (owner OR list_shares else 403) + try/catch-503:
+    - POST /:id/items (zod: text 1..500) → compute rank via rankForAppend(last active item's rank), insert, return the row.
+    - GET /:id/items → access-gated select ordered by rank ASC.
+    - PATCH /list-items/:itemId (zod patchItemSchema: {checked?,text?,position?}.partial().refine(exactly one)) → apply single-field write with updatedAt=NOW(); on checked:false recompute rank to active-bottom in the same statement/transaction.
+    - DELETE /list-items/:itemId → delete (delete-wins; no rollback path).
+    Note the route paths: items-by-list use /:id/items (nested under lists); single-item mutations use /list-items/:itemId at the listsRouter root (matches RESEARCH architecture diagram). Mount accordingly so both resolve under /api. Do NOT add publishListEvent here — Plan 06 inserts fan-out triggers (leave a clearly commented seam after each successful write).
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts src/lib/rank.test.ts && pnpm --filter @familysync/api typecheck</automated>
+  </verify>
+  <acceptance_criteria>
+    - rank.ts tests green; ordering stable.
+    - Item POST assigns active-bottom rank; per-field PATCH enforces exactly-one-field (zod refine) and is tested for checked/text/uncheck-rank.
+    - DELETE works with access gating; no edit can resurrect a deleted item.
+    - typecheck passes.
+  </acceptance_criteria>
+  <done>Item endpoints with fractional rank + per-field LWW PATCH + delete-wins, all access-gated; tests green.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: ListDetail with active/completed split + ItemRow + AddItemInput + optimistic UI (LIST-02, D-05/D-07/D-09)</name>
+  <files>apps/pwa/src/api/listsClient.ts, apps/pwa/src/routes/ListDetail.tsx, apps/pwa/src/routes/ListDetail.test.tsx, apps/pwa/src/components/ItemRow.tsx, apps/pwa/src/components/AddItemInput.tsx, apps/pwa/src/App.tsx</files>
+  <read_first>
+    - apps/pwa/src/routes/ListDetail.tsx (placeholder from Plan 01)
+    - apps/pwa/src/routes/ListDetail.test.tsx (optimistic-update RED stub from Plan 01)
+    - apps/pwa/src/components/CalendarShell.tsx (loading/error/success branch convention)
+    - apps/pwa/src/api/listsClient.ts (add item fns here)
+    - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"ListDetail", §"ItemRow", §"AddItemInput", §"ListEmptyState", §"Optimistic Updates", §"Checked-Off Sink Behavior", §"Item Delete"
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"ListDetail.tsx", §"ItemRow.tsx", §"listsClient.ts"
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 6 (optimistic onMutate/onError/onSettled)
+  </read_first>
+  <action>
+    Add item functions to listsClient.ts: fetchListItems(listId), addItem(listId,{text}), patchListItem(itemId, {checked} | {text} | {position}), deleteItem(itemId) — all credentials:'include'.
+
+    Replace the ListDetail placeholder (and point the App.tsx /lists/:listId route at the real ListDetail). ListDetail: read :listId from useParams; useQuery(['list', listId], fetchListItems) with refetchInterval:30000 (D-12 polling fallback active now; SSE hook layered in Plan 06). Split items into activeItems (!checked, sorted by rank ASC) and completedItems (checked) per D-05. Render header (back ChevronLeft, list name, kebab placeholder, sharing badge), active ItemRow list, a collapsible "Completed (N)" section (default expanded), AddItemInput sticky at bottom, and ListEmptyState when no items.
+
+    ItemRow.tsx per UI-SPEC: 44px min-height row, checkbox (20px visual / 44px touch, accent fill when checked), item text (plain-text JSX; line-through + muted when completed), instant delete affordance (swipe-left zone on phone / hover Trash2 on desktop, no confirmation per D-06). Include the GripVertical handle slot for active items but it is non-functional here (Plan 05 wires dnd-kit). Apply transition 'transform 150ms ease-out' so Plan 05's remote-reorder animation slot exists.
+
+    Wire optimistic mutations (D-07) with React Query onMutate/onError/onSettled against ['list', listId]: add (append optimistically at active bottom, opacity 0.6 until confirm, rollback on error), check (move to completed optimistically, rollback on error), delete (remove optimistically, NO rollback — delete-wins D-09).
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/pwa exec vitest run src/routes/ListDetail.test.tsx && pnpm --filter @familysync/pwa exec tsc --noEmit</automated>
+  </verify>
+  <acceptance_criteria>
+    - ListDetail.test.tsx optimistic-update + rollback test (D-07) is now real and green.
+    - Active/completed split renders per D-05; checking an item moves it to Completed.
+    - Individual item delete is instant (no dialog); add shows optimistic pending state.
+    - App.tsx /lists/:listId route renders the real ListDetail (placeholder removed).
+    - PWA typecheck passes.
+    - Browser check (`playwright-cli`): open a list, add "milk", check it off (sinks to Completed), delete an item (vanishes instantly). Record in SUMMARY.
+  </acceptance_criteria>
+  <done>User can add, check off (sink), and delete items in a list with optimistic UI; tests green.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| browser → item endpoints | client supplies text/checked/item id — untrusted |
+| API → MariaDB | item mutations gated by list access |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-05 | Elevation of Privilege | mutating items in a list the caller cannot access | mitigate | Every item handler verifies owner OR list_shares before read/write; 403 otherwise; tested |
+| T-04-07 | Tampering | overposting on item PATCH (writing fields beyond checked/text/position) | mitigate | zod patchItemSchema .partial().refine(exactly one field) — tested |
+| T-04-06 | Tampering | XSS via item text | mitigate | Item text rendered as plain-text JSX child; no dangerouslySetInnerHTML |
+| T-04-09 | Tampering | resurrecting a deleted item via an in-flight edit (D-09) | mitigate | DELETE is final; PATCH on a missing id affects zero rows (no upsert); delete-wins test asserts no resurrection |
+</threat_model>
+
+<verification>
+<automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts src/lib/rank.test.ts && pnpm --filter @familysync/pwa exec vitest run src/routes/ListDetail.test.tsx</automated>
+- `playwright-cli`: add / check / delete items in a real browser.
+</verification>
+
+<success_criteria>
+- LIST-02 satisfied: add, check-off (sink to Completed), delete items end to end.
+- Per-field PATCH (D-08) + delete-wins (D-09) + optimistic UI (D-07) in place.
+- Fractional rank assigned on create (foundation for Plan 05 reorder).
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification):**
+- `apps/api/src/lib/rank.ts`: `rankForAppend`, `rankBetween` (+ rank.test.ts)
+- Item routes on listsRouter: POST /:id/items, GET /:id/items, PATCH /list-items/:itemId, DELETE /list-items/:itemId
+- listsClient additions: `fetchListItems`, `addItem`, `patchListItem`, `deleteItem`
+- Components: `ItemRow`, `AddItemInput`, real `ListDetail` (replaces Plan 01 placeholder)
+- App.tsx /lists/:listId now renders ListDetail
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-04-SUMMARY.md` when done.
+</output>

.planning/phases/04-shared-lists-live-sync/04-05-PLAN.md

@@ -0,0 +1,158 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 05
+type: execute
+wave: 4
+depends_on: ["04-04"]
+files_modified:
+  - apps/pwa/src/routes/ListDetail.tsx
+  - apps/pwa/src/components/ItemRow.tsx
+  - apps/pwa/src/api/listsClient.ts
+  - apps/api/src/lib/rank.test.ts
+  - apps/api/src/routes/lists.test.ts
+autonomous: true
+requirements: [LIST-03]
+user_setup: []
+
+must_haves:
+  truths:
+    - "A member can drag an active item to a new position and the order persists"
+    - "A reorder writes only the moved item's rank (one-row write), not a renumber"
+    - "Touch drag requires a deliberate long-press on the handle (no accidental drags while scrolling)"
+    - "A reorder arriving from another member animates to the new position rather than hard-snapping (D-14)"
+  artifacts:
+    - path: "apps/pwa/src/components/ItemRow.tsx"
+      provides: "dnd-kit sortable item with drag handle"
+      contains: "useSortable"
+    - path: "apps/pwa/src/routes/ListDetail.tsx"
+      provides: "DndContext/SortableContext over active items with onDragEnd → rank PATCH"
+      contains: "DndContext"
+  key_links:
+    - from: "apps/pwa/src/routes/ListDetail.tsx"
+      to: "PATCH /api/list-items/:id { position }"
+      via: "onDragEnd computes generateKeyBetween + optimistic patch"
+      pattern: "generateKeyBetween|position"
+    - from: "apps/pwa/src/components/ItemRow.tsx"
+      to: "@dnd-kit/sortable"
+      via: "useSortable handle listeners"
+      pattern: "useSortable"
+---
+
+<objective>
+Deliver the drag-to-reorder vertical slice (LIST-03): a member can drag an active item to a new position using @dnd-kit, and the move persists as a single-row fractional-rank write (D-13). Touch drag requires a 200ms long-press on the handle (no accidental drags); concurrent reorders converge via last-write-wins (D-15); and a reorder that arrives from another member animates to its new position rather than hard-snapping (D-14).
+
+MVP slice: after this plan a real user can reorder list items — the last interactive capability of the lists surface — building directly on the items rendered in Plan 04.
+
+Purpose: Layer drag-and-drop and client-side fractional-rank computation onto the existing ItemRow/ListDetail, reusing the server-side per-field position PATCH already built in Plan 04.
+Output: dnd-kit DndContext/SortableContext in ListDetail; sortable ItemRow with handle-scoped listeners + sensors; client computes the new rank via generateKeyBetween and PATCHes position optimistically.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Sortable ItemRow + DndContext reorder with optimistic rank PATCH (LIST-03, D-13/D-14/D-15)</name>
+  <files>apps/pwa/src/components/ItemRow.tsx, apps/pwa/src/routes/ListDetail.tsx, apps/pwa/src/api/listsClient.ts</files>
+  <read_first>
+    - apps/pwa/src/components/ItemRow.tsx (from Plan 04 — add useSortable; handle slot already present)
+    - apps/pwa/src/routes/ListDetail.tsx (active-items rendering from Plan 04)
+    - apps/pwa/src/api/listsClient.ts (patchListItem supports { position })
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 7 (dnd-kit + handle + sensors + rank-on-drop)
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"ItemRow.tsx"
+    - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"Drag-to-Reorder", §"Accessibility Baseline" (keyboard reorder)
+  </read_first>
+  <action>
+    Make ItemRow sortable: use useSortable({ id: item.id }) from @dnd-kit/sortable; attach setNodeRef + style (CSS.Transform.toString(transform), transition fallback 'transform 150ms ease-out' for D-14 remote animation, opacity 0.8 + slight scale-down when isDragging). Attach drag listeners to the GripVertical handle button ONLY (not the whole row) so taps on checkbox/text/delete still work. Drag handle only on active items (completed items not reorderable per UI-SPEC).
+
+    In ListDetail, wrap the active-items list in DndContext (collisionDetection={closestCenter}) + SortableContext (items = active item ids, verticalListSortingStrategy). Configure sensors via useSensors: PointerSensor/MouseSensor immediate, TouchSensor with activationConstraint { delay: 200, tolerance: 5 } (no accidental drags), and KeyboardSensor for the accessibility keyboard-reorder fallback.
+
+    onDragEnd: ignore no-op (no over / same id). Compute the destination index after the move; derive prevRank/nextRank from the active list at the destination and compute newRank = generateKeyBetween(prevRank, nextRank) (fractional-indexing). Fire an optimistic reorder mutation: setQueryData(['list', listId]) to reflect the new order immediately (snap), then patchListItem(itemId, { position: newRank }); onError animate back / rollback to previous; onSettled invalidate. Only the moved item's rank is written (one-row PATCH — D-13). Concurrent same-item reorder converges by server LWW on updatedAt (D-15) — no drag-state broadcasting.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/pwa exec tsc --noEmit && grep -q "useSortable" apps/pwa/src/components/ItemRow.tsx && grep -q "DndContext" apps/pwa/src/routes/ListDetail.tsx && grep -q "generateKeyBetween" apps/pwa/src/routes/ListDetail.tsx</automated>
+  </verify>
+  <acceptance_criteria>
+    - ItemRow uses useSortable with listeners on the handle only; completed items have no handle.
+    - ListDetail wraps active items in DndContext/SortableContext with Pointer/Touch(delay 200)/Keyboard sensors.
+    - onDragEnd computes newRank via generateKeyBetween and issues a single-item position PATCH optimistically with rollback.
+    - PWA typecheck passes.
+    - Browser check (`playwright-cli`): drag an item to a new position; the new order persists after a reload (rank written). Record in SUMMARY. (Touch long-press + keyboard reorder are dnd-kit built-ins; note manual/device coverage where playwright cannot simulate long-press reliably.)
+  </acceptance_criteria>
+  <done>User can drag-reorder active items; move persists as a one-row rank write; remote reorders animate.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Strengthen server-side reorder ordering tests (LIST-03, D-13)</name>
+  <files>apps/api/src/lib/rank.test.ts, apps/api/src/routes/lists.test.ts</files>
+  <read_first>
+    - apps/api/src/lib/rank.test.ts (from Plan 04)
+    - apps/api/src/routes/lists.test.ts (PATCH position coverage)
+    - .planning/phases/04-shared-lists-live-sync/04-VALIDATION.md (LIST-03 row: "PATCH new rank produces correct fractional order")
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md §"Common Pitfalls" Pitfall 2 (precision)
+  </read_first>
+  <action>
+    Add server-side tests proving reorder correctness: (a) repeated mid-point inserts via rankBetween produce strictly increasing distinct strings over many iterations (precision does not collapse — Pitfall 2); (b) PATCH /api/list-items/:id { position } updates only rank and a subsequent GET returns items in the new ASC order; (c) moving an item between two neighbors yields a rank strictly between theirs. These align the LIST-03 row in 04-VALIDATION.md to a green automated check. No production behavior change — Plan 04 already implements the PATCH position path.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/api exec vitest run src/lib/rank.test.ts src/routes/lists.test.ts</automated>
+  </verify>
+  <acceptance_criteria>
+    - LIST-03 ordering test ("PATCH new rank produces correct fractional order") is present and green.
+    - Mid-point-insert precision test passes for many iterations.
+  </acceptance_criteria>
+  <done>Server-side reorder ordering + rank precision are covered by green automated tests.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| browser → PATCH /api/list-items/:id { position } | client supplies the new rank string — untrusted |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-07 | Tampering | client sending position alongside other fields | mitigate | zod patchItemSchema refine (exactly one field) already enforces position-only PATCH (Plan 04); reasserted by tests |
+| T-04-05 | Elevation of Privilege | reordering items in an inaccessible list | mitigate | PATCH list-items access-gated (owner OR list_shares) from Plan 04 |
+| T-04-10 | Denial of Service | pathological "zipper" inserts growing rank strings | accept | VARCHAR(255) headroom; fractional-indexing degrades gracefully; rebalance available via generateNKeysBetween if ever needed (not in scope) |
+</threat_model>
+
+<verification>
+<automated>pnpm --filter @familysync/api exec vitest run src/lib/rank.test.ts src/routes/lists.test.ts && pnpm --filter @familysync/pwa exec tsc --noEmit</automated>
+- `playwright-cli`: drag-reorder persists across reload.
+</verification>
+
+<success_criteria>
+- LIST-03 satisfied: drag-to-reorder works, persists as a single-row rank write.
+- Touch long-press + keyboard reorder available; remote reorders animate (D-14).
+- Reorder ordering + precision covered by automated tests.
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification):**
+- ItemRow gains useSortable + handle-scoped drag listeners
+- ListDetail gains DndContext/SortableContext + useSensors + onDragEnd rank computation
+- Additional rank/order tests in rank.test.ts and lists.test.ts (no new production endpoints — reuses Plan 04 PATCH position)
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-05-SUMMARY.md` when done.
+</output>

.planning/phases/04-shared-lists-live-sync/04-06-PLAN.md

@@ -0,0 +1,194 @@
+---
+phase: 04-shared-lists-live-sync
+plan: 06
+type: execute
+wave: 5
+depends_on: ["04-02", "04-04", "04-05"]
+files_modified:
+  - apps/api/src/routes/sse.ts
+  - apps/api/src/routes/lists.ts
+  - apps/api/src/routes/lists.test.ts
+  - apps/pwa/src/hooks/useListSSE.ts
+  - apps/pwa/src/hooks/useListSSE.test.ts
+  - apps/pwa/src/components/LiveSyncIndicator.tsx
+  - apps/pwa/src/routes/ListDetail.tsx
+autonomous: true
+requirements: [LIST-04]
+user_setup: []
+
+must_haves:
+  truths:
+    - "When one member adds/checks/deletes/reorders an item, the other member's open list updates within seconds without a manual refresh"
+    - "A private list's events sync to the owner's own devices (D-03) but are never delivered to a member who is not its owner (D-04)"
+    - "On SSE reconnect the client full-refetches the affected list (D-10)"
+    - "After capped backoff is exhausted, the UI shows an 'Updates paused' indicator and stops hammering (D-11); polling keeps data fresh (D-12)"
+  artifacts:
+    - path: "apps/api/src/routes/sse.ts"
+      provides: "GET /api/sse/lists scoped SSE stream"
+      contains: "/lists"
+    - path: "apps/pwa/src/hooks/useListSSE.ts"
+      provides: "bounded-backoff EventSource wrapper invalidating React Query"
+      exports: ["useListSSE"]
+    - path: "apps/pwa/src/components/LiveSyncIndicator.tsx"
+      provides: "connected/reconnecting/disconnected indicator"
+      min_lines: 20
+  key_links:
+    - from: "apps/api/src/routes/lists.ts"
+      to: "publishListEvent"
+      via: "fan-out trigger after every successful item/list write"
+      pattern: "publishListEvent"
+    - from: "apps/api/src/routes/sse.ts"
+      to: "subscribeListEvents + getAccessibleListIds"
+      via: "scoped per-list subscription inside streamSSE"
+      pattern: "subscribeListEvents|getAccessibleListIds"
+    - from: "apps/pwa/src/hooks/useListSSE.ts"
+      to: "/api/sse/lists"
+      via: "EventSource(withCredentials) → invalidateQueries"
+      pattern: "EventSource"
+---
+
+<objective>
+Deliver the live-sync vertical slice (LIST-04, success criterion 3): wire the scoped SSE endpoint (`GET /api/sse/lists`), emit fan-out events from every list/item write (consuming the Plan 02 emitter), and add the bounded-backoff EventSource client hook + LiveSyncIndicator so one member's edits appear for the other within seconds — surviving a brief reconnect — without leaking private-list events (D-04).
+
+MVP slice: this is the final capability that makes the lists "shared and live" rather than single-user. All CRUD/reorder built in Plans 03–05 becomes collaborative.
+
+Purpose: Connect the proven scoped fan-out primitive (Plan 02) to real route writes and to a robust client (bounded backoff per D-11, full-refetch-on-reconnect per D-10, polling fallback per D-12), and prove the load-bearing no-leak invariant at the HTTP/route layer.
+Output: /api/sse/lists endpoint; publishListEvent triggers in lists.ts; useListSSE hook; LiveSyncIndicator; ListDetail consumes the hook and renders the indicator.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md
+@.planning/phases/04-shared-lists-live-sync/04-RESEARCH.md
+@.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md
+@.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md
+@.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md
+@apps/api/src/routes/sse.ts
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Scoped /api/sse/lists endpoint + fan-out triggers on every write (LIST-04, D-04/D-10)</name>
+  <files>apps/api/src/routes/sse.ts, apps/api/src/routes/lists.ts, apps/api/src/routes/lists.test.ts</files>
+  <read_first>
+    - apps/api/src/routes/sse.ts (existing /heartbeat streamSSE pattern — extend)
+    - apps/api/src/routes/lists.ts (item/list write handlers from Plans 03–04 — add emit seams)
+    - apps/api/src/lib/listEmitter.ts (publishListEvent, subscribeListEvents — Plan 02)
+    - apps/api/src/lib/listAccess.ts (getAccessibleListIds — Plan 02)
+    - apps/api/src/routes/lists.test.ts (LIST-04 stub incl. private-list no-leak)
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"apps/api/src/routes/sse.ts" (the /lists endpoint pattern verbatim)
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 1 + Finding 3
+  </read_first>
+  <behavior>
+    - Test: a successful POST item / PATCH item / DELETE item / list:update / list:delete causes publishListEvent to fire with the matching ListEvent type for that listId. (LIST-04)
+    - Test (D-04, load-bearing): an event published for member A's PRIVATE list is NOT delivered to member B's /api/sse/lists subscription — B's accessible-list set (getAccessibleListIds) excludes it, so B never subscribes to that channel. This is the "private-list events NOT emitted to a non-owner subscriber" assertion in 04-VALIDATION.md, asserted at the route/subscription layer (Plan 02 proved it at the emitter layer).
+    - Test: a member subscribed via /api/sse/lists DOES receive events for a list shared with them.
+    - Test: the endpoint returns 401 when unauthenticated.
+  </behavior>
+  <action>
+    Extend sseRouter (sse.ts) with `GET /lists` following the 04-PATTERNS pattern: resolveUserId → 401 on null; const accessibleListIds = await getAccessibleListIds(userId); inside streamSSE, for each accessible listId call subscribeListEvents(listId, handler) where the handler writes an SSE event (event: event.type, data: JSON.stringify(event)) when !stream.aborted; run a 30s heartbeat loop; on exit call every unsubscribe. (resolveUserId: reuse the lists.ts copy or import a shared helper consistently — match the existing duplication convention.)
+
+    Add publishListEvent fan-out triggers in lists.ts after every successful write (the seams left in Plans 03–04): item:added after POST item, item:updated after PATCH item, item:deleted after DELETE item, list:updated after PATCH list, list:deleted after DELETE list. Each carries { type, listId, payload } with the minimal payload needed; the client uses events only to trigger invalidate/refetch (D-10), so payload need not be the full row.
+
+    Mount: /api/sse/lists is already under /api/sse (sseRouter mounted in index.ts) — no index.ts change needed beyond what exists. Confirm it sits behind the OIDC/dev-bypass guard.
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts && grep -q "publishListEvent" apps/api/src/routes/lists.ts && grep -q "/lists" apps/api/src/routes/sse.ts && pnpm --filter @familysync/api typecheck</automated>
+  </verify>
+  <acceptance_criteria>
+    - GET /api/sse/lists subscribes only to getAccessibleListIds channels; 401 when unauthenticated.
+    - Every list/item write emits the correct ListEvent via publishListEvent.
+    - The D-04 route-layer no-leak test (private list of member A not delivered to member B) is present and green.
+    - typecheck passes.
+  </acceptance_criteria>
+  <done>Scoped SSE stream live; writes fan out to accessible subscribers only; no-leak invariant proven at the route layer.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: useListSSE bounded-backoff hook + LiveSyncIndicator + ListDetail wiring (LIST-04, D-10/D-11/D-12)</name>
+  <files>apps/pwa/src/hooks/useListSSE.ts, apps/pwa/src/hooks/useListSSE.test.ts, apps/pwa/src/components/LiveSyncIndicator.tsx, apps/pwa/src/routes/ListDetail.tsx</files>
+  <read_first>
+    - apps/pwa/src/hooks/useListSSE.test.ts (D-11 bounded-backoff RED stub from Plan 01)
+    - apps/pwa/src/routes/ListDetail.tsx (already has refetchInterval:30000 from Plan 04)
+    - .planning/phases/04-shared-lists-live-sync/04-RESEARCH.md Finding 4 (EventSource wrapper verbatim) + Pitfall 3 + Pitfall 7
+    - .planning/phases/04-shared-lists-live-sync/04-PATTERNS.md §"useListSSE.ts"
+    - .planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md §"LiveSyncIndicator", §"Live Sync + Reconnect"
+  </read_first>
+  <behavior>
+    - Test (D-11): with a mocked EventSource that always errors, the hook retries on the backoff schedule 250→500→1000→2000→4000→cap 8000ms and, after the capped attempts are exhausted (≥6), transitions to 'disconnected' and STOPS scheduling further reconnects.
+    - Test: on a successful (mocked) open, the hook resets the attempt counter, reports 'connected', and invalidates ['list', listId] (full refetch on reconnect, D-10).
+    - Test: on a received list-change event, the hook invalidates ['list', listId].
+    - Test: the hook closes the EventSource and clears timers on unmount (no reconnect storm — Pitfall 3).
+  </behavior>
+  <action>
+    Create apps/pwa/src/hooks/useListSSE.ts using the RESEARCH Finding 4 pattern verbatim: refs for the EventSource/attempt-count/timer (not state), connect() in useCallback, BACKOFF_STEPS_MS=[250,500,1000,2000,4000,8000], MAX_ATTEMPTS=length; new EventSource('/api/sse/lists',{withCredentials:true}); on open → reset attempts, onStateChange('connected'), invalidateQueries(['list',listId]); on each list-change event type → invalidateQueries(['list',listId]); on error → es.close(), if attempts≥MAX → onStateChange('disconnected') and stop, else onStateChange('reconnecting') and setTimeout(connect, backoff[attempt++]); cleanup closes es + clears timer on unmount. Convert the Plan 01 stub into these real assertions (mock EventSource).
+
+    Create LiveSyncIndicator.tsx per UI-SPEC: connected = 8px green dot (var(--color-member-1)), reconnecting = pulsing muted dot + "Reconnecting…", disconnected = red dot + "Updates paused"; role="status" with the aria-labels from UI-SPEC; role="alert" for the disconnected state.
+
+    Wire into ListDetail: call useListSSE({ listId, onStateChange: setSyncState }) and render LiveSyncIndicator in the header. Keep refetchInterval:30000 as the always-on polling fallback (D-12) so data stays fresh even when SSE is 'disconnected'. (Consider hoisting the single SSE connection so it does not reconnect on every list navigation — acceptable to keep it in ListDetail for Phase 4 per RESEARCH note; document the choice.)
+  </action>
+  <verify>
+    <automated>pnpm --filter @familysync/pwa exec vitest run src/hooks/useListSSE.test.ts && pnpm --filter @familysync/pwa exec tsc --noEmit && grep -q "useListSSE" apps/pwa/src/routes/ListDetail.tsx</automated>
+  </verify>
+  <acceptance_criteria>
+    - useListSSE.test.ts: bounded-backoff exhaustion test (D-11) and reconnect-invalidate test (D-10) are real and green.
+    - Hook uses withCredentials:true and closes EventSource on error before scheduling retry (no storm).
+    - LiveSyncIndicator renders connected/reconnecting/disconnected with correct ARIA.
+    - ListDetail consumes the hook + renders the indicator; refetchInterval polling fallback retained.
+    - PWA typecheck passes.
+    - Browser check (`playwright-cli`, two contexts where feasible): in context A add an item; context B's open list reflects it within a few seconds without manual refresh. Record in SUMMARY. (Cross-device/iOS-standalone live co-edit remains a device-only manual check per 04-VALIDATION.md.)
+  </acceptance_criteria>
+  <done>Live co-edit works: one member's edits appear for the other within seconds, with bounded reconnect + visible paused state + polling fallback.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| API publisher → SSE subscribers | the load-bearing leak boundary (D-04) |
+| browser EventSource → /api/sse/lists | session cookie must cross (withCredentials); endpoint behind OIDC |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-04-02 | Information Disclosure | scoped-fan-out leak (D-04) — load-bearing | mitigate | /api/sse/lists subscribes ONLY to getAccessibleListIds channels; route-layer test asserts member B never receives member A's private-list events |
+| T-04-01 | Spoofing/AuthZ | unauthenticated SSE subscription | mitigate | resolveUserId → 401; endpoint behind OIDC middleware; EventSource sends session cookie via withCredentials (Pitfall 7) |
+| T-04-11 | Denial of Service | EventSource reconnect storm | mitigate | es.close() on error + manual bounded-backoff setTimeout; give-up after MAX_ATTEMPTS (Pitfall 3) |
+| T-04-12 | Information Disclosure | over-broad event payload exposing other lists' data | mitigate | Payload carries only { type, listId, minimal } and is per-list-channel scoped; client uses it solely to trigger invalidate/refetch (D-10) |
+</threat_model>
+
+<verification>
+<automated>pnpm --filter @familysync/api exec vitest run src/routes/lists.test.ts && pnpm --filter @familysync/pwa exec vitest run src/hooks/useListSSE.test.ts && pnpm --filter @familysync/pwa exec tsc --noEmit</automated>
+- `playwright-cli` two-context live-update check.
+- D-04 route-layer no-leak test green.
+</verification>
+
+<success_criteria>
+- LIST-04 satisfied: live co-edit within seconds, surviving a brief reconnect.
+- D-04 no-leak proven at both emitter (Plan 02) and route (this plan) layers.
+- D-10 full-refetch-on-reconnect, D-11 bounded backoff + paused indicator, D-12 polling fallback all in place.
+</success_criteria>
+
+<artifacts_produced>
+**Symbols/files this plan creates (exclude from drift verification):**
+- `GET /api/sse/lists` endpoint on sseRouter (apps/api/src/routes/sse.ts)
+- `publishListEvent(...)` fan-out triggers in apps/api/src/routes/lists.ts (item:added/updated/deleted, list:updated/deleted)
+- `apps/pwa/src/hooks/useListSSE.ts` exporting `useListSSE` (bounded-backoff EventSource wrapper)
+- `apps/pwa/src/components/LiveSyncIndicator.tsx`
+- ListDetail wiring of useListSSE + LiveSyncIndicator
+</artifacts_produced>
+
+<output>
+Create `.planning/phases/04-shared-lists-live-sync/04-06-SUMMARY.md` when done.
+</output>

.planning/phases/04-shared-lists-live-sync/04-CONTEXT.md

@@ -0,0 +1,131 @@
+# Phase 4: Shared Lists + Live Sync - Context
+
+**Gathered:** 2026-06-07
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Deliver **app-native shared lists** (stored in MariaDB, NOT CalDAV/Fastmail) with real-time co-edit sync:
+
+- Create and delete named lists (LIST-01)
+- Add, check off, and delete items (LIST-02)
+- Reorder items by drag-and-drop (LIST-03)
+- Live co-edit sync over SSE — one member's change appears for the other within seconds, surviving a brief reconnect (LIST-04, success criterion 3)
+
+Lists are entirely app-owned data — no CalDAV write-back, no Fastmail involvement. This is the one track independent of the calendar write path.
+
+**⚠️ ENTRY GATE (D-14, issue #1034 — STILL UNVERIFIED as of 2026-06-07):** The 5-minute SSE-over-Pangolin smoke test must PASS before the live-sync layer is built (`/api/sse/heartbeat` held open 5+ min through the tunnel without being cut — see `docs/deployment.md` Gate 2 row 5). This is an operator/infra task requiring the Authelia+Pangolin/Newt rig. If it FAILS: fix Pangolin idle-timeout/buffering, OR the polling fallback (decided below) becomes mandatory rather than optional. Do not build live sync on an unverified transport.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Sharing model (List & item behavior)
+- **D-01:** Lists support **shared and private** visibility. New lists **default to Shared** (visible+editable by both members); creator can toggle a single list to Private. Default-shared chosen deliberately — the grocery/family-hub use case is collaborative and default-private would add friction to the primary action.
+- **D-02:** Data model is a **`list_shares` join table** (list has an `owner`; join table records who each list is shared with) — NOT a simple boolean. v1 UI is only shared/private, but the schema must be **member-count-agnostic** so granular N-recipient sharing is a future UI addition, not a migration.
+- **D-03:** A private list still **live-syncs across its owner's own devices** (phone + tablet); it is never pushed to other members.
+- **D-04:** **SSE fan-out MUST be scoped to who can see a list.** A list's change events broadcast only to members with access (owner + shares), never to all connected clients. This is the load-bearing consequence of the sharing model — get it right or private lists leak.
+
+### Item behavior
+- **D-05:** Checked-off items **sink to a "completed" section** at the bottom (active items stay on top). Not strikethrough-in-place, not immediate-disappear — keeps the active list clean for groceries while preserving "what was done."
+- **D-06:** **Confirm-on-delete for whole lists only.** Individual items delete instantly (live sync makes mistakes visible; easy to re-add). Reuse Phase 3's `DeleteConfirmationDialog` component for the list-delete dialog.
+
+### Live feel & conflict resolution
+- **D-07:** **Optimistic UI** — the editing member's change shows instantly, then reconciles against the server (rollback on rejection). Fits the low-friction constraint. Use React Query optimistic updates.
+- **D-08:** **Per-field writes + per-field last-write-wins** ("field-level merge", BOUNDED — no CRDT). The API PATCHes only the changed field (`checked`, `text`, or `position`), not the whole row; the server applies last-write-wins per field on a server timestamp. Result: "one toggles checked while the other edits text" → both stick. Same-field collisions fall back to last-write-wins. Do NOT build CRDTs or per-field vector clocks.
+- **D-09:** **Delete-wins** — if one member deletes an item while the other edits it, deletion is final; the in-flight edit is dropped (editor sees it vanish via live sync). Edits never resurrect deleted items.
+
+### Reconnect & transport (success criterion 3)
+- **D-10:** **Full refetch on reconnect** — on SSE reconnect, React Query invalidates and refetches the affected list(s) fresh. No server-side event log / Last-Event-ID replay. Lists are tiny so refetch is cheap and guaranteed-correct.
+- **D-11:** **Silent auto-recover with capped backoff, then a visible indicator.** Reconnect silently with bounded (capped exponential) backoff; after backoff is exhausted, surface a visible "disconnected / updates paused" indicator and stop hammering. NOTE for planner: raw `EventSource` auto-reconnects forever with no backoff control — implementing bounded backoff + a give-up indicator requires wrapping `EventSource` in a manual reconnect loop or using a small SSE client lib.
+- **D-12:** **Polling fallback via React Query `refetchInterval`** if SSE is unavailable/flaky through Pangolin. Already have React Query; trivial to add. Guarantees criterion 3 even if the tunnel misbehaves. (Mandatory if the entry-gate smoke test fails.)
+
+### Reordering (LIST-03)
+- **D-13:** **String-based fractional rank** for item positions (e.g., the `fractional-indexing` approach) — NOT raw floats (precision exhausts fast on repeated mid-point inserts) and NOT integer-renumber (a single move rewrites many rows, noisy over SSE). A move rewrites only the moved item's rank — one-row write, plays well with live sync and concurrent reorders.
+- **D-14:** **Animate to new order** when a remote reorder arrives (smooth transition, matches the live-sync promise).
+- **D-15:** **Last-write-wins with brief settle** on concurrent reorder of the same item — both see their local drag instantly (optimistic), server resolves to the last write, both converge within ~1s. No drag-locking / drag-state broadcasting.
+
+### Navigation / app shell
+- **D-16:** **Bottom tab bar** (Calendar | Lists) — thumb-reachable, matches native iOS/Android, low-friction for the non-technical member. Currently `App.tsx` renders `CalendarShell` directly with no nav.
+- **D-17:** **Add react-router** for real URLs (e.g. `/lists/:id`). No router is installed today. Real URLs enable Phase 5 push deep-linking ("tap to open Groceries"), browser back button, and PWA shortcuts. Small dependency that pays off next phase.
+
+### Project-level principle (applies beyond this phase)
+- **D-18:** **Design for N family members, not hard-coded two.** Schema, auth/access checks, and SSE fan-out must be member-count-agnostic. Same philosophy as treating Fastmail as a generic provider — set the framework now for future expansion to more family members. The `list_shares` table (D-02) and scoped fan-out (D-04) are the first applications.
+
+### Claude's Discretion (deferred to research/planner)
+- **Fan-out mechanism:** in-memory EventEmitter vs Redis pub/sub. API runs as a **single Node process** today (no replicas), so in-memory is the YAGNI default; Redis is in docker-compose but `ioredis` is NOT installed. Planner must address this explicitly and justify the choice against D-18 (multi-process future).
+- Exact position-rank datatype/column, SSE auth/middleware wiring, and React Query cache-key structure.
+
+### Reviewed Todos
+- **Adopt drizzle generate+migrate workflow (retire `db:push` on MariaDB)** — directly relevant: Phase 4 adds new tables (`lists`, `list_items`, `list_shares`). `drizzle-kit push` is unsafe on populated MariaDB (emits false destructive diff — see memory). New tables MUST use `drizzle-kit generate` + `migrate`, not `push`. Folded as a hard constraint on this phase's schema work.
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Entry gate & transport
+- `docs/deployment.md` §"SSE idle timeout (Phase 4 dependency, issue #1034)" and §"Gate 2 — Live verification checklist" row 5 — the SSE-over-Pangolin smoke-test procedure that is this phase's entry gate
+- `apps/api/src/routes/sse.ts` — existing `/api/sse/heartbeat` SSE pattern (Hono `streamSSE`, `stream.aborted` loop); the live-list SSE endpoint(s) build on this
+
+### Prior decisions & requirements
+- `.planning/ROADMAP.md` §"Phase 4: Shared Lists + Live Sync" — goal, success criteria, entry gate
+- `.planning/REQUIREMENTS.md` — LIST-01 through LIST-04
+- `.planning/STATE.md` §Decisions — D-14 (SSE-over-WebSocket choice, entry gate), real-time transport notes
+- `.planning/phases/01-foundation-broker-spike/01-CONTEXT.md` §D-08 — why the SSE smoke test was folded into Phase 1 to de-risk Phase 4 transport
+
+### Schema & code patterns
+- `apps/api/src/db/schema.ts` — Drizzle table conventions (mysqlTable, indexes, unique keys, `references`/`onDelete`); model new list tables on these
+- `apps/pwa/src/components/DeleteConfirmationDialog.tsx` — reuse for list-delete confirmation (D-06)
+- `apps/pwa/src/App.tsx` / `apps/pwa/src/components/CalendarShell.tsx` — current shell with no router; tab-bar + react-router (D-16/D-17) wrap this
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `apps/api/src/routes/sse.ts` — working Hono `streamSSE` heartbeat; the live-list event stream extends this pattern (auth via existing `/api/*` middleware).
+- `apps/pwa/src/components/DeleteConfirmationDialog.tsx` — Phase 3 confirmation dialog, reuse for list delete.
+- React Query + Zustand already established (CLAUDE.md split: React Query = server state, Zustand = UI-only state). Optimistic updates (D-07) and polling fallback (D-12) use React Query; tab/route UI state is Zustand-adjacent.
+- CSS token layer + colorUtils from Phase 2 available for list theming.
+
+### Established Patterns
+- `/api/*` routes sit behind OIDC middleware (or dev-auth bypass) — list routes inherit this; identity resolved to `users.id` via oidc iss+sub (D-10 from prior phases).
+- Drizzle schema conventions in `schema.ts`: int autoincrement PKs, `references(() => x.id, { onDelete: 'cascade' })`, composite unique keys, named indexes.
+- Schema migrations: **generate+migrate, never `push`** on MariaDB (see Reviewed Todos).
+
+### Integration Points
+- New `/api/lists` (+ items + SSE) routes mount in `apps/api/src/index.ts` alongside `eventsRouter`, `sseRouter`.
+- New `lists` / `list_items` / `list_shares` tables in `apps/api/src/db/schema.ts`.
+- PWA gains a router + bottom tab bar in `App.tsx`; Lists surface is a sibling of `CalendarShell`.
+- SSE fan-out must integrate with the (TBD) in-memory-vs-Redis pub/sub decision; `redis` service exists in docker-compose, `ioredis` not yet a dependency.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- "Sink to bottom" for checked items modeled on a clean active-list / completed-section split (grocery-list mental model).
+- Sharing UI vision (future): pick specific recipients from the user DB; v1 collapses this to shared/private but the `list_shares` model preserves the path.
+- Backoff-then-pause reconnect UX: "set backoff and then display an indicator to pause more updates" — i.e., don't retry forever silently; tell the user when data may be stale.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **Anonymous list sharing via a unique public URL** (share a list with a non-member through a link) — NEW CAPABILITY, its own phase. Introduces unauthenticated access that bypasses the Authelia OIDC model (every `/api/*` route is currently authenticated), plus link-token generation, revocation, and abuse handling. Explicitly out of scope for Phase 4; revisit as a dedicated "external/guest sharing" phase.
+- **Granular per-recipient sharing UI** (a member picker) — the `list_shares` data model (D-02) supports it, but no picker UI in v1 (only two members; "shared" == shared with the other person). Becomes relevant once the household has 3+ members (D-18).
+- **List metadata** (icons, per-list colors, max items) — not raised as required; standard approaches fine unless a future UI phase wants them.
+
+</deferred>
+
+---
+
+*Phase: 4-Shared Lists + Live Sync*
+*Context gathered: 2026-06-07*

.planning/phases/04-shared-lists-live-sync/04-DISCUSSION-LOG.md

@@ -0,0 +1,122 @@
+# Phase 4: Shared Lists + Live Sync - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-06-07
+**Phase:** 4-Shared Lists + Live Sync
+**Areas discussed:** List & item behavior, Live feel & conflicts, Reconnect catch-up, Reordering behavior, Lists navigation
+
+---
+
+## List & item behavior — Sharing
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| All lists shared | Every list visible+editable by both; no permission model | |
+| Shared + private | Lists can be private; owner/visibility model + permission checks | ✓ (refined below) |
+
+**User's choice:** Shared + private — initially "default private, share to specific userdb members, optionally anonymous via unique URL."
+**Notes:** Claude challenged three points: (1) anonymous URL = scope creep + unauthenticated security surface → deferred; (2) recipient picker = YAGNI for two members → boolean shared/private UI but `list_shares` join table underneath; (3) default-private fights the collaborative grocery use case → recommend default-shared. User accepted re-framing.
+
+## List & item behavior — Privacy (refined)
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Default Shared, toggle to Private | Family-hub default; flip individual list private; boolean model | ✓ |
+| Default Private, toggle to Shared | Owner-only default; explicit share step | |
+| All shared, no private | Drop private entirely | |
+
+**User's choice:** Default Shared, toggle to Private.
+**Notes:** Anonymous URL → Defer it. Data model → `list_shares` join table, with the explicit instruction: "remember this project is intended to expand to other family members in the future... similar to treating fastmail like a generic provider helps set that framework." Captured as project-level principle D-18.
+
+## List & item behavior — Checked items & delete guard
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Strikethrough in place | Item stays, struck-through | |
+| Sink to bottom | Checked move to completed section | ✓ |
+| Disappear immediately | Removed from view | |
+| Confirm list delete only | Dialog for lists; items delete instantly | ✓ |
+| Confirm both | Dialog for lists and items | |
+| No confirmation | Everything instant | |
+
+**User's choice:** Sink to bottom; confirm list-delete only.
+**Notes:** Private lists still live-sync across the owner's own devices (owner-only visibility, multi-device sync).
+
+---
+
+## Live feel & conflicts
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Optimistic (instant local, reconcile) | Snappy; rollback on failure | ✓ |
+| Server-confirmed | Wait for round-trip | |
+| Last-write-wins | Later write wins per row | |
+| Field-level merge | Merge non-conflicting fields | ✓ (bounded) |
+| Delete wins | Deletion final, edit dropped | ✓ |
+| Edit resurrects | Edit re-creates deleted item | |
+
+**User's choice:** Optimistic UI; field-level merge; delete wins.
+**Notes:** Claude bounded "field-level merge" to per-field PATCH + per-field last-write-wins (no CRDT) to prevent over-engineering. User context implied agreement (momentum).
+
+---
+
+## Reconnect catch-up
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Full refetch on reconnect | React Query invalidate+refetch | ✓ |
+| Last-Event-ID replay | Server replays missed events | |
+| Hybrid | Replay, refetch fallback | |
+| Silent + auto-recover | EventSource native reconnect, no UI | ✓ (refined) |
+| Subtle indicator when offline | Show reconnecting hint | |
+| Polling fallback (refetchInterval) | Periodic refetch if SSE drops | ✓ |
+| SSE only, fix the proxy | Commit to SSE, no fallback | |
+
+**User's choice:** Full refetch; silent auto-recover with capped backoff then a "pause updates" indicator; polling fallback.
+**Notes:** User specified "set back off and then display an indicator to pause more updates." Claude flagged that raw EventSource has no backoff control → needs a manual reconnect wrapper or SSE client lib.
+
+---
+
+## Reordering behavior
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Fractional rank | One-row write per move | ✓ (string-based) |
+| Integer position + renumber | Many-row writes per move | |
+| Animate to new order | Smooth remote reorder | ✓ |
+| Update on next interaction | No animation | |
+| Last-write-wins, brief settle | Optimistic, converge ~1s | ✓ |
+| Lock during drag | Broadcast drag state | |
+
+**User's choice:** Fractional rank; animate to new order; last-write-wins settle.
+**Notes:** Claude steered fractional rank to a string-based fractional index (e.g. `fractional-indexing`) rather than raw floats to avoid precision exhaustion on repeated mid-point inserts.
+
+---
+
+## Lists navigation
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Bottom tab bar | Persistent Calendar \| Lists tabs | ✓ |
+| Hamburger drawer | Slide-out menu | |
+| Top segmented control | Calendar/Lists toggle at top | |
+| Add a router (real URLs) | react-router; deep-linkable lists | ✓ |
+| Zustand view toggle (no router) | UI-state flag, no URLs | |
+
+**User's choice:** Bottom tab bar + react-router (real URLs).
+**Notes:** No router installed today (`App.tsx` renders `CalendarShell` directly). Real URLs justified by Phase 5 push deep-linking to specific lists.
+
+---
+
+## Claude's Discretion
+
+- Fan-out mechanism (in-memory EventEmitter vs Redis pub/sub) — single Node process today; in-memory is YAGNI default; planner must address explicitly vs the N-member future.
+- Position-rank column datatype, SSE auth/middleware wiring, React Query cache-key structure.
+
+## Deferred Ideas
+
+- Anonymous list sharing via unique public URL (unauthenticated, bypasses Authelia) — own phase.
+- Granular per-recipient sharing UI (member picker) — `list_shares` model supports it; relevant at 3+ members.
+- List metadata (icons, per-list colors, max items) — not required; standard approaches fine.

.planning/phases/04-shared-lists-live-sync/04-PATTERNS.md

@@ -0,0 +1,749 @@
+# Phase 4: Shared Lists + Live Sync — Pattern Map
+
+**Mapped:** 2026-06-09
+**Files analyzed:** 18 new/modified files
+**Analogs found:** 16 / 18
+
+---
+
+## File Classification
+
+| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|-------------------|------|-----------|----------------|---------------|
+| `apps/api/src/db/schema.ts` | model (modify) | CRUD | self | exact |
+| `apps/api/src/db/migrations/0002_lists_schema.sql` | migration | batch | `0001_calendars_user_url_unique.sql` | role-match |
+| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | none in codebase | no analog |
+| `apps/api/src/routes/lists.ts` | route/controller | CRUD | `apps/api/src/routes/events.ts` | exact |
+| `apps/api/src/routes/sse.ts` | route (modify) | streaming | self | exact |
+| `apps/api/src/index.ts` | config (modify) | request-response | self | exact |
+| `apps/pwa/src/App.tsx` | component (modify) | request-response | self | exact |
+| `apps/pwa/src/components/BottomTabBar.tsx` | component | request-response | `apps/pwa/src/components/AppNav.tsx` | role-match |
+| `apps/pwa/src/routes/ListsIndex.tsx` | component | CRUD | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
+| `apps/pwa/src/routes/ListDetail.tsx` | component | CRUD + event-driven | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
+| `apps/pwa/src/components/ListCard.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
+| `apps/pwa/src/components/ItemRow.tsx` | component | event-driven | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
+| `apps/pwa/src/components/AddItemInput.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
+| `apps/pwa/src/components/CreateListSheet.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
+| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | none — novel | no analog |
+| `apps/pwa/src/components/ListsEmptyState.tsx` | component | request-response | `apps/pwa/src/components/SkeletonCalendar.tsx` | role-match |
+| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | none in codebase | no analog |
+| `apps/pwa/src/api/listsClient.ts` | utility | request-response | `apps/pwa/src/api/client.ts` | exact |
+| `apps/pwa/src/store/listsStore.ts` | store | request-response | `apps/pwa/src/store/calendarStore.ts` | exact |
+
+---
+
+## Pattern Assignments
+
+### `apps/api/src/db/schema.ts` (model, CRUD — append new tables)
+
+**Analog:** self — read `apps/api/src/db/schema.ts` lines 1–163 in full above.
+
+**Imports pattern** (lines 1–13):
+```typescript
+import {
+  mysqlTable,
+  varchar,
+  int,
+  timestamp,
+  boolean,
+  index,
+  unique,
+} from 'drizzle-orm/mysql-core'
+```
+Note: `mysqlEnum` is imported for `calendarOutbox` but is not needed for list tables. Import only what the new tables use.
+
+**Table definition pattern** (lines 40–54, `memberCredentials` — simplest table with FK):
+```typescript
+export const memberCredentials = mysqlTable(
+  'member_credentials',
+  {
+    id: int().primaryKey().autoincrement(),
+    userId: int('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    encryptedPassword: text('encrypted_password').notNull(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at').defaultNow().onUpdateNow(),
+  },
+  (t) => [index('idx_member_credentials_user_id').on(t.userId)],
+)
+```
+
+**Composite unique key pattern** (lines 61–86, `calendars`):
+```typescript
+(t) => [
+  index('idx_calendars_user_id').on(t.userId),
+  unique('uniq_calendar_user_url').on(t.userId, t.url),
+]
+```
+
+**New tables to append** — follow the schema from RESEARCH.md §Database Schema Design exactly:
+- `lists` — int PK, `owner_id` FK to `users`, `name varchar(255)`, `is_shared boolean DEFAULT true`, `created_at`, `updated_at`; index on `owner_id`
+- `listShares` — int PK, `list_id` FK to `lists` cascade, `user_id` FK to `users` cascade, `created_at`; unique on `(list_id, user_id)`, index on `user_id`
+- `listItems` — int PK, `list_id` FK to `lists` cascade, `text varchar(500)`, `checked boolean DEFAULT false`, `rank varchar(255)`, `created_at`, `updated_at`; composite index on `(list_id, rank)`, index on `(list_id, checked)`
+
+---
+
+### `apps/api/src/routes/lists.ts` (route, CRUD)
+
+**Analog:** `apps/api/src/routes/events.ts` (full file above)
+
+**File header doc-block pattern** (lines 1–22 of events.ts):
+```typescript
+/**
+ * Lists router — list + item CRUD with SSE fan-out trigger.
+ *
+ * Security:
+ *   - All endpoints resolve currentUserId via resolveUserId (returns null → 401).
+ *   - Access control: list must be owned by currentUser OR appear in list_shares.
+ *   - Drizzle parameterized queries prevent SQL injection.
+ *   - zod validates all write payloads (name max 255, text max 500).
+ *
+ * Mounted under /api/* in index.ts — behind oidcAuthMiddleware.
+ */
+```
+
+**Imports pattern** (lines 24–37 of events.ts):
+```typescript
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+import { and, or, eq } from 'drizzle-orm'
+import { db } from '../db/client.js'
+import { lists, listItems, listShares, users } from '../db/schema.js'
+import { getAuth } from '../auth/middleware.js'
+import { upsertUser, deriveDisplayName } from '../auth/user.js'
+import { publishListEvent } from '../lib/listEmitter.js'
+import '../auth/devBypass.js'
+
+export const listsRouter = new Hono()
+```
+
+**`resolveUserId` helper** — copy verbatim from `events.ts` lines 59–76. This function is duplicated per router (not extracted to a shared module) — maintain that pattern.
+
+**Zod schema pattern** (lines 82–105 of events.ts):
+```typescript
+const createListSchema = z.object({
+  name: z.string().min(1).max(255),
+  isShared: z.boolean().default(true),
+})
+
+const createItemSchema = z.object({
+  text: z.string().min(1).max(500),
+})
+
+// Per-field PATCH — enforce exactly one field per D-08
+const patchItemSchema = z
+  .object({
+    checked: z.boolean(),
+    text: z.string().min(1).max(500),
+    position: z.string().min(1).max(255),
+  })
+  .partial()
+  .refine((obj) => Object.keys(obj).length === 1, {
+    message: 'PATCH must update exactly one field',
+  })
+```
+
+**Route handler pattern** — GET with auth + access check + try/catch (lines 122–221 of events.ts):
+```typescript
+listsRouter.get('/', async (c) => {
+  const currentUserId = await resolveUserId(c)
+  if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
+
+  try {
+    // SELECT lists WHERE owner_id = ? OR id IN (SELECT list_id FROM list_shares WHERE user_id = ?)
+    const rows = await db
+      .select({ /* ... */ })
+      .from(lists)
+      .where(or(eq(lists.ownerId, currentUserId), /* join with listShares */ ))
+
+    return c.json({ lists: rows })
+  } catch (err) {
+    console.error('[lists] DB query failed:', err)
+    return c.json({ error: 'Service unavailable' }, 503)
+  }
+})
+```
+
+**Fan-out trigger pattern** — call after every successful write:
+```typescript
+// After insert/update/delete succeeds:
+publishListEvent(listId, { type: 'item:added', listId, payload: newItem })
+```
+
+**Ownership verification pattern** (lines 326–339 of events.ts):
+```typescript
+// Verify list access before any item mutation
+const [listRow] = await db
+  .select({ ownerId: lists.ownerId })
+  .from(lists)
+  .where(eq(lists.id, listId))
+
+if (!listRow) return c.json({ error: 'Not found' }, 404)
+
+const isOwner = listRow.ownerId === currentUserId
+const [shareRow] = isOwner ? [{}] : await db
+  .select({ listId: listShares.listId })
+  .from(listShares)
+  .where(and(eq(listShares.listId, listId), eq(listShares.userId, currentUserId)))
+
+if (!isOwner && !shareRow) return c.json({ error: 'Access denied' }, 403)
+```
+
+---
+
+### `apps/api/src/routes/sse.ts` (route, streaming — extend existing)
+
+**Analog:** self — `apps/api/src/routes/sse.ts` lines 1–40 (full file above).
+
+**Core streamSSE pattern** (lines 28–40):
+```typescript
+sseRouter.get('/heartbeat', (c) => {
+  return streamSSE(c, async (stream) => {
+    let id = 0
+    while (!stream.aborted) {
+      await stream.writeSSE({
+        data: JSON.stringify({ ts: new Date().toISOString(), id }),
+        event: 'heartbeat',
+        id: String(id++),
+      })
+      await stream.sleep(10_000)
+    }
+  })
+})
+```
+
+**New `/lists` endpoint** extends this with:
+- `resolveUserId(c)` call first → 401 on null (same as events.ts pattern)
+- `getAccessibleListIds(userId)` DB query before `streamSSE` call
+- `subscribeListEvents(listId, handler)` loop inside `streamSSE`
+- Heartbeat loop at 30s cadence (not 10s — Pangolin smoke test used 10s for the heartbeat, 30s is fine for production load)
+- Cleanup: `unsubscribers.forEach(unsub => unsub())` after the while loop exits
+
+```typescript
+sseRouter.get('/lists', async (c) => {
+  const userId = await resolveUserId(c)
+  if (!userId) return c.json({ error: 'Unauthorized' }, 401)
+
+  const accessibleListIds = await getAccessibleListIds(userId)
+
+  return streamSSE(c, async (stream) => {
+    const unsubscribers: Array<() => void> = []
+
+    for (const listId of accessibleListIds) {
+      const unsub = subscribeListEvents(listId, async (event) => {
+        if (stream.aborted) return
+        await stream.writeSSE({
+          data: JSON.stringify(event),
+          event: event.type,
+          id: `${listId}-${Date.now()}`,
+        })
+      })
+      unsubscribers.push(unsub)
+    }
+
+    let tick = 0
+    while (!stream.aborted) {
+      await stream.writeSSE({
+        data: JSON.stringify({ ts: new Date().toISOString() }),
+        event: 'heartbeat',
+        id: String(tick++),
+      })
+      await stream.sleep(30_000)
+    }
+
+    unsubscribers.forEach((unsub) => unsub())
+  })
+})
+```
+
+---
+
+### `apps/api/src/lib/listEmitter.ts` (utility, event-driven)
+
+**No codebase analog** — this is new. Use the pattern from RESEARCH.md Finding 1 verbatim:
+
+```typescript
+import { EventEmitter } from 'node:events'
+
+const emitter = new EventEmitter()
+emitter.setMaxListeners(200)
+
+export type ListEvent = {
+  type: 'item:added' | 'item:updated' | 'item:deleted' | 'list:updated' | 'list:deleted'
+  listId: number
+  payload: unknown
+}
+
+export function publishListEvent(listId: number, event: ListEvent): void {
+  emitter.emit(`list:${listId}`, event)
+}
+
+export function subscribeListEvents(
+  listId: number,
+  handler: (event: ListEvent) => void,
+): () => void {
+  const channel = `list:${listId}`
+  emitter.on(channel, handler)
+  return () => emitter.off(channel, handler)
+}
+```
+
+---
+
+### `apps/api/src/index.ts` (config, modify)
+
+**Analog:** self — lines 1–83 (full file above).
+
+**Route mount pattern** (lines 59–61):
+```typescript
+app.route('/api/me', meRouter)
+app.route('/api/events', eventsRouter)
+app.route('/api/sse', sseRouter)
+```
+
+**Add after `sseRouter` mount:**
+```typescript
+import { listsRouter } from './routes/lists.js'
+// ...
+app.route('/api/lists', listsRouter)
+```
+
+**Auto-migrate pattern** — add before `startBrokerPoller()` (line 65):
+```typescript
+import { migrate } from 'drizzle-orm/mysql2/migrator'
+// ...
+await migrate(db, { migrationsFolder: './src/db/migrations' })
+```
+
+---
+
+### `apps/pwa/src/App.tsx` (component, modify)
+
+**Analog:** self — lines 1–5 (full file above). Currently a one-liner.
+
+**Transform to** (pattern from RESEARCH.md Finding 5):
+```tsx
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router'
+import { CalendarShell } from './components/CalendarShell.js'
+import { ListsIndex } from './routes/ListsIndex.js'
+import { ListDetail } from './routes/ListDetail.js'
+import { BottomTabBar } from './components/BottomTabBar.js'
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <AppShell />
+    </BrowserRouter>
+  )
+}
+
+function AppShell() {
+  return (
+    <>
+      <Routes>
+        <Route path="/" element={<Navigate to="/calendar" replace />} />
+        <Route path="/calendar" element={<CalendarShell />} />
+        <Route path="/lists" element={<ListsIndex />} />
+        <Route path="/lists/:listId" element={<ListDetail />} />
+      </Routes>
+      <BottomTabBar />
+    </>
+  )
+}
+```
+
+---
+
+### `apps/pwa/src/components/BottomTabBar.tsx` (component, request-response)
+
+**Analog:** `apps/pwa/src/components/AppNav.tsx` (nav component with active-state links — check that file if needed for CSS token conventions)
+
+**Key pattern** — NavLink with isActive callback (from RESEARCH.md Finding 5):
+```tsx
+import { NavLink } from 'react-router'
+import { CalendarDays, List } from 'lucide-react'
+
+export function BottomTabBar() {
+  return (
+    <nav
+      style={{
+        position: 'fixed',
+        bottom: 0,
+        left: 0,
+        right: 0,
+        height: '56px',
+        display: 'flex',
+        background: 'var(--color-surface)',
+        borderTop: '1px solid var(--color-border)',
+        zIndex: 100,
+      }}
+    >
+      <NavLink
+        to="/calendar"
+        className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
+      >
+        <CalendarDays size={22} aria-hidden="true" />
+        <span>Calendar</span>
+      </NavLink>
+      <NavLink
+        to="/lists"
+        className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
+      >
+        <List size={22} aria-hidden="true" />
+        <span>Lists</span>
+      </NavLink>
+    </nav>
+  )
+}
+```
+
+CSS tokens: use `var(--color-surface)`, `var(--color-border)`, `var(--color-text-primary)`, `var(--color-text-secondary)` — the existing token layer from Phase 2.
+
+---
+
+### `apps/pwa/src/api/listsClient.ts` (utility, request-response)
+
+**Analog:** `apps/pwa/src/api/client.ts` lines 1–53 (full pattern above).
+
+**Imports + credential pattern**:
+```typescript
+// credentials: 'include' on every fetch — session cookie required (same as client.ts)
+const BASE = '/api'
+
+async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(`${BASE}${path}`, {
+    credentials: 'include',
+    ...init,
+  })
+  if (!res.ok) throw new Error(`${init?.method ?? 'GET'} ${path} failed: ${res.status}`)
+  return res
+}
+```
+
+**Type + function pattern** (mirrors client.ts):
+```typescript
+export interface List {
+  id: number
+  name: string
+  isShared: boolean
+  ownerId: number
+}
+
+export interface ListItem {
+  id: number
+  listId: number
+  text: string
+  checked: boolean
+  rank: string
+}
+
+export async function fetchLists(): Promise<{ lists: List[] }> {
+  return apiFetch('/lists').then((r) => r.json())
+}
+
+export async function createList(payload: { name: string; isShared: boolean }): Promise<{ id: number }> {
+  return apiFetch('/lists', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  }).then((r) => r.json())
+}
+
+export async function patchListItem(
+  itemId: number,
+  patch: { checked?: boolean } | { text: string } | { position: string },
+): Promise<void> {
+  await apiFetch(`/list-items/${itemId}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(patch),
+  })
+}
+```
+
+---
+
+### `apps/pwa/src/store/listsStore.ts` (store, request-response)
+
+**Analog:** `apps/pwa/src/store/calendarStore.ts` lines 1–89 (full file above).
+
+**Imports + create pattern** (lines 26–27 of calendarStore.ts):
+```typescript
+import { create } from 'zustand'
+
+export interface ListsStore {
+  // UI-only state — no server data
+  activeTab: 'calendar' | 'lists'
+  createListSheetOpen: boolean
+  // ...
+
+  setActiveTab: (tab: 'calendar' | 'lists') => void
+  setCreateListSheetOpen: (open: boolean) => void
+}
+
+export const useListsStore = create<ListsStore>()((set) => ({
+  activeTab: 'calendar',
+  createListSheetOpen: false,
+  setActiveTab: (tab) => set({ activeTab: tab }),
+  setCreateListSheetOpen: (open) => set({ createListSheetOpen: open }),
+}))
+```
+
+Convention from calendarStore.ts: no `persist` middleware used in this project — state is ephemeral (view persistence done manually with localStorage in calendarStore; lists UI state does not need persistence).
+
+---
+
+### `apps/pwa/src/routes/ListsIndex.tsx` (component, CRUD)
+
+**Analog:** `apps/pwa/src/components/CalendarShell.tsx` lines 1–60 (header shown above).
+
+**Data fetching pattern** — useQuery with credentials (from CalendarShell + client.ts):
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { fetchLists, createList, deleteList } from '../api/listsClient.js'
+
+const { data, isLoading, isError } = useQuery({
+  queryKey: ['lists'],
+  queryFn: fetchLists,
+})
+```
+
+**State branches** — mirror CalendarShell: `isLoading` → skeleton/empty, `isError` → error state with retry, `data` → render list. CalendarShell uses `isLoading` / `isError` / success branches explicitly.
+
+**useMutation with optimistic update** (from RESEARCH.md Finding 6):
+```tsx
+const queryClient = useQueryClient()
+
+const deleteMutation = useMutation({
+  mutationFn: (listId: number) => deleteList(listId),
+  onMutate: async (listId) => {
+    await queryClient.cancelQueries({ queryKey: ['lists'] })
+    const previous = queryClient.getQueryData(['lists'])
+    queryClient.setQueryData(['lists'], (old: any) => ({
+      ...old,
+      lists: old.lists.filter((l: any) => l.id !== listId),
+    }))
+    return { previous }
+  },
+  onError: (_err, _vars, context) => {
+    if (context?.previous) queryClient.setQueryData(['lists'], context.previous)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['lists'] })
+  },
+})
+```
+
+**DeleteConfirmationDialog reuse** — import from `../components/DeleteConfirmationDialog.js` and render conditionally. The existing dialog is tightly coupled to `calendarStore`; create a new list-delete confirmation component (`ListDeleteDialog`) that mirrors its structure but is driven by `listsStore`. Do NOT modify the existing dialog — it is stable (D-06 says reuse, but the implementation is wired to calendarStore).
+
+---
+
+### `apps/pwa/src/routes/ListDetail.tsx` (component, CRUD + event-driven)
+
+**Analog:** `apps/pwa/src/components/CalendarShell.tsx`
+
+**SSE + polling pattern** (from RESEARCH.md Finding 4):
+```tsx
+import { useListSSE } from '../hooks/useListSSE.js'
+
+const { data } = useQuery({
+  queryKey: ['list', listId],
+  queryFn: () => fetchListItems(listId),
+  refetchInterval: 30_000, // D-12: polling fallback always active
+})
+
+useListSSE({ listId, onStateChange: setSyncState })
+```
+
+**Active / completed section split** (D-05):
+```tsx
+const activeItems = items.filter((i) => !i.checked).sort(/* by rank ASC */)
+const completedItems = items.filter((i) => i.checked)
+```
+
+---
+
+### `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (reuse — no modification)
+
+**This file is not modified.** A new `ListDeleteDialog.tsx` mirrors its structure:
+- Same modal layout: fixed backdrop + centered dialog
+- Same CSS tokens: `var(--color-overlay)`, `var(--color-surface-raised)`, `var(--color-destructive)`, `var(--space-*)`, `var(--text-*)`, `var(--font-family-base)`
+- Same `useMutation` + `onSuccess` → close pattern (lines 64–76 of DeleteConfirmationDialog.tsx)
+- Same accessibility: `role="dialog"`, `aria-modal="true"`, Escape key listener, `tabIndex={-1}` + focus on open
+
+Key lines to copy for the modal skeleton (lines 86–208 of DeleteConfirmationDialog.tsx) — swap the heading text to "Delete list?" and the body text to "All items in this list will be permanently deleted."
+
+---
+
+### `apps/pwa/src/components/ItemRow.tsx` (component, event-driven)
+
+**Analog:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (for mutation + CSS token patterns)
+
+**dnd-kit drag handle pattern** (from RESEARCH.md Finding 7):
+```tsx
+import { useSortable } from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { GripVertical } from 'lucide-react'
+
+export function ItemRow({ item, onCheck, onDelete }) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } =
+    useSortable({ id: item.id })
+
+  return (
+    <div
+      ref={setNodeRef}
+      style={{
+        transform: CSS.Transform.toString(transform),
+        transition: transition ?? 'transform 150ms ease-out', // D-14: animate remote reorders
+        opacity: isDragging ? 0.8 : 1,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--space-2)',
+        minHeight: '44px', // touch target
+      }}
+      {...attributes}
+    >
+      {/* Drag handle — listeners on handle only (not whole row) */}
+      <button
+        {...listeners}
+        aria-label="Drag to reorder"
+        style={{ background: 'none', border: 'none', cursor: 'grab', padding: 'var(--space-1)' }}
+      >
+        <GripVertical size={16} color="var(--color-text-secondary)" />
+      </button>
+      {/* ... checkbox, text, delete button */}
+    </div>
+  )
+}
+```
+
+---
+
+### `apps/pwa/src/hooks/useListSSE.ts` (hook, event-driven)
+
+**No codebase analog.** Use the pattern from RESEARCH.md Finding 4 verbatim. Key conventions:
+- `useCallback` for `connect` to keep the `useEffect` dependency stable
+- `esRef`, `attemptsRef`, `timerRef` — all `useRef` (not state) to avoid re-render loops
+- Close `es` on error before scheduling retry (prevents browser auto-reconnect stacking with manual reconnect)
+- `withCredentials: true` on `new EventSource(...)` — required for session cookie (Pitfall 7)
+- Return `syncState` so the caller can render `LiveSyncIndicator`
+
+---
+
+## Shared Patterns
+
+### Auth / User Resolution
+**Source:** `apps/api/src/routes/events.ts` lines 59–76
+**Apply to:** `apps/api/src/routes/lists.ts`
+```typescript
+async function resolveUserId(c: any): Promise<number | null> {
+  const devUser = c.get('user') as { id: number } | undefined
+  if (devUser) return devUser.id
+
+  const auth = await getAuth(c)
+  if (!auth) return null
+
+  const iss = (auth.iss as string | undefined) ?? ''
+  const sub = auth.sub ?? ''
+  const displayName = deriveDisplayName(auth)
+  const user = await upsertUser(iss, sub, displayName)
+  return user?.id ?? null
+}
+```
+Copy verbatim — do not extract to a shared module (existing convention duplicates this per router).
+
+### Error Handling (API routes)
+**Source:** `apps/api/src/routes/events.ts` (every handler's catch block)
+**Apply to:** `apps/api/src/routes/lists.ts`
+```typescript
+try {
+  // ... db operations ...
+  return c.json({ /* result */ })
+} catch (err) {
+  console.error('[lists/<endpoint>] DB operation failed:', err)
+  return c.json({ error: 'Service unavailable' }, 503)
+}
+```
+Pattern: 503 on caught exceptions, not 500. `console.error` with a `[module/endpoint]` prefix tag.
+
+### 401 Guard Pattern
+**Source:** `apps/api/src/routes/events.ts` (every handler, lines 125–126):
+```typescript
+const currentUserId = await resolveUserId(c)
+if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
+```
+First two lines of every protected handler.
+
+### CSS Token Usage (PWA components)
+**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (all inline styles)
+**Apply to:** all new PWA components
+Token set in use:
+- `var(--color-surface)`, `var(--color-surface-raised)`, `var(--color-overlay)`
+- `var(--color-text-primary)`, `var(--color-text-secondary)`
+- `var(--color-destructive)`, `var(--color-border)`
+- `var(--space-1)` through `var(--space-6)`
+- `var(--text-body-size)`, `var(--text-heading-size)`, `var(--text-label-size)`, `var(--font-family-base)`
+- Minimum touch target: `minHeight: '44px'` (buttons/rows)
+
+### Fetch with Credentials (PWA API client)
+**Source:** `apps/pwa/src/api/client.ts` lines 36–39
+**Apply to:** `apps/pwa/src/api/listsClient.ts`
+```typescript
+const res = await fetch('/api/...', {
+  credentials: 'include',
+  redirect: 'manual', // only for /api/me; not required for data endpoints
+})
+```
+All list API calls use `credentials: 'include'`. `redirect: 'manual'` is only needed for the initial session check (`/api/me`) — not for list CRUD endpoints.
+
+### TanStack Query Keys
+**Apply to:** `apps/pwa/src/routes/ListsIndex.tsx`, `apps/pwa/src/routes/ListDetail.tsx`
+```typescript
+// List of lists
+queryKey: ['lists']
+
+// Items for a specific list
+queryKey: ['list', listId]  // listId is a number
+```
+Invalidate `['lists']` after create/delete list. Invalidate `['list', listId]` after any item mutation or SSE event for that list.
+
+### Lucide Icons (PWA)
+**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` line 27, CalendarShell.tsx line 43
+**Apply to:** all new PWA components
+```tsx
+import { Trash2 } from 'lucide-react'
+// Usage: <Trash2 size={16} aria-hidden="true" />
+```
+Always pass `aria-hidden="true"` to decorative icons. Use `size={16}` for inline/dense contexts, `size={22}` for navigation tabs.
+
+### Zustand Store Shape
+**Source:** `apps/pwa/src/store/calendarStore.ts`
+**Apply to:** `apps/pwa/src/store/listsStore.ts`
+- Use `create<StoreInterface>()((set) => ({ ... }))` — no `persist`, no `immer`
+- Actions are inline setter functions, not separate files
+- UI-only state: no server data, no async in store actions (mutations live in components via `useMutation`)
+
+### Plain-text XSS Guard (PWA)
+**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (comment `/* Plain text — XSS guard */` on every text node, line 133 etc.)
+**Apply to:** all new PWA components that render user-supplied strings (list names, item text)
+Never use `dangerouslySetInnerHTML`. All user content is a JSX text child.
+
+---
+
+## No Analog Found
+
+| File | Role | Data Flow | Reason |
+|------|------|-----------|--------|
+| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | No EventEmitter or pub/sub pattern exists in the codebase. Use RESEARCH.md Finding 1 pattern. |
+| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | No live-sync state indicator exists. Novel UI component — use CSS token conventions and the "disconnected / updates paused" UX from D-11. |
+| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | No custom hooks exist in the codebase. Novel — use RESEARCH.md Finding 4 pattern. |
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/api/src/routes/`, `apps/api/src/db/`, `apps/api/src/lib/`, `apps/api/src/index.ts`, `apps/pwa/src/`, `apps/pwa/src/components/`, `apps/pwa/src/api/`, `apps/pwa/src/store/`
+**Files scanned:** 12 source files read in full
+**Pattern extraction date:** 2026-06-09

.planning/phases/04-shared-lists-live-sync/04-UI-SPEC.md

@@ -0,0 +1,476 @@
+---
+phase: 4
+slug: shared-lists-live-sync
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-06-09
+---
+
+# Phase 4 — UI Design Contract
+
+> Visual and interaction contract for the Shared Lists + Live Sync phase.
+> Generated by gsd-ui-researcher. Verified by gsd-ui-checker.
+>
+> **Design approach:** Extend the established token system from `apps/pwa/src/styles/tokens.css`
+> without reinventing it. The lists surface must feel like a first-class sibling of the calendar —
+> same font, same spacing scale, same surface/border/text palette.
+
+---
+
+## Design System
+
+| Property | Value | Source |
+|----------|-------|--------|
+| Tool | none (custom CSS token layer) | tokens.css — established Phase 2 |
+| Preset | not applicable | — |
+| Component library | none (hand-built inline-style React components) | existing pattern |
+| Icon library | lucide-react 1.17.0 | package.json |
+| Font | system-ui / -apple-system stack | `--font-family-base` in tokens.css |
+
+**shadcn gate result:** `components.json` not found. Project uses a custom CSS custom-property token
+system (`apps/pwa/src/styles/tokens.css`). This is an established pattern across all Phase 2–3
+components. Do NOT introduce shadcn or any Radix primitives in Phase 4 — extend the existing
+token system and inline-style component convention.
+
+---
+
+## Spacing Scale
+
+Declared values — multiples of 4px only. Inherited from `tokens.css`; do not declare new tokens.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--space-1` | 4px | Icon gaps, badge padding, inline micro-gaps |
+| `--space-2` | 8px | Compact padding (chip inner padding, tight row gaps) |
+| `--space-3` | 12px | Dialog inner spacing, button horizontal padding |
+| `--space-4` | 16px | Default horizontal padding (list cards, input fields) |
+| `--space-6` | 24px | Section gaps, card padding top/bottom |
+| `--space-8` | 32px | Layout gap between list cards |
+| `--space-12` | 48px | Empty-state vertical padding, bottom-tab-bar height |
+
+**Exceptions:**
+- Touch targets: minimum 44px height/width on all interactive elements (tap targets, checkboxes,
+  drag handles, delete buttons). This is a hard constraint for the non-technical Apple member.
+- Bottom tab bar: 56px height on phone (aligns with iOS safe-area; provides 44px touch target with
+  padding). Use `env(safe-area-inset-bottom)` to push content above the home indicator.
+- FAB ("New List"): 56px diameter on phone.
+- Checkbox tap area: 44px × 44px min; visual checkbox can be 20px × 20px centered inside.
+
+---
+
+## Typography
+
+Inherited from `tokens.css`. Use existing CSS custom properties — no new sizes.
+
+| Role | Token | Size | Weight | Line Height | Usage in Lists |
+|------|-------|------|--------|-------------|----------------|
+| Body | `--text-body-*` | 15px | 400 | 1.5 | Item text (active and completed), list description, confirmation body |
+| Label | `--text-label-*` | 13px | 400 | 1.4 | Item metadata, "Completed" section header, badge counts, tab labels, timestamp |
+| Heading | `--text-heading-*` | 18px | 600 | 1.25 | List name (in list detail), dialog heading ("Delete list?"), section separator |
+| Display | `--text-display-*` | 24px | 600 | 1.2 | App name in AppNav (no change); NOT used inside list surfaces |
+
+**Weight contract:** 400 (regular) and 600 (semibold) only. No 500 or 700.
+
+**Completed items:** render at body size/weight but at `--color-text-muted` color with
+`text-decoration: line-through`. Do NOT reduce font size for completed items.
+
+---
+
+## Color
+
+Inherited palette from `tokens.css`. No new hex values introduced in Phase 4.
+
+| Role | Token / Value | Usage |
+|------|---------------|-------|
+| Dominant (60%) | `--color-surface` `#FFFFFF` | App background, list-detail content area, input backgrounds |
+| Secondary (30%) | `--color-surface-dim` `#F7F7F8` | List cards on the list index, completed-section background, bottom tab bar background |
+| Accent (10%) | `--color-member-0` `#4A90D9` | **Reserved exclusively for:** active tab indicator, FAB background, checkbox fill when checked, primary "Add Item" confirm button |
+| Destructive | `--color-destructive` `#DC2626` | List delete button, item delete button (if surfaced as icon), "Delete" in confirmation dialog — destructive actions only |
+
+**Accent reserved for (complete list — nothing else uses accent):**
+1. Active tab indicator (bottom tab bar selected state)
+2. FAB background ("New List" button on list index)
+3. Checked checkbox fill
+4. "Add item" primary action button background
+
+**Secondary semantic colors (non-accent, non-destructive):**
+- Live sync connected indicator: `--color-member-1` `#50C878` (green dot — reuses the
+  calendar's existing green; no new token needed)
+- Live sync disconnected indicator: `--color-destructive` `#DC2626` (reuses existing destructive)
+- Completed item text: `--color-text-muted` `#9CA3AF`
+- Drag handle: `--color-text-muted` `#9CA3AF`
+
+**Border, text, focus ring:** use existing `--color-border`, `--color-text-*`, `--color-focus-ring`
+tokens unchanged.
+
+---
+
+## Layout: App Shell Changes
+
+Phase 4 restructures `App.tsx` to add routing and a bottom tab bar (D-16, D-17).
+
+### Bottom Tab Bar (phone, ≤767px)
+
+```
+┌───────────────────────────────────────────────┐
+│  ┌─────────────────┐  ┌─────────────────────┐ │
+│  │   📅 Calendar   │  │     📋 Lists        │ │
+│  │   (tab label)   │  │    (tab label)      │ │
+│  └─────────────────┘  └─────────────────────┘ │
+└───────────────────────────────────────────────┘
+  height: 56px + env(safe-area-inset-bottom)
+  background: --color-surface-dim
+  border-top: 1px solid --color-border
+  active tab: icon + label in --color-member-0 (accent), underline 2px accent
+  inactive tab: icon + label in --color-text-muted
+```
+
+- Tab icons: `CalendarDays` (Calendar tab) and `List` (Lists tab) from lucide-react.
+- Tab labels: 13px / 400 / `--text-label-*`.
+- Active indicator: 2px bottom border on the tab in `--color-member-0`. Icon and label both take
+  accent color when active.
+- Touch target: full tab cell (≥44px height guaranteed by 56px bar).
+
+### Desktop / Tablet (≥768px) — Left Sidebar Navigation
+
+On desktop the existing `AppNav` sidebar (240px) gains a "Lists" nav link below "Calendars".
+No bottom tab bar on desktop. Use `react-router` `<NavLink>` for both Calendar and Lists links.
+
+### Routing (D-17)
+
+| Path | Component |
+|------|-----------|
+| `/` or `/calendar` | `CalendarShell` (existing) |
+| `/lists` | `ListsIndex` — lists overview |
+| `/lists/:listId` | `ListDetail` — single list items |
+
+`react-router` `<BrowserRouter>` wraps `App.tsx`. Back button and PWA deep-links must work.
+
+---
+
+## Component Inventory
+
+### New Components for Phase 4
+
+All components follow the established inline-style pattern (no Tailwind, no CSS modules, no
+shadcn). All text rendered as plain-text JSX children — no `dangerouslySetInnerHTML`.
+
+#### `BottomTabBar`
+
+```
+props: { activeTab: 'calendar' | 'lists' }
+layout: fixed bottom, full-width, 56px + safe-area-inset-bottom
+background: --color-surface-dim
+border-top: 1px solid --color-border
+tabs: 2 equal-width flex items, each min 44px height
+icon size: 22px (lucide-react)
+label size: --text-label-* (13px/400)
+active: accent color + 2px top border-bottom on tab cell
+inactive: --color-text-muted
+z-index: 200 (below dialogs at 300)
+```
+
+#### `ListsIndex`
+
+```
+layout: full-height scrollable column with 16px horizontal padding
+header: "Lists" heading (--text-display-* on desktop; --text-heading-* on phone)
+        + FAB ("+ New List") in top-right corner
+list of cards: ListCard components in vertical stack, gap --space-4
+empty state: ListsEmptyState component (see Copywriting)
+FAB position: phone — fixed bottom-right above tab bar, 56px circle, --color-member-0 bg
+              desktop — top-right inline button, not FAB
+```
+
+#### `ListCard`
+
+```
+layout: rounded card, padding --space-4 --space-6, background --color-surface
+        border: 1px solid --color-border
+        border-radius: --space-2 (8px)
+        box-shadow: 0 1px 3px rgba(0,0,0,0.06)
+content:
+  - List name: --text-heading-* (18px/600), --color-text-primary
+  - Item count badge: "N items" or "N active · M done" at --text-label-* / --color-text-muted
+  - Sharing indicator: "Shared" pill (--color-surface-dim bg, --color-text-secondary text,
+    --space-1 --space-2 padding) or nothing for private
+  - Chevron right: lucide ChevronRight 16px, --color-text-muted, right edge
+  - Long-press / swipe-reveal on phone: reveal "Delete" button (--color-destructive)
+  - Tap: navigates to /lists/:listId
+touch target: min 56px row height
+```
+
+#### `ListDetail`
+
+```
+layout: full-height flex column
+header row: back arrow (ChevronLeft 20px) + list name (--text-heading-*) + kebab menu (MoreVertical)
+            Sharing badge: "Shared" or "Private" pill next to list name
+active items section: scrollable list of ItemRow components
+completed section: collapsible section header "Completed (N)" at --text-label-* / --color-text-muted
+                   collapses/expands on tap; completed ItemRow components below
+live sync indicator: top-right or header-right area — small colored dot (8px) +
+                     "Live" label at --text-label-* or "Disconnected" on backoff-exhaust
+add-item input: sticky bottom input above keyboard — full-width text input + "Add" button
+                (see Input Contract below)
+```
+
+#### `ItemRow`
+
+```
+layout: horizontal flex, min 44px height, padding --space-2 --space-4
+left: checkbox (20px visual, 44px touch area) — unchecked: --color-border ring;
+      checked: --color-member-0 fill, checkmark in white
+center: item text — body size/weight for active; body size + line-through + --color-text-muted
+        for completed
+right: drag handle (GripVertical 16px, --color-text-muted) — only on active items
+       hidden on completed items (completed items not reorderable)
+delete: swipe-left reveals red delete zone on phone; hover shows X button on desktop
+        individual item delete is instant — no confirmation (D-06)
+optimistic: item appears immediately on add; briefly dims (opacity 0.6) while server confirms;
+            rolls back (removes) if server rejects
+drag-active: 4px drop-target line indicator between rows (--color-member-0);
+             dragged item shows 0.8 opacity with slight scale-down (0.98)
+```
+
+#### `AddItemInput`
+
+```
+position: sticky bottom of ListDetail, above keyboard on mobile
+layout: horizontal flex — text input (flex:1) + "Add" button
+input: --text-body-*, background --color-surface, border 1px --color-border,
+       border-radius --space-1, padding --space-2 --space-4, min-height 44px
+       placeholder: "Add an item…"
+       focus: border-color --color-focus-ring, outline none (custom ring)
+button: "Add" label, background --color-member-0, color #fff,
+        --text-label-* / weight 600, border-radius --space-1,
+        min-height 44px, padding 0 --space-4
+        disabled (empty input): opacity 0.5, cursor not-allowed
+submit: Enter key OR tap "Add" button
+```
+
+#### `ListsEmptyState`
+
+```
+center-aligned in the list-index scrollable area
+icon: ClipboardList (lucide-react, 32px, --color-text-muted)
+heading: "No lists yet"  (--text-heading-* / --color-text-primary)
+body: "Tap + to create your first shared list — Groceries, Gift Ideas, or anything else."
+      (--text-body-* / --color-text-muted, max-width 280px)
+```
+
+#### `ListEmptyState` (used inside ListDetail when list has no items)
+
+```
+center-aligned in items area
+icon: ListPlus (lucide-react, 32px, --color-text-muted)
+heading: "Nothing here yet"  (--text-heading-*)
+body: "Add your first item below."  (--text-body-* / --color-text-muted)
+```
+
+#### `CreateListSheet` (new list creation)
+
+```
+mobile: bottom sheet — slides up from bottom, 50vh height, backdrop overlay
+desktop: inline modal — centered, max-width 360px
+content:
+  - Heading: "New list" (--text-heading-*)
+  - Name input: required, --text-body-*, placeholder "e.g. Groceries"
+  - Sharing toggle: "Shared" (default) / "Private" — segmented control or toggle
+    shared = default (D-01), clearly labeled
+  - "Create" button: full-width, --color-member-0 bg, white text, 48px height
+  - Cancel: ghost text button above or below Create
+focus: Name input auto-focuses on sheet open
+validation: "Create" disabled while name is empty; no inline error until submit attempt
+            if blank submit attempted: input border turns --color-destructive, no toast
+```
+
+#### `LiveSyncIndicator`
+
+```
+position: right end of ListDetail header row
+states:
+  connected: 8px filled circle in --color-member-1 (#50C878), no label (accessible via aria-label)
+  reconnecting: 8px pulsing circle in --color-text-muted + "Reconnecting…" label at --text-label-*
+  disconnected: 8px filled circle in --color-destructive + "Updates paused" label at --text-label-*
+aria-label: "Live sync connected" / "Reconnecting" / "Updates paused — tap to retry"
+visible: only inside ListDetail (not on ListsIndex)
+```
+
+---
+
+## Interaction Contracts
+
+### Drag-to-Reorder (LIST-03, D-13)
+
+- **Library:** `@dnd-kit/core` + `@dnd-kit/sortable` (install in Phase 4; not yet in package.json).
+  Do NOT use `react-beautiful-dnd` (deprecated). Do NOT use HTML5 drag API directly (poor mobile).
+- Drag handle: `GripVertical` lucide icon (16px), visible at all times in active-item rows.
+  Touch: drag initiates after 200ms long-press on the handle; prevents accidental drags.
+  Mouse: drag initiates on mousedown on the handle immediately.
+- During drag: dragged item floats with `box-shadow: 0 4px 12px rgba(0,0,0,0.15)`, opacity 0.9.
+  Drop target gap: 3px line in `--color-member-0` renders between candidate drop positions.
+- On drop: optimistic reorder (item snaps to new position immediately). PATCH `/api/list-items/:id`
+  with new fractional rank. On server rejection: animate item back to original position.
+- Completed items: no drag handle, not reorderable. Only active items have drag affordance.
+- Remote reorder (D-14): when an SSE event carries a position change, animate the affected item
+  sliding to its new position using a CSS transition (`transform` 150ms ease-out).
+  Do NOT hard-snap remote reorders — animate them.
+
+### Optimistic Updates (D-07)
+
+- Add item: item appears immediately at bottom of active list, with a loading state (opacity 0.6).
+  Snaps to full opacity on server confirm. Rolls back (removes with a brief flash) on rejection.
+- Check off item: item moves immediately to completed section with animation (height collapse in
+  active list, height expand in completed section). CSS transition 200ms ease. Rolls back on
+  server rejection.
+- Reorder: immediate snap to new order as described above.
+- Delete item: item disappears immediately. No rollback — delete-wins (D-09).
+
+### Checked-Off Sink Behavior (D-05)
+
+- Active items occupy the top section, ordered by fractional rank.
+- On check: item animates from active section → completed section.
+  Animation: height-collapse from active (200ms) + height-expand into completed (200ms staggered).
+  The `completed` section is always present at bottom; its header shows count ("Completed (3)").
+- On uncheck: reverses — item moves from completed → top of active section (append to bottom of
+  active, not restored to original rank position).
+- The completed section header is a tappable toggle to collapse/expand the completed list.
+  Default state: expanded.
+
+### Live Sync + Reconnect (D-10, D-11, D-12)
+
+- SSE connection established on mount of `ListDetail`. One SSE stream per user session.
+  Events scoped to lists the member has access to (D-04 — no leakage of other members' private lists).
+- On SSE event received: `queryClient.invalidateQueries({ queryKey: ['list', listId] })` triggers
+  a background refetch. Do NOT patch local cache manually — full refetch is the reconciliation
+  strategy (D-10).
+- Reconnect backoff: `250ms → 500ms → 1000ms → 2000ms → 4000ms → cap 8000ms`.
+  Silent during backoff — no indicator while attempts remain.
+  After backoff exhausted (≥6 failed attempts): show `LiveSyncIndicator` "Updates paused" state.
+  React Query `refetchInterval: 30000` (D-12 polling fallback) activates when SSE disconnects.
+- On reconnect: full refetch of active list(s), clear "Updates paused" indicator, show brief
+  "Connected" indicator (2s flash of green dot), return to normal state.
+- SSE stream auth: inherited from existing `/api/*` OIDC middleware — same auth as all other routes.
+
+### List Delete (D-06)
+
+- Trigger: kebab menu (MoreVertical) → "Delete list" option in `ListDetail` header.
+  OR: swipe-reveal "Delete" button on `ListCard` in `ListsIndex`.
+- Dialog: reuse `DeleteConfirmationDialog` pattern (same layout, backdrop, focus trap).
+  Heading: "Delete list?"
+  Body: ""{list name}" and all its items will be permanently removed."
+  Buttons: "Cancel" (ghost) + "Delete" (destructive, `--color-destructive` bg).
+- On confirm: optimistic — navigate back to `/lists` immediately, list card disappears.
+  On server rejection (rare): toast "Couldn't delete. Try again." (same toast pattern as SyncStateToast).
+
+### Item Delete (D-06 — no confirmation for individual items)
+
+- Phone: swipe-left on `ItemRow` reveals a red delete zone (full row height, `--color-destructive`
+  background, white "Delete" label or `Trash2` icon). Tap the zone to delete. Swipe right or tap
+  elsewhere to cancel reveal.
+- Desktop: hover on `ItemRow` reveals a `Trash2` button (16px, `--color-destructive`) at right edge.
+  Click to delete immediately.
+- No confirmation dialog. Delete is instant and final (delete-wins, D-09).
+
+### Sharing Toggle (D-01, D-02)
+
+- Inside `CreateListSheet` and accessible via `ListDetail` kebab menu → "Edit list".
+- Two-state toggle: "Shared" (default) | "Private".
+- Visual: segmented control or labeled toggle — "Shared" selected by default, clearly labeled.
+- Shared lists show a "Shared" pill badge on `ListCard`. Private lists show nothing.
+- v1 only: "Shared" means shared with all other household members (no per-recipient picker).
+
+---
+
+## Copywriting Contract
+
+| Element | Copy | Source |
+|---------|------|--------|
+| Primary CTA (new list) | "New List" (FAB label + sheet heading "New list") | D-01, default |
+| Primary CTA (add item) | "Add" (button in AddItemInput) | D-02, default |
+| Lists tab label | "Lists" | D-16, default |
+| Calendar tab label | "Calendar" | D-16, default |
+| Lists index empty heading | "No lists yet" | default |
+| Lists index empty body | "Tap + to create your first shared list — Groceries, Gift Ideas, or anything else." | REQUIREMENTS LIST-01 + default |
+| List detail empty heading | "Nothing here yet" | default |
+| List detail empty body | "Add your first item below." | default |
+| Add item placeholder | "Add an item…" | default |
+| New list name placeholder | "e.g. Groceries" | default |
+| Completed section header | "Completed ({N})" | D-05 |
+| List delete dialog heading | "Delete list?" | D-06, matches Phase 3 pattern |
+| List delete dialog body | ""{list name}" and all its items will be permanently removed." | D-06 |
+| List delete confirm button | "Delete" | D-06, matches Phase 3 pattern |
+| Item delete (swipe zone) | "Delete" | D-06, default |
+| Live sync connected | aria-label: "Live sync connected" (no visible label) | D-11 |
+| Live sync reconnecting | "Reconnecting…" | D-11 |
+| Live sync disconnected | "Updates paused" | D-11 per CONTEXT.md "backoff-then-pause" |
+| SSE error toast | "Couldn't load updates. Retrying…" | D-12 |
+| List delete failure toast | "Couldn't delete. Try again." | D-06, matches SyncStateToast pattern |
+| "Shared" sharing badge | "Shared" | D-01 |
+| Create list button | "Create" | default |
+| Sharing toggle labels | "Shared" / "Private" | D-01 |
+| New list sheet cancel | "Cancel" | default, matches Phase 3 pattern |
+
+**Destructive action confirmation matrix:**
+
+| Action | Confirmation approach |
+|--------|-----------------------|
+| Delete a whole list | `DeleteConfirmationDialog` modal — explicit two-tap confirmation (D-06) |
+| Delete an individual item | Instant on swipe-confirm / click — no dialog (D-06) |
+
+---
+
+## Registry Safety
+
+No shadcn registry initialized. Registry safety gate: not applicable.
+
+| Package | Source | Safety Note |
+|---------|--------|-------------|
+| `@dnd-kit/core` + `@dnd-kit/sortable` | npm (open source, MIT) | New dependency; add to `apps/pwa/package.json`. No third-party registry. Standard npm vetting applies. |
+| `react-router` (v7.x) | npm (open source, MIT) | New dependency for D-17 routing. No third-party registry. |
+| All other libs | Existing in package.json | No change |
+
+---
+
+## Accessibility Baseline
+
+All new components must meet these minimums (consistent with Phase 2–3 patterns):
+
+| Requirement | Specification |
+|-------------|---------------|
+| Touch targets | min 44px × 44px on ALL tappable elements |
+| Focus ring | visible on all interactive elements; use `--color-focus-ring` (#4A90D9) |
+| Keyboard nav | Tab order follows DOM order; dialogs trap focus; Escape closes dialogs/sheets |
+| ARIA roles | `role="dialog"` + `aria-modal="true"` on sheets/dialogs; `role="list"` + `role="listitem"` on item lists |
+| Drag-and-drop | Keyboard reorder fallback via arrow keys (dnd-kit provides this); ARIA announcement on drop |
+| Live regions | `role="status"` for sync indicator changes; `role="alert"` for disconnected state |
+| Empty states | `aria-live="polite"` on the list container so screen readers announce when items arrive |
+| Checkboxes | `role="checkbox"`, `aria-checked`, `aria-label` with item text |
+
+---
+
+## Security Notes
+
+Consistent with Phase 3 threat model:
+
+| Threat | Control |
+|--------|---------|
+| XSS via list/item names | All list names and item text rendered as plain-text JSX children — no `dangerouslySetInnerHTML` |
+| SSE fan-out leak | Server MUST scope SSE events to members with list access (D-04); never broadcast to all connections |
+| Delete-without-auth | All list/item routes behind OIDC middleware; identity resolved from session, not client payload |
+| Private list leakage | `GET /api/lists` returns only lists owned by or shared with the current member |
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

.planning/phases/04-shared-lists-live-sync/04-VALIDATION.md

@@ -0,0 +1,85 @@
+---
+phase: 4
+slug: shared-lists-live-sync
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-06-09
+---
+
+# Phase 4 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+> Source: `04-RESEARCH.md` §"Validation Architecture".
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Vitest ^4.1.8 (existing) |
+| **Config file** | `apps/api/vitest.config.ts` + `apps/pwa/vitest.config.ts` (existing) |
+| **Quick run command** | `pnpm --filter @familysync/api test` / `pnpm --filter @familysync/pwa test` |
+| **Full suite command** | `pnpm test` (root, all workspaces) |
+| **Estimated runtime** | ~TBD seconds (planner to confirm) |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run the relevant workspace quick command (`pnpm --filter @familysync/api test` or `… pwa test`)
+- **After every plan wave:** Run `pnpm test`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** TBD seconds
+
+---
+
+## Per-Task Verification Map
+
+> Planner fills this from the Phase Requirements → Test Map in `04-RESEARCH.md`.
+> Seed rows (from RESEARCH):
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 4-XX-XX | XX | X | LIST-01 | — | Create list inserts row + list_shares for shared | unit (API) | `pnpm --filter @familysync/api test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | LIST-01 | — | `GET /api/lists` returns only accessible lists (owner + shares) | unit (API) | `pnpm --filter @familysync/api test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | LIST-02 | — | PATCH `checked:true` updates only `checked` (per-field) | unit (API) | `pnpm --filter @familysync/api test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | LIST-03 | — | PATCH new rank produces correct fractional order | unit (API) | `pnpm --filter @familysync/api test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | LIST-04 | T-4-xx | Private-list events NOT emitted to non-owner subscriber | unit (API) | `pnpm --filter @familysync/api test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | D-11 | — | Bounded backoff hook exhausts after capped attempts | unit (PWA) | `pnpm --filter @familysync/pwa test` | ❌ W0 | ⬜ pending |
+| 4-XX-XX | XX | X | D-07 | — | Optimistic update rolls back on mutation error | unit (PWA) | `pnpm --filter @familysync/pwa test` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `apps/api/src/routes/lists.test.ts` — LIST-01/02/03/04 API behavior
+- [ ] `apps/api/src/lib/listEmitter.test.ts` — scoped fan-out correctness (D-04)
+- [ ] `apps/pwa/src/hooks/useListSSE.test.ts` — D-11 bounded backoff with mock EventSource
+- [ ] `apps/pwa/src/routes/ListDetail.test.tsx` — optimistic update + rollback (D-07)
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Cross-device live co-edit (one member's change appears for the other within seconds) | LIST-04 / success criterion 3 | Two-client real-time behavior over the deployed tunnel; better observed in a browser | Drive with `playwright-cli` (two contexts) where possible; iOS-Safari standalone behavior needs a device |
+
+*Drag-and-drop reorder (LIST-03) and SSE live sync should be validated in-browser via `playwright-cli` per project convention.*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency target set
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/06-ux-polish/.gitkeep

@@ -0,0 +1 @@
+

.planning/quick/260607-u8o-record-sse-over-pangolin-smoke-test-pass/260607-u8o-PLAN.md

@@ -0,0 +1,126 @@
+---
+phase: quick-260607-u8o
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+  - .planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+autonomous: true
+requirements: [D-14]
+
+must_haves:
+  truths:
+    - "01-HUMAN-UAT.md item 4 (SSE smoke) shows a PASS result note dated 2026-06-08"
+    - "01-HUMAN-UAT.md Summary shows passed:1 pending:3 (no longer passed:0)"
+    - "03-GATE2-RESULTS.md Part C row C1 shows a PASS marker dated 2026-06-08 with evidence"
+    - "03-GATE2-RESULTS.md Summary Part-C row shows PASS/CLEARED (no longer DEFERRED)"
+    - "No PENDING/DEFERRED/passed: 0 markers remain on any SSE row in either file"
+  artifacts:
+    - path: ".planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md"
+      provides: "Phase 1 UAT item 4 marked PASS"
+    - path: ".planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md"
+      provides: "Gate 2 Part C SSE row + summary marked PASS"
+  key_links: []
+---
+
+<objective>
+Record the SSE-over-Pangolin smoke test PASS in the two gate-tracking docs. This is the Phase 4 entry gate (D-14 / issue #1034), which was just executed live and PASSED. Documentation-only — no source changes.
+
+Purpose: Clear the Phase 4 entry gate so the Phase 4 planner/executor reads cleared gate docs.
+Output: Two updated markdown gate-tracking files reflecting the PASS with verbatim evidence.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+@.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+</context>
+
+<verbatim_evidence>
+Record these facts (do not embellish, do not overstate):
+
+- Endpoint: GET /api/sse/heartbeat over the public tunnel host `familysync-dev.bergerhouse.net` (Pangolin → Newt → api), with a valid authenticated session cookie.
+- Duration: stream held open continuously ~6 minutes (first event 2026-06-08T01:37:53Z, last observed 2026-06-08T01:43:54Z) before being terminated manually — well past the 5-minute bar.
+- Heartbeats: 35 `heartbeat` events received, id 0 → 34, at ~10s cadence (matches server sleep(10_000)).
+- Delivery: incremental/real-time (response bytes grew steadily 71 → 2535 as events arrived) → confirms Pangolin response buffering is OFF; not a buffered end-of-stream dump.
+- Result: no early cut by the proxy. PASS. Phase 4 entry gate (D-14 / issue #1034) is CLEARED.
+- Date executed: 2026-06-08.
+- Caveat: proves no idle-timeout cutoff and no buffering over ~6 min; does NOT prove the absence of a max total connection-duration cap. That residual risk is covered by the already-decided Phase 4 design (D-10 refetch-on-reconnect + D-11 capped-backoff reconnect + D-12 polling fallback in 04-CONTEXT.md) — no further infra work required to clear the gate.
+</verbatim_evidence>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Mark Phase 1 UAT item 4 (SSE smoke) as PASS</name>
+  <files>.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md</files>
+  <action>
+    Edit `.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md`:
+
+    1. In section "### 4. SSE-over-Pangolin smoke test (de-risks Phase 4)", change the line `result: [pending]` (the one belonging to item 4, immediately after the `expected:` line on/near line 30) to a PASS result that records the verbatim evidence. Use this form, preserving the file's `result:` field convention:
+
+       `result: PASS (2026-06-08) — GET /api/sse/heartbeat over familysync-dev.bergerhouse.net (Pangolin→Newt→api) with a valid session cookie held open ~6 min (01:37:53Z→01:43:54Z), 35 heartbeat events id 0→34 at ~10s cadence; response bytes grew 71→2535 (incremental delivery → Pangolin buffering OFF); no early cut. Phase 4 entry gate (D-14 / issue #1034) CLEARED. Caveat: proves no idle-timeout/buffering over ~6 min, not the absence of a max total connection-duration cap — residual risk covered by Phase 4 design (D-10/D-11/D-12 in 04-CONTEXT.md).`
+
+    2. Update the `## Summary` block: change `passed: 0` → `passed: 1` and `pending: 4` → `pending: 3`. Leave `total: 4`, `issues: 0`, `skipped: 0`, `blocked: 0` unchanged.
+
+    Do NOT touch items 1–3 (AUTH-01/02/03) or their `result: [pending]` lines. Preserve all existing Markdown formatting and front-matter.
+  </action>
+  <verify>
+    <automated>grep -n "PASS (2026-06-08)" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md && grep -qx "passed: 1" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md && grep -qx "pending: 3" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md && ! grep -qx "passed: 0" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md</automated>
+  </verify>
+  <done>Item 4 shows a PASS result note with the 2026-06-08 evidence; Summary reads passed:1 / pending:3; no passed:0 remains; items 1–3 unchanged.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Mark Gate 2 Part C SSE row + summary as PASS</name>
+  <files>.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md</files>
+  <action>
+    Edit `.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md`:
+
+    1. In "### Part C — SSE Smoke Test (Gate before Phase 4)", row C1 (currently `| C1 | SSE | Hold stream open 5+ min ... | [ ] PENDING — operator | |`): change the Result cell `[ ] PENDING — operator` to `✅ PASS (2026-06-08)` and fill the empty Notes cell with the evidence. Keep the table column structure (4 `|` separators, same Check text). Notes cell content:
+
+       `Held GET /api/sse/heartbeat open ~6 min over familysync-dev.bergerhouse.net (Pangolin→Newt→api) with a valid session cookie (01:37:53Z→01:43:54Z); 35 heartbeat events id 0→34 at ~10s cadence; response bytes grew 71→2535 (incremental → Pangolin buffering OFF); no early cut. Phase 4 entry gate (D-14 / issue #1034) CLEARED. Caveat: proves no idle-timeout/buffering over ~6 min, not the absence of a max total connection-duration cap — residual risk covered by Phase 4 design (D-10/D-11/D-12 in 04-CONTEXT.md).`
+
+    2. In the `## Summary` table at the bottom, change the row `| C — SSE smoke test | ⏳ DEFERRED — Phase 4 ENTRY gate (D-14), not a Phase 3 deliverable |` to `| C — SSE smoke test | ✅ PASS (2026-06-08) — Phase 4 ENTRY gate (D-14 / issue #1034) CLEARED; held ~6 min, 35 heartbeats, incremental delivery, no proxy cut |`.
+
+    Do NOT modify any other rows (A/B/D parts), the Header, the Gate 2 outcome paragraph, or any code fences. Preserve all Markdown formatting.
+  </action>
+  <verify>
+    <automated>grep -n "✅ PASS (2026-06-08)" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md | grep -E "C1|C — SSE" ; grep -c "✅ PASS (2026-06-08)" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md && ! grep -q "PENDING — operator" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md && ! grep -q "⏳ DEFERRED" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md</automated>
+  </verify>
+  <done>Part C row C1 and the Summary Part-C row both show PASS (2026-06-08) with evidence; no "PENDING — operator" or "⏳ DEFERRED" remains; all other rows and the outcome paragraph unchanged.</done>
+</task>
+
+</tasks>
+
+<verification>
+After both edits, confirm both files reflect the SSE PASS and no stale markers remain on SSE rows:
+
+```bash
+# Phase 1 UAT: PASS recorded, summary updated, no passed:0
+grep -q "passed: 1" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+! grep -qx "passed: 0" /home/luc/Projects/familysync/.planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+
+# Gate 2: no PENDING/DEFERRED on the SSE rows
+! grep -q "PENDING — operator" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+! grep -q "⏳ DEFERRED" /home/luc/Projects/familysync/.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+```
+
+Confirm NO changes were made to: 04-CONTEXT.md, ROADMAP.md, or any source code.
+</verification>
+
+<success_criteria>
+- 01-HUMAN-UAT.md item 4 marked PASS with 2026-06-08 evidence; Summary passed:1 / pending:3.
+- 03-GATE2-RESULTS.md Part C row C1 and Summary Part-C row marked PASS (2026-06-08) with evidence.
+- No PENDING/DEFERRED/passed:0 markers remain on any SSE row.
+- No other files touched; table structures and Markdown formatting preserved.
+</success_criteria>
+
+<output>
+Create `.planning/quick/260607-u8o-record-sse-over-pangolin-smoke-test-pass/260607-u8o-SUMMARY.md` when done.
+</output>

.planning/quick/260607-u8o-record-sse-over-pangolin-smoke-test-pass/260607-u8o-SUMMARY.md

@@ -0,0 +1,64 @@
+---
+phase: quick-260607-u8o
+plan: 01
+subsystem: planning-docs
+tags: [gate, sse, pangolin, phase-4-entry, documentation]
+requires: []
+provides:
+  - "Phase 1 UAT item 4 (SSE smoke) marked PASS"
+  - "Gate 2 Part C SSE row + summary marked PASS — Phase 4 entry gate (D-14) cleared"
+affects:
+  - .planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+  - .planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+tech-stack:
+  added: []
+  patterns: []
+key-files:
+  created: []
+  modified:
+    - .planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
+    - .planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
+decisions: []
+metrics:
+  duration_min: 3
+  completed: 2026-06-08
+  tasks: 2
+  files: 2
+---
+
+# Quick Task 260607-u8o: Record SSE-over-Pangolin Smoke Test PASS Summary
+
+Recorded the live SSE-over-Pangolin smoke test PASS (Phase 4 entry gate, D-14 / issue #1034) in the two gate-tracking docs, clearing the gate for Phase 4 planning.
+
+## What Was Done
+
+Documentation-only record-keeping. The SSE smoke test was executed live and PASSED; this task transcribes that result into the gate docs with verbatim evidence.
+
+- **Task 1** — `01-HUMAN-UAT.md`: item 4 (SSE-over-Pangolin smoke) changed from `result: [pending]` to a PASS (2026-06-08) note with full evidence; Summary updated `passed: 0 → 1`, `pending: 4 → 3`. Items 1–3 (AUTH-01/02/03) untouched.
+- **Task 2** — `03-GATE2-RESULTS.md`: Part C row C1 changed from `[ ] PENDING — operator` to `✅ PASS (2026-06-08)` with evidence in the Notes cell; Summary Part-C row changed from `⏳ DEFERRED` to `✅ PASS (2026-06-08)`. No other rows or the outcome paragraph touched.
+
+## Evidence Recorded (verbatim)
+
+- Endpoint: GET /api/sse/heartbeat over `familysync-dev.bergerhouse.net` (Pangolin → Newt → api) with a valid authenticated session cookie.
+- Duration: stream held open ~6 min (01:37:53Z → 01:43:54Z) before manual termination — past the 5-min bar.
+- Heartbeats: 35 `heartbeat` events, id 0 → 34, ~10s cadence.
+- Delivery: response bytes grew 71 → 2535 incrementally → Pangolin response buffering OFF (not a buffered end-of-stream dump).
+- Result: no early proxy cut. PASS. Phase 4 entry gate (D-14 / issue #1034) CLEARED.
+- Caveat (recorded, not overstated): proves no idle-timeout cutoff and no buffering over ~6 min; does NOT prove the absence of a max total connection-duration cap. That residual risk is covered by the already-decided Phase 4 design (D-10/D-11/D-12 in 04-CONTEXT.md).
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Verification
+
+- `passed: 1` present in 01-HUMAN-UAT.md; no `passed: 0` remains.
+- No `PENDING — operator` or `⏳ DEFERRED` markers remain in 03-GATE2-RESULTS.md.
+- Only the two intended files were modified (`git diff --name-only`); no source, no 04-CONTEXT.md, no ROADMAP.md.
+
+## Commits
+
+- dea6cb6: docs(260607-u8o): mark Phase 1 UAT item 4 (SSE smoke) PASS
+- 26655cf: docs(260607-u8o): mark Gate 2 Part C SSE row + summary PASS
+
+## Self-Check: PASSED

.planning/todos/pending/event-creation-reminder-options.md

@@ -1,34 +0,0 @@
----
-title: Add notification/reminder (VALARM) options to event creation
-date: 2026-06-07
-priority: medium
-phase_hint: Phase 5 (push) or earlier in Phase 03 write-path polish
----
-
-# Add notification/reminder options to event creation
-
-The event-create/edit form (`apps/pwa` EventForm → `POST /api/events`, `PATCH /:uid/edit`)
-has **no UI for setting a reminder/alarm on an event**. A user creating an event cannot
-choose "remind me 10 min / 1 hour / 1 day before". The written `.ics` therefore contains
-no `VALARM` component, so neither Fastmail's native clients nor any downstream notification
-path can fire an event reminder.
-
-This is distinct from (but feeds) the Active requirement
-"Web Push notifications for event reminders and list changes" (Phase 5): even with web-push
-infrastructure, there is nothing to notify *about* unless events carry reminder data.
-
-## Scope to decide when promoted
-
-- Add a reminder selector to EventForm (none / at time / 10m / 30m / 1h / 1d before; possibly
-  multiple).
-- Serialize chosen offsets as `VALARM` (TRIGGER) blocks in the iCalendar payload written
-  back to Fastmail via the outbox.
-- On read, parse existing `VALARM`s so edits preserve/show the current reminder.
-- Decide division of labour vs Phase 5 web-push: VALARM gives native-client reminders
-  (Fastmail/Apple Calendar) for free; app-delivered web-push reminders are the separate
-  Phase 5 piece that would read these offsets.
-
-## Open question
-
-- iCalendar `VALARM` round-trips through `ical.js`; confirm tsdav PUT preserves it and that
-  Fastmail honours `DISPLAY`/`AUDIO` alarms set by a third-party CalDAV client.

apps/api/src/auth/user.ts

@@ -8,22 +8,27 @@
  * Source: RESEARCH.md § "User upsert with color assignment"
  */
 
-import { and, eq, sql } from 'drizzle-orm'
+import { and, eq } from 'drizzle-orm'
 import { db } from '../db/client.js'
 import { users } from '../db/schema.js'
 
 /**
- * Accessible, visually-distinct palette for per-member color assignment.
- * Assigned round-robin by join order (COUNT of existing users at insert time).
+ * Accessible, visually-distinct palette for per-member member-color assignment.
+ * A new member is given the first entry not already in use (see upsertUser).
+ *
+ * Ordering matters: the SHARED-family calendar is reserved rose (#F25C7A, D-06),
+ * so the warm near-rose hues (coral, amber) are placed LAST. Early members get
+ * cool colors (blue, green, teal) that read clearly distinct from the shared
+ * lane — otherwise a member's coral was mistaken for the shared rose.
  * Values are Claude's choice per D-06.
  */
 export const COLOR_PALETTE: string[] = [
   '#4A90D9', // calm blue
-  '#E8734A', // warm coral
   '#5BA85A', // forest green
-  '#9B6DC5', // soft purple
-  '#E8A840', // warm amber
   '#3AAFA9', // teal
+  '#9B6DC5', // soft purple
+  '#E8A840', // warm amber  (near shared rose — assigned only after cool colors)
+  '#E8734A', // warm coral  (closest to shared rose — assigned last)
 ]
 
 /** Coerce an OIDC claim to a trimmed non-empty string, else undefined. */
@@ -35,22 +40,29 @@ const claimStr = (v: unknown): string | undefined =>
  *   1. name              — full name set by the IdP (most human-friendly)
  *   2. preferred_username — often the login handle; still readable
  *   3. email             — readable but reveals contact info; acceptable fallback
- *   4. `Member <sub>`    — sub is always present; never blank
+ *   4. null              — no usable claim; the UI degrades to a generic "Member"
+ *
+ * Returns null (NOT a synthetic `Member <sub>`) when no real claim is present so
+ * we never persist an ugly sub-derived string. Whether Authelia emits
+ * name/preferred_username/email in the ID TOKEN (not just at the userinfo
+ * endpoint) is an operator config concern: Authelia 4.39+ requires a
+ * `claims_policies` entry adding those claims to `id_token` for this client,
+ * because @hono/oidc-auth reads ID-token claims only (no userinfo fetch). Until
+ * that is set, every claim here is absent and the legend shows "Member".
  *
  * Shared by every call site that upserts a user (me.ts, events.ts resolveUserId)
- * so a write-path upsert never overwrites a correctly-derived name with a worse
- * one. Whether Authelia emits name/preferred_username is an operator config
- * concern (userinfo scope + claim mappings) — out of scope here.
+ * so the write-path upsert agrees with /api/me.
  */
-export function deriveDisplayName(
-  claims: { name?: unknown; preferred_username?: unknown; email?: unknown },
-  sub: string,
-): string {
+export function deriveDisplayName(claims: {
+  name?: unknown
+  preferred_username?: unknown
+  email?: unknown
+}): string | null {
   return (
     claimStr(claims.name) ??
     claimStr(claims.preferred_username) ??
     claimStr(claims.email) ??
-    `Member ${String(sub).slice(0, 8)}`
+    null
   )
 }
 
@@ -67,7 +79,7 @@ export function deriveDisplayName(
 export async function upsertUser(
   oidcIss: string,
   oidcSub: string,
-  displayName?: string,
+  displayName?: string | null,
 ) {
   // 1. Look up by composite identity key (iss + sub) — never email
   const existing = await db
@@ -77,9 +89,14 @@ export async function upsertUser(
     .limit(1)
 
   if (existing[0]) {
-    // If the existing row has no displayName but the caller supplies one, update it now.
-    // This corrects rows created before robust claim derivation was in place (BUG 2 fix).
-    if (!existing[0].displayName && displayName) {
+    // Track the IdP display name authoritatively: when the caller supplies a
+    // real (non-null) name that differs from what's stored, update it. This both
+    // corrects rows created before robust claim derivation (blank → name) and
+    // self-heals once an operator adds the name/email claims to Authelia's ID
+    // token (e.g. a stale "Member …"/email → the real name) — no DB surgery.
+    // A null displayName (no usable claim this request) never overwrites a good
+    // stored value.
+    if (displayName != null && displayName !== existing[0].displayName) {
       await db
         .update(users)
         .set({ displayName })
@@ -89,13 +106,18 @@ export async function upsertUser(
     return existing[0]
   }
 
-  // 2. Count existing users to determine round-robin color slot
-  const countResult = await db
-    .select({ count: sql<number>`COUNT(*)` })
-    .from(users)
-
-  const count = Number(countResult[0]?.count ?? 0)
-  const color = COLOR_PALETTE[count % COLOR_PALETTE.length]
+  // 2. Assign the first palette color NOT already in use by another member.
+  //    A plain COUNT(*) % palette collides under deletions: a deleted user
+  //    shifts the count so the next insert reuses an in-use slot (observed in
+  //    Gate 2 — two members both got #E8734A). Selecting the first unused color
+  //    guarantees distinct, stable colors for up to COLOR_PALETTE.length members
+  //    (AUTH-03). Falls back to round-robin by count only once the palette is
+  //    exhausted (more members than colors).
+  const usedRows = await db.select({ color: users.color }).from(users)
+  const usedColors = new Set(usedRows.map((r) => r.color))
+  const color =
+    COLOR_PALETTE.find((c) => !usedColors.has(c)) ??
+    COLOR_PALETTE[usedColors.size % COLOR_PALETTE.length]
 
   // 3. Insert new user row
   // mysql2 has no RETURNING clause — use $returningId() then re-select

apps/api/src/broker/outboxWorker.ts

@@ -24,14 +24,15 @@
  */
 
 import { schedule } from 'node-cron'
+import { z } from 'zod'
 import { and, eq, lte } from 'drizzle-orm'
 import { db } from '../db/client.js'
-import { calendarEvents, calendarOutbox, memberCredentials } from '../db/schema.js'
+import { calendarEvents, calendarOutbox, calendars, memberCredentials } from '../db/schema.js'
 import { createFastmailClient } from './client.js'
 import { decryptPassword } from './crypto.js'
 import { syncCalendar } from './sync.js'
 import { createCalendarEvent, updateCalendarEvent, deleteCalendarEvent } from './write.js'
-import { buildVeventString, RRULE_PRESETS } from './vevent.js'
+import { buildVeventString, extractRruleString, RRULE_PRESETS } from './vevent.js'
 import type { FastmailClient } from './client.js'
 
 // ── Constants (D-07) ────────────────────────────────────────────────────────
@@ -53,6 +54,35 @@ const HARD_FAIL_STATUSES = new Set([400, 401, 403])
 /** HTTP status code for CalDAV If-Match conflict — D-08 conflict flow. */
 const CONFLICT_STATUS = 412
 
+// ── Outbox payload re-validation (IN-03) ─────────────────────────────────────
+
+/**
+ * IN-03: re-validate the JSON payload read back out of calendar_outbox before building
+ * a VEVENT from it. The payload was zod-validated at enqueue (routes/events.ts
+ * eventFieldsSchema), but a manually-inserted row or enqueue→drain schema drift could
+ * feed undefined/wrong-typed fields into buildVeventString, producing SUMMARY:undefined
+ * or an Invalid Date. Such a row can NEVER succeed, so on validation failure the caller
+ * hard-fails the row (no retry) instead of burning the backoff budget.
+ *
+ * Mirrors eventFieldsSchema in routes/events.ts. `_preservedRrule` (added by the edit-as-
+ * move route, CR-01) is allowed via .passthrough() so the move payload still validates.
+ */
+const outboxPayloadSchema = z
+  .object({
+    title: z.string().min(1).max(255),
+    allDay: z.boolean(),
+    start: z.string().min(1).max(64),
+    end: z.string().min(1).max(64),
+    location: z.string().max(2000).optional(),
+    description: z.string().max(2000).optional(),
+    recurrence: z.enum(['none', 'daily', 'weekly', 'monthly', 'yearly']).optional(),
+    calendarUrl: z.string().url().max(1024).optional(),
+    _preservedRrule: z.string().max(1024).optional(),
+  })
+  .passthrough()
+
+type OutboxPayloadFields = z.infer<typeof outboxPayloadSchema>
+
 // ── Drain concurrency guard (CR-05) ──────────────────────────────────────────
 
 /**
@@ -104,11 +134,24 @@ async function loadClientForUser(userId: number): Promise<FastmailClient> {
  * Triggers a targeted single-calendar re-sync after a successful write or 412 conflict.
  * Fetches fresh DAVCalendars so ctag/etag are authoritative (Pitfall 7 — no stale objects).
  * All errors are caught and logged — re-sync failure is non-fatal.
+ *
+ * IN-01: accepts an optional per-drain-cycle client cache. Without it, every settled or
+ * conflicted row independently reloaded + AES-GCM-decrypted the member credential,
+ * widening the window the decrypted app password lives in memory (T-03-13). When a cache
+ * is supplied, the decrypted client is built at most once per userId per drain cycle.
  */
-async function triggerTargetedResync(calendarUrl: string, userId: number): Promise<void> {
+async function triggerTargetedResync(
+  calendarUrl: string,
+  userId: number,
+  clientCache?: Map<number, FastmailClient>,
+): Promise<void> {
   try {
     // loadClientForUser may throw in test environments — caught below
-    const client = await loadClientForUser(userId)
+    let client = clientCache?.get(userId)
+    if (!client) {
+      client = await loadClientForUser(userId)
+      clientCache?.set(userId, client)
+    }
     const davCalendars = await client.fetchCalendars()
 
     // Pitfall 7: find the DAVCalendar by URL match (normalize trailing slash differences)
@@ -177,22 +220,32 @@ async function dispatchRow(row: OutboxRow): Promise<DispatchResult> {
       }
     }
     // CR-02: parse the stored form JSON and build a real VCALENDAR string
-    let fields: Record<string, unknown>
+    let rawFields: Record<string, unknown>
     try {
-      fields = JSON.parse(row.payload) as Record<string, unknown>
+      rawFields = JSON.parse(row.payload) as Record<string, unknown>
     } catch {
       return { success: false, conflict: false, hardFail: true, transient: false, error: 'payload parse failed' }
     }
-    const { icsString } = buildVeventString({
-      uid: row.uid,
-      summary: fields.title as string,
-      allDay: fields.allDay as boolean,
-      dtstart: fields.allDay ? (fields.start as string) : new Date(fields.start as string),
-      dtend: fields.allDay ? (fields.end as string) : new Date(fields.end as string),
-      location: fields.location as string | undefined,
-      description: fields.description as string | undefined,
-      rruleString: fields.recurrence && fields.recurrence !== 'none' ? RRULE_PRESETS[fields.recurrence as string] : undefined,
-    })
+    // IN-03: re-validate the parsed payload. A schema-invalid row can never succeed —
+    // hard-fail it (no retry) rather than feeding undefined/Invalid Date into the VEVENT.
+    const parsedFields = outboxPayloadSchema.safeParse(rawFields)
+    if (!parsedFields.success) {
+      return { success: false, conflict: false, hardFail: true, transient: false, error: `payload validation failed: ${parsedFields.error.message}` }
+    }
+    const fields: OutboxPayloadFields = parsedFields.data
+    // WR-01: recurrence preservation. The PWA omits `recurrence` from an edit payload
+    // (it cannot read the existing RRULE — not in the occurrence contract, D-03), so on
+    // update we must NOT rebuild the VEVENT with no RRULE — that would silently convert a
+    // recurring series into a single event. When the payload carries no explicit
+    // recurrence, fall back to the RRULE already stored in calendarEvents.rawVevent.
+    // An explicit recurrence value (including 'none') still overrides — that is a
+    // deliberate user change. Read rawVevent in the same scoped query as the fresh etag.
+    let preservedRrule: string | undefined
+    const hasExplicitRecurrence = Object.prototype.hasOwnProperty.call(fields, 'recurrence')
+    const rruleFromPayload =
+      fields.recurrence && fields.recurrence !== 'none'
+        ? RRULE_PRESETS[fields.recurrence as string]
+        : undefined
     // WR-02: re-read the freshest etag from calendarEvents just before PUT.
     // Rapid successive edits to the same uid enqueue multiple update rows, each
     // carrying the etag at enqueue time. If a prior edit succeeded and triggered
@@ -201,15 +254,47 @@ async function dispatchRow(row: OutboxRow): Promise<DispatchResult> {
     // Using the freshest cached etag here prevents the spurious conflict toast
     // while still preserving genuine conflict detection (D-08): a real external
     // change updates calendarEvents.etag differently from any pending row's etag.
+    // CR-02: calendar_events is keyed (calendarId, uid), and a shared Fastmail
+    // account (D-16) caches the same uid once per member's calendar. A uid-only
+    // re-read returns multiple rows and an arbitrary [0] — potentially the OTHER
+    // member's etag, which would spuriously 412 (false conflict → edit dropped,
+    // D-08) or coincidentally match and overwrite. Scope the re-read to THIS row's
+    // own calendar by joining through calendars on the outbox row's userId +
+    // calendarUrl so the freshest etag belongs to the writing member.
     let etagForPut: string | null = row.etag ?? null
     const freshEtagRows = (await db
-      .select({ etag: calendarEvents.etag })
+      .select({ etag: calendarEvents.etag, rawVevent: calendarEvents.rawVevent })
       .from(calendarEvents)
-      .where(eq(calendarEvents.uid, row.uid))) as Array<{ etag: string | null }>
+      .innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))
+      .where(
+        and(
+          eq(calendarEvents.uid, row.uid),
+          eq(calendars.userId, row.userId),
+          eq(calendars.url, row.calendarUrl),
+        ),
+      )
+      .limit(1)) as Array<{ etag: string | null; rawVevent: string | null }>
     if (freshEtagRows.length > 0 && freshEtagRows[0].etag != null) {
       etagForPut = freshEtagRows[0].etag
     }
 
+    // WR-01: when the edit payload carries no explicit recurrence, preserve the RRULE
+    // already on the stored event so an edit does not strip a recurring series.
+    if (!hasExplicitRecurrence && freshEtagRows.length > 0 && freshEtagRows[0].rawVevent) {
+      preservedRrule = extractRruleString(freshEtagRows[0].rawVevent)
+    }
+
+    const { icsString } = buildVeventString({
+      uid: row.uid,
+      summary: fields.title as string,
+      allDay: fields.allDay as boolean,
+      dtstart: fields.allDay ? (fields.start as string) : new Date(fields.start as string),
+      dtend: fields.allDay ? (fields.end as string) : new Date(fields.end as string),
+      location: fields.location as string | undefined,
+      description: fields.description as string | undefined,
+      rruleString: hasExplicitRecurrence ? rruleFromPayload : (preservedRrule ?? rruleFromPayload),
+    })
+
     response = await updateCalendarEvent(
       client,
       row.calendarObjectUrl,
@@ -228,12 +313,35 @@ async function dispatchRow(row: OutboxRow): Promise<DispatchResult> {
       }
     }
     // CR-02: parse the stored form JSON and build a real VCALENDAR string
-    let fields: Record<string, unknown>
+    let rawFields: Record<string, unknown>
     try {
-      fields = JSON.parse(row.payload) as Record<string, unknown>
+      rawFields = JSON.parse(row.payload) as Record<string, unknown>
     } catch {
       return { success: false, conflict: false, hardFail: true, transient: false, error: 'payload parse failed' }
     }
+    // IN-03: re-validate the parsed payload — hard-fail a schema-invalid create row.
+    const parsedFields = outboxPayloadSchema.safeParse(rawFields)
+    if (!parsedFields.success) {
+      return { success: false, conflict: false, hardFail: true, transient: false, error: `payload validation failed: ${parsedFields.error.message}` }
+    }
+    const fields: OutboxPayloadFields = parsedFields.data
+    // CR-01: edit-as-move RRULE preservation. The same-calendar `update` branch
+    // preserves a recurring series' RRULE by reading rawVevent; the `create` branch
+    // (used for the create half of an edit-as-move, D-04) has no source for the
+    // original RRULE because it writes under a brand-new uid. The edit route extracts
+    // the source event's RRULE and stashes it on the payload as `_preservedRrule` so
+    // the worker can re-apply it here. An explicit `recurrence` on the payload still
+    // wins (deliberate user change); the preserved RRULE only fills the gap when the
+    // edit omitted recurrence — matching the update-branch semantics and the WR-01 fix.
+    const hasExplicitRecurrence = Object.prototype.hasOwnProperty.call(fields, 'recurrence')
+    const rruleFromPayload =
+      fields.recurrence && fields.recurrence !== 'none'
+        ? RRULE_PRESETS[fields.recurrence as string]
+        : undefined
+    const preservedRrule =
+      typeof fields._preservedRrule === 'string' && fields._preservedRrule.length > 0
+        ? fields._preservedRrule
+        : undefined
     const { icsString } = buildVeventString({
       uid: row.uid,
       summary: fields.title as string,
@@ -242,7 +350,7 @@ async function dispatchRow(row: OutboxRow): Promise<DispatchResult> {
       dtend: fields.allDay ? (fields.end as string) : new Date(fields.end as string),
       location: fields.location as string | undefined,
       description: fields.description as string | undefined,
-      rruleString: fields.recurrence && fields.recurrence !== 'none' ? RRULE_PRESETS[fields.recurrence as string] : undefined,
+      rruleString: hasExplicitRecurrence ? rruleFromPayload : (preservedRrule ?? rruleFromPayload),
     })
     // Build a minimal DAVCalendar for the write wrapper (only url is needed)
     const davCalendar = { url: row.calendarUrl } as Parameters<typeof createCalendarEvent>[1]
@@ -285,7 +393,23 @@ async function dispatchRow(row: OutboxRow): Promise<DispatchResult> {
     return { success: true, conflict: false, hardFail: false, transient: false }
   }
 
-  // Unknown status — treat as transient to avoid silent data loss
+  // IN-02: an unmapped 4xx (e.g. 405, 409, 422) is a permanent client error — retrying it
+  // for the full backoff window just delays settling and burns the attempt budget before
+  // dead-lettering. The transient-eligible 4xx codes (408 request timeout, 429 too many
+  // requests) are already in TRANSIENT_STATUSES and handled above, so any remaining 4xx
+  // here is a hard fail. 5xx, network failures, and truly unknown statuses still fall
+  // through to transient so genuinely recoverable conditions keep their retries.
+  if (status >= 400 && status < 500) {
+    return {
+      success: false,
+      conflict: false,
+      hardFail: true,
+      transient: false,
+      error: `Hard fail: HTTP ${status} for uid=${row.uid}`,
+    }
+  }
+
+  // Unknown / 5xx status — treat as transient to avoid silent data loss
   return {
     success: false,
     conflict: false,
@@ -347,6 +471,10 @@ export async function runOutboxDrain(): Promise<void> {
     // Cross-batch ordering is enforced durably by the DB sibling-status check inside the loop.
     const failedCreateGroups = new Set<string>()
 
+    // IN-01: per-drain-cycle client cache so triggerTargetedResync decrypts each member's
+    // credential at most once per cycle. Discarded when the drain returns — never persisted.
+    const clientCache = new Map<number, FastmailClient>()
+
     for (const row of sorted) {
       // D-04 fast path: if the create for this group already failed in this batch, skip the delete
       if (row.operation === 'delete' && row.groupId && failedCreateGroups.has(row.groupId)) {
@@ -399,23 +527,41 @@ export async function runOutboxDrain(): Promise<void> {
         const result = await dispatchRow(row)
 
         if (result.conflict) {
+          // WR-06: distinguish an edit-as-move create-412 from a same-calendar conflict.
+          // For a move (D-04) the create runs first; on 412 the paired delete is later
+          // marked failed and the original event survives — so this is NOT a "the event
+          // changed elsewhere" conflict, it is "the move could not be applied". The PWA
+          // set lastSyncedUid to the NEW (move) uid, whose only outbox row is this failed
+          // create, so without a distinct message the user sees the wrong conflict copy
+          // and has no cue to retry. Emit a move-specific lastError that does NOT contain
+          // '412' so the toast routes it to the dedicated move-failed copy instead of the
+          // generic etag-conflict copy.
+          const isMoveCreate = !!row.groupId && row.operation === 'create'
+          const conflictError = isMoveCreate
+            ? 'move-failed: the event could not be moved — re-open it and save again'
+            : (result.error ?? '412 conflict')
           // 412 — mark failed (no retry), re-sync calendar so UI sees authoritative state (D-08)
           await db
             .update(calendarOutbox)
-            .set({ status: 'failed', lastError: result.error ?? '412 conflict' })
+            .set({ status: 'failed', lastError: conflictError })
             .where(eq(calendarOutbox.id, row.id))
-          await triggerTargetedResync(row.calendarUrl, row.userId)
+          await triggerTargetedResync(row.calendarUrl, row.userId, clientCache)
 
           if (row.groupId && row.operation === 'create') {
             failedCreateGroups.add(row.groupId)
           }
         } else if (result.success) {
-          // Success — mark done, trigger targeted re-sync to refresh the cache (D-06)
+          // Success — refresh the local cache BEFORE marking done. The PWA's
+          // SyncStateToast polls sync-status and invalidates ['events'] the
+          // instant it sees status='done'; if we marked done first, that refetch
+          // raced the re-sync and returned stale cache (deleted event still
+          // present, edit not yet applied) — forcing a manual refresh. Re-syncing
+          // first means 'done' guarantees the cache already reflects the write.
+          await triggerTargetedResync(row.calendarUrl, row.userId, clientCache)
           await db
             .update(calendarOutbox)
             .set({ status: 'done' })
             .where(eq(calendarOutbox.id, row.id))
-          await triggerTargetedResync(row.calendarUrl, row.userId)
         } else if (result.hardFail) {
           // Hard fail — mark failed immediately, no retry (D-07)
           await db

apps/api/src/broker/sync.ts

@@ -18,7 +18,7 @@
 import type { DAVCalendar } from 'tsdav'
 import type { FastmailClient } from './client.js'
 import ICAL from 'ical.js'
-import { and, eq } from 'drizzle-orm'
+import { and, eq, notInArray } from 'drizzle-orm'
 import { db } from '../db/client.js'
 import { calendars, calendarEvents } from '../db/schema.js'
 
@@ -73,6 +73,9 @@ export async function syncCalendar(
   const objects = await client.fetchCalendarObjects({ calendar: davCal })
 
   // 4. Parse each VCALENDAR/VEVENT and upsert into calendar_events.
+  //    Track every uid we see on the server so step 5 can prune cache rows that
+  //    no longer exist on Fastmail (deletes — local or external).
+  const seenUids: string[] = []
   for (const obj of objects) {
     if (!obj.data) continue
 
@@ -92,6 +95,7 @@ export async function syncCalendar(
     const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time | null
     const uid = vevent.getFirstPropertyValue('uid') as string | null
     if (!uid) continue
+    seenUids.push(uid)
 
     // D-13 / Pitfall #3: isDate=true → DATE column; isDate=false → TIMESTAMP column
     const allDay: boolean = dtstart?.isDate ?? false
@@ -133,4 +137,19 @@ export async function syncCalendar(
         },
       })
   }
+
+  // 5. Prune deletes: remove cached events for THIS calendar whose uid is no
+  //    longer present on the server. Without this, a deleted event (local delete
+  //    via the outbox, or an external delete in another client) lingers in
+  //    calendar_events forever — GET /api/events keeps returning it and the UI
+  //    shows a ghost event that "won't delete". Scoped to cal.id so it never
+  //    touches another calendar or the other household member's rows (BUG B).
+  //    When the server returns zero events, prune the whole calendar's cache.
+  if (seenUids.length > 0) {
+    await db
+      .delete(calendarEvents)
+      .where(and(eq(calendarEvents.calendarId, cal.id), notInArray(calendarEvents.uid, seenUids)))
+  } else {
+    await db.delete(calendarEvents).where(eq(calendarEvents.calendarId, cal.id))
+  }
 }

apps/api/src/broker/vevent.ts

@@ -35,6 +35,16 @@ export interface NewEventParams {
 /**
  * Simple RRULE preset strings for whole-series recurring events (D-11 / CAL-07).
  * "weekly on Monday" example: 'FREQ=WEEKLY;BYDAY=MO' (not a key in this map; compose manually).
+ *
+ * IN-01 (v1 limitation — lossy round-trip): these presets map only to a BARE
+ * FREQ=DAILY|WEEKLY|MONTHLY|YEARLY. extractRruleString() preserves the FULL stored RECUR
+ * (which may carry BYDAY/INTERVAL/COUNT/UNTIL), and the preserve-on-edit path keeps that
+ * rich rule. But if a `recurrence` preset value is ever applied to a previously-rich rule,
+ * it COLLAPSES the rule to the bare preset — silently dropping BYDAY/INTERVAL/UNTIL/COUNT.
+ * This is acceptable in v1 only because the picker offers just these four bare presets and
+ * is disabled on edit (EventForm WR-01). When recurrence EDITING ships, do NOT replace the
+ * stored rule with a preset: parse the existing RECUR and modify it in place so qualifiers
+ * survive. See CR-01/WR-01 preserve paths for the precedent.
  */
 export const RRULE_PRESETS: Record<string, string> = {
   daily: 'FREQ=DAILY',
@@ -43,6 +53,29 @@ export const RRULE_PRESETS: Record<string, string> = {
   yearly: 'FREQ=YEARLY',
 }
 
+/**
+ * WR-01: Extract the existing RRULE string from a stored VCALENDAR/VEVENT, so the
+ * outbox worker can preserve recurrence on an edit whose payload omits it (the PWA
+ * occurrence contract does not expose recurrence, D-03). Returns the RRULE value as a
+ * 'FREQ=…' string (e.g. 'FREQ=WEEKLY'), or undefined when the event has no RRULE or
+ * the input cannot be parsed.
+ */
+export function extractRruleString(rawVevent: string): string | undefined {
+  let parsed: ReturnType<typeof ICAL.parse>
+  try {
+    parsed = ICAL.parse(rawVevent)
+  } catch {
+    return undefined
+  }
+  const comp = new ICAL.Component(parsed)
+  const vevent = comp.getFirstSubcomponent('vevent')
+  if (!vevent) return undefined
+  const rrule = vevent.getFirstPropertyValue('rrule')
+  if (!rrule) return undefined
+  // ICAL.Recur#toString() yields the RECUR value, e.g. 'FREQ=WEEKLY'.
+  return typeof rrule === 'string' ? rrule : (rrule as ICAL.Recur).toString()
+}
+
 /**
  * Builds a VCALENDAR/VEVENT iCalendar string from form parameters.
  *

apps/api/src/broker/write.ts

@@ -65,6 +65,17 @@ export async function updateCalendarEvent(
   icsString: string,
   etag: string | null,
 ): Promise<Response> {
+  // WR-03: a missing etag maps to NO If-Match header → an UNCONDITIONAL PUT, which
+  // defeats D-08 conflict detection for exactly the rows most likely to be stale (an
+  // event cached before an etag was captured, or one Fastmail omitted the etag for).
+  // We do not block the write (it would strand the user's edit), but we make the
+  // unconditional-write path observable so it can be diagnosed instead of silently
+  // overwriting a concurrent external edit with no 412.
+  if (etag == null || etag === '') {
+    console.warn(
+      `[write] updateCalendarObject dispatching with NO If-Match (unconditional PUT) — conflict detection disabled for url=${calendarObjectUrl}`,
+    )
+  }
   return client.updateCalendarObject({
     calendarObject: {
       url: calendarObjectUrl,
@@ -87,6 +98,13 @@ export async function deleteCalendarEvent(
   calendarObjectUrl: string,
   etag: string | null,
 ): Promise<Response> {
+  // WR-03: see updateCalendarEvent — a missing etag is an unconditional DELETE that
+  // bypasses D-08 conflict detection. Log so the path is observable rather than silent.
+  if (etag == null || etag === '') {
+    console.warn(
+      `[write] deleteCalendarObject dispatching with NO If-Match (unconditional DELETE) — conflict detection disabled for url=${calendarObjectUrl}`,
+    )
+  }
   return client.deleteCalendarObject({
     calendarObject: {
       url: calendarObjectUrl,

apps/api/src/index.ts

@@ -1,3 +1,5 @@
+import { fileURLToPath } from 'node:url'
+import { realpathSync } from 'node:fs'
 import { serve } from '@hono/node-server'
 import { serveStatic } from '@hono/node-server/serve-static'
 import { Hono } from 'hono'
@@ -60,11 +62,12 @@ app.route('/api/me', meRouter)
 app.route('/api/events', eventsRouter)
 app.route('/api/sse', sseRouter)
 
-// Start the CalDAV broker poller (5-min cron, D-13 ctag change-detection)
-// Runs in the background — errors are caught and logged per-credential (T-03-04)
-startBrokerPoller()
-// Drain the D-05 outbox every 15s: dispatches pending CalDAV writes to Fastmail
-startOutboxWorker()
+// WR-04: background worker startup (cron schedules) moved into the isMainModule()
+// guard below. Calling them at top level registered real node-cron schedules whenever
+// ./index.js was imported — the route tests import `app` from here, so the poller/outbox
+// drain fired during the test run, touched the mocked DB/CalDAV layers nondeterministically,
+// and left open handles that blocked clean process exit. They now start only when the
+// module is the process entrypoint.
 
 // Serve React PWA static assets from ./public (Vite build output).
 // MUST serve the whole ./public tree, not just /assets/* — root-level PWA files
@@ -75,8 +78,36 @@ startOutboxWorker()
 app.use('/*', serveStatic({ root: './public' }))
 app.get('*', serveStatic({ path: './public/index.html' }))
 
-// Only start the HTTP server when this module is run directly (not imported in tests)
-if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/^.*\//, ''))) {
+/**
+ * True only when this module is the process entrypoint (run directly), not when it
+ * is imported (e.g. by route tests that import `app`).
+ *
+ * WR-05: the previous basename-tail comparison
+ *   import.meta.url.endsWith(process.argv[1].replace(/^.*\//, ''))
+ * was fragile — a symlinked entrypoint or a differently-located file sharing the same
+ * basename could make it mis-fire (start the server during an unrelated import, or fail
+ * to start it in production). Compare fully-resolved real paths instead. realpathSync
+ * resolves symlinks on argv[1]; fileURLToPath turns the module URL into a real path.
+ */
+function isMainModule(): boolean {
+  if (!process.argv[1]) return false
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+  } catch {
+    return false
+  }
+}
+
+// Only start the HTTP server AND background workers when this module is run directly
+// (not imported in tests). WR-04: gating the cron schedules here keeps them out of the
+// test process.
+if (isMainModule()) {
+  // Start the CalDAV broker poller (5-min cron, D-13 ctag change-detection).
+  // Runs in the background — errors are caught and logged per-credential (T-03-04).
+  startBrokerPoller()
+  // Drain the D-05 outbox every 15s: dispatches pending CalDAV writes to Fastmail.
+  startOutboxWorker()
+
   serve({ fetch: app.fetch, port: 3000 }, (info) => {
     console.log(`FamilySync API running on http://localhost:${info.port}`)
   })

apps/api/src/routes/events.ts

@@ -23,6 +23,7 @@
 
 import { randomUUID } from 'node:crypto'
 import { Hono } from 'hono'
+import type { Context } from 'hono'
 import { zValidator } from '@hono/zod-validator'
 import { z } from 'zod'
 import { and, or, eq, desc } from 'drizzle-orm'
@@ -30,6 +31,7 @@ import { sql } from 'drizzle-orm'
 import { db } from '../db/client.js'
 import { calendarEvents, calendars, users, calendarOutbox } from '../db/schema.js'
 import { expandOccurrences } from '../broker/expand.js'
+import { extractRruleString } from '../broker/vevent.js'
 import { getAuth } from '../auth/middleware.js'
 import { upsertUser, deriveDisplayName } from '../auth/user.js'
 // Side-effect import: brings in the ContextVariableMap augmentation for c.get('user')
@@ -55,8 +57,10 @@ const MAX_WINDOW_DAYS = 90
 //      Identity is keyed on oidc_iss + oidc_sub (D-10), never email.
 //   3. Callers emit 401 when resolveUserId returns null.
 //
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function resolveUserId(c: any): Promise<number | null> {
+// IN-04: typed as Hono's Context instead of `any`. c.get('user') resolves through the
+// ContextVariableMap augmentation in auth/devBypass.ts (typed as the DEV_USER shape),
+// and getAuth(c) accepts a Context — so no `any` / eslint-disable is needed here.
+async function resolveUserId(c: Context): Promise<number | null> {
   const devUser = c.get('user') as { id: number } | undefined
   if (devUser) return devUser.id
 
@@ -69,7 +73,7 @@ async function resolveUserId(c: any): Promise<number | null> {
   // Derive displayName via the shared helper (name → preferred_username → email
   // → sub fallback) so the write-path upsert agrees with me.ts and never
   // overwrites a correctly-derived name with a worse one.
-  const displayName = deriveDisplayName(auth, sub)
+  const displayName = deriveDisplayName(auth)
 
   const user = await upsertUser(iss, sub, displayName)
   return user?.id ?? null
@@ -256,11 +260,17 @@ eventsRouter.post('/create', zValidator('json', eventFieldsSchema), async (c) =>
       }
       targetCalendarUrl = calRow.url
     } else {
-      // Default to first personal calendar (D-01)
+      // Default to the member's first personal calendar (D-01).
+      // WR-02: add a deterministic ORDER BY + LIMIT. Without them, a member with
+      // multiple personal calendars gets an arbitrary, query-to-query-unstable "first"
+      // row. Ordering by id (insertion order) gives a stable default; limit(1) avoids
+      // fetching the whole set just to take [0].
       const [calRow] = await db
         .select({ url: calendars.url })
         .from(calendars)
         .where(eq(calendars.userId, currentUserId))
+        .orderBy(calendars.id)
+        .limit(1)
 
       if (!calRow) {
         return c.json({ error: 'No writable calendar found for user' }, 422)
@@ -308,6 +318,15 @@ eventsRouter.patch('/:uid/edit', zValidator('json', eventFieldsSchema), async (c
     // Join calendarEvents → calendars so we can read calendars.url and calendars.userId
     // in the same query. Without the join, referencing calendars.* produces invalid SQL
     // (Drizzle throws at toSQL() time) → 503. Mirrors the GET / join idiom at line 153.
+    //
+    // CR-01: calendar_events is keyed (calendarId, uid), NOT uid alone (schema.ts:121).
+    // With a shared Fastmail account (D-16) the SAME uid is cached once per member's
+    // calendar, so a uid-only lookup returns 2+ rows and an arbitrary [0] (typically the
+    // OTHER member's row). Scope the lookup to the acting member's writable set
+    // (own calendars OR shared) so the etag/objectUrl/ownership we act on belong to the
+    // right calendar. Order so the current user's OWN row ranks before a shared/other row
+    // — when both a personal and a shared copy of the uid exist, the acting member's copy
+    // is authoritative for the write target. limit(1) makes the pick deterministic.
     const [eventRow] = await db
       .select({
         uid: calendarEvents.uid,
@@ -316,16 +335,26 @@ eventsRouter.patch('/:uid/edit', zValidator('json', eventFieldsSchema), async (c
         calendarId: calendarEvents.calendarId,
         calendarUrl: calendars.url,
         userId: calendars.userId,
+        rawVevent: calendarEvents.rawVevent,
       })
       .from(calendarEvents)
       .innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))
-      .where(eq(calendarEvents.uid, uid))
+      .where(
+        and(
+          eq(calendarEvents.uid, uid),
+          or(eq(calendars.userId, currentUserId), eq(calendars.isShared, true)),
+        ),
+      )
+      .orderBy(sql`(${calendars.userId} = ${currentUserId}) desc`)
+      .limit(1)
 
     if (!eventRow) {
       return c.json({ error: 'Event not found' }, 404)
     }
 
-    // Ownership check: must be the calendar owner or shared (T-03-06)
+    // Ownership check: must be the calendar owner or shared (T-03-06).
+    // The WHERE above already restricts to the writable set, so any returned row is
+    // either the user's own calendar or a shared one — re-verify defensively.
     if (eventRow.userId !== currentUserId) {
       // Check if the calendar is shared (shared calendars are writable by all household members)
       const [calRow] = await db
@@ -346,6 +375,25 @@ eventsRouter.patch('/:uid/edit', zValidator('json', eventFieldsSchema), async (c
       const newUid = `${randomUUID()}@familysync`
       const groupId = randomUUID()
 
+      // CR-01: carry the existing RRULE through the move. The edit payload omits
+      // `recurrence` (the occurrence contract does not expose it, D-03), and the
+      // create lands under a brand-new uid that the worker can never look up the
+      // original RRULE from. Unlike the same-calendar `update` branch — which reads
+      // rawVevent and re-applies the stored RRULE — the create branch has no source
+      // for it. Extract the RRULE from the source event here and stash it on the
+      // create payload so the worker re-applies it, preventing a recurring series
+      // from silently collapsing into a single occurrence on a calendar move.
+      // Only stash when the edit did NOT carry an explicit recurrence: an explicit
+      // value (including 'none') is a deliberate user change and must win.
+      const preservedRrule =
+        payload.recurrence === undefined
+          ? extractRruleString(eventRow.rawVevent ?? '')
+          : undefined
+      const createPayload =
+        preservedRrule !== undefined
+          ? { ...payload, _preservedRrule: preservedRrule }
+          : payload
+
       await db.transaction(async (tx) => {
         // Delete from old calendar
         await tx.insert(calendarOutbox).values({
@@ -365,7 +413,7 @@ eventsRouter.patch('/:uid/edit', zValidator('json', eventFieldsSchema), async (c
           status: 'pending',
           uid: newUid,
           calendarUrl: newCalendarUrl,
-          payload: JSON.stringify(payload),
+          payload: JSON.stringify(createPayload),
           groupId,
         })
       })
@@ -408,6 +456,10 @@ eventsRouter.delete('/:uid', async (c) => {
     // Look up the event — join calendars so calendars.url / calendars.userId are accessible.
     // Same innerJoin idiom as the GET / handler (line 153). Without this join, Drizzle
     // throws at toSQL() time → 503.
+    //
+    // CR-01: scope to the acting member's writable set and pick deterministically — a
+    // shared Fastmail account (D-16) caches the same uid once per member's calendar, so a
+    // uid-only lookup would otherwise act on an arbitrary member's etag/objectUrl.
     const [eventRow] = await db
       .select({
         uid: calendarEvents.uid,
@@ -419,7 +471,14 @@ eventsRouter.delete('/:uid', async (c) => {
       })
       .from(calendarEvents)
       .innerJoin(calendars, eq(calendarEvents.calendarId, calendars.id))
-      .where(eq(calendarEvents.uid, uid))
+      .where(
+        and(
+          eq(calendarEvents.uid, uid),
+          or(eq(calendars.userId, currentUserId), eq(calendars.isShared, true)),
+        ),
+      )
+      .orderBy(sql`(${calendars.userId} = ${currentUserId}) desc`)
+      .limit(1)
 
     if (!eventRow) {
       return c.json({ error: 'Event not found' }, 404)
@@ -470,6 +529,14 @@ eventsRouter.get('/sync-status', zValidator('query', syncStatusQuerySchema), asy
 
   try {
     // Scope strictly to current member's rows (T-03-07 — never leak another member's outbox).
+    //
+    // WR-04: rapid successive same-uid edits enqueue multiple outbox rows. A plain
+    // "newest row" pick (ORDER BY createdAt DESC LIMIT 1) reports only the latest row's
+    // status — so if the newest succeeds but an older row dead-lettered, the user sees
+    // "Saved" while a queued write silently failed. Rank an unsettled/failed row ABOVE a
+    // done row: a row in pending/failed/dead for the uid outranks a done row, and only
+    // among same-priority rows do we fall back to newest-first. This surfaces a failure
+    // for ANY row of the uid instead of masking it behind a later success.
     const rows = await db
       .select({
         uid: calendarOutbox.uid,
@@ -478,7 +545,11 @@ eventsRouter.get('/sync-status', zValidator('query', syncStatusQuerySchema), asy
       })
       .from(calendarOutbox)
       .where(and(eq(calendarOutbox.userId, currentUserId), eq(calendarOutbox.uid, uid)))
-      .orderBy(desc(calendarOutbox.createdAt))
+      // status priority: failed/dead first, then pending, then done.
+      .orderBy(
+        sql`case ${calendarOutbox.status} when 'failed' then 0 when 'dead' then 0 when 'pending' then 1 else 2 end`,
+        desc(calendarOutbox.createdAt),
+      )
       .limit(1)
 
     if (!rows.length) {

apps/api/src/routes/me.ts

@@ -56,7 +56,7 @@ meRouter.get('/', async (c) => {
   // Derive the best available display name from OIDC claims (name →
   // preferred_username → email → sub fallback). Shared helper keeps every
   // upsert call site in agreement (see deriveDisplayName).
-  const displayName = deriveDisplayName(auth, sub)
+  const displayName = deriveDisplayName(auth)
 
   const user = await upsertUser(iss, sub, displayName)
 

apps/api/tests/auth/user.test.ts

@@ -68,7 +68,7 @@ describe('upsertUser', () => {
     const sub = 'user-sub-001'
 
     // First select: no existing user
-    // Second select (count): count = 0
+    // Second select (used colors): no existing users → no colors in use → palette[0]
     // Third select (re-fetch after insert): return the inserted row
     let selectCallCount = 0
     mockDb.select.mockImplementation(() => {
@@ -78,9 +78,9 @@ describe('upsertUser', () => {
         return makeSelectChain([])
       }
       if (selectCallCount === 2) {
-        // COUNT(*) query — 0 users
+        // Used-colors query — no existing users
         return {
-          from: vi.fn().mockResolvedValue([{ count: 0 }]),
+          from: vi.fn().mockResolvedValue([]),
         }
       }
       // Re-fetch after insert
@@ -109,9 +109,10 @@ describe('upsertUser', () => {
         return makeSelectChain([]) // not found
       }
       if (selectCallCount === 2) {
-        // COUNT(*) — 1 existing user
+        // Used-colors query — one existing user already holds palette[0],
+        // so the next member must get the first unused color: palette[1].
         return {
-          from: vi.fn().mockResolvedValue([{ count: 1 }]),
+          from: vi.fn().mockResolvedValue([{ color: COLOR_PALETTE[0] }]),
         }
       }
       return makeSelectChain([
@@ -126,6 +127,39 @@ describe('upsertUser', () => {
     expect(user!.color).toBe(COLOR_PALETTE[1])
   })
 
+  // Regression (Gate 2): a new member must get a color NOT already in use, even
+  // after a deletion. The old COUNT(*) % palette logic reused an in-use slot
+  // when the user count had shifted (two members both got #E8734A). With colors
+  // [0] and [2] taken (slot [1] freed by a delete), the next member fills [1].
+  it('assigns the first UNUSED palette color (no collision after deletions)', async () => {
+    const iss = 'https://auth.example.com'
+    const sub = 'user-sub-005'
+
+    let selectCallCount = 0
+    mockDb.select.mockImplementation(() => {
+      selectCallCount++
+      if (selectCallCount === 1) return makeSelectChain([]) // not found
+      if (selectCallCount === 2) {
+        // palette[0] and palette[2] in use; palette[1] is free
+        return {
+          from: vi
+            .fn()
+            .mockResolvedValue([{ color: COLOR_PALETTE[0] }, { color: COLOR_PALETTE[2] }]),
+        }
+      }
+      return makeSelectChain([
+        { id: 5, oidcIss: iss, oidcSub: sub, displayName: null, color: COLOR_PALETTE[1], createdAt: new Date() },
+      ])
+    })
+    mockDb.insert.mockReturnValue(makeInsertChain([{ id: 5 }]))
+
+    await upsertUser(iss, sub)
+
+    // The inserted row's color must be the first unused palette entry (palette[1]).
+    const insertValues = mockDb.insert.mock.results[0]?.value?.values.mock.calls[0]?.[0]
+    expect(insertValues.color).toBe(COLOR_PALETTE[1])
+  })
+
   it('returns the same user row on re-upsert (idempotent — no duplicate insert)', async () => {
     const iss = 'https://auth.example.com'
     const sub = 'user-sub-001'

apps/api/tests/broker/outboxWorker.test.ts

@@ -139,7 +139,15 @@ function wireMockChain() {
       return { where: vi.fn().mockResolvedValue([FAKE_CRED_ROW]) }
     }
     if (tableName === 'calendar_events') {
-      return { where: mockWhereCalEvents }
+      // CR-02: the freshest-etag re-read now scopes to the writing member's calendar:
+      //   .from(calendarEvents).innerJoin(calendars, ...).where(...).limit(1)
+      // mockWhereCalEvents stays the awaited terminal (returned by .limit) so existing
+      // mockWhereCalEvents.mockResolvedValue([{ etag }]) overrides still drive the etag.
+      return {
+        innerJoin: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({ limit: mockWhereCalEvents }),
+        }),
+      }
     }
     return { where: mockWherePending }
   })
@@ -273,6 +281,81 @@ describe('runOutboxDrain — ICS building from form JSON (CR-02)', () => {
     const setArg = mockUpdateSet.mock.calls[0]?.[0] as { status?: string }
     expect(setArg?.status).toBe('failed')
   })
+
+  // IN-03 (iteration 2): a JSON-parseable but schema-INVALID payload (e.g. missing the
+  // required title) can never produce a valid VEVENT, so the row is hard-failed (no
+  // retry) rather than dispatched with SUMMARY:undefined.
+  it('IN-03: create row with schema-invalid payload (missing title) is hard-failed, never dispatched', async () => {
+    const { createCalendarEvent } = await import('../../src/broker/write.js')
+    vi.mocked(createCalendarEvent).mockResolvedValue(makeResponse(201))
+    // Valid JSON, but title is missing → fails outboxPayloadSchema
+    const badPayload = JSON.stringify({
+      allDay: false,
+      start: '2026-06-10T12:00:00',
+      end: '2026-06-10T13:00:00',
+    })
+    mockPendingRows = [makeRow({ payload: badPayload })]
+
+    await runOutboxDrain()
+
+    // Must NOT have dispatched a CalDAV write with an invalid VEVENT
+    expect(createCalendarEvent).not.toHaveBeenCalled()
+    const setArg = mockUpdateSet.mock.calls[0]?.[0] as { status?: string; lastError?: string }
+    expect(setArg?.status).toBe('failed')
+    expect(setArg?.lastError).toMatch(/validation/i)
+  })
+
+  // CR-01 (iteration 2): the edit-as-move create branch must re-apply the RRULE the
+  // route stashed on the payload as `_preservedRrule`, so a moved recurring series keeps
+  // its RRULE instead of collapsing into a single occurrence.
+  it('CR-01: create row re-applies _preservedRrule → emitted ICS contains RRULE:', async () => {
+    const { createCalendarEvent } = await import('../../src/broker/write.js')
+    let capturedIcsString: unknown = null
+    vi.mocked(createCalendarEvent).mockImplementation(async (_client, _cal, _uid, icsString) => {
+      capturedIcsString = icsString
+      return makeResponse(201)
+    })
+    // Move payload: no explicit `recurrence`, but the route stashed the source RRULE.
+    const movePayload = JSON.stringify({
+      title: 'Moved weekly standup',
+      allDay: false,
+      start: '2026-06-10T12:00:00',
+      end: '2026-06-10T13:00:00',
+      _preservedRrule: 'FREQ=WEEKLY;BYDAY=MO',
+    })
+    mockPendingRows = [makeRow({ operation: 'create', payload: movePayload, groupId: 'move-grp-1' })]
+
+    await runOutboxDrain()
+
+    expect(typeof capturedIcsString).toBe('string')
+    expect(capturedIcsString as string).toContain('RRULE:')
+    expect(capturedIcsString as string).toContain('FREQ=WEEKLY')
+  })
+
+  // CR-01 corollary: an explicit `recurrence` on a create still wins over any preserved
+  // RRULE (deliberate user choice); recurrence:'none' must emit no RRULE.
+  it("CR-01: explicit recurrence:'none' wins → emitted ICS has no RRULE even if _preservedRrule present", async () => {
+    const { createCalendarEvent } = await import('../../src/broker/write.js')
+    let capturedIcsString: unknown = null
+    vi.mocked(createCalendarEvent).mockImplementation(async (_client, _cal, _uid, icsString) => {
+      capturedIcsString = icsString
+      return makeResponse(201)
+    })
+    const payload = JSON.stringify({
+      title: 'One-off',
+      allDay: false,
+      start: '2026-06-10T12:00:00',
+      end: '2026-06-10T13:00:00',
+      recurrence: 'none',
+      _preservedRrule: 'FREQ=WEEKLY;BYDAY=MO',
+    })
+    mockPendingRows = [makeRow({ operation: 'create', payload })]
+
+    await runOutboxDrain()
+
+    expect(typeof capturedIcsString).toBe('string')
+    expect(capturedIcsString as string).not.toContain('RRULE:')
+  })
 })
 
 describe('runOutboxDrain — edit-as-move ordering (D-04)', () => {

apps/api/tests/broker/sync.test.ts

@@ -26,12 +26,16 @@ const mockLimit = vi.fn().mockResolvedValue([{ id: 42 }])
 const mockWhere = vi.fn().mockReturnValue({ limit: mockLimit })
 const mockFrom = vi.fn().mockReturnValue({ where: mockWhere })
 const mockSelect = vi.fn().mockReturnValue({ from: mockFrom })
+// Prune chain: db.delete(calendarEvents).where(...)
+const mockDeleteWhere = vi.fn().mockResolvedValue([])
+const mockDelete = vi.fn().mockReturnValue({ where: mockDeleteWhere })
 
 // Mock the db singleton at module level (Vitest hoisting)
 vi.mock('../../src/db/client.js', () => ({
   db: {
     insert: mockInsert,
     select: mockSelect,
+    delete: mockDelete,
   },
 }))
 
@@ -46,6 +50,8 @@ describe('syncCalendar', () => {
     mockWhere.mockReturnValue({ limit: mockLimit })
     mockFrom.mockReturnValue({ where: mockWhere })
     mockSelect.mockReturnValue({ from: mockFrom })
+    mockDeleteWhere.mockResolvedValue([])
+    mockDelete.mockReturnValue({ where: mockDeleteWhere })
   })
 
   it('stores all-day events with dtstart_date (DATE) and dtstart_utc=NULL', async () => {
@@ -313,4 +319,50 @@ describe('syncCalendar', () => {
     expect(calValuesArg.ctag).toBe('new-ctag-123')
     expect(calValuesArg.syncToken).toBe('sync-token-abc')
   })
+
+  // Regression: deletes must be reconciled out of the cache. Before this fix,
+  // syncCalendar only upserted present events, so a deleted event lingered in
+  // calendar_events forever and the UI showed a ghost that "wouldn't delete".
+  it('prunes cached events whose uid is absent from the server (delete reconciliation)', async () => {
+    const { syncCalendar } = await import('../../src/broker/sync.js')
+
+    // Server returns ONE timed event; any other cached uid for this calendar must be pruned.
+    const mockClient = {
+      fetchCalendarObjects: vi.fn().mockResolvedValue([
+        { data: SAMPLE_VEVENT_TIMED, etag: '"etag-timed"', url: '/cal/timed.ics' },
+      ]),
+    }
+    const mockDavCal = {
+      url: 'https://caldav.fastmail.com/dav/calendars/user/test@fm.com/Default/',
+      displayName: 'Test Calendar',
+      ctag: 'ctag-v2',
+      syncToken: null,
+    }
+
+    await syncCalendar(mockClient as never, mockDavCal as never, 1)
+
+    // A prune DELETE must run, scoped by calendarId AND excluding the seen uid(s).
+    expect(mockDelete).toHaveBeenCalledTimes(1)
+    expect(mockDeleteWhere).toHaveBeenCalledTimes(1)
+  })
+
+  it('prunes the entire calendar cache when the server returns zero events', async () => {
+    const { syncCalendar } = await import('../../src/broker/sync.js')
+
+    const mockClient = {
+      fetchCalendarObjects: vi.fn().mockResolvedValue([]),
+    }
+    const mockDavCal = {
+      url: 'https://caldav.fastmail.com/dav/calendars/user/test@fm.com/Default/',
+      displayName: 'Test Calendar',
+      ctag: 'ctag-empty',
+      syncToken: null,
+    }
+
+    await syncCalendar(mockClient as never, mockDavCal as never, 1)
+
+    // Empty server result → prune-all DELETE (scoped to this calendar id only).
+    expect(mockDelete).toHaveBeenCalledTimes(1)
+    expect(mockDeleteWhere).toHaveBeenCalledTimes(1)
+  })
 })

apps/api/tests/routes/events.test.ts

@@ -385,9 +385,14 @@ describe('PATCH /api/events/:uid/edit', () => {
         userId: 1,
       },
     ]
-    // After BUG 1 fix, the edit lookup uses .from(calendarEvents).innerJoin(calendars, ...).where(...)
-    // Wire mockFromFn to expose innerJoin → where so the handler resolves mockDbRows.
-    const mockInnerJoinWhere = vi.fn().mockImplementation(() => Promise.resolve(mockDbRows))
+    // After BUG 1 + CR-01 fix, the edit lookup uses
+    // .from(calendarEvents).innerJoin(calendars, ...).where(...).orderBy(...).limit(1).
+    // Wire mockFromFn to expose innerJoin → where → orderBy → limit so the handler resolves mockDbRows.
+    const mockInnerJoinWhere = vi.fn().mockReturnValue({
+      orderBy: vi.fn().mockReturnValue({
+        limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+      }),
+    })
     const mockInnerJoin = vi.fn().mockReturnValue({ where: mockInnerJoinWhere })
     mockFromFn.mockReturnValue({ innerJoin: mockInnerJoin })
     mockSelectFn.mockReturnValue({ from: mockFromFn })
@@ -408,6 +413,60 @@ describe('PATCH /api/events/:uid/edit', () => {
     })
     expect(res.status).toBe(202)
   })
+
+  // CR-01 (iteration 2): edit-as-move must carry the source event's RRULE through
+  // to the create row so a moved recurring series does not silently collapse into a
+  // single occurrence. The edit payload omits `recurrence`; the route must extract the
+  // RRULE from the source event's rawVevent and stash it on the create payload as
+  // `_preservedRrule` so the worker re-applies it.
+  it('CR-01: move of a recurring event stashes the source RRULE on the create outbox row', async () => {
+    // Seed a recurring source event (RRULE:FREQ=WEEKLY;BYDAY=MO) on the user's calendar.
+    mockDbRows = [
+      {
+        uid: 'uid-001@familysync',
+        etag: '"etag-abc"',
+        objectUrl: 'https://caldav.fastmail.com/dav/calendars/user/test@fm.com/Default/uid-001.ics',
+        calendarId: 1,
+        calendarUrl: 'https://caldav.fastmail.com/dav/calendars/user/test@fm.com/Default/',
+        userId: 1,
+        rawVevent: SAMPLE_VEVENT_RECURRING_TIMED,
+      },
+    ]
+    const mockInnerJoinWhere = vi.fn().mockReturnValue({
+      orderBy: vi.fn().mockReturnValue({
+        limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+      }),
+    })
+    const mockInnerJoin = vi.fn().mockReturnValue({ where: mockInnerJoinWhere })
+    mockFromFn.mockReturnValue({ innerJoin: mockInnerJoin })
+    mockSelectFn.mockReturnValue({ from: mockFromFn })
+
+    const { app } = await import('../../src/index.js')
+    const res = await app.request('/api/events/uid-001%40familysync/edit', {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        title: 'Moved event',
+        allDay: false,
+        start: '2026-06-15T10:00:00Z',
+        end: '2026-06-15T11:00:00Z',
+        // Different calendarUrl than the source → triggers the edit-as-move path (D-04)
+        calendarUrl: 'https://caldav.fastmail.com/dav/calendars/user/test@fm.com/Family/',
+      }),
+    })
+    expect(res.status).toBe(202)
+
+    // The move inserts a delete+create pair inside a transaction. Find the create row's
+    // payload and assert the preserved RRULE survived.
+    const createInsertCall = mockInsertValuesFn.mock.calls.find((call) => {
+      const arg = call[0] as { operation?: string; payload?: string }
+      return arg?.operation === 'create'
+    })
+    expect(createInsertCall).toBeDefined()
+    const createArg = createInsertCall![0] as { payload: string }
+    const parsed = JSON.parse(createArg.payload) as { _preservedRrule?: string }
+    expect(parsed._preservedRrule).toBe('FREQ=WEEKLY;BYDAY=MO')
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -426,9 +485,14 @@ describe('DELETE /api/events/:uid', () => {
         userId: 1,
       },
     ]
-    // After BUG 1 fix, the delete lookup uses .from(calendarEvents).innerJoin(calendars, ...).where(...)
-    // Wire mockFromFn to expose innerJoin → where so the handler resolves mockDbRows.
-    const mockInnerJoinWhere = vi.fn().mockImplementation(() => Promise.resolve(mockDbRows))
+    // After BUG 1 + CR-01 fix, the delete lookup uses
+    // .from(calendarEvents).innerJoin(calendars, ...).where(...).orderBy(...).limit(1).
+    // Wire mockFromFn to expose innerJoin → where → orderBy → limit so the handler resolves mockDbRows.
+    const mockInnerJoinWhere = vi.fn().mockReturnValue({
+      orderBy: vi.fn().mockReturnValue({
+        limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+      }),
+    })
     const mockInnerJoin = vi.fn().mockReturnValue({ where: mockInnerJoinWhere })
     mockFromFn.mockReturnValue({ innerJoin: mockInnerJoin })
     mockSelectFn.mockReturnValue({ from: mockFromFn })
@@ -483,6 +547,46 @@ describe('GET /api/events/sync-status', () => {
     const body = await res.json() as { uid: string; status: string }
     expect(body.status).toBe('done')
   })
+
+  // WR-04 (iteration 2): with multiple rows for one uid, the query must rank a
+  // failed/dead row above a later done row so a silently-failed queued write is not
+  // masked by a subsequent success. The handler returns the top-ranked row's status and
+  // surfaces its error. The orderBy must include the status-priority CASE expression so
+  // the ranking is enforced in SQL (the mock cannot run real ORDER BY).
+  it('WR-04: prioritizes a dead row over a done row and surfaces its error', async () => {
+    // Seed the row the priority-ordered query WOULD return first: the dead one.
+    mockDbRows = [{ uid: 'uid-001@familysync', status: 'dead', lastError: 'boom', userId: 1 }]
+    const orderBySpy = vi.fn().mockReturnValue({
+      limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+    })
+    const mockSimpleWhere = vi.fn().mockReturnValue({ orderBy: orderBySpy })
+    mockFromFn.mockReturnValue({ where: mockSimpleWhere })
+    mockSelectFn.mockReturnValue({ from: mockFromFn })
+
+    const { app } = await import('../../src/index.js')
+    const res = await app.request('/api/events/sync-status?uid=uid-001%40familysync')
+    expect(res.status).toBe(200)
+    const body = (await res.json()) as { uid: string; status: string; error?: string }
+    expect(body.status).toBe('dead')
+    expect(body.error).toBe('boom')
+
+    // The status-priority CASE expression must be part of the ORDER BY (WR-04).
+    // Drizzle sql`` builds a SQL object whose static text lives in queryChunks; scan
+    // those for the literal 'case' rather than JSON.stringify (the Drizzle structures
+    // are circular and throw on serialization).
+    expect(orderBySpy).toHaveBeenCalled()
+    const orderByArgs = orderBySpy.mock.calls[0] as Array<{ queryChunks?: unknown[] }>
+    const caseText = orderByArgs
+      .flatMap((arg) => (Array.isArray(arg?.queryChunks) ? arg.queryChunks : []))
+      .map((chunk) => {
+        // String chunks are { value: string[] } (StringChunk); join their values.
+        const value = (chunk as { value?: unknown })?.value
+        return Array.isArray(value) ? value.join('') : ''
+      })
+      .join(' ')
+      .toLowerCase()
+    expect(caseText).toContain('case')
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -543,8 +647,12 @@ describe('CR-01: canonical client payload (title/start/end) accepted by server',
         userId: 1,
       },
     ]
-    // Edit lookup uses innerJoin after BUG 1 fix
-    const mockInnerJoinWhere = vi.fn().mockImplementation(() => Promise.resolve(mockDbRows))
+    // Edit lookup uses innerJoin → where → orderBy → limit after BUG 1 + CR-01 fix
+    const mockInnerJoinWhere = vi.fn().mockReturnValue({
+      orderBy: vi.fn().mockReturnValue({
+        limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+      }),
+    })
     const mockInnerJoin = vi.fn().mockReturnValue({ where: mockInnerJoinWhere })
     mockFromFn.mockReturnValue({ innerJoin: mockInnerJoin })
     mockSelectFn.mockReturnValue({ from: mockFromFn })
@@ -674,9 +782,14 @@ describe('regression: edit/delete lookups join calendars (BUG 1)', () => {
 
   beforeEach(() => {
     mockDbRows = [seededRow]
-    // Wire from() → innerJoin() → where(); the innerJoin spy proves the handler
-    // routes through the join rather than calling .where() directly on from().
-    const innerJoinWhere = vi.fn().mockImplementation(() => Promise.resolve(mockDbRows))
+    // Wire from() → innerJoin() → where() → orderBy() → limit(); the innerJoin spy
+    // proves the handler routes through the join rather than calling .where() directly
+    // on from(). The CR-01 fix appends .orderBy(...).limit(1) after .where(...).
+    const innerJoinWhere = vi.fn().mockReturnValue({
+      orderBy: vi.fn().mockReturnValue({
+        limit: vi.fn().mockImplementation(() => Promise.resolve(mockDbRows)),
+      }),
+    })
     innerJoinSpy = vi.fn().mockReturnValue({ where: innerJoinWhere })
     mockFromFn.mockReturnValue({ innerJoin: innerJoinSpy })
     mockSelectFn.mockReturnValue({ from: mockFromFn })

apps/pwa/src/api/client.ts

@@ -138,7 +138,10 @@ export interface CreateEventPayload {
   allDay: boolean
   start: string            // 'YYYY-MM-DD' for allDay; ISO 8601 for timed
   end: string              // same format as start
-  recurrence: RecurrencePreset
+  // WR-01: optional. CREATE always sends it; EDIT omits it so the API/worker preserve
+  // the event's existing RRULE (the occurrence contract does not expose recurrence, so
+  // the form cannot echo it back without silently resetting it to 'none').
+  recurrence?: RecurrencePreset
   location?: string
   description?: string
   calendarUrl?: string     // omit to use the member's default writable calendar (D-01)

apps/pwa/src/components/CalendarShell.tsx

@@ -93,10 +93,22 @@ export function CalendarShell() {
     staleTime: 5 * 60 * 1000,
   })
 
-  // Fetch windowed occurrences — key includes start/end so navigation refetches
+  // Fetch windowed occurrences — key includes start/end so navigation refetches.
+  //
+  // enabled: meQuery.isSuccess is load-bearing for the OIDC login flow, not just
+  // an optimization. When unauthenticated, every /api/* request hits the OIDC
+  // guard, which 302-redirects to Authelia AND sets a fresh state cookie. If this
+  // query ran concurrently with fetchMe (and retried), each /api/events redirect
+  // would overwrite the OIDC state cookie mid-login — so the state returned to
+  // /callback no longer matched the cookie, producing OAUTH_INVALID_RESPONSE
+  // ("unexpected state parameter") and an Internal Server Error after Authelia.
+  // Gating on a successful /api/me means only fetchMe (redirect:'manual',
+  // retry:false) touches a guarded endpoint while unauthenticated, so the single
+  // top-level /api/login navigation owns the state cookie uncontested.
   const eventsQuery = useQuery({
     queryKey: ['events', start, end],
     queryFn: () => fetchEvents(start, end),
+    enabled: meQuery.isSuccess,
     retry: 2,
     staleTime: 5 * 60 * 1000,
   })
@@ -224,9 +236,15 @@ export function CalendarShell() {
 
   // ── Calendar content ───────────────────────────────────────────────────────
 
-  // The content panel (right of sidebar on desktop, full-width on phone)
-  function CalendarContent() {
-    return (
+  // The content panel (right of sidebar on desktop, full-width on phone).
+  //
+  // This is a plain JSX value, NOT a nested `function CalendarContent()` rendered
+  // as `<CalendarContent />`. A component defined inside render has a new identity
+  // every render, so React unmounts+remounts its entire subtree — including
+  // <ScheduleXCalendar> — on ANY CalendarShell re-render (popup/form close, post-
+  // write events refetch). That full remount is the "calendar flash" (Bug B). As
+  // an element value it reconciles in place across re-renders: no remount, no flash.
+  const calendarContent = (
       <div
         style={{
           flex: 1,
@@ -318,8 +336,7 @@ export function CalendarShell() {
           </div>
         )}
       </div>
-    )
-  }
+  )
 
   // ── Full layout ────────────────────────────────────────────────────────────
 
@@ -343,7 +360,7 @@ export function CalendarShell() {
           currentUserName={meQuery.data?.user.displayName ?? undefined}
         />
         <InstallPrompt />
-        <CalendarContent />
+        {calendarContent}
         <EventDetailPopover />
 
         {/* New Event FAB — phone: bottom-right floating action button (UI-SPEC §Interaction Contract) */}
@@ -445,7 +462,7 @@ export function CalendarShell() {
           </button>
         </div>
 
-        <CalendarContent />
+        {calendarContent}
       </div>
 
       {/* EventDetailPopover — standalone mode driven by Zustand openEventId */}

apps/pwa/src/components/EventForm.test.tsx

@@ -262,6 +262,36 @@ describe('EventForm', () => {
     expect(timeInputs.length).toBeGreaterThan(0)
   })
 
+  // WR-02 (iteration 2): toggling all-day ON deterministically clamps endDate to
+  // max(startDate, endDate). When the end day is BEHIND the start day, it snaps forward
+  // to a single-day event rather than validating as an inconsistent span, and any stale
+  // end-time error from the timed view is cleared.
+  it('toggling All-day ON clamps an end date that is behind the start date up to the start date', async () => {
+    renderForm()
+    fireEvent.change(screen.getByPlaceholderText('Event title'), {
+      target: { value: 'Span Title' },
+    })
+    const dateInputs = document.querySelectorAll('input[type="date"]')
+    expect(dateInputs.length).toBeGreaterThanOrEqual(2)
+    // Start 2026-06-10, end 2026-06-09 (end behind start) — invalid timed span
+    fireEvent.change(dateInputs[0], { target: { value: '2026-06-10' } })
+    fireEvent.change(dateInputs[1], { target: { value: '2026-06-09' } })
+
+    // Toggle all-day ON: endDate must clamp up to the start date (single-day event)
+    const allDaySwitch = screen.getByRole('switch')
+    fireEvent.click(allDaySwitch)
+
+    const dateInputsAfter = document.querySelectorAll('input[type="date"]')
+    expect((dateInputsAfter[1] as HTMLInputElement).value).toBe('2026-06-10')
+
+    // The clamped all-day event validates cleanly (no end-time error surfaced)
+    const saveButton = screen.getByText('Create Event')
+    fireEvent.click(saveButton)
+    await waitFor(() => {
+      expect(screen.queryByText('End time must be after start')).toBeNull()
+    })
+  })
+
   // ── Calendar picker D-02 ───────────────────────────────────────────────────
 
   it('calendar picker is absent when fetchWritableCalendars returns 1 calendar (D-02)', () => {
@@ -368,6 +398,39 @@ describe('EventForm', () => {
     })
   })
 
+  // WR-01 (iteration 2): edit mode shows explanatory helper text near the disabled
+  // recurrence select so the locked schedule is not a silent surprise.
+  it('WR-01: edit mode surfaces helper text that repeat cannot be changed', () => {
+    renderForm({ mode: 'edit', uid: 'edit-uid-456', eventOccurrence: EDIT_OCCURRENCE })
+    expect(screen.getByText(/Repeat can't be changed yet/i)).toBeDefined()
+  })
+
+  it('WR-01: create mode does NOT show the repeat helper text', () => {
+    renderForm({ mode: 'create' })
+    expect(screen.queryByText(/Repeat can't be changed yet/i)).toBeNull()
+  })
+
+  // IN-02 (iteration 2): in edit mode an unparseable cached start/end must leave the
+  // field blank and block submit, rather than silently rewriting the event to today/09:00.
+  it('IN-02: edit mode with an unparseable start leaves the date blank and blocks submit', async () => {
+    const corruptOccurrence: CalendarOccurrence = {
+      ...EDIT_OCCURRENCE,
+      start: 'not-a-real-date',
+    }
+    renderForm({ mode: 'edit', uid: 'edit-uid-456', eventOccurrence: corruptOccurrence })
+
+    // The start date input must be blank (not today's date)
+    const dateInputs = document.querySelectorAll('input[type="date"]')
+    expect((dateInputs[0] as HTMLInputElement).value).toBe('')
+
+    // Submit must be blocked with a guidance message; updateEvent must NOT fire.
+    fireEvent.click(screen.getByText('Save Changes'))
+    await waitFor(() => {
+      expect(screen.getByText(/Couldn't read this event's date/i)).toBeDefined()
+    })
+    expect(mockUpdateEvent).not.toHaveBeenCalled()
+  })
+
   // ── Close behaviors ────────────────────────────────────────────────────────
 
   it('pressing Escape closes the form', () => {

apps/pwa/src/components/EventForm.tsx

@@ -74,6 +74,27 @@ function writeLastCalendarUrl(url: string): void {
   }
 }
 
+/**
+ * CR-03: convert an EXCLUSIVE all-day end date ('YYYY-MM-DD') to the INCLUSIVE
+ * last day the form displays. The occurrence/expand contract keeps all-day ends
+ * exclusive (matching the DTEND Fastmail stores, RFC-5545 §3.6.1), and
+ * buildVeventString re-advances the inclusive form value by one day on write.
+ * Without this subtraction, round-tripping an edit re-advances an already-exclusive
+ * end, silently growing multi-day all-day events by one day per save. Parses by
+ * UTC components so the roll-back is DST-safe (mirrors vevent.ts's roll-forward).
+ */
+function exclusiveEndToInclusiveDate(dateStr: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateStr)
+  if (!m) return dateStr
+  const [, y, mo, d] = m
+  const date = new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d)))
+  date.setUTCDate(date.getUTCDate() - 1)
+  const yy = String(date.getUTCFullYear())
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0')
+  const dd = String(date.getUTCDate()).padStart(2, '0')
+  return `${yy}-${mm}-${dd}`
+}
+
 /**
  * Parse an ISO date string (possibly with time + offset) into
  * { date: 'YYYY-MM-DD', time: 'HH:MM' }. Falls back to today/09:00 if malformed.
@@ -83,13 +104,16 @@ function writeLastCalendarUrl(url: string): void {
  * Both date and time use getFullYear/getMonth/getDate/getHours/getMinutes so
  * the pair describes the same wall-clock consistently in the viewer's zone.
  */
-function parseDateTime(iso: string): { date: string; time: string } {
+function parseDateTime(iso: string): { date: string; time: string; ok: boolean } {
   try {
     // Strip IANA bracket suffix e.g. '[America/Toronto]'
     const clean = iso.replace(/\[[^\]]*\]$/, '')
-    if (/^\d{4}-\d{2}-\d{2}$/.test(iso)) {
+    // WR-03: test and return `clean`, not the raw `iso`. Testing `iso` would let a
+    // date-only value carrying a bracket suffix skip the all-day branch and fall through
+    // to new Date(clean); using `clean` matches the "strip IANA suffix" intent above.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(clean)) {
       // All-day date string — use as-is (no time component)
-      return { date: iso, time: '09:00' }
+      return { date: clean, time: '09:00', ok: true }
     }
     const d = new Date(clean)
     if (isNaN(d.getTime())) throw new Error('Invalid date')
@@ -100,12 +124,35 @@ function parseDateTime(iso: string): { date: string; time: string } {
     const day = String(d.getDate()).padStart(2, '0')
     const hours = String(d.getHours()).padStart(2, '0')
     const mins = String(d.getMinutes()).padStart(2, '0')
-    return { date: `${year}-${month}-${day}`, time: `${hours}:${mins}` }
+    return { date: `${year}-${month}-${day}`, time: `${hours}:${mins}`, ok: true }
   } catch {
-    return { date: todayIso(), time: '09:00' }
+    // IN-02: signal failure so the CREATE path can fall back to today/09:00 (a benign
+    // default for a brand-new event) while the EDIT path leaves the field blank and
+    // blocks submit — never silently rewriting a corrupt cached value to today/09:00.
+    return { date: todayIso(), time: '09:00', ok: false }
   }
 }
 
+/**
+ * IN-02: resolve the form's initial date/time for a pre-filled occurrence value.
+ * In CREATE mode (or when there is no occurrence) a parse failure falls back to the
+ * benign today/09:00 default. In EDIT mode a parse failure leaves the field BLANK so
+ * the user sees the value did not load and submit is blocked (validate() treats a blank
+ * start/end as invalid), rather than silently substituting today/09:00 and saving it.
+ */
+function initFormDateTime(
+  iso: string | undefined,
+  isEdit: boolean,
+  fallbackTime: string,
+): { date: string; time: string } {
+  if (iso === undefined) return { date: todayIso(), time: fallbackTime }
+  const parsed = parseDateTime(iso)
+  if (parsed.ok) return { date: parsed.date, time: parsed.time }
+  // Parse failed
+  if (isEdit) return { date: '', time: '' }
+  return { date: todayIso(), time: fallbackTime }
+}
+
 // ── Component ─────────────────────────────────────────────────────────────────
 
 export function EventForm() {
@@ -141,14 +188,21 @@ export function EventForm() {
 
   // ── Form state ──────────────────────────────────────────────────────────────
 
-  const initStart = occurrence ? parseDateTime(occurrence.start) : { date: todayIso(), time: '09:00' }
-  const initEnd = occurrence ? parseDateTime(occurrence.end) : { date: todayIso(), time: '10:00' }
+  const isEditMode = eventFormMode === 'edit' && !!eventFormUid
+  const initStart = initFormDateTime(occurrence?.start, isEditMode, '09:00')
+  const initEnd = initFormDateTime(occurrence?.end, isEditMode, '10:00')
+  // CR-03: occurrence.end for an all-day event is the EXCLUSIVE DTEND; the form's
+  // end-date input is the INCLUSIVE last day. Convert when pre-filling so a re-edit
+  // does not re-advance the span (buildVeventString rolls forward again on write).
+  // IN-02: skip the roll-back when initEnd.date is blank (parse failure in edit mode).
+  const initEndDate =
+    occurrence?.allDay && initEnd.date ? exclusiveEndToInclusiveDate(initEnd.date) : initEnd.date
 
   const [title, setTitle] = useState(occurrence?.title ?? '')
   const [allDay, setAllDay] = useState(occurrence?.allDay ?? false)
   const [startDate, setStartDate] = useState(initStart.date)
   const [startTime, setStartTime] = useState(initStart.time)
-  const [endDate, setEndDate] = useState(initEnd.date)
+  const [endDate, setEndDate] = useState(initEndDate)
   const [endTime, setEndTime] = useState(initEnd.time)
   const [recurrence, setRecurrence] = useState<RecurrencePreset>('none')
   const [location, setLocation] = useState(occurrence?.location ?? '')
@@ -177,13 +231,21 @@ export function EventForm() {
   // has hydrated the occurrence for the requested UID.
   useEffect(() => {
     if (eventFormOpen) {
-      const startParsed = occurrence ? parseDateTime(occurrence.start) : { date: todayIso(), time: '09:00' }
-      const endParsed = occurrence ? parseDateTime(occurrence.end) : { date: todayIso(), time: '10:00' }
+      const editMode = eventFormMode === 'edit' && !!eventFormUid
+      const startParsed = initFormDateTime(occurrence?.start, editMode, '09:00')
+      const endParsed = initFormDateTime(occurrence?.end, editMode, '10:00')
+      // CR-03: see exclusiveEndToInclusiveDate — pre-fill the inclusive last day for
+      // all-day events so re-saving an edit does not grow the span by a day each time.
+      // IN-02: skip the roll-back when endParsed.date is blank (parse failure in edit mode).
+      const endDateValue =
+        occurrence?.allDay && endParsed.date
+          ? exclusiveEndToInclusiveDate(endParsed.date)
+          : endParsed.date
       setTitle(occurrence?.title ?? '')
       setAllDay(occurrence?.allDay ?? false)
       setStartDate(startParsed.date)
       setStartTime(startParsed.time)
-      setEndDate(endParsed.date)
+      setEndDate(endDateValue)
       setEndTime(endParsed.time)
       // WR-03 recurrence: derive from occurrence if present; default 'none' only when
       // genuinely absent. Note: occurrence.recurrence is not in CalendarOccurrence type
@@ -231,9 +293,15 @@ export function EventForm() {
       setStartTime('09:00')
       setEndTime('10:00')
     }
-    if (next && endDate < startDate) {
-      // All-day ON: advance end date to match start date if it's behind
-      setEndDate(startDate)
+    if (next) {
+      // WR-02: turning all-day ON discards the time inputs, so a midnight-spanning
+      // timed event (start 06-10 23:00, end 06-11 01:00) would otherwise leave endDate
+      // at 06-11 — a 2-day all-day span the user did not intend. Clamp endDate to
+      // max(startDate, endDate) deterministically: when the end day is behind the start
+      // it snaps forward to a single-day event; an already-valid multi-day all-day span
+      // is preserved. Also clear any stale end-time error left over from the timed view.
+      setEndDate((prev) => (prev < startDate ? startDate : prev))
+      setErrors((prev) => (prev.endTime ? { ...prev, endTime: undefined } : prev))
     }
   }
 
@@ -244,6 +312,15 @@ export function EventForm() {
       newErrors.title = 'Title is required'
     }
 
+    // IN-02: a blank start/end date means a cached value failed to parse in edit mode
+    // (initFormDateTime left it empty rather than substituting today/09:00). Block submit
+    // so the corrupt value is never silently saved as today/09:00.
+    if (!startDate || !endDate || (!allDay && (!startTime || !endTime))) {
+      newErrors.endTime = "Couldn't read this event's date — re-open it from the calendar"
+      setErrors(newErrors)
+      return false
+    }
+
     if (!allDay) {
       const startISO = `${startDate}T${startTime}:00`
       const endISO = `${endDate}T${endTime}:00`
@@ -275,12 +352,19 @@ export function EventForm() {
       endTime,
     )
 
+    // WR-01: on EDIT, omit `recurrence` from the payload. The occurrence/expand contract
+    // does not expose the event's existing recurrence (D-03), so the form cannot know it
+    // and would otherwise send 'none' — silently stripping the RRULE and converting a
+    // recurring series into a single event. Omitting the field signals "unchanged"; the
+    // outbox worker then preserves the stored RRULE (see outboxWorker.ts WR-01). On
+    // CREATE the user explicitly chose a recurrence, so it is always sent.
+    const isEdit = eventFormMode === 'edit' && !!eventFormUid
     const payload: CreateEventPayload = {
       title: title.trim(),
       allDay,
       start: serializedStart,
       end: serializedEnd,
-      recurrence,
+      ...(isEdit ? {} : { recurrence }),
       ...(location.trim() ? { location: location.trim() } : {}),
       ...(description.trim() ? { description: description.trim() } : {}),
       ...(writableCalendars.length > 1 && calendarUrl ? { calendarUrl } : {}),
@@ -672,7 +756,11 @@ export function EventForm() {
           </div>
         )}
 
-        {/* Recurrence picker (D-11: whole-series only) */}
+        {/* Recurrence picker (D-11: whole-series only).
+            WR-01: disabled in edit mode — the occurrence contract does not expose the
+            event's recurrence, so the form cannot show/change it without risking a
+            silent reset. Editing recurrence is deferred until the contract exposes it;
+            the existing RRULE is preserved server-side on edit. */}
         <div style={fieldStyle}>
           <label htmlFor="event-recurrence" style={labelStyle}>
             Repeat
@@ -680,8 +768,14 @@ export function EventForm() {
           <select
             id="event-recurrence"
             value={recurrence}
+            disabled={eventFormMode === 'edit'}
             onChange={(e) => setRecurrence(e.target.value as RecurrencePreset)}
-            style={{ ...inputStyle, padding: '0 var(--space-3)', cursor: 'pointer' }}
+            style={{
+              ...inputStyle,
+              padding: '0 var(--space-3)',
+              cursor: eventFormMode === 'edit' ? 'not-allowed' : 'pointer',
+              opacity: eventFormMode === 'edit' ? 0.6 : 1,
+            }}
           >
             <option value="none">None</option>
             <option value="daily">Daily</option>
@@ -689,6 +783,21 @@ export function EventForm() {
             <option value="monthly">Monthly</option>
             <option value="yearly">Yearly</option>
           </select>
+          {/* WR-01: surface the v1 constraint so a user editing a recurring event is not
+              silently surprised that the schedule is locked. Additive helper text only —
+              the existing RRULE is preserved server-side on edit. */}
+          {eventFormMode === 'edit' && (
+            <div
+              style={{
+                fontSize: 'var(--text-label-size)',
+                color: 'var(--color-text-secondary)',
+                marginTop: 'var(--space-1)',
+              }}
+            >
+              {/* Plain text — XSS guard (T-03-15) */}
+              Repeat can&apos;t be changed yet — edits keep the existing schedule.
+            </div>
+          )}
         </div>
 
         {/* Location */}

apps/pwa/src/components/InstallPrompt.tsx

@@ -278,10 +278,27 @@ function WalkthroughSheet({ onClose }: WalkthroughSheetProps) {
  *
  * Mount this at the top level of CalendarShell, below the nav bar.
  */
+// IN-03: localStorage access is guarded — in private-mode / SSR contexts the API can
+// throw on read or write. Mirrors calendarStore.ts's pattern so a storage failure
+// degrades gracefully (treated as "not dismissed") instead of crashing the component.
+function readDismissed(): boolean {
+  try {
+    return localStorage.getItem('installPromptDismissed') === '1'
+  } catch {
+    return false
+  }
+}
+
+function persistDismissed(): void {
+  try {
+    localStorage.setItem('installPromptDismissed', '1')
+  } catch {
+    // Ignore write failures (private mode / storage disabled)
+  }
+}
+
 export function InstallPrompt() {
-  const [dismissed, setDismissed] = useState<boolean>(
-    () => localStorage.getItem('installPromptDismissed') === '1',
-  )
+  const [dismissed, setDismissed] = useState<boolean>(readDismissed)
   const [walkthroughOpen, setWalkthroughOpen] = useState(false)
   const { canInstall, triggerInstall } = useAndroidInstallPrompt()
 
@@ -295,7 +312,7 @@ export function InstallPrompt() {
   if (installed) return null
 
   function dismiss() {
-    localStorage.setItem('installPromptDismissed', '1')
+    persistDismissed()
     setDismissed(true)
   }
 

apps/pwa/src/components/SyncStateToast.tsx

@@ -50,7 +50,12 @@ export function SyncStateToast() {
   })
 
   const status = data?.status
-  const isConflict = status === 'failed' && data?.error?.includes('412')
+  // WR-06: an edit-as-move whose create hits 412 dead-ends with no retry path (the
+  // original event is preserved, but the new uid's only outbox row is failed). The
+  // worker tags that case with a 'move-failed:' lastError so we can show distinct copy
+  // guiding the user to re-open and re-save, rather than the etag-conflict copy.
+  const isMoveFailed = status === 'failed' && !!data?.error?.startsWith('move-failed')
+  const isConflict = status === 'failed' && !isMoveFailed && data?.error?.includes('412')
   const isPersistent = status === 'failed' || status === 'dead'
 
   // Invalidate events on done OR on conflict (D-06/D-08)
@@ -113,6 +118,16 @@ export function SyncStateToast() {
         aria-hidden="true"
       />
     )
+  } else if (isMoveFailed) {
+    // WR-06: the move could not be applied; the original event is unchanged.
+    copy = "Couldn't move the event. Open it and save again."
+    icon = (
+      <AlertCircle
+        size={14}
+        style={{ color: 'var(--color-destructive)', flexShrink: 0 }}
+        aria-hidden="true"
+      />
+    )
   } else if (status === 'failed') {
     copy = "Didn't save. Try again."
     icon = (

apps/pwa/src/lib/hydrateEvents.test.ts

@@ -76,6 +76,23 @@ describe('hydrateEvents — RED stubs (Wave 0)', () => {
       expect(evt.end).toBeInstanceOf(Temporal.PlainDate)
     })
 
+    it('converts an all-day exclusive DTEND to an inclusive last day for Schedule-X', () => {
+      // Single-day event: iCal DTSTART:24 / DTEND:25 (exclusive). Schedule-X end is
+      // inclusive, so a 1-day event must have start === end (renders on one day only).
+      const single = hydrateEvents([
+        makeOccurrence({ allDay: true, start: '2026-06-24', end: '2026-06-25' }),
+      ])[0]
+      expect((single.start as Temporal.PlainDate).toString()).toBe('2026-06-24')
+      expect((single.end as Temporal.PlainDate).toString()).toBe('2026-06-24')
+
+      // Two-day event: DTSTART:26 / DTEND:28 (exclusive) → inclusive last day = 27.
+      const multi = hydrateEvents([
+        makeOccurrence({ allDay: true, start: '2026-06-26', end: '2026-06-28' }),
+      ])[0]
+      expect((multi.start as Temporal.PlainDate).toString()).toBe('2026-06-26')
+      expect((multi.end as Temporal.PlainDate).toString()).toBe('2026-06-27')
+    })
+
     it('converts timed occurrence (allDay:false) to Temporal.ZonedDateTime for start and end', () => {
       const occurrences = [
         makeOccurrence({

apps/pwa/src/lib/hydrateEvents.ts

@@ -76,11 +76,24 @@ export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent
     if (occ.allDay) {
       // All-day: use Temporal.PlainDate — do NOT construct ZonedDateTime from
       // midnight UTC. occ.start and occ.end are 'YYYY-MM-DD' strings.
+      //
+      // Exclusive→inclusive end conversion: iCalendar all-day DTEND is EXCLUSIVE
+      // (a single-day event on the 24th is DTSTART:24 / DTEND:25), and the server
+      // occurrence carries that exclusive end. Schedule-X treats an all-day event's
+      // `end` as INCLUSIVE (the last day it covers), so passing the exclusive DTEND
+      // straight through renders every all-day event one day too long (a 1-day event
+      // showed across two days). Subtract one day to get the inclusive last day,
+      // clamped to never precede start.
+      const startPd = Temporal.PlainDate.from(occ.start)
+      const endExclusive = Temporal.PlainDate.from(occ.end)
+      const endInclusive = endExclusive.subtract({ days: 1 })
+      const end =
+        Temporal.PlainDate.compare(endInclusive, startPd) < 0 ? startPd : endInclusive
       return {
         id: occ.id,
         title: occ.title,
-        start: Temporal.PlainDate.from(occ.start),
-        end: Temporal.PlainDate.from(occ.end),
+        start: startPd,
+        end,
         calendarId,
         _familySync: {
           uid: occ.uid,