# Phase 5: Web Push Notifications - 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-09
**Phase:** 5-web-push-notifications
**Areas discussed:** Copy & anti-spam, Reminder scope & timing, Onboarding & opt-out

---

## Area selection

| Option                  | Description                              | Selected |
| ----------------------- | ---------------------------------------- | -------- |
| Copy & anti-spam        | Wording per type + coalescing            | ✓        |
| Reminder scope & timing | Whose events, fixed/custom lead, all-day | ✓        |
| Quiet hours / DND       | Suppress non-urgent in a quiet window    |          |
| Onboarding & opt-out    | When to prompt, toggle granularity       | ✓        |

**Notes:** Quiet hours/DND left to Claude's discretion (v1 = no quiet hours).

---

## Copy & anti-spam

### List-change batching

| Option                     | Description                                      | Selected |
| -------------------------- | ------------------------------------------------ | -------- |
| Coalesce per list          | Batch same-list changes in ~30–60s into one push | ✓        |
| Coalesce + skip check-offs | Same, but check-offs never push                  |          |
| One push per change        | Immediate, no batching                           |          |

### Detail level

| Option                         | Description                            | Selected |
| ------------------------------ | -------------------------------------- | -------- |
| Specific details               | Full specifics for everything          |          |
| Specific events, generic lists | Events show detail; list pings generic | ✓        |
| Generic only                   | Everything generic                     |          |

### Attribution

| Option         | Description         | Selected |
| -------------- | ------------------- | -------- |
| Name the actor | "Wife checked off…" | ✓        |
| No name        | "Milk checked off…" |          |

### Event-change granularity

| Option                  | Description                                             | Selected |
| ----------------------- | ------------------------------------------------------- | -------- |
| Meaningful changes only | new/delete/time/date/title/location; description silent | ✓        |
| Time/date only          | only reschedules + add/delete                           |          |
| Any change              | including description edits                             |          |

**User's choice:** Coalesce per list; specific-for-events/generic-for-lists; name the actor; meaningful changes only.
**Notes:** Generic-list + name-actor reconciled as "Wife made 3 changes to Groceries" (actor + list + count, no item text).

---

## Reminder scope & timing

### Whose events remind

| Option             | Description                     | Selected |
| ------------------ | ------------------------------- | -------- |
| Own + shared       | Own personal + shared Family    |          |
| Everything visible | Incl. partner's personal events |          |
| Shared only        | Shared Family calendar only     | ✓        |

### Lead time

| Option                   | Description            | Selected |
| ------------------------ | ---------------------- | -------- |
| Fixed 15 min (v1)        | Always ~15 min         | ✓        |
| User default, changeable | One global offset      |          |
| Per-event lead time      | Per-event offset field |          |

### All-day events

| Option         | Description    | Selected |
| -------------- | -------------- | -------- |
| Morning-of     | Fixed AM time  |          |
| No reminder    | Never push     | ✓        |
| Evening before | ~6pm prior day |          |

**User's choice:** Shared-only; fixed 15 min; no all-day reminder.
**Notes (load-bearing rationale, free-text):** "the native mail client on the device will still send notifications. we dont want to duplicate that." Personal-calendar reminders are already covered by each member's native device calendar app; FamilySync owns reminders for the shared Family calendar only. Confirmed deliberately after a challenge that this narrows NOTIF-01.

---

## Onboarding & opt-out

### Permission prompt timing

| Option                    | Description                         | Selected |
| ------------------------- | ----------------------------------- | -------- |
| Contextual, after install | Explainer + tap right after install | ✓        |
| On first relevant action  | After first event create            |          |
| Settings toggle only      | No auto-prompt                      |          |

### Opt-out granularity

| Option               | Description                   | Selected |
| -------------------- | ----------------------------- | -------- |
| Single master toggle | One on/off                    | ✓        |
| Per-category toggles | reminders/event/list switches |          |
| Master + categories  | Both                          |          |

### Dead-subscription recovery

| Option                       | Description                                   | Selected |
| ---------------------------- | --------------------------------------------- | -------- |
| Silent auto re-subscribe     | Background re-subscribe if permission granted | ✓        |
| Silent, then banner fallback | Banner if silent fails                        |          |
| Always prompt                | Banner on every death                         |          |

**User's choice:** Contextual after-install prompt; single master toggle; silent auto re-subscribe.

---

## Claude's Discretion

- No quiet-hours / DND in v1 (reminders/alerts always fire).
- Tap-to-open deep-link targets (reminder/event-change → event; list-change → `/lists/:id`).
- Service-worker strategy (generateSW vs injectManifest for push handler).
- VAPID key generation/storage, push-subscription table schema, reminder-scheduler mechanism, coalescing debounce, event-change detection source (poller vs outbox).

## Deferred Ideas

- Quiet hours / DND — v1.x
- Per-event / custom reminder lead time — v1.x
- Per-category opt-out — v1.x
- Reminders for personal-calendar events — intentionally excluded (native clients cover these)
- Notifying on own changes — out of scope

**Reviewed todos (not folded):** drizzle generate+migrate (false-positive "push" match, but schema constraint noted); new-project kickoff (stale).
