docs: correct rrule drift (code uses ical.js RecurExpansion) + minor fixes

Recurrence expansion uses ical.js ICAL.RecurExpansion, not the rrule
library (never installed/imported). Also fix playwright-cli path
(/usr/bin), prod-compose service count (two, post-Redis-removal), and
CI job count (six). Found via /gsd-docs-update --verify-only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/skills/playwright-cli/SKILL.md

@@ -193,11 +193,13 @@ playwright-cli --raw localstorage-get theme
 ```
 
 For structured output wrapping every reply as JSON, pass --json
+
 ```bash
 playwright-cli list --json
 ```
 
 ## Open parameters
+
 ```bash
 # Use specific browser when creating session
 playwright-cli open --browser=chrome
@@ -376,13 +378,13 @@ playwright-cli show --annotate
 
 ## Specific tasks
 
-* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
-* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
-* **Running Playwright code** [references/running-code.md](references/running-code.md)
-* **Browser session management** [references/session-management.md](references/session-management.md)
-* **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
-* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
-* **Test generation** [references/test-generation.md](references/test-generation.md)
-* **Tracing** [references/tracing.md](references/tracing.md)
-* **Video recording** [references/video-recording.md](references/video-recording.md)
-* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)
+- **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
+- **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+- **Running Playwright code** [references/running-code.md](references/running-code.md)
+- **Browser session management** [references/session-management.md](references/session-management.md)
+- **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
+- **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+- **Test generation** [references/test-generation.md](references/test-generation.md)
+- **Tracing** [references/tracing.md](references/tracing.md)
+- **Video recording** [references/video-recording.md](references/video-recording.md)
+- **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

.claude/skills/playwright-cli/references/running-code.md

@@ -17,7 +17,6 @@ You can also load the function from a file:
 playwright-cli run-code --filename=./my-script.js
 ```
 
-
 The code must be a single function expression, it is wrapped in `(...)` and evaluated.
 import/export/require syntax is not supported.
 

.claude/skills/playwright-cli/references/session-management.md

@@ -21,6 +21,7 @@ playwright-cli -s=public snapshot
 ## Browser Session Isolation Properties
 
 Each browser session has independent:
+
 - Cookies
 - LocalStorage / SessionStorage
 - IndexedDB

.claude/skills/playwright-cli/references/spec-driven-testing.md

@@ -32,7 +32,7 @@ npm init playwright@latest
 
 ### 1.2 Prerequisite: seed test
 
-A **seed test** is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start *after* the seed. `--debug=cli` pauses *inside* this test, so the seed is where every planning and generation session begins.
+A **seed test** is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start _after_ the seed. `--debug=cli` pauses _inside_ this test, so the seed is where every planning and generation session begins.
 
 Minimum viable seed:
 
@@ -124,13 +124,16 @@ Save under `specs/<feature>.plan.md`. Use this structure:
 **File:** `tests/<group>/<kebab-case-scenario-name>.spec.ts`
 
 **Steps:**
-  1. <Concrete user step>
-    - expect: <observable outcome>
-    - expect: <another observable outcome>
-  2. <Next step>
-    - expect: <outcome>
+
+1. <Concrete user step>
+   - expect: <observable outcome>
+   - expect: <another observable outcome>
+
+2. <Next step>
+   - expect: <outcome>
 
 #### 1.2. <next-scenario>
+
 ...
 
 ### 2. <Next Group>
@@ -189,7 +192,7 @@ Collect the generated code and write the test file at the path given in the spec
 ```ts
 // spec: specs/basic-operations.plan.md
 // seed: tests/seed.spec.ts
-import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file
+import { test, expect } from './fixtures'; // or '@playwright/test' if no fixtures file
 
 test.describe('Singing in and out', () => {
   test('should sign in', async ({ page }) => {
@@ -291,15 +294,15 @@ Only after the user answers, either update the spec (intentional change) or file
 ### 3.5 Iteration and giving up
 
 - Fix failures one at a time; rerun after each.
-- If after thorough investigation you are confident the test is correct but the app is wrong *and* the user has confirmed it's a bug: mark the test `test.fixme(...)` with a comment pointing at the user's decision or issue link. Never silently skip.
+- If after thorough investigation you are confident the test is correct but the app is wrong _and_ the user has confirmed it's a bug: mark the test `test.fixme(...)` with a comment pointing at the user's decision or issue link. Never silently skip.
 
 ---
 
 ## Cross-references
 
-| For... | See |
-|---|---|
-| `--debug=cli` / attach mechanics | [playwright-tests.md](playwright-tests.md) |
-| How `playwright-cli` actions become TS | [test-generation.md](test-generation.md) |
-| Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md) |
-| Managing the CLI browser session | [session-management.md](session-management.md) |
+| For...                                         | See                                            |
+| ---------------------------------------------- | ---------------------------------------------- |
+| `--debug=cli` / attach mechanics               | [playwright-tests.md](playwright-tests.md)     |
+| How `playwright-cli` actions become TS         | [test-generation.md](test-generation.md)       |
+| Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md)       |
+| Managing the CLI browser session               | [session-management.md](session-management.md) |

.claude/skills/playwright-cli/references/tracing.md

@@ -24,6 +24,7 @@ When you start tracing, Playwright creates a `traces/` directory with several fi
 ### `trace-{timestamp}.trace`
 
 **Action log** - The main trace file containing:
+
 - Every action performed (clicks, fills, navigations)
 - DOM snapshots before and after each action
 - Screenshots at each step
@@ -34,6 +35,7 @@ When you start tracing, Playwright creates a `traces/` directory with several fi
 ### `trace-{timestamp}.network`
 
 **Network log** - Complete network activity:
+
 - All HTTP requests and responses
 - Request headers and bodies
 - Response headers and bodies
@@ -44,20 +46,21 @@ When you start tracing, Playwright creates a `traces/` directory with several fi
 ### `resources/`
 
 **Resources directory** - Cached resources:
+
 - Images, fonts, stylesheets, scripts
 - Response bodies for replay
 - Assets needed to reconstruct page state
 
 ## What Traces Capture
 
-| Category | Details |
-|----------|---------|
-| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
-| **DOM** | Full DOM snapshot before/after each action |
-| **Screenshots** | Visual state at each step |
-| **Network** | All requests, responses, headers, bodies, timing |
-| **Console** | All console.log, warn, error messages |
-| **Timing** | Precise timing for each operation |
+| Category        | Details                                            |
+| --------------- | -------------------------------------------------- |
+| **Actions**     | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM**         | Full DOM snapshot before/after each action         |
+| **Screenshots** | Visual state at each step                          |
+| **Network**     | All requests, responses, headers, bodies, timing   |
+| **Console**     | All console.log, warn, error messages              |
+| **Timing**      | Precise timing for each operation                  |
 
 ## Use Cases
 
@@ -102,14 +105,14 @@ playwright-cli tracing-stop
 
 ## Trace vs Video vs Screenshot
 
-| Feature | Trace | Video | Screenshot |
-|---------|-------|-------|------------|
-| **Format** | .trace file | .webm video | .png/.jpeg image |
-| **DOM inspection** | Yes | No | No |
-| **Network details** | Yes | No | No |
-| **Step-by-step replay** | Yes | Continuous | Single frame |
-| **File size** | Medium | Large | Small |
-| **Best for** | Debugging | Demos | Quick capture |
+| Feature                 | Trace       | Video       | Screenshot       |
+| ----------------------- | ----------- | ----------- | ---------------- |
+| **Format**              | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection**      | Yes         | No          | No               |
+| **Network details**     | Yes         | No          | No               |
+| **Step-by-step replay** | Yes         | Continuous  | Single frame     |
+| **File size**           | Medium      | Large       | Small            |
+| **Best for**            | Debugging   | Demos       | Quick capture    |
 
 ## Best Practices
 

.claude/skills/playwright-cli/references/video-recording.md

@@ -42,14 +42,14 @@ playwright-cli video-start recordings/checkout-test-run-42.webm
 When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
 It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
 
-1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
-2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
-3) Use playwright-cli run-code --filename your-script.js
+1. Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2. Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3. Use playwright-cli run-code --filename your-script.js
 
 **Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
 
 ```js
-async page => {
+async (page) => {
   await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
   await page.goto('https://demo.playwright.dev/todomvc');
 
@@ -63,7 +63,9 @@ async page => {
   });
 
   // Perform action
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page
+    .getByRole('textbox', { name: 'What needs to be done?' })
+    .pressSequentially('Walk the dog', { delay: 60 });
   await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
   await page.waitForTimeout(1000);
 
@@ -84,7 +86,9 @@ async page => {
   `);
 
   // Perform more actions while the annotation is visible
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page
+    .getByRole('textbox', { name: 'What needs to be done?' })
+    .pressSequentially('Buy groceries', { delay: 60 });
   await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
   await page.waitForTimeout(1500);
 
@@ -93,7 +97,8 @@ async page => {
 
   // You can also highlight relevant locators and provide contextual annotations.
   const bounds = await page.getByText('Walk the dog').boundingBox();
-  await page.screencast.showOverlay(`
+  await page.screencast.showOverlay(
+    `
     <div style="position: absolute;
       top: ${bounds.y}px;
       left: ${bounds.x}px;
@@ -111,31 +116,33 @@ async page => {
       font-size: 14px;
       color: white;">Check it out, it is right above this text
     </div>
-  `, { duration: 2000 });
+  `,
+    { duration: 2000 },
+  );
 
   await page.screencast.stop();
-}
+};
 ```
 
 Embrace creativity, overlays are powerful.
 
 ### Overlay API Summary
 
-| Method | Use Case |
-|--------|----------|
+| Method                                                                         | Use Case                                                                       |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
 | `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
-| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
-| `disposable.dispose()` | Remove a sticky overlay added without duration |
-| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+| `page.screencast.showOverlay(html, { duration? })`                             | Custom HTML overlay — use for callouts, labels, highlights                     |
+| `disposable.dispose()`                                                         | Remove a sticky overlay added without duration                                 |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()`            | Temporarily hide/show all overlays                                             |
 
 ## Tracing vs Video
 
-| Feature | Video | Tracing |
-|---------|-------|---------|
-| Output | WebM file | Trace file (viewable in Trace Viewer) |
-| Shows | Visual recording | DOM snapshots, network, console, actions |
-| Use case | Demos, documentation | Debugging, analysis |
-| Size | Larger | Smaller |
+| Feature  | Video                | Tracing                                  |
+| -------- | -------------------- | ---------------------------------------- |
+| Output   | WebM file            | Trace file (viewable in Trace Viewer)    |
+| Shows    | Visual recording     | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis                      |
+| Size     | Larger               | Smaller                                  |
 
 ## Limitations
 

.dockerignore

@@ -0,0 +1,60 @@
+# === Secrets and credentials (NEVER in build context) ===
+.env
+.env.*
+!.env.example
+# Phase 19 (D-15 / IMG-02): exclude the entire break-glass scripts directory so
+# reset-admin.ts and any future dev-only scripts never ship in the production image.
+apps/api/scripts/
+
+# === VCS (large and unnecessary) ===
+.git
+.gitignore
+
+# === Build artifacts (regenerated in-build) ===
+**/dist/
+**/.dist/
+
+# === Dependencies (reinstalled in-build) ===
+**/node_modules/
+
+# === Tests (not needed in build; keep out of prod) ===
+apps/api/tests/
+apps/api/test/
+apps/pwa/e2e/
+
+# === Playwright artifacts ===
+apps/pwa/test-results/
+apps/pwa/playwright-report/
+apps/pwa/blob-report/
+.playwright/
+.playwright-cli/
+
+# === Planning / docs / dev tooling ===
+.planning/
+docs/
+graphify-out/
+.venv/
+
+# === Editor / OS ===
+.vscode/
+.idea/
+.DS_Store
+
+# === CI / dev config files (not needed in image) ===
+.gitea/
+.markdownlint-cli2.jsonc
+.prettierignore
+.prettierrc
+eslint.config.js
+
+# === SQL dumps (if any) ===
+*.sql.dump
+*.sql.gz
+
+# NOTE: apps/api/src/db/migrations/*.sql are included in the build context
+# because the builder stage's `COPY apps/api ./apps/api` needs them.
+# However, migrations are applied at runtime (drizzle-kit migrate), not
+# baked into the image — they travel with the app source in builder stage only.
+# The production stage does NOT copy apps/api/src directly; it only copies
+# apps/api/dist (via --from=builder) and apps/api/package.json.
+# So migration .sql files in src/db/migrations/ never reach the production image.

.env.example

@@ -1,22 +1,37 @@
-# Database
-DB_HOST=mariadb
-DB_PORT=3306
-DB_USER=familysync
-DB_PASSWORD=
-DB_NAME=familysync
-DB_ROOT_PASSWORD=
+# FamilySync — environment variable reference
+# Copy to .env and fill in real values. .env is gitignored and must never be committed.
+#
+# Deployment: these vars are injected into the Docker Compose `api` service via
+# the `environment:` block in docker-compose.yml. All values are resolved at
+# container start time from the host .env file.
 
-# OIDC (Authelia) — fill in after registering the client
-OIDC_AUTH_SECRET=
-OIDC_ISSUER=
+# ── MariaDB ───────────────────────────────────────────────────────────────────
+DB_PASSWORD=change_me_strong_password
+DB_ROOT_PASSWORD=change_me_root_password
+
+# ── OIDC / Authelia ───────────────────────────────────────────────────────────
+# Authorization code + PKCE flow (client_secret_basic). See CLAUDE.md §Authelia.
+OIDC_AUTH_SECRET=change_me_32_char_secret_minimum
+OIDC_ISSUER=https://auth.example.com
 OIDC_CLIENT_ID=familysync
-OIDC_CLIENT_SECRET=
-OIDC_REDIRECT_URI=https://familysync.yourdomain.com/callback
-OIDC_AUTH_EXTERNAL_URL=https://familysync.yourdomain.com
+OIDC_CLIENT_SECRET=change_me_client_secret
+OIDC_REDIRECT_URI=https://familysync.example.com/callback
+OIDC_AUTH_EXTERNAL_URL=https://auth.example.com
+# Scopes granted by the Authelia client definition (must include offline_access for
+# refresh-token session persistence).
+OIDC_SCOPES=openid profile email offline_access
 
-# CalDAV broker encryption key — generate with:
-# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-APP_PASSWORD_ENCRYPTION_KEY=
+# ── App-password encryption ───────────────────────────────────────────────────
+# 32-byte hex key used to AES-256-GCM encrypt Fastmail app passwords at rest.
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+APP_PASSWORD_ENCRYPTION_KEY=change_me_64_hex_chars
 
-# DEV ONLY — injects a fixed dev user, skips Authelia. Hard-disabled when NODE_ENV=production. NEVER set in prod.
-# DEV_AUTH_BYPASS=true
+# ── VAPID — Web Push notifications (Phase 5) ─────────────────────────────────
+# Generate a keypair (one-time, per deployment):
+#   npx web-push generate-vapid-keys --json
+# VAPID_PUBLIC_KEY  is served to the PWA at GET /api/push/vapid-public-key (no secret).
+# VAPID_PRIVATE_KEY signs push messages — treat as a secret; never commit it.
+# VAPID_SUBJECT     is a contact URL (mailto: or https:) sent to push services.
+VAPID_PUBLIC_KEY=replace_with_url_safe_base64_public_key
+VAPID_PRIVATE_KEY=replace_with_url_safe_base64_private_key
+VAPID_SUBJECT=mailto:admin@familysync.example.com

.gitea/workflows/ci.yml

@@ -0,0 +1,525 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      pull-requests: read
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: dorny/paths-filter@v4
+        id: filter
+        with:
+          # 'every' + negation-only globs. dorny combines a filter's patterns with
+          # Array.some by default, and picomatch compiles '!.gitea/**' as "matches any
+          # path NOT under .gitea" — so under 'some' that single line matched EVERY
+          # non-.gitea file (incl. .planning/** and *.md), flipping code=true for
+          # doc-only PRs and silently running the heavy api/harness jobs (regression
+          # introduced by quick task 260613-dmw; the old positive allowlist also never
+          # actually excluded .gitea because '**/*.yml' already matched workflow files).
+          # With predicate-quantifier 'every' a changed file counts as "code" ONLY if it
+          # matches ALL patterns — i.e. it is outside .gitea/, outside .planning/, and is
+          # not Markdown. Verified against representative file sets in quick task 260613-fp9.
+          predicate-quantifier: 'every'
+          filters: |
+            code:
+              - '!.gitea/**'
+              - '!.planning/**'
+              - '!**/*.md'
+
+  fast-checks:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      # actions/cache@v4 intentionally omitted (D-PROBE-04). Installs now target the
+      # host-mounted pnpm store at /pnpm-store (see act_runner config.yaml container.options).
+      # Without the host mount the flag still works — pnpm creates an ephemeral store there.
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --store-dir /pnpm-store --prefer-offline
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Format check
+        run: pnpm format:check
+
+      - name: Markdown lint
+        run: pnpm md:lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: PWA unit tests
+        run: pnpm --filter @familysync/pwa test
+
+  api:
+    runs-on: ubuntu-latest
+    needs: [changes]
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
+    # Runs in PARALLEL with fast-checks (D-03) — skipped for doc-only PRs.
+    services:
+      mariadb:
+        image: mariadb:11
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: familysync
+          MARIADB_USER: familysync
+          MARIADB_PASSWORD: testpass
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+          --health-start-period=30s
+    # Throwaway creds scoped to the ephemeral service container — never production secrets (T-08-03).
+    env:
+      DB_HOST: mariadb
+      DB_PORT: 3306
+      DB_USER: familysync
+      DB_PASSWORD: testpass
+      DB_NAME: familysync
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      # actions/cache@v4 intentionally omitted (D-PROBE-04). Installs now target the
+      # host-mounted pnpm store at /pnpm-store (see act_runner config.yaml container.options).
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --store-dir /pnpm-store --prefer-offline
+
+      # Pitfall 11: service container healthy != MariaDB accepting connections.
+      # No mysql CLI in the runner image (D-PROBE-03); poll via the already-installed
+      # mysql2 driver using an inline Node script. 90s deadline covers cold-start InnoDB init.
+      - name: Wait for MariaDB to accept connections
+        # No mysql CLI in the runner image (D-PROBE-03). Poll via the mysql2 driver
+        # already installed in apps/pwa (devDependency). --input-type=commonjs forces
+        # CJS mode even though apps/pwa has "type":"module" in its package.json.
+        run: |
+          node --input-type=commonjs - <<'EOF'
+          const mysql = require('mysql2/promise');
+          const deadline = Date.now() + 90_000;
+          (async () => {
+            while (true) {
+              try {
+                const conn = await mysql.createConnection({
+                  host: process.env.DB_HOST,
+                  port: Number(process.env.DB_PORT ?? 3306),
+                  user: process.env.DB_USER,
+                  password: process.env.DB_PASSWORD,
+                  database: process.env.DB_NAME,
+                });
+                await conn.query('SELECT 1');
+                await conn.end();
+                console.log('MariaDB ready');
+                process.exit(0);
+              } catch (err) {
+                if (Date.now() >= deadline) {
+                  console.error('MariaDB did not become ready within 90s:', err.message);
+                  process.exit(1);
+                }
+                await new Promise(r => setTimeout(r, 3000));
+              }
+            }
+          })();
+          EOF
+        working-directory: apps/pwa
+
+      # Apply schema migrations. Uses drizzle-kit migrate (applies committed SQL files).
+      # Never use drizzle push — unsafe on MariaDB (emits destructive TRUNCATE diff, T-08-04).
+      - name: Run DB migrations
+        run: pnpm --filter @familysync/api db:migrate
+
+      # Full DB-backed API test suite (all tests in apps/api/tests/ require a real MariaDB).
+      - name: Run API tests
+        run: pnpm --filter @familysync/api test
+
+  harness:
+    runs-on: ubuntu-latest
+    needs: [changes]
+    if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
+    # Runs in PARALLEL with fast-checks (D-03) — skipped for doc-only PRs.
+    services:
+      mariadb:
+        image: mariadb:11
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: familysync
+          MARIADB_USER: familysync
+          MARIADB_PASSWORD: testpass
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+          --health-start-period=30s
+    # Throwaway creds scoped to the ephemeral service container — never production secrets (T-08-06).
+    env:
+      DB_HOST: mariadb
+      DB_PORT: 3306
+      DB_USER: familysync
+      DB_PASSWORD: testpass
+      DB_NAME: familysync
+      # Persist Playwright browser binaries across runs via host-mounted /ms-playwright.
+      # Without the host mount CI still works — binaries are downloaded to the ephemeral dir.
+      PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      # actions/cache@v4 intentionally omitted (D-PROBE-04). Installs now target the
+      # host-mounted pnpm store at /pnpm-store (see act_runner config.yaml container.options).
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --store-dir /pnpm-store --prefer-offline
+
+      # Pitfall 11: service container healthy != MariaDB accepting connections.
+      # No mysql CLI in the runner image (D-PROBE-03); poll via the mysql2 driver
+      # already installed in apps/pwa (devDependency). --input-type=commonjs forces
+      # CJS mode even though apps/pwa has "type":"module" in its package.json.
+      - name: Wait for MariaDB to accept connections
+        run: |
+          node --input-type=commonjs - <<'EOF'
+          const mysql = require('mysql2/promise');
+          const deadline = Date.now() + 90_000;
+          (async () => {
+            while (true) {
+              try {
+                const conn = await mysql.createConnection({
+                  host: process.env.DB_HOST,
+                  port: Number(process.env.DB_PORT ?? 3306),
+                  user: process.env.DB_USER,
+                  password: process.env.DB_PASSWORD,
+                  database: process.env.DB_NAME,
+                });
+                await conn.query('SELECT 1');
+                await conn.end();
+                console.log('MariaDB ready');
+                process.exit(0);
+              } catch (err) {
+                if (Date.now() >= deadline) {
+                  console.error('MariaDB did not become ready within 90s:', err.message);
+                  process.exit(1);
+                }
+                await new Promise(r => setTimeout(r, 3000));
+              }
+            }
+          })();
+          EOF
+        working-directory: apps/pwa
+
+      # Apply schema migrations. Uses drizzle-kit migrate (applies committed SQL files).
+      # Never use drizzle push — unsafe on MariaDB (emits destructive TRUNCATE diff, T-08-07).
+      - name: Run DB migrations
+        run: pnpm --filter @familysync/api db:migrate
+
+      # Seed the dev user (id=1). DEV_AUTH_BYPASS injects DEV_USER (id=1) into the request
+      # context in-memory only — it never writes a users row (devBypass.ts). global-setup.ts
+      # seeds calendars/lists/events for user_id=1 but ASSUMES that user row already exists
+      # (true on the dev DB, false on a fresh CI DB): without it the calendars INSERT IGNORE is
+      # silently skipped on the users FK, so calendar 10 is missing and the calendar_events
+      # insert fails its FK. Idempotent INSERT IGNORE; matches DEV_USER (oidc dev/dev-user, #4A90D9).
+      - name: Seed dev user (id=1)
+        run: |
+          node --input-type=commonjs - <<'EOF'
+          const mysql = require('mysql2/promise');
+          (async () => {
+            const conn = await mysql.createConnection({
+              host: process.env.DB_HOST,
+              port: Number(process.env.DB_PORT ?? 3306),
+              user: process.env.DB_USER,
+              password: process.env.DB_PASSWORD,
+              database: process.env.DB_NAME,
+            });
+            await conn.execute(
+              "INSERT IGNORE INTO users (id, oidc_iss, oidc_sub, display_name, color) VALUES (1, 'dev', 'dev-user', 'Dev User', '#4A90D9')",
+            );
+            console.log('seeded dev user id=1');
+            await conn.end();
+          })();
+          EOF
+        working-directory: apps/pwa
+
+      # Build the API before starting it — dist/ is gitignored and does not exist in CI (Pitfall 4).
+      - name: Build API
+        run: pnpm --filter @familysync/api build
+
+      # Install Playwright browsers with system deps BEFORE starting the API, so the long
+      # browser download does not run during the API's lifetime.
+      # Must run from apps/pwa/ where @playwright/test is installed (D-PROBE-05 confirmed exit 0).
+      # PLAYWRIGHT_BROWSERS_PATH=/ms-playwright (job-level env) persists binaries across runs via
+      # the host-mounted dir. The --with-deps apt step cannot be cached; baking a runner image
+      # with browsers preinstalled would also drop the --with-deps apt step (future optimization).
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps webkit chromium
+        working-directory: apps/pwa
+
+      # Start the API AND run the harness in ONE step. A bare `node &` started in an EARLIER
+      # step is reaped at the step boundary: CI run #7 proved :3000 was healthy during a
+      # separate "wait" step but dead by the time global-setup polled :5173/health → :3000
+      # (after the multi-minute browser install). Keeping the API a child of THIS step's shell
+      # guarantees it stays alive for the entire Playwright run.
+      # DEV_AUTH_BYPASS=true + NODE_ENV=development are set both inline and in env: — global-setup.ts
+      # refuses NODE_ENV=production and the API devBypass.ts checks development. DB_* come from env:.
+      # CI=true makes Playwright start Vite :5173 itself (reuseExistingServer=false), use
+      # retries:2/workers:1, and apply reporter:'github' — which --reporter=list,html overrides
+      # because Gitea does not render github annotations (Pitfall 5 / D-06). Both projects run.
+      # Phase 19 (AUTH-LOCAL-16, D-14/D-15): seed local_credentials for dev user (id=1).
+      # devSessionCookieMiddleware issues a local-session cookie on each /api/* request
+      # when DEV_AUTH_BYPASS=true and LOCAL_SESSION_SECRET is set, so the PWA login gate
+      # skips /login and existing specs still reach the authed app unchanged.
+      # global-setup.ts also seeds this row via hashPasswordInline — this step is a
+      # belt-and-suspenders seed for the initial CI DB state before Playwright runs.
+      # The dev password 'devpass' is NOT a secret — it only exists in the ephemeral CI DB.
+      - name: Seed local_credentials for dev user (id=1)
+        env:
+          DB_HOST: mariadb
+          DB_PORT: 3306
+          DB_USER: familysync
+          DB_PASSWORD: testpass
+          DB_NAME: familysync
+        run: |
+          node --input-type=commonjs - <<'EOF'
+          const mysql = require('mysql2/promise');
+          const crypto = require('crypto');
+          // Inline PHC scrypt hash (matches apps/api/src/auth/localCredentials.ts)
+          function hashPassword(password) {
+            const salt = crypto.randomBytes(16);
+            const hash = crypto.scryptSync(password, salt, 32, { N: 16384, r: 8, p: 1 });
+            return ['scrypt', 16384, 8, 1, salt.toString('base64url'), hash.toString('base64url')].join('$');
+          }
+          (async () => {
+            const conn = await mysql.createConnection({
+              host: process.env.DB_HOST,
+              port: Number(process.env.DB_PORT ?? 3306),
+              user: process.env.DB_USER,
+              password: process.env.DB_PASSWORD,
+              database: process.env.DB_NAME,
+            });
+            const passwordHash = hashPassword('devpass');
+            await conn.execute(
+              "INSERT INTO local_credentials (user_id, username, password_hash) VALUES (1, 'devuser', ?) ON DUPLICATE KEY UPDATE password_hash = VALUES(password_hash)",
+              [passwordHash],
+            );
+            console.log('seeded local_credentials for dev user id=1');
+            await conn.end();
+          })();
+          EOF
+        working-directory: apps/pwa
+
+      - name: Run harness (start API + Playwright iphone + pixel + desktop)
+        env:
+          CI: 'true'
+          # Use 127.0.0.1 (not localhost): the runner image resolves `localhost` to ::1 first,
+          # but the Vite dev server binds IPv4-only (127.0.0.1:5173). global-setup.ts uses Node
+          # fetch (no IPv4 fallback, unlike curl), so localhost→::1:5173 → ECONNREFUSED → its
+          # /health poll never returns 200. Proven via [::1]:5173 ECONNREFUSED vs 127.0.0.1:5173 200.
+          # --dns-result-order=ipv4first is defense-in-depth for any remaining localhost hop
+          # (Vite's /health proxy → localhost:3000; the API is dual-stack so that hop already works).
+          PLAYWRIGHT_BASE_URL: http://127.0.0.1:5173
+          NODE_OPTIONS: '--dns-result-order=ipv4first'
+          DEV_AUTH_BYPASS: 'true'
+          NODE_ENV: development
+          # Phase 19 (AUTH-LOCAL-16, D-14/D-15): LOCAL_SESSION_SECRET required for
+          # devSessionCookieMiddleware to issue real local-session cookies under bypass.
+          # This is a fixed dev-only value — NEVER a production secret.
+          # Must be >=32 chars (assertLocalSessionSecretSet boot guard skips in bypass mode,
+          # but the cookie signing requires a non-empty secret to function).
+          LOCAL_SESSION_SECRET: 'dev-secret-change-me-0000000000000000'
+          DB_HOST: mariadb
+          DB_PORT: 3306
+          DB_USER: familysync
+          DB_PASSWORD: testpass
+          DB_NAME: familysync
+        run: |
+          NODE_ENV=development DEV_AUTH_BYPASS=true node apps/api/dist/index.js &
+          API_PID=$!
+          echo "API PID: $API_PID"
+
+          # Wait for the API :3000/health before launching Playwright (D-02 / T-08-08).
+          deadline=$((SECONDS + 60))
+          until curl -sf http://localhost:3000/health > /dev/null 2>&1; do
+            if ! kill -0 "$API_PID" 2>/dev/null; then echo "API process exited before becoming ready"; exit 1; fi
+            if [ $SECONDS -ge $deadline ]; then echo "API did not become ready within 60s"; kill "$API_PID" 2>/dev/null || true; exit 1; fi
+            sleep 2
+          done
+          echo "API ready at :3000"
+
+          # Run the Phase 7/14 harness across all three profiles (iphone, pixel, desktop); preserve its exit code, always kill the API.
+          # Call the pwa test:e2e script DIRECTLY (single pnpm layer) and append --reporter without a
+          # `--` separator: `pnpm <root> test:e2e -- <args>` double-forwards the `--` into
+          # `playwright test -- <args>`, where playwright treats --reporter as a test-file filter →
+          # "No tests found" (run #10). The filtered single-layer form forwards the flag cleanly.
+          set +e
+          pnpm --filter @familysync/pwa test:e2e --reporter=list,html
+          rc=$?
+          kill "$API_PID" 2>/dev/null || true
+          exit $rc
+
+      # Upload traces/screenshots/videos on failure for debugging (D-06).
+      # MUST use ChristopherHX/gitea-upload-artifact@v4 — the standard upload-artifact action
+      # detects Gitea as GHES and aborts (Pitfall 6 / D-PROBE-06).
+      - name: Upload Playwright test artifacts
+        if: failure()
+        uses: https://github.com/ChristopherHX/gitea-upload-artifact@v4
+        with:
+          name: playwright-traces-${{ github.run_id }}
+          # Upload BOTH the raw traces/screenshots/videos (test-results/) AND the
+          # navigable HTML report (playwright-report/, built by --reporter=list,html).
+          # Without the report dir the most useful triage artifact for a remote CI
+          # failure is built on every run and then discarded at runner teardown (WR-02).
+          path: |
+            apps/pwa/test-results/
+            apps/pwa/playwright-report/
+          retention-days: 14
+
+  security:
+    runs-on: ubuntu-latest
+    needs: [changes]
+    if: github.event_name == 'pull_request'
+    # Runs in PARALLEL with fast-checks (D-15). gitleaks always runs (D-12 — secrets
+    # can appear in doc-only commits). pnpm audit + pnpm outdated run only on
+    # code/lockfile-changing PRs (step-level if: keeps the job always-running).
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required: base.sha must be locally available for git log range (Pitfall 3)
+
+      # ── Probe PR base/head SHA with merge-base fallback (A2 / OQ-1) ──────────
+      # github.event.pull_request.base.sha may be empty on some Gitea versions.
+      # If so, fall back to git merge-base to compute the real branch-point SHA.
+      - name: Probe PR base/head SHA
+        # WR-01: bind context values through env: so they are never substituted
+        # into the rendered shell body (script-injection vector — github.base_ref
+        # is an attacker-influenceable branch name). Reference them as already-
+        # quoted shell variables only.
+        env:
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_BASE_REF: ${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          echo "Event base.sha: $PR_BASE_SHA"
+          echo "Event head.sha: $PR_HEAD_SHA"
+          BASE_SHA="$PR_BASE_SHA"
+          HEAD_SHA="$PR_HEAD_SHA"
+          if [ -z "$BASE_SHA" ]; then
+            echo "base.sha empty — computing merge-base fallback"
+            BASE_SHA=$(git merge-base "$(git rev-parse "origin/$PR_BASE_REF")" HEAD)
+            echo "Computed BASE_SHA via merge-base: $BASE_SHA"
+          fi
+          # WR-03: mirror the base fallback for head so the scan range is never
+          # silently left half-empty (A.. only happens to default to A..HEAD).
+          if [ -z "$HEAD_SHA" ]; then
+            echo "head.sha empty — falling back to git rev-parse HEAD"
+            HEAD_SHA=$(git rev-parse HEAD)
+            echo "Computed HEAD_SHA via rev-parse: $HEAD_SHA"
+          fi
+          echo "Secret-scan range: ${BASE_SHA}..${HEAD_SHA}"
+          echo "BASE_SHA=$BASE_SHA" >> "$GITHUB_ENV"
+          echo "HEAD_SHA=$HEAD_SHA" >> "$GITHUB_ENV"
+
+      # ── Gitleaks (always runs, D-12) ─────────────────────────────────────────
+      - name: Install gitleaks
+        run: |
+          set -euo pipefail
+          VERSION=8.30.1
+          curl -sL \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${VERSION}/gitleaks_${VERSION}_linux_x64.tar.gz" \
+            | tar -xz gitleaks
+          chmod +x gitleaks
+          mv gitleaks /usr/local/bin/gitleaks
+
+      - name: Secret scan (PR diff, blocking)
+        run: |
+          set -euo pipefail
+          gitleaks git \
+            --log-opts="--no-merges ${BASE_SHA}..${HEAD_SHA}" \
+            --config .gitleaks.toml \
+            --baseline-path scripts/gitleaks-baseline.json \
+            --report-path /tmp/gitleaks-pr-report.json \
+            --exit-code 1
+
+      # ── pnpm audit + outdated (code-change PRs only, D-12) ───────────────────
+      # actions/cache@v4 intentionally omitted (D-PROBE-04). Installs now target the
+      # host-mounted pnpm store at /pnpm-store (see act_runner config.yaml container.options).
+
+      - uses: actions/setup-node@v4
+        if: needs.changes.outputs.code == 'true'
+        with:
+          node-version: '22'
+
+      - name: Enable pnpm
+        if: needs.changes.outputs.code == 'true'
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        if: needs.changes.outputs.code == 'true'
+        run: pnpm install --frozen-lockfile --store-dir /pnpm-store --prefer-offline
+
+      - name: Dependency audit (blocking on High+Critical)
+        if: needs.changes.outputs.code == 'true'
+        run: node scripts/check-audit.mjs
+
+      - name: Dependency outdated report (advisory only)
+        if: needs.changes.outputs.code == 'true'
+        run: node scripts/check-outdated.mjs
+        # Always exits 0 — log output only, never gates (D-06)
+
+  gate:
+    runs-on: ubuntu-latest
+    needs: [fast-checks, changes, api, harness, security]
+    if: always()
+    steps:
+      - name: Check all required jobs passed or were skipped
+        run: |
+          # fast-checks always runs — must be success
+          if [ "${{ needs.fast-checks.result }}" != "success" ]; then
+            echo "fast-checks: ${{ needs.fast-checks.result }}"
+            exit 1
+          fi
+          # security always runs (gitleaks fires on every PR, D-12) — must be success.
+          # NOT folded into the success-or-skipped loop below — security can never be skipped.
+          # NOTE: individual needs.X.result check (not wildcard) due to Gitea #31007.
+          if [ "${{ needs.security.result }}" != "success" ]; then
+            echo "security: ${{ needs.security.result }}"
+            exit 1
+          fi
+          # api and harness are conditionally skipped — success OR skipped are both acceptable
+          # NOTE: uses individual needs.X.result checks (not the wildcard aggregate) due to
+          # Gitea 1.26.2 bug #31007 where the wildcard expression returns false even when jobs succeed.
+          for result in "${{ needs.api.result }}" "${{ needs.harness.result }}"; do
+            if [ "$result" != "success" ] && [ "$result" != "skipped" ]; then
+              echo "Heavy job failed or was cancelled: $result"
+              exit 1
+            fi
+          done
+          echo "Gate passed."

.gitea/workflows/publish.yml

@@ -0,0 +1,182 @@
+# Publishing / Releases
+#
+# Trigger: push to main — i.e. when any PR merges — EXCEPT pushes whose changed
+# files are confined to .gitea/** (CI/workflow edits) and/or .planning/** (GSD
+# planning docs, which push straight to main under the unprotected .planning/*
+# branch-protection pattern). Those never alter the shipped image (.dockerignore
+# already excludes .planning), so the paths-ignore filter below skips a wasted
+# build + re-push. A push that also touches code/Dockerfile/manifests still publishes.
+# Image: git.bergerhouse.net/luckberg/familysync-api
+# Tags:
+#   :latest                        — moving pointer for easy pulls
+#   :<MILESTONE>-<shortsha>        — immutable, rollback-traceable (e.g. v1.1-98acff8)
+#
+# Required secret: REGISTRY_PAT — a Gitea Actions secret holding a PAT with write:package scope.
+# Named REGISTRY_PAT (not GITEA_*): Gitea reserves the GITEA_ prefix for secret names, so
+# GITEA_-prefixed names cannot be created. GITEA_TOKEN / GITHUB_TOKEN cannot push packages.
+#
+# Safety gate: branch protection on main, NOT a needs: dependency in this file.
+# The PR test jobs (fast-checks, api, harness, gate in ci.yml) run on pull_request — they
+# never run in the same workflow invocation as publish.yml. Tests gate the PR; main is
+# trusted to be green because direct push and force push are blocked and the two required
+# checks (CI / fast-checks, CI / gate) must pass before merge. CI / api and CI / harness
+# are conditionally skipped on doc-only PRs and are gated via the always-running CI / gate
+# aggregate rather than being required directly.
+#
+# To bump the milestone tag at a milestone boundary: edit MILESTONE below.
+
+name: Publish
+
+on:
+  push:
+    branches: [main]
+    # Doc/CI-only pushes produce a byte-identical image — skip the build entirely.
+    # paths-ignore skips the run only when EVERY changed file matches; a mixed
+    # push (code + .planning) still publishes.
+    paths-ignore:
+      - '.gitea/**'
+      - '.planning/**'
+
+env:
+  MILESTONE: v1.1
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Compute both image tags per D-04:
+      #   :latest        — moving pointer for easy pulls
+      #   :<milestone>-<shortsha> — immutable, rollback-traceable (e.g. v1.1-4303a1b)
+      # GITHUB_SHA is confirmed available in Gitea Actions (probe P-13).
+      # MILESTONE is read from the workflow-level env var (set to v1.1 above) — update at milestone boundaries.
+      - name: Compute image tags
+        id: tags
+        run: |
+          set -euo pipefail
+          # Fail closed if GITHUB_SHA is empty/unset (Gitea runner env parity is not
+          # guaranteed across versions). Without this guard SHORT_SHA degrades to ""
+          # and the immutable tag silently becomes :v1.1- — a valid-but-wrong tag that
+          # overwrites the milestone pointer and destroys rollback traceability (WR-03).
+          : "${GITHUB_SHA:?GITHUB_SHA is empty — refusing to build a malformed image tag}"
+          SHORT_SHA=${GITHUB_SHA:0:7}
+          MILESTONE="${{ env.MILESTONE }}"
+          echo "latest=git.bergerhouse.net/luckberg/familysync-api:latest" >> $GITHUB_OUTPUT
+          echo "sha_tag=git.bergerhouse.net/luckberg/familysync-api:${MILESTONE}-${SHORT_SHA}" >> $GITHUB_OUTPUT
+
+      # Pitfall 13 (load-bearing security step): PAT piped via stdin — never via -p/--password.
+      # GITEA_TOKEN/GITHUB_TOKEN cannot push packages; a PAT with write:package scope is required
+      # (confirmed: Gitea forum + registry docs). Token is masked by Gitea's secret-log scrubber
+      # and never echoed elsewhere or set as a plain env var.
+      # Secret is named REGISTRY_PAT (not GITEA_REGISTRY_PAT): Gitea reserves the GITEA_ prefix
+      # for secret names, so the GITEA_-prefixed name cannot be created.
+      - name: Docker login
+        # Bind the secret through env: so it is never substituted into the rendered
+        # script body. Read it as $REGISTRY_PAT and pipe with printf '%s' (echo is not
+        # safe for arbitrary strings — a trailing newline or shell-significant char
+        # would mangle the password into a confusing `unauthorized`) (WR-05).
+        env:
+          REGISTRY_PAT: ${{ secrets.REGISTRY_PAT }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$REGISTRY_PAT" | \
+          docker login git.bergerhouse.net \
+            --username luckberg \
+            --password-stdin
+
+      # Build from REPO ROOT (T-08-10): the Dockerfile copies the pnpm workspace manifest +
+      # lockfile from the root context; building from apps/api/ would fail to find them.
+      - name: Build production image
+        # DOCKER_BUILDKIT=1 is required: the Dockerfile uses `RUN --mount=type=cache`
+        # (BuildKit) to persist the pnpm store across builds. The legacy builder would
+        # fail on that syntax. BuildKit is default on Docker 23+, set explicitly for safety.
+        env:
+          DOCKER_BUILDKIT: '1'
+        run: |
+          set -euo pipefail
+          docker build --target production \
+            -f apps/api/Dockerfile \
+            -t ${{ steps.tags.outputs.latest }} \
+            -t ${{ steps.tags.outputs.sha_tag }} \
+            .
+
+      # ── D-10 image hygiene assertions — run AFTER build, BEFORE push ───────────
+      # A failure here stops the job before any push, so a regressed image can
+      # never be published (T-16-18 / T-16-19 / T-16-20).
+      - name: Image hygiene — static assertions
+        run: |
+          set -euo pipefail
+          # Assert .dockerignore exists
+          if [ ! -f ".dockerignore" ]; then
+            echo "FAIL: .dockerignore does not exist"
+            exit 1
+          fi
+          # Assert every forbidden pattern is an ACTIVE ignore rule (WR-05).
+          # Strip comment lines first, then fixed-string match so a commented-out
+          # "# .env was here" can't satisfy the check and "$pattern" is never
+          # treated as a regex (e.g. ".env" matching "denv").
+          for pattern in ".env" "node_modules" "apps/api/scripts" ".git" \
+                         ".planning" "apps/api/tests" "apps/pwa/e2e"; do
+            if ! grep -v '^[[:space:]]*#' .dockerignore | grep -qF "$pattern"; then
+              echo "FAIL: .dockerignore missing active rule: $pattern"
+              exit 1
+            fi
+          done
+          # Assert this workflow still pins --target production (D-10 / T-16-19)
+          if ! grep -q "\-\-target production" .gitea/workflows/publish.yml; then
+            echo "FAIL: publish.yml does not build --target production"
+            exit 1
+          fi
+          echo "Static image hygiene assertions PASSED."
+
+      # Boot-smoke: run the freshly-built production image with the forbidden
+      # NODE_ENV=production + DEV_AUTH_BYPASS=true combo and assert it refuses to
+      # boot — proving the D-08 guard (assertNotDevBypassInProduction) fires in
+      # the ACTUAL shipped image (T-16-18 / T-16-21).
+      # EXIT==0  → image started  → guard NOT working  → FAIL
+      # EXIT==124 → timeout (15s) → guard not firing   → FAIL
+      # Any other non-zero exit   → image refused boot → PASS
+      - name: Image hygiene — boot-smoke (must refuse dev-bypass in production)
+        run: |
+          set -euo pipefail
+          IMAGE="${{ steps.tags.outputs.sha_tag }}"
+          # WR-02: capture docker's exit code DIRECTLY, not a pipeline exit. Piping
+          # through `head -20` would let a chatty-but-booting regressed image emit
+          # 20 lines, SIGPIPE docker (exit 141), and false-PASS. Capture all output
+          # to a variable, then print a bounded slice for the log.
+          set +e
+          OUT=$(timeout 15 docker run --rm \
+            --env NODE_ENV=production \
+            --env DEV_AUTH_BYPASS=true \
+            "$IMAGE" 2>&1)
+          EXIT=$?
+          set -e
+          echo "$OUT" | head -20
+          # 0 (clean start) and 124 (timeout) both mean the guard did NOT refuse boot.
+          if [ "$EXIT" -eq 0 ] || [ "$EXIT" -eq 124 ]; then
+            echo "FAIL: Production image did not refuse DEV_AUTH_BYPASS=true (exit $EXIT)"
+            exit 1
+          fi
+          # Belt-and-suspenders: require the FATAL guard marker, so a refusal for
+          # some UNRELATED reason cannot masquerade as the guard working.
+          if ! echo "$OUT" | grep -q "DEV_AUTH_BYPASS=true is set in a production environment"; then
+            echo "FAIL: image refused boot (exit $EXIT) but NOT via the expected D-08 guard"
+            exit 1
+          fi
+          echo "PASS: Production image refused to start with DEV_AUTH_BYPASS=true (exit $EXIT)"
+
+      # Push the IMMUTABLE :<milestone>-<sha> tag FIRST. set -euo pipefail stops on
+      # the first failed push, so :latest is only moved after the immutable,
+      # rollback-traceable tag has landed — a failed second push can never leave
+      # :latest advanced without a corresponding rollback tag (WR-04).
+      - name: Push image
+        run: |
+          set -euo pipefail
+          docker push ${{ steps.tags.outputs.sha_tag }}   # immutable first (WR-04)
+          docker push ${{ steps.tags.outputs.latest }}    # move pointer only after immutable lands
+
+      # Always drop the stored credential from the runner after push (defence in depth).
+      - name: Docker logout
+        if: always()
+        run: docker logout git.bergerhouse.net || true

.gitignore

@@ -17,6 +17,9 @@ dist/
 *.swp
 *.swo
 
+# Claude Code local (per-machine) settings — never tracked
+.claude/settings.local.json
+
 # OS
 .DS_Store
 Thumbs.db
@@ -49,3 +52,24 @@ 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/graphs/.last-build-status.json
+.planning/research/.cache/
+
+# Transient workflow scratch
+.planning/tmp/
+
+# Playwright e2e harness outputs (regenerated every run; Phase 7 mobile test harness)
+apps/pwa/test-results/
+apps/pwa/playwright-report/
+apps/pwa/blob-report/
+
+# PWA icon generator intermediate output (pwa:icons renames these to canonical names)
+apps/pwa/public/pwa-64x64.png
+apps/pwa/public/pwa-192x192.png
+apps/pwa/public/pwa-512x512.png
+apps/pwa/public/maskable-icon-512x512.png
+apps/pwa/public/apple-touch-icon-180x180.png
+
+# MemPalace per-project files (issue #185)
+mempalace.yaml
+entities.json

.gitleaks.toml

@@ -0,0 +1,36 @@
+# .gitleaks.toml — gitleaks configuration
+# Repo: familysync
+
+title = "FamilySync gitleaks config"
+
+[extend]
+# Extend with the default ruleset (all standard secret patterns)
+useDefault = true
+
+[[allowlists]]
+description = "Test fixture VAPID keys — documented test-only values, not production keys"
+paths = ['''apps/api/tests/fixtures/vapid\.ts''']
+
+[[allowlists]]
+description = ".env.example — intentional placeholder/template values, not live secrets"
+paths = ['''\.env\.example$''']
+
+[[allowlists]]
+description = "apps/api/.env.spike — dev/spike values, not production secrets"
+paths = ['''apps/api/\.env\.spike$''']
+
+[[allowlists]]
+description = "apps/api/tests/broker/crypto.test.ts — synthetic AES-256-GCM test key assigned to process.env.APP_PASSWORD_ENCRYPTION_KEY in a Vitest beforeAll; not a real credential"
+paths = ['''apps/api/tests/broker/crypto\.test\.ts''']
+
+[[allowlists]]
+description = "apps/api/tests/routes/setup.test.ts — synthetic VAPID public/private test pair used to set process.env.VAPID_* in the setup-route tests; not a real credential (verified not present in .env)"
+paths = ['''apps/api/tests/routes/setup\.test\.ts''']
+
+[[allowlists]]
+description = "apps/api/tests/auth/localSession.test.ts — TEST_SECRET is a synthetic >=32-char JWT signing secret used only to exercise issue/verify cookie round-trips under Vitest; not a real credential (Phase 19)"
+paths = ['''apps/api/tests/auth/localSession\.test\.ts''']
+
+[[allowlists]]
+description = ".planning/ design docs are internal planning prose (PLAN/SUMMARY/SECURITY/etc.) that frequently discuss credentials, tokens, and auth — they trip generic regex rules (e.g. 'credential atomically, 409-equivalent') but never carry production secrets; not shipped in any image"
+paths = ['''\.planning/''']

.markdownlint-cli2.jsonc

@@ -0,0 +1,23 @@
+// .markdownlint-cli2.jsonc
+{
+  "config": {
+    // Disable all rules that conflict with Prettier (23 rules — line-length, list-indent,
+    // blanks-around-fences, emphasis-style, etc.)
+    "extends": "markdownlint/style/prettier",
+
+    // Content rules to KEEP:
+    "MD001": true, // heading-increment: no skipping h1→h3
+    "MD024": true, // no-duplicate-heading
+    "MD040": true, // fenced-code-language: all fences must declare a language
+    "MD031": true, // blanks-around-fences (re-enabled — see Pitfall 4 in RESEARCH.md)
+    "MD051": true, // link-fragments: broken anchor links
+    "MD052": true, // reference-links-images: undefined link references
+
+    // Rules DISABLED (Prettier owns these OR they fire on non-author-controlled files):
+    "MD041": false, // first-line-h1: CLAUDE.md legitimately starts with ## Project
+    "MD034": false, // no-bare-urls: CLAUDE.md version table uses pkg@version syntax
+    "MD036": false, // no-emphasis-as-heading: docs/API.md uses **Response 200** as label
+  },
+  "globs": ["docs/**/*.md", "*.md", "apps/**/*.md"],
+  "ignores": [".planning/**", "node_modules/**", "**/node_modules/**", ".pnpm-store/**"],
+}

.planning/HANDOFF.json

@@ -1,35 +1,78 @@
 {
   "version": "1.0",
-  "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,
+  "timestamp": "2026-06-10T02:49:45.903Z",
+  "phase": "05",
+  "phase_name": "web-push-notifications",
+  "phase_dir": ".planning/phases/05-web-push-notifications",
+  "plan": 8,
   "task": null,
   "total_tasks": null,
   "status": "paused",
-  "stage": "discuss-complete; entry-gate-cleared; ready-to-plan",
   "completed_tasks": [
-    {"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"}
+    {
+      "id": 1,
+      "name": "All 8 plans (05-01..05-08) executed across 5 waves, sequential (worktree degrade)",
+      "status": "done"
+    },
+    {
+      "id": 2,
+      "name": "Code review --fix --all --auto: 14 findings fixed over 3 iterations; 05-REVIEW.md clean",
+      "status": "done"
+    },
+    {
+      "id": 3,
+      "name": "Phase verification: 12/12 must-haves in code; NOTIF-01/02/03 traced; 05-VERIFICATION.md status human_needed",
+      "status": "done"
+    },
+    {
+      "id": 4,
+      "name": "5 device-only UAT items persisted to 05-UAT.md; ROADMAP reverted to pending device UAT",
+      "status": "done"
+    }
   ],
   "remaining_tasks": [
-    {"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"}
+    {
+      "id": 5,
+      "name": "On-device UAT (iOS 16.4+ Home-Screen PWA + Android) via /gsd-verify-work 5 — 5 items in 05-UAT.md",
+      "status": "not_started"
+    },
+    {
+      "id": 6,
+      "name": "After UAT passes, phase auto-transitions to complete (verify-work); milestone can advance to Phase 6",
+      "status": "not_started"
+    }
   ],
   "blockers": [],
   "human_actions_pending": [
-    {"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}
+    {
+      "action": "Run /gsd-verify-work 5 on a physical iOS device and an Android device",
+      "context": "Phase goal 'reliably on iOS and Android' is device-only; 5 UAT items cannot be automated (CLAUDE.md)",
+      "blocking": true
+    },
+    {
+      "action": "Create + share the 'Family' calendar and set is_shared=1 (Phase 2 D-16)",
+      "context": "Reminders (NOTIF-01/SC-1) only fire on shared Family-calendar events; needed before SC-1 has real events",
+      "blocking": false
+    }
   ],
   "decisions": [
-    {"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"}
+    {
+      "decision": "VAPID keypair generated by assistant; user pasted into root .env (gitignored); wired into docker-compose.yml env + .env.example",
+      "rationale": "Config env-injected for Docker transposability; no key baked into image; .env is permission-blocked from assistant Read/Write",
+      "phase": "05"
+    },
+    {
+      "decision": "Reverted premature ROADMAP [x] complete to [ ] pending device UAT",
+      "rationale": "Verification is human_needed; goal not confirmable without devices; avoid false completion claim",
+      "phase": "05"
+    },
+    {
+      "decision": "Ran code review --fix --all --auto rather than ship-then-fix",
+      "rationale": "4 Criticals (esp. iOS gesture gate) defeated success criteria; fixed before declaring done",
+      "phase": "05"
+    }
   ],
   "uncommitted_files": [],
-  "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."
+  "next_action": "Run /gsd-verify-work 5 on iOS + Android devices to close the 5 UAT items in 05-UAT.md. Dev MariaDB (familysync-mariadb-1, host port 3306) is up for any API re-checks.",
+  "context_notes": "Phase 5 is code-complete and fully verified at the code level (12/12). The only open work is on-device confirmation. The iOS user-gesture bug was the highest-stakes issue and was fixed correctly only on the 3rd review iteration (pre-resolve SW registration + VAPID key into state, disable Enable control until both ready, zero await before pushManager.subscribe()). Do NOT reintroduce any await between the tap and pushManager.subscribe() when touching push UI."
 }

.planning/MILESTONES.md

@@ -0,0 +1,56 @@
+# Milestones
+
+## v1.1 Operability & Polish (Shipped: 2026-06-18)
+
+**Scope:** 14 phases (7–20), 57 plans, ~110 tasks. Continues v1.0 numbering; merged to `main` across a series of phase PRs (latest #27).
+
+**Delivered:** Turned the v1.0 MVP into a configurable, administrable, and maintainable app — guided first-run setup, in-app role-gated admin, per-event reminders, near-instant write-back, local-auth (no-OIDC) mode, auto timezone — backed by a full self-hosted Gitea CI/CD pipeline (mobile + desktop e2e, security scanning, image hygiene, Docker publish) and a real lint gate. No more hand-editing env files or the database.
+
+**Key accomplishments:**
+
+- **Phase 7 — Mobile Test Harness:** Playwright harness (`@playwright/test`) with an iPhone/WebKit + Pixel/Chromium device matrix, SW-block, env-driven baseURL, deterministic dev-DB seed, and `DEV_AUTH_BYPASS` auth; layout/calendar/lists specs assert tap-targets, overflow, and populated/empty/error states. TEST-01/02. (Consumed by Phase 8 CI.)
+- **Phase 8 — Gitea CI:** Self-hosted Gitea Actions pipeline — parallel `fast-checks` (lint/typecheck/PWA unit) + `api` (MariaDB 11 service container + migrate + DB-backed tests) + `harness` (dev-stack bring-up + Phase 7 specs on both profiles) gating every PR to `main`, plus a publish job pushing the API production image (`:latest` + `:v1.1-<sha>`, `--password-stdin`). CI-01/02.
+- **Phase 9 — Faster Write-Back:** Event-driven outbox drain via a zero-dependency in-process EventEmitter (`outboxTrigger.ts`) — committed enqueues fire `signalOutboxDrain()` so edits land in ~1–2s instead of ~15s, preserving optimistic-202, create-before-delete, per-uid exactly-once, and the 15s fallback sweep. CAL-15.
+- **Phase 10 — Admin Role & Settings:** v1.1 DB foundation (`users.is_admin`, `member_credentials.provider_type`, `calendar_events.reminder_lead_minutes`, `app_config`); DB-backed `requireAdmin` gating all `/api/admin/*`; one shared `validateEncryptAndStoreCredential` (CalDAV PROPFIND + AES-256-GCM) for admin rotation + member self-service; gated `/admin` PWA route. ADMIN-01/02/03.
+- **Phase 11 — Per-Event Reminders:** Per-event reminder picker (None / 5m … 2d, all-day → 9 AM local) serialized as a VALARM, with a variable-lead scheduler (`uid:dtstartMs` dedup, dropped the hardcoded 15-min/shared-only restriction) that honors each event's lead, fires nothing without an alarm, and preserves VALARMs set in other clients. CAL-13/14, NOTIF-04/05/06.
+- **Phase 12 — Initial Setup Wizard:** Pre-auth `/api/setup/*` first-run wizard validating DB / VAPID / OIDC / app-password before completion, generating env secrets (never persisted to DB), promoting the completing user to admin, and locking with a 423 guard on every invocation. SETUP-01/02/03/04.
+- **Phase 13 — Real Lint Gate (ESLint):** ESLint flat config (typescript-eslint + React) across both apps + a Prettier `format:check` gate, turning the hollow `--if-present` no-op into a CI lint gate that actually fails; full first-run baseline cleanup to green.
+- **Phase 14 — Desktop E2E Coverage:** Added a `desktop` (Desktop Chrome, no-touch) Playwright project and made the mobile-authored specs desktop-safe, so the CI regression gate validates desktop as well as iphone/pixel.
+- **Phase 15 — Doc-Only CI Skip + Markdown Lint:** `dorny/paths-filter` classifies each PR so doc-only changes skip the slow `api`/`harness` jobs, with an always-running `gate` aggregate (avoids the required-check deadlock) and markdownlint-cli2 added to `fast-checks`.
+- **Phase 16 — CI Dependency Audit, Security & Image Hygiene:** Boot-time refuse-to-boot guard + baked `NODE_ENV=production` confining `DEV_AUTH_BYPASS` to dev; `pnpm audit` gate with GHSA waiver allowlist + tiered outdated report; eslint-plugin-security; gitleaks (clean 613-commit baseline) + `.dockerignore`; publish-time image-hygiene assertions. SEC/DEP/IMG/CI-03.
+- **Phase 17 — UI Optimization & Polish:** Fixed the long-standing phone BottomTabBar/FAB overlap (with a CI regression guard), shipped the real FamilySync logo + full favicon/PWA-icon set + brand accent, restructured `tokens.css` into a themeable semantic-token layer (light-only groundwork), and added a logout control + desktop-centered sheets + admin toasts.
+- **Phase 18 — Auto Timezone Detection:** Made the household timezone an explicit, stored, browser-auto-detected, admin-changeable setting (`getHouseholdTimezone(db)` + IANA validation), routing the all-day "9 AM local" reminder computation through it instead of the implicit `process.env.TZ`.
+- **Phase 19 — Local Auth (No-OIDC Mode):** Full local username/password account model (scrypt + stateless `local-session` JWT cookie, `local_credentials` table, rate-limit/lockout, login/logout, admin create/reset, self-change, OIDC-link, break-glass CLI) coexisting with the Authelia OIDC path — removing the hard dependency on a deployed Authelia.
+- **Phase 20 — Admin Member Editor & Form Declutter:** Replaced per-row Rotate/Reset buttons with a single tappable member-editor sheet (display name + local password + app password) over a new `PATCH /api/admin/members/:id` with a last-admin guard, and collapsed the Add-member form — retiring the confusing "Rotate" copy.
+
+**Requirements:** 17/17 v1.1 requirements complete (TEST, CI, CAL, ADMIN, NOTIF, SETUP). Phases 13–20 were driven by decision contracts (D-IDs / AUTH-LOCAL-*) rather than REQ-IDs. Deferred to backlog: self-service onboarding (999.5), provider abstraction (999.1), multiple reminders per event (v1.2), dark mode / theming (999.20), modern styling refresh (999.21).
+
+**Known deferred items at close:** none carried — all phase verifications (incl. Phase 11 & 17 human-needed checks) confirmed by the operator at close.
+
+---
+
+## v1.0 MVP (Shipped: 2026-06-10)
+
+**Scope:** 6 phases, 42 plans, 68 tasks. Shipped via Gitea PR #1 (`gsd/v1.0-milestone` → `main`, 375 commits).
+
+**Delivered:** A self-hosted, Dockerized family-organization PWA on the household's existing Fastmail account — unified color-coded calendar (shared + personal) with full event CRUD written back via CalDAV, installable PWA, shared collaborative lists with real-time co-edit sync, and Web Push notifications — usable cross-ecosystem with no app store.
+
+**Key accomplishments:**
+
+- **Phase 1 — Foundation + Broker Spike:** Authelia OIDC sessions with stable per-member identity (iss+sub) + auto-assigned color, AES-256-GCM credential encryption, and a tsdav CalDAV broker reading Fastmail calendars. CAL-08 resolved **GO** (per-member app-password model — no cross-account ACL).
+- **Phase 2 — Calendar Display:** Unified color-coded calendar across day/week/month/agenda with server-side occurrence expansion (VTIMEZONE/DST, all-day, EXDATE), each member's events in their assigned color.
+- **Phase 3 — Event Write-Back + PWA Install:** Full event CRUD written back to Fastmail (enqueue-only outbox, 202 optimistic-accept), installable PWA with auth-safe service worker and guided iOS install. Taken live over real Authelia/Pangolin and verified end-to-end on desktop and iOS.
+- **Phase 4 — Shared Lists + Live Sync:** Named collaborative lists with item CRUD, fractional-rank drag-reorder, and real-time SSE co-edit sync — member-scoped with no cross-tenant leak proven at the route layer.
+- **Phase 5 — Web Push Notifications:** VAPID push for event reminders, event-change alerts, and coalesced list-change notifications; resilient `setInterval` broker workers (poller/outbox/reminder) with catch-up + per-uid exactly-once dedup.
+- **Phase 6 — UX Polish:** All-day visual distinction, duration-preserving event end-tracking, RRULE UNTIL/COUNT bounding + whole-series edit prompt, pre-auth AuthSplash gating, session-expiry interstitial, and persistent nav chrome.
+
+**Requirements:** 20/20 v1 requirements complete (AUTH, CAL, PWA, LIST, NOTIF). Deferred out of scope: CAL-09…CAL-12 (v1.x), DISP-01/DISP-02 (v2).
+
+**Known deferred items at close** (acknowledged, device-only / live-infra — not regressions):
+
+- Phase 01 Gate-2 live checks (Authelia OIDC over Pangolin, iOS standalone install/redirect, session persistence) — carried under D-14; spot-check at go-live.
+- Phase 06 iOS device-only residuals: standalone cold-load + OIDC redirect (D-10/D-11), PushPermissionPrompt spinner (CP-04.3).
+- Android event-change push: server-side FCM delivery proven (201); on-device confirmation + operator channel-importance bump pending (05-UAT Test 4).
+- Stale `kickoff-new-project` todo (superseded; archived during 2026-06-10 backlog review).
+
+---

.planning/PROJECT.md

@@ -8,6 +8,18 @@ FamilySync is a self-hosted, Dockerized family organization hub for a two-person
 
 The household can see and co-edit one color-coded family calendar (shared + each member's personal) and shared lists from a single low-friction PWA — cross-ecosystem, no app store, no per-member calendar credential juggling.
 
+## Current State
+
+**Shipped: v1.1 Operability & Polish (2026-06-18)** — 14 phases (7–20), 57 plans. Full detail in [`MILESTONES.md`](MILESTONES.md) and [`milestones/v1.1-ROADMAP.md`](milestones/v1.1-ROADMAP.md).
+
+v1.1 turned the v1.0 MVP into a configurable, administrable, maintainable app: guided first-run setup wizard, role-gated in-app admin (credential rotation, shared-calendar designation, member editor), per-event reminders with a variable-lead scheduler, near-instant (~1–2s) event write-back, local-auth (no-OIDC) mode, and auto timezone detection — all backed by a full self-hosted Gitea CI/CD pipeline (mobile + desktop Playwright regression, a real ESLint gate, dependency/secret/security scanning, dev↔prod image hygiene, and Docker publish). No more hand-editing env files or the database.
+
+Deferred to backlog: self-service provider onboarding (999.5), provider abstraction (999.1), dark mode / theming (999.20), and a broader modern-styling refresh (999.21 — future milestone).
+
+## Next Milestone
+
+Not yet defined. Start with `/gsd-new-milestone` (questioning → research → requirements → roadmap). Candidate seeds in the backlog: dark mode / theming (999.20), modern visual refresh (999.21), self-service onboarding (999.5), provider abstraction (999.1), dev-user full-app exercise without a real calendar (999.19), and acting on the CI dependency report (999.18).
+
 ## Requirements
 
 ### Validated
@@ -18,13 +30,22 @@ The household can see and co-edit one color-coded family calendar (shared + each
 - [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).
+- [x] Shared collaborative lists (groceries, gift ideas) co-edited by both members, stored in MariaDB — **Validated in Phase 4 (shared-lists-live-sync)**: list + item CRUD, fractional-rank drag-reorder, member-scoped access (no cross-tenant leak proven at route layer).
+- [x] Live list sync so co-edits appear without manual refresh — **Validated in Phase 4**: scoped SSE fan-out over Pangolin (transport smoke-tested), bounded-backoff reconnect, co-edits land within seconds.
+- [x] Web Push notifications for event reminders and list changes — **Validated in Phase 5 (web-push-notifications)**: VAPID push for reminders, event-change, and coalesced list alerts; on-device UAT 1/2/5 PASS (iOS reminder delivery, iOS push, coalescing). Android event-change on-device confirmation + iOS standalone spinner remain device-only spot-checks at go-live.
+- [x] Faster write-back so edits reach Fastmail in ~1–2s instead of ~15s (CAL-15) — **Validated in Phase 9 (faster-write-back)**: event-driven outbox drain via a zero-dependency in-process EventEmitter (`outboxTrigger.ts`); a committed enqueue publishes a fire-and-forget `signalOutboxDrain()` that funnels through the existing `isDraining`-guarded drain with a `drainRequested` trailing-re-drain, preserving optimistic-202, create-before-delete on moves, exactly-once per uid, and the 15s `setInterval` fallback. 5/5 success criteria verified; trigger-wiring tests assert SC-1/D-05/D-07.
+- [x] Per-event reminders — choose a reminder lead per event (None / 5m / 10m / 15m / 30m / 1h / 2h / 1d / 2d, all-day → day-granularity + 9 AM fire), serialized as a VALARM, with a variable-lead scheduler that honors each event's lead (CAL-13/CAL-14, NOTIF-04/05/06) — **Validated in Phase 11 (per-event-reminders)**: pure VALARM serialization/classification layer (`buildTimedValarm`/`buildAllDayValarm`/`classifyValarms`/`extractValarms`/`computeAlertInstantUtc`); variable-lead scheduler with `uid:dtstartMs` dedup, dropped fixed-15-min/shared-only restriction, all-day 9 AM-local branch; `reminderLeadMinutes` threaded end-to-end with preserve-on-no-change (D-08); allDay-aware reminder picker with edit pre-population. Gap-closure (Plan 11-05) fixed two code-review blockers — custom/other-client VALARMs are now preserved on edit via a surfaced `reminderIsCustom` signal (CAL-14 / Pitfall 1), and the all-day push body no longer reads "Starts in 0 min" — plus post-event-trigger classification, a server-side max bound, and helper-text gating. 5/5 must-haves verified; 347 API + 206 PWA tests green. **Deferred:** live Fastmail VALARM round-trip + on-device push fire (untestable in dev — no provider connected; backlog 999.19).
+- [x] Admin role + role-gated settings surface to rotate member Fastmail app passwords and designate the shared calendar (ADMIN-01/02/03) — **Validated in Phase 10 (admin-role-settings)**: v1.1 DB foundation (`users.is_admin`, `member_credentials.provider_type`+`unique(user_id)`, `calendar_events.reminder_lead_minutes`, `app_config`) via an additive generate+migrate migration; DB-backed `requireAdmin` gating all `/api/admin/*` (client `isAdmin` UX-only, server 403 the real boundary, D-03); one shared `validateEncryptAndStoreCredential` helper for admin rotation + member self-service `/api/me/credential` (400-no-echo, session-userId only); exclusive shared-calendar designation made transactional + 404-guarded (CR-01 fix); gated `/admin` PWA route + conditional nav + `SetupBanner`. 12/12 must-haves verified; admin route-guard/nav-gating green in real Chromium (e2e 5/5). Deferred follow-ups: WR-01 bootstrap-race (Phase 12 reworks the bootstrap), broker `credentialSync.ts`/`CredentialSheet.tsx` crypto re-audit under full read access.
+- [x] Initial setup wizard — first-run validated bootstrap of env/secrets/DB/OIDC/VAPID/app-password instead of hand-editing files; locks once complete (SETUP-01/02/03/04) — **Validated in Phase 12 (initial-setup-wizard)**: pre-auth `/api/setup/*` router mounted before the OIDC guard; each input validated (DB connects, VAPID decodes to 32 bytes + pairs with the public key, OIDC discovery resolves, app password reaches CalDAV); generated secrets shown for env copy and never persisted to the DB; completing user promoted to admin and a 423 guard enforced on every invocation. First-login-claims rework in `upsertUser` (no email coupling).
+- [x] Self-hosted Gitea CI/CD + automated browser test coverage (TEST-01/02, CI-01/02) — **Validated in Phases 7/8/13/14/15/16**: a mobile (iPhone/WebKit + Pixel/Chromium) **and** desktop Playwright harness reached via `DEV_AUTH_BYPASS`; a PR pipeline gating lint (real ESLint flat config) / typecheck / unit / MariaDB-backed API integration / the headless harness; doc-only PRs skip the slow jobs via an always-running `gate` aggregate; dependency audit + gitleaks + eslint-plugin-security + dev↔prod image-hygiene assertions; and a publish job pushing the API production image on merge to `main`.
+- [x] Local-auth (no-OIDC) mode (AUTH-LOCAL-*) — **Validated in Phase 19 (local-auth-no-oidc-mode)**: full local username/password account model — scrypt hashing, stateless `local-session` JWT cookie, `local_credentials` table, rate-limit/lockout login + logout, admin create/reset member, self-change password, OIDC-link to claim a local user, and a break-glass reset-admin CLI — coexisting with the Authelia OIDC path, removing the hard dependency on a deployed Authelia for solo/small self-hosters.
+- [x] Household timezone as an explicit, stored, auto-detected, admin-changeable setting (Phase 18 D-01..D-07) — **Validated in Phase 18 (auto-timezone-detection)**: `getHouseholdTimezone(db)` with IANA validation is the source of truth for the all-day "9 AM local" reminder computation (replacing the implicit `process.env.TZ`), seeded from the browser at first run and changeable from `/admin`; browser-local display/timed-write path untouched.
+- [x] PWA visual identity + phone-layout polish + admin member editor (Phase 17 D-01..D-10, Phase 20 D-01..D-07) — **Validated in Phases 17 & 20**: fixed the phone BottomTabBar/FAB overlap (with a CI regression guard), shipped the real FamilySync logo + full favicon/PWA-icon set + brand accent, restructured `tokens.css` into a themeable semantic-token layer (light-only groundwork), added a logout control + desktop-centered sheets; and replaced the per-row Rotate/Reset buttons with a single tappable member-editor sheet over `PATCH /api/admin/members/:id` (last-admin guard), retiring the confusing "Rotate" copy.
 
 ### Active
 
-<!-- v1 scope. Hypotheses until shipped and validated. -->
-- [ ] 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)
-- [ ] Web Push notifications for event reminders and list changes
+<!-- Carried into v1.x — partially validated or device-pending. -->
+
 - [ ] 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)
 
@@ -47,10 +68,12 @@ The household can see and co-edit one color-coded family calendar (shared + each
 - **One app to build:** backend + MariaDB + React PWA behind Authelia, sitting on top of Fastmail. This is far lighter than the prior Baikal + Vikunja + PWA design that was evaluated and dropped.
 - **Calendars are all on Fastmail.** Personal calendars are also Fastmail-hosted calendar collections, so the app reads and writes everything (shared + personal) through a single Fastmail JMAP/CalDAV broker token — no external ICS feeds, no per-member credential management. The primary user gets the shared calendar natively in the Fastmail app; Apple members use the PWA (optionally subscribe in native Apple Calendar via CalDAV).
 - **Prior exploration:** Architecture was revised across two sessions (explore → Opus verification). See `.planning/notes/familysync-architecture.md` for full reasoning behind the dropped options.
-- **Open questions (for phase research):**
-  - Fastmail API — JMAP vs CalDAV for the app's calendar read/write. Which is cleaner to build against?
-  - PWA Web Push — sufficient/reliable enough for family alerts on iOS, or is a fallback needed?
-  - Mechanics of surfacing each member's *personal* Fastmail calendar to the broker token (calendar sharing/ACLs within Fastmail).
+- **Shipped state (v1.0, 2026-06-10):** pnpm monorepo — `apps/api` (Hono + Drizzle/MariaDB + tsdav/ical.js CalDAV broker) and `apps/pwa` (React 19 + Vite + vite-plugin-pwa + Schedule-X). Live over real Authelia OIDC + Pangolin/Newt. ~338 files changed across the milestone.
+- **Open questions — resolved this milestone:**
+  - Fastmail API → **CalDAV via tsdav** (JMAP calendars unavailable on Fastmail); locked.
+  - PWA Web Push → **sufficient with caveats**: VAPID direct push works on iOS 16.4+ installed PWAs and Android; iOS revokes subscriptions after 3 silent pushes (every push must be visible) and standalone install is mandatory. No FCM broker needed.
+  - Per-member personal calendar → **CAL-08 GO**: a per-member Fastmail app password reaches all of that account's calendars; no cross-account ACL. Onboarding flow to collect each member's app password is backlog 999.5.
+- **Known issues / tech debt carried to v1.x:** event write-back latency (15s outbox drain, 999.13); per-event reminder config / VALARM authoring (999.4); first-login provider setup (999.5); admin Settings + setup wizard (999.10/999.11); Gitea CI (999.14); mobile-emulated authed browser testing (999.12).
 
 ## Constraints
 
@@ -66,25 +89,29 @@ The household can see and co-edit one color-coded family calendar (shared + each
 
 ## Key Decisions
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| Calendar hosted on Fastmail, not self-hosted (Baikal dropped) | Fastmail reaches the whole household native-or-PWA with one fewer self-hosted service; Fastmail Android app can't show self-hosted CalDAV anyway | — Pending |
-| Personal calendars also Fastmail-hosted collections, aggregated via one broker token | Avoids external ICS feeds and per-member credential management; uniform read/write path | — Pending |
-| Shared lists in custom MariaDB, not Vikunja | Cross-ecosystem native task sync is impossible; a list table in the backend being built anyway is trivial vs another container + SSO integration | — Pending |
-| React PWA only, no React Native / App Store | App-like UX with one codebase for all surfaces; lowest onboarding friction (one URL) | — Pending |
-| Authelia OIDC for all members | True SSO consistent with existing infra; no separate calendar-credential problem | — Pending |
-| Web Push notifications in v1 (not deferred) | Family alerts judged essential day one; build push into the foundation | — Pending |
-| Personal-calendar overlay in v1 (not shared-only) | Unified view of everyone's schedules is the Skylight magic worth shipping early | — Validated (CAL-08 GO, Phase 1): per-member app password reaches all of an account's calendars; no cross-account ACL needed |
-| **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). |
+| Decision                                                                                                                                                                                                                                                                                                                                                                                                                                  | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Outcome                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Calendar hosted on Fastmail, not self-hosted (Baikal dropped)                                                                                                                                                                                                                                                                                                                                                                             | Fastmail reaches the whole household native-or-PWA with one fewer self-hosted service; Fastmail Android app can't show self-hosted CalDAV anyway                                                                                                                                                                                                                                                                                                                 | ✓ Validated (v1.0)                                                                                                                                                          |
+| Personal calendars also Fastmail-hosted collections, aggregated via one broker token                                                                                                                                                                                                                                                                                                                                                      | Avoids external ICS feeds and per-member credential management; uniform read/write path                                                                                                                                                                                                                                                                                                                                                                          | ✓ Validated (v1.0, CAL-08 GO)                                                                                                                                               |
+| Shared lists in custom MariaDB, not Vikunja                                                                                                                                                                                                                                                                                                                                                                                               | Cross-ecosystem native task sync is impossible; a list table in the backend being built anyway is trivial vs another container + SSO integration                                                                                                                                                                                                                                                                                                                 | ✓ Validated (v1.0, Phase 4)                                                                                                                                                 |
+| React PWA only, no React Native / App Store                                                                                                                                                                                                                                                                                                                                                                                               | App-like UX with one codebase for all surfaces; lowest onboarding friction (one URL)                                                                                                                                                                                                                                                                                                                                                                             | ✓ Validated (v1.0, Phase 3)                                                                                                                                                 |
+| Authelia OIDC for all members                                                                                                                                                                                                                                                                                                                                                                                                             | True SSO consistent with existing infra; no separate calendar-credential problem                                                                                                                                                                                                                                                                                                                                                                                 | ✓ Validated (v1.0, Phase 3)                                                                                                                                                 |
+| Web Push notifications in v1 (not deferred)                                                                                                                                                                                                                                                                                                                                                                                               | Family alerts judged essential day one; build push into the foundation                                                                                                                                                                                                                                                                                                                                                                                           | ✓ Validated (v1.0, Phase 5)                                                                                                                                                 |
+| Personal-calendar overlay in v1 (not shared-only)                                                                                                                                                                                                                                                                                                                                                                                         | Unified view of everyone's schedules is the Skylight magic worth shipping early                                                                                                                                                                                                                                                                                                                                                                                  | — Validated (CAL-08 GO, Phase 1): per-member app password reaches all of an account's calendars; no cross-account ACL needed                                                |
+| **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.                                                                                                                                        | ✓ Validated (Gate 2 executed live in Phase 3 / D-17)                                                                                                                        |
+| **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). | ✓ Resolved (2026-06-10): "FamilySync" shared calendar created on the primary account, synced as `calendars.id=10`, marked `is_shared=1`; shared lane + reminders now active |
+| **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).                                                           |
+| **D-18 (2026-06-12, Phase 9):** Faster write-back uses a **zero-dependency in-process EventEmitter** drain signal, not Redis — the drain is single-process by design; Redis stays only for list SSE. | The optimistic-202 outbox is single-process; an in-process signal funnelled through the existing `isDraining` guard preserves all durability guarantees without a new external dependency. (Redis was later removed entirely — quick 260618-smr — as it was unused at runtime.) | ✓ Validated (v1.1, Phase 9, CAL-15) |
+| **D-19 (2026-06-17, Phase 19):** FamilySync ships **local username/password auth as a first-class mode coexisting with Authelia OIDC**, not OIDC-only. | The operator runs it this way; a hard dependency on a deployed Authelia is too heavy for solo/small self-hosters. A local user can be linked to an OIDC identity later (claim flow, never email-matched per D-10). | ✓ Validated (v1.1, Phase 19) |
+| **D-20 (2026-06-11, Phase 8):** CI runs on the self-hosted Gitea runner with `runs-on: ubuntu-latest` (no self-hosted label) in Docker-executor mode; MariaDB readiness uses `healthcheck.sh --connect`, never `mysqladmin ping` (removed in MariaDB 11); the secret is `REGISTRY_PAT` (the `GITEA_` prefix is silently dropped). | Established by the runner-probe-first approach (PITFALLS 11/12); these constraints are load-bearing for every CI workflow in the repo. | ✓ Validated (v1.1, Phases 8/16, CI-01/02) |
 
 ## Evolution
 
 This document evolves at phase transitions and milestone boundaries.
 
 **After each phase transition** (via `/gsd-transition`):
+
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
@@ -92,10 +119,12 @@ This document evolves at phase transitions and milestone boundaries.
 5. "What This Is" still accurate? → Update if drifted
 
 **After each milestone** (via `/gsd-complete-milestone`):
+
 1. Full review of all sections
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
 4. Update Context with current state
 
 ---
-*Last updated: 2026-06-07 after Phase 3 (event-write-back-pwa-install)*
+
+_Last updated: 2026-06-18 after v1.1 milestone — Operability & Polish shipped (Phases 7–20, 57 plans): guided setup, in-app admin + member editor, per-event reminders, faster write-back, local-auth mode, auto timezone, and full Gitea CI/CD. Next milestone undefined — start with `/gsd-new-milestone`._

.planning/REQUIREMENTS.md

@@ -1,122 +0,0 @@
-# Requirements: FamilySync
-
-**Defined:** 2026-06-03
-**Core Value:** The household can see and co-edit one color-coded family calendar (shared + each member's personal) and shared lists from a single low-friction PWA — cross-ecosystem, no app store.
-
-## v1 Requirements
-
-Requirements for initial release. Each maps to roadmap phases.
-
-### Authentication & Onboarding
-
-> **Given:** Authelia is already deployed and both household members already have Authelia accounts. Auth scope is therefore app-side only — register FamilySync as an OIDC confidential client in Authelia and integrate the login flow. No Authelia deployment, no account provisioning.
-
-- [ ] **AUTH-01**: User can log in through Authelia (OIDC SSO) — no separate FamilySync account or password to create
-- [ ] **AUTH-02**: User stays logged in across sessions so re-authentication is rare (persistent session)
-- [ ] **AUTH-03**: Each member maps to a stable identity (OIDC `iss`+`sub`) and is assigned a consistent per-member color
-
-### Calendar
-
-- [ ] **CAL-01**: App reads the shared family Fastmail calendar via a CalDAV broker token and caches it locally (ctag polling)
-- [x] **CAL-02**: User sees a unified, color-coded calendar that aggregates every accessible calendar into one view
-- [x] **CAL-03**: User can switch between week, month, day, and agenda/list views
-- [x] **CAL-04**: User can create a timed or all-day event, written back to the correct Fastmail calendar
-- [x] **CAL-05**: User can edit an existing event
-- [x] **CAL-06**: User can delete an event
-- [x] **CAL-07**: User can create a recurring event and see all its occurrences expanded correctly (single-occurrence editing deferred to v1.x)
-- [ ] **CAL-08**: Each member's personal Fastmail calendar is overlaid into the unified view — *spike-gated in Phase 1*; if cross-account CalDAV sharing proves infeasible, v1 falls back to shared-family-only and this moves to v1.x
-
-### Lists
-
-- [ ] **LIST-01**: User can create and delete named lists (e.g. Groceries, Gift Ideas)
-- [ ] **LIST-02**: User can add items to a list, check them off, and delete them
-- [ ] **LIST-03**: User can reorder items within a list
-- [ ] **LIST-04**: Both members' list edits appear live for the other member without manual refresh
-
-### Notifications
-
-- [ ] **NOTIF-01**: User receives a Web Push reminder before an event starts
-- [ ] **NOTIF-02**: User receives a Web Push alert when the other member changes a shared list
-- [ ] **NOTIF-03**: User receives a Web Push alert when an event is added or changed
-
-### PWA & Install
-
-- [x] **PWA-01**: App is installable to the Home Screen on iPhone and Android (web manifest + service worker, served over HTTPS)
-- [x] **PWA-02**: First-time users get a guided "Add to Home Screen" prompt (prerequisite for iOS Web Push)
-
-## v1.x Requirements
-
-Deferred to a near-term follow-up release. Tracked but not in the v1 roadmap.
-
-### Calendar
-
-- **CAL-09**: User can edit/delete a single occurrence of a recurring event (RECURRENCE-ID / EXDATE)
-- **CAL-10**: User can apply a "this and following" edit to a recurring series
-- **CAL-11**: Documentation for subscribing to the Fastmail calendar natively in Apple Calendar via CalDAV (no new code)
-- **CAL-12**: Secondary-timezone display toggle for travel
-
-## v2 Requirements
-
-### Display
-
-- **DISP-01**: Always-on wall-display / kiosk dashboard view (Skylight-style)
-- **DISP-02**: Upcoming-events / agenda summary widget tuned for the wall display
-
-## Out of Scope
-
-Explicitly excluded. Documented to prevent scope creep. Anti-features sourced from research (`.planning/research/FEATURES.md`).
-
-| Feature | Reason |
-|---------|--------|
-| Email features | Members keep existing mail clients; never the product's job |
-| Self-hosted calendar server (Baikal/Radicale) | Fastmail hosts all calendars via CalDAV; one fewer service |
-| Vikunja / external task backend | Lists live in MariaDB; cross-ecosystem native task sync is impossible anyway |
-| React Native / App Store app | PWA delivers app-like UX without publishing overhead |
-| PostgreSQL | Not in the stack; MariaDB is the database |
-| Chores / rewards / star system | No children in the household; lists cover any task need |
-| Meal planning / recipe box | Separate domain, high cost; grocery list covers the coordination need |
-| Kids / sub-accounts | No children; irrelevant |
-| AI email-to-event import | Requires email access (out of scope) + LLM backend; privacy risk |
-| RSVP / invite flows (iTIP/iMIP) | Two people share one calendar; both attend by default |
-| Event-level comments / photos | Two people can text; adds chat/media storage for ~zero value |
-| Activity feed / audit log | Obvious with two users |
-| Multi-household / accounts at scale | One household, two hardcoded Authelia accounts |
-| Ads / monetization | Self-hosted; no revenue model |
-| Complex permissions / role tiers | Two equal partners with identical write access |
-| Offline-first with CRDT conflict resolution | Home WiFi is primary; optimistic updates + retry suffice |
-| Grocery delivery integration | Third-party dependency; not needed |
-
-## Traceability
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| AUTH-01 | Phase 1 | Pending |
-| AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| CAL-01 | Phase 1 | Pending |
-| CAL-08 | Phase 1 | Pending |
-| CAL-02 | Phase 2 | Complete |
-| CAL-03 | Phase 2 | Complete |
-| CAL-04 | Phase 3 | Complete |
-| CAL-05 | Phase 3 | Complete |
-| CAL-06 | Phase 3 | Complete |
-| CAL-07 | Phase 3 | Complete |
-| PWA-01 | Phase 3 | Complete |
-| PWA-02 | Phase 3 | Complete |
-| LIST-01 | Phase 4 | Pending |
-| LIST-02 | Phase 4 | Pending |
-| LIST-03 | Phase 4 | Pending |
-| LIST-04 | Phase 4 | Pending |
-| NOTIF-01 | Phase 5 | Pending |
-| NOTIF-02 | Phase 5 | Pending |
-| NOTIF-03 | Phase 5 | Pending |
-
-**Coverage:**
-
-- v1 requirements: 20 total
-- Mapped to phases: 20
-- Unmapped: 0 ✓
-
----
-*Requirements defined: 2026-06-03*
-*Last updated: 2026-06-03 — traceability populated by roadmapper*

.planning/RETROSPECTIVE.md

@@ -0,0 +1,115 @@
+# Project Retrospective
+
+_A living document updated after each milestone. Lessons feed forward into future planning._
+
+## Milestone: v1.0 — MVP
+
+**Shipped:** 2026-06-10
+**Phases:** 6 | **Plans:** 42 | **Sessions:** not tracked
+
+### What Was Built
+
+- Unified color-coded Fastmail calendar (shared + personal) with full event CRUD written back via CalDAV — read views, recurrence/DST expansion, all-day, and an enqueue-only outbox write path.
+- Installable React PWA behind Authelia OIDC, taken live over Pangolin/Newt and verified end-to-end on desktop and iOS.
+- Shared collaborative lists with real-time SSE co-edit sync, and VAPID Web Push for reminders / event-change / list alerts.
+
+### What Worked
+
+- **Dev-auth bypass to build behind a deferred gate (D-14):** Phases 2–3 were built against a documented bypass while live Authelia/Pangolin infra wasn't ready, with no rework when Gate 2 finally ran live in Phase 3.
+- **Wave-based parallel plans** within phases kept large phases (Phase 3 = 12 plans) moving.
+- **Enqueue-only outbox with optimistic 202** cleanly separated request handling from the slow CalDAV write, and made create-before-delete ordering + etag/412 handling tractable.
+
+### What Was Inefficient
+
+- **A long tail of bugs only reproduced under live conditions** (Newt MTU blackhole, OIDC state-cookie race, write-path timezone/identity/join/cache bugs, all-day off-by-one, color collisions, silent Android notifications, session-cookie expiry). Building behind the bypass too long delayed their discovery — they all surfaced at once during live bring-up.
+- **Background workers silently failed:** node-cron 4.2.1 skipped _every_ scheduled tick in the long-lived API process, so reminders/poller/outbox never fired on schedule — caught late, during Phase 5 UAT, not by tests.
+- **Repeated mobile-only defects could only be found by the operator on real devices** because the test harness is desktop-Chromium and the prod PWA is behind OIDC (→ backlog 999.12).
+
+### Patterns Established
+
+- **`setInterval`, not node-cron, for in-process schedulers** (node-cron silently no-ops in a long-lived process). Do not reintroduce node-cron.
+- **drizzle-kit `generate`+`migrate`, never `push`, on MariaDB** — `push` emits a false destructive (truncate) diff against populated MariaDB.
+- **iOS-Safari standalone behavior is a human/device checkpoint**, not a playwright-cli check — keep those as explicit manual gates.
+- **Run `tsc --noEmit` (both apps) in the post-merge gate** — esbuild strips types so vitest stays green while tsc fails.
+
+### Key Lessons
+
+1. Bring the real external topology (auth + tunnel) up _early_ and behind a small reversible config, rather than deferring all live verification — the live-only bug class is large and clusters at first contact.
+2. Long-running Node schedulers need an integration-level "does it actually fire on a tick" check; unit tests pass while the scheduler silently does nothing.
+3. Push has hard platform footguns (iOS revokes after 3 silent pushes; standalone install mandatory; VAPID key truncation = silent Apple 403) — encode them as guards from day one, not after a missed notification.
+
+### Cost Observations
+
+- Model mix: not tracked
+- Sessions: not tracked
+- Notable: TDD red→green discipline is visible in commit history, but per-commit `gate_status:` trailers were never emitted across the milestone — the ship-time TDD audit had nothing structured to aggregate. Wire gate_status trailers in v1.x if the audit is wanted.
+
+---
+
+## Milestone: v1.1 — Operability & Polish
+
+**Shipped:** 2026-06-18
+**Phases:** 14 (7–20) | **Plans:** 57 | **Sessions:** not tracked
+
+### What Was Built
+
+- A self-hosted Gitea CI/CD pipeline: PR-gating lint (real ESLint flat config) / typecheck / MariaDB-backed API integration / a mobile + desktop Playwright regression harness, plus dependency-audit / gitleaks / eslint-plugin-security / dev↔prod image-hygiene gates and a Docker publish on merge.
+- In-app operability: role-gated admin (credential rotation, shared-calendar designation, member editor), a validated first-run setup wizard, per-event reminders with a variable-lead scheduler, auto timezone detection, and ~1–2s event write-back.
+- A first-class local-auth (no-OIDC) mode coexisting with Authelia OIDC, removing the hard dependency on a deployed Authelia.
+
+### What Worked
+
+- **Backlog → phase promotion pipeline:** most of v1.1 (999.4/10/11/12/13/14/15/16) was captured as backlog during v1.0, then promoted cleanly into scoped phases — the deferred-idea capture paid off directly.
+- **Runner-probe-first for self-hosted CI (PITFALL 12):** probing `node`/`pnpm`/Docker/registry access on the Gitea runner *before* authoring any test/build steps surfaced every fork answer (Docker-executor, `ubuntu-latest`, artifact-fork, `REGISTRY_PAT` naming) up front and avoided blind CI iteration.
+- **Zero-dependency in-process solutions:** the EventEmitter outbox-drain signal (CAL-15) hit the latency goal with no new infra; the project later removed Redis entirely as unused.
+- **TDD discipline on the admin/auth chain** (Phases 10/11/12/19) kept the role boundary and credential-handling correct, with route-level 403/423/409 guards asserted in tests.
+
+### What Was Inefficient
+
+- **Dev user can't exercise calendar features end-to-end:** `DEV_AUTH_BYPASS` user 1 has no `member_credentials`/calendars, so per-event reminders (Phase 11) could only be verified via tests + a route-mocked smoke, not hands-on by the operator (→ backlog 999.19). Recurring dev-testability friction.
+- **Gitea-specific quirks cost cycles:** secrets with the `GITEA_` prefix are silently dropped (→ `REGISTRY_PAT`); `actions/upload-artifact@v4` is broken on Gitea (needs the `ChristopherHX` fork); `actions/cache@v4` timed out; skipped jobs may not emit a commit-status (drove the always-running `gate` aggregate). None are documented as GitHub-incompatible up front.
+- **Scope grew mid-milestone:** the milestone planned as 7–17 but accreted 18/19/20 via `/gsd-phase`, and the ROADMAP header wasn't kept in sync — the phase-detail sections for 18–20 ended up appended after the Backlog. Keep the roadmap header + section ordering current when inserting late phases.
+
+### Patterns Established
+
+- **Runner-probe-first** for any new self-hosted-CI capability — never author steps against an unprobed runner.
+- **Always-running `gate` aggregate** (`if: always()`, passes on success-or-skipped) is the only safe required-check surface when path-filtering jobs — never mark a path-filtered job itself required (deadlock).
+- **In-process EventEmitter over Redis** for single-process work (the outbox drain); reserve external infra for genuinely cross-process needs.
+- **Local auth is a first-class mode**, not a fallback — identity stays OIDC-`iss+sub` (never email); a local user is *linked* to an OIDC identity via an explicit claim flow (D-10/D-19).
+- **Confine dev-only affordances at build + boot:** bake `NODE_ENV=production` into the prod image and refuse-to-boot if `DEV_AUTH_BYPASS` is set — defense-in-depth beyond the runtime guard.
+
+### Key Lessons
+
+1. Capturing deferred ideas as structured backlog entries during one milestone makes the next milestone's roadmap nearly write-itself — invest in the capture.
+2. Self-hosted GitHub-Actions-compatible runners are *not* drop-in GitHub — probe the runtime, the action ecosystem (forks), and the status/secret semantics before designing the pipeline.
+3. Dev-environment testability is a feature: if the dev user can't exercise the real flows, every feature regresses to test-only verification and the operator can't UAT — fix the dev seed/provider story early (999.19).
+
+### Cost Observations
+
+- Model mix: not tracked
+- Sessions: not tracked
+- Notable: 14 phases shipped in ~8 days (2026-06-10 → 2026-06-18) with heavy parallelization across independent tracks (CI chain vs admin chain vs polish) once the harness landed.
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Sessions | Phases | Key Change                                                                                                                    |
+| --------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| v1.0      | n/a      | 6      | Established GSD plan→execute→verify→ship→complete loop; dev-auth bypass for gated infra; milestone-branch + Gitea PR shipping |
+| v1.1      | n/a      | 14     | Self-hosted Gitea CI/CD as the merge gate; per-phase branch + PR shipping; backlog→phase promotion pipeline; parallel independent tracks |
+
+### Cumulative Quality
+
+| Milestone | Tests                                 | Coverage     | Zero-Dep Additions                          |
+| --------- | ------------------------------------- | ------------ | ------------------------------------------- |
+| v1.0      | PWA 191 + API broker/events 114 green | not measured | n/a                                         |
+| v1.1      | PWA ~249 + API ~347 green             | not measured | `outboxTrigger.ts` EventEmitter (CAL-15); Redis later removed entirely as unused |
+
+### Top Lessons (Verified Across Milestones)
+
+1. **Capture deferred ideas as structured backlog during the milestone** — v1.1's roadmap came almost entirely from v1.0-era backlog entries.
+2. **iOS-Safari standalone / on-device push stays a human gate** across both milestones — automated harnesses (desktop + mobile-emulated) cover layout/flows, never the device-only behavior.
+3. **`setInterval` + in-process signals over external schedulers/brokers** for this single-process app — node-cron silently no-ops (v1.0), Redis went unused (v1.1).

.planning/ROADMAP.md

@@ -1,221 +1,74 @@
 # Roadmap: FamilySync
 
-## Overview
+## Milestones
 
-FamilySync is built in five phases, each delivering an end-to-end user-observable capability. Phase 1 is both the foundation and the highest-risk gate: OIDC auth must work and the CalDAV broker must prove it can read personal Fastmail calendars before any calendar UI is built. Phases 2–3 complete the calendar. Phase 4 delivers shared lists with live co-edit sync. Phase 5 wires up Web Push notifications. The dependency chain is strict: each phase is a prerequisite for the next, except the lists track (Phase 4) which is independent of the calendar write path.
+- ✅ **v1.0 MVP** — Phases 1–6 (shipped 2026-06-10) — see [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md)
+- ✅ **v1.1 Operability & Polish** — Phases 7–20 (shipped 2026-06-18) — see [`milestones/v1.1-ROADMAP.md`](milestones/v1.1-ROADMAP.md)
+
+> Next milestone not yet defined — start with `/gsd-new-milestone`.
 
 ## Phases
 
-**Phase Numbering:**
+<details>
+<summary>✅ v1.0 MVP (Phases 1–6) — SHIPPED 2026-06-10</summary>
 
-- Integer phases (1, 2, 3): Planned milestone work
-- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+- [x] Phase 1: Foundation + Broker Spike (4/4 plans) — completed 2026-06-04
+- [x] Phase 2: Calendar Display (5/5 plans) — completed 2026-06-05
+- [x] Phase 3: Event Write-Back + PWA Install (12/12 plans) — completed 2026-06-07
+- [x] Phase 4: Shared Lists + Live Sync (7/7 plans) — completed 2026-06-09
+- [x] Phase 5: Web Push Notifications (8/8 plans) — completed 2026-06-10
+- [x] Phase 6: UX Polish (6/6 plans) — completed 2026-06-10
 
-Decimal phases appear between their surrounding integers in numeric order.
+Full phase detail archived in [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md).
 
-- [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)
-- [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
+</details>
 
-## Phase Details
+<details>
+<summary>✅ v1.1 Operability & Polish (Phases 7–20) — SHIPPED 2026-06-18</summary>
 
-### Phase 1: Foundation + Broker Spike
+- [x] Phase 7: Mobile Test Harness (4/4 plans) — completed 2026-06-11
+- [x] Phase 8: Gitea CI (4/4 plans) — completed 2026-06-11
+- [x] Phase 9: Faster Write-Back (2/2 plans) — completed 2026-06-12
+- [x] Phase 10: Admin Role & Settings (4/4 plans) — completed 2026-06-13
+- [x] Phase 11: Per-Event Reminders (5/5 plans) — completed 2026-06-14
+- [x] Phase 12: Initial Setup Wizard (7/7 plans) — completed 2026-06-16
+- [x] Phase 13: Real Lint Gate (ESLint) (3/3 plans) — completed 2026-06-12
+- [x] Phase 14: Desktop E2E Coverage (1/1 plans) — completed 2026-06-12
+- [x] Phase 15: Doc-Only CI Skip + Markdown Lint (3/3 plans) — completed 2026-06-12
+- [x] Phase 16: CI Dependency Audit, Security & Image Hygiene (6/6 plans) — completed 2026-06-13
+- [x] Phase 17: UI Optimization & Polish (6/6 plans) — completed 2026-06-18
+- [x] Phase 18: Auto Timezone Detection (4/4 plans) — completed 2026-06-14
+- [x] Phase 19: Local Auth (No-OIDC Mode) (5/5 plans) — completed 2026-06-17
+- [x] Phase 20: Admin Member Editor & Form Declutter (3/3 plans) — completed 2026-06-18
 
-**Goal**: The app stack is running, both members can authenticate, and the CalDAV broker can read Fastmail calendars — with a confirmed go/no-go decision on personal-calendar cross-account sharing
-**Mode:** mvp
-**Depends on**: Nothing (first phase)
-**Requirements**: AUTH-01, AUTH-02, AUTH-03, CAL-01, CAL-08
-**Success Criteria** (what must be TRUE):
+Full phase detail archived in [`milestones/v1.1-ROADMAP.md`](milestones/v1.1-ROADMAP.md).
 
-  1. Both members can reach the app URL, authenticate through Authelia OIDC, and land on the app home page without entering any Fastmail credentials
-  2. Sessions persist across browser restarts — neither member is asked to log in again on the next visit
-  3. Each member is assigned a stable, distinct display color that does not change between sessions
-  4. The broker successfully fetches and caches at least one event from the shared Fastmail calendar via CalDAV PROPFIND/REPORT
-  5. The personal-calendar ACL spike produces a documented go/no-go decision: either the broker token sees the wife's personal calendar after Fastmail share+accept, or the fallback strategy (shared-family-only or per-member app password) is chosen and recorded
-
-**Verification status (D-14, 2026-06-04):** Code + **Gate 1** complete. Gate 1 = stack up (`/health` live), CAL-01 proven live (503 real events cached via REPORT), CAL-08 = **GO** (per-member app-password model, see `CAL-08-DECISION.md`). **Gate 2 deferred** — criteria 1/2/3 (live Authelia OIDC login over Pangolin, session persistence, distinct colors in a real browser) and the SSE-over-Pangolin smoke test require the operator's Authelia + Pangolin/Newt infra; tracked in `01-HUMAN-UAT.md` and `docs/deployment.md`. The live AUTH smoke (incl. iOS) is folded into **Phase 3**; the SSE smoke is a hard gate before **Phase 4**. Phases 2–3 develop behind a documented dev-auth bypass.
-
-**Plans**: 4 plans
-Plans:
-
-- [x] 01-01-PLAN.md — Walking skeleton: monorepo scaffold + Docker/MariaDB + Drizzle schema (push) + /health end-to-end slice + Vitest Wave 0 harness
-- [x] 01-02-PLAN.md — Authelia OIDC slice: stable identity (iss+sub) + auto-assigned member color + /api/me + authenticated PWA shell (AUTH-01/02/03)
-- [x] 01-03-PLAN.md — CalDAV broker slice: AES-256-GCM credential encryption + tsdav broker + ical.js sync (all-day DATE) + ctag poller + /api/events (CAL-01)
-- [x] 01-04-PLAN.md — Integration + gate: wire poller/routes, event-proof landing page, CAL-08 spike + go/no-go doc, live Pangolin deploy + SSE smoke test
-
-### Phase 2: Calendar Display
-
-**Goal**: Both members can see a unified, color-coded calendar aggregating all accessible Fastmail calendars across day, week, month, and agenda views — read-only, no write-back yet
-**Mode:** mvp
-**Depends on**: Phase 1
-**Requirements**: CAL-02, CAL-03, CAL-07
-**Success Criteria** (what must be TRUE):
-
-  1. Opening the app shows a color-coded calendar where each member's events appear in their assigned color, with shared events distinguishable from personal events
-  2. The user can switch between day, week, month, and agenda views and all events render correctly in each view
-  3. A recurring event (e.g., weekly meeting) displays all its occurrences correctly in the current view window, including correct behavior across DST boundaries
-  4. All-day events (birthdays, holidays) appear as full-day banners on the correct date with no timezone shift
-
-**Plans**: 5 plansPlans:
-**Wave 1**
-
-- [x] 02-01-PLAN.md — Foundation: schema (hasRrule + calendars.isShared, pushed) + dev-auth bypass + PWA vitest/jsdom harness + ICS fixtures + RED test stubs
-
-**Wave 2** *(blocked on Wave 1 completion)*
-
-- [x] 02-02-PLAN.md — Backend slice: expandOccurrences() (VTIMEZONE/DST + all-day + EXDATE) + windowed/joined/zod-validated /api/events + shared-calendar checkpoint (CAL-02/CAL-07)
-- [x] 02-03-PLAN.md — Frontend foundation: CSS token layer + colorUtils + calendarConfig (firstDayOfWeek 0→7) + hydrateEvents (Temporal/PlainDate guard) + Zustand store + windowed fetchEvents
-
-**Wave 3** *(blocked on Wave 2 completion)*
-
-- [x] 02-04-PLAN.md — Vertical slice: CalendarShell mounts Schedule-X, renders real windowed Fastmail events color-coded across all four views (CAL-02/CAL-03)
-
-**Wave 4** *(blocked on Wave 3 completion)*
-
-- [x] 02-05-PLAN.md — UX completion: read-only EventDetailPopover + ColorLegend + nav/toolbar + skeleton/empty/error states + human visual verification
-
-**Gap-closure waves** *(from 03-REVIEW.md — write path was broken end-to-end; Gate 2 / 03-08 is blocked on these)*
-
-- [x] 03-09-PLAN.md — Route layer: align zod schema to client title/start/end contract (CR-01) + real OIDC iss/sub→users.id resolution on all 5 handlers (CR-06) [wave 1]
-- [x] 03-12-PLAN.md — PWA EventForm: edit-mode population + recurrence preselect (WR-03), zone-consistent dates (WR-05), real focus trap (WR-07); PWA-01/02 install assets verified [wave 1]
-- [x] 03-10-PLAN.md — Worker dispatch: build real VEVENT via buildVeventString + all-day DTEND+1 (CR-02/WR-04), fail closed on bad creds (CR-03), backoff index + randomUUID (WR-01/WR-08) [wave 2, after 03-09]
-- [x] 03-11-PLAN.md — Outbox durability: durable create-before-delete (CR-04), drain concurrency guard (CR-05), fresh-etag-before-PUT (WR-02) [wave 3, after 03-10]
-
-**UI hint**: yes
-
-### Phase 3: Event Write-Back + PWA Install
-
-**Goal**: Both members can create, edit, and delete events that are written back to the correct Fastmail calendar, and the app is installable to the iPhone and Android home screens with a guided onboarding flow
-**Mode:** mvp
-**Depends on**: Phase 2
-**Requirements**: CAL-04, CAL-05, CAL-06, CAL-07, PWA-01, PWA-02
-**Success Criteria** (what must be TRUE):
-
-  1. A member can create a timed or all-day event (including recurring events) in the app and see it appear in the native Fastmail app within the next sync cycle
-  2. A member can edit an existing event's title, time, or description and the change persists correctly in Fastmail
-  3. A member can delete an event and it disappears from all views on the next sync
-  4. On Android, the app shows a browser install prompt and installs to the home screen; on iOS, the app shows a guided "Add to Home Screen" walkthrough with annotated screenshots that a non-technical user can follow independently
-  5. The installed PWA opens full-screen without browser chrome on both iOS and Android
-  6. **(Carried from Phase 1 Gate 2, D-14)** Live Authelia OIDC login works over the public Pangolin URL — including the **iOS standalone-PWA** flow: the wife can install to Home Screen and complete login without the redirect breaking out of standalone mode; sessions persist (AUTH-01/02) and members get distinct stable colors (AUTH-03). Verify per `docs/deployment.md` Gate 2 checklist; this is the first real external deploy (local Newt test rig is sufficient — Unraid prod is optional until go-live).
-
-**Plans**: 12 plans (8 original + 4 gap-closure from 03-REVIEW.md)
-Plans:
-**Wave 1**
-
-- [x] 03-01-PLAN.md — Foundation: calendarOutbox table + calendarEvents.objectUrl (pushed), vite-plugin-pwa install + legitimacy gate, sync.ts objectUrl, full Wave 0 RED test scaffold
-
-**Wave 2** *(blocked on Wave 1)*
-
-- [x] 03-02-PLAN.md — TDD: VEVENT builder (vevent.ts, D-13 DATE/DATETIME + RRULE) + tsdav write wrappers (write.ts, D-12 broker boundary)
-- [x] 03-03-PLAN.md — Write API: POST/PATCH/DELETE events + GET sync-status, enqueue-only, D-03 ownership, D-04 edit-as-move pair (CAL-04/05/06/07)
-
-**Wave 3** *(blocked on Wave 2)*
-
-- [x] 03-04-PLAN.md — TDD: outbox worker state machine (D-05/06/07/08 retry/backoff/dead/conflict, edit-as-move ordering) + index.ts wiring
-- [x] 03-05-PLAN.md — Frontend create/edit slice: write client calls + Zustand keys + EventForm (D-01/02/11) + New Event FAB
-- [x] 03-07-PLAN.md — PWA install: VitePWA manifest + auth-safe SW denylist + icons + InstallPrompt (iOS walkthrough + Android prompt) (PWA-01/02)
-
-**Wave 4** *(blocked on Wave 3)*
-
-- [x] 03-06-PLAN.md — Delete + sync feedback: popover Edit/Delete footer + DeleteConfirmationDialog + SyncStateToast polling (D-06/08/09) (CAL-05/06)
-
-**Wave 5** *(blocked on Wave 4)*
-
-- [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
-
-### Phase 4: Shared Lists + Live Sync
-
-**Goal**: Both members can create and manage shared named lists with real-time co-edit sync — edits by one member appear for the other without any manual refresh
-**Mode:** mvp
-**Depends on**: Phase 1
-**⚠️ Entry gate (D-14):** The **SSE-over-Pangolin smoke test** (deferred from Phase 1 Gate 2, issue #1034) MUST pass before building live sync — hold `/api/sse/heartbeat` open 5+ min through the tunnel without it being cut (see `docs/deployment.md`). If it FAILS: fix Pangolin idle-timeout/buffering, or plan a reconnect/polling fallback into this phase before proceeding. Do not build the live-sync layer on an unverified transport.
-**Requirements**: LIST-01, LIST-02, LIST-03, LIST-04
-**Success Criteria** (what must be TRUE):
-
-  1. Either member can create a named list (e.g., "Groceries") and delete a list they no longer need
-  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
-
-**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
-
-**Goal**: Both members receive timely Web Push alerts for upcoming events, event changes made by the other member, and list changes — reliably on both iOS and Android
-**Mode:** mvp
-**Depends on**: Phase 3, Phase 4
-**Requirements**: NOTIF-01, NOTIF-02, NOTIF-03
-**Success Criteria** (what must be TRUE):
-
-  1. A member receives a push notification on their phone approximately 15 minutes before a calendar event starts — delivered to the installed PWA, including on iOS
-  2. When the other member adds or changes a calendar event, the first member receives a push notification with the event title and action described in the payload
-  3. When the other member modifies a shared list (adds, checks off, or deletes an item), the first member receives a push notification identifying the list and the change
-  4. After an extended period of app inactivity, push notifications are still delivered (subscription health-check prevents silent revocation on iOS)
-
-**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
+</details>
 
 ## Progress
 
-**Execution Order:**
-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 | 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 | - |
+| Phase | Milestone | Plans Complete | Status   | Completed  |
+| ----- | --------- | -------------- | -------- | ---------- |
+| 1. Foundation + Broker Spike      | v1.0 | 4/4   | Complete | 2026-06-04 |
+| 2. Calendar Display               | v1.0 | 5/5   | Complete | 2026-06-05 |
+| 3. Event Write-Back + PWA Install | v1.0 | 12/12 | Complete | 2026-06-07 |
+| 4. Shared Lists + Live Sync       | v1.0 | 7/7   | Complete | 2026-06-09 |
+| 5. Web Push Notifications         | v1.0 | 8/8   | Complete | 2026-06-10 |
+| 6. UX Polish                      | v1.0 | 6/6   | Complete | 2026-06-10 |
+| 7. Mobile Test Harness            | v1.1 | 4/4   | Complete | 2026-06-11 |
+| 8. Gitea CI                       | v1.1 | 4/4   | Complete | 2026-06-11 |
+| 9. Faster Write-Back              | v1.1 | 2/2   | Complete | 2026-06-12 |
+| 10. Admin Role & Settings         | v1.1 | 4/4   | Complete | 2026-06-13 |
+| 11. Per-Event Reminders           | v1.1 | 5/5   | Complete | 2026-06-14 |
+| 12. Initial Setup Wizard          | v1.1 | 7/7   | Complete | 2026-06-16 |
+| 13. Real Lint Gate (ESLint)       | v1.1 | 3/3   | Complete | 2026-06-12 |
+| 14. Desktop E2E Coverage          | v1.1 | 1/1   | Complete | 2026-06-12 |
+| 15. Doc-Only CI Skip + MD Lint    | v1.1 | 3/3   | Complete | 2026-06-12 |
+| 16. CI Dep Audit, Sec & Img Hyg   | v1.1 | 6/6   | Complete | 2026-06-13 |
+| 17. UI Optimization & Polish      | v1.1 | 6/6   | Complete | 2026-06-18 |
+| 18. Auto Timezone Detection       | v1.1 | 4/4   | Complete | 2026-06-14 |
+| 19. Local Auth (No-OIDC Mode)     | v1.1 | 5/5   | Complete | 2026-06-17 |
+| 20. Admin Member Editor & Declutter | v1.1 | 3/3 | Complete | 2026-06-18 |
 
 ## Backlog
 
@@ -223,21 +76,43 @@ 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:** 12/12 plans complete
+**Plans:** 6/6 plans complete
 
 Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.2: Slick unauthenticated-entry — no calendar/"Sign-in required" flash before Authelia redirect (BACKLOG)
+### Phase 999.4: Per-event reminder configuration (VALARM authoring + scheduler honors it) (BACKLOG)
 
-**Goal:** [Captured for future planning] On a cold unauthenticated load the PWA briefly paints the calendar shell + skeleton, then flashes a "Sign-in required" error, then redirects to Authelia — not slick (violates the "low-friction for the non-technical Apple member" hard constraint). Make unauthenticated entry render a single neutral "Signing you in…" splash and go straight to Authelia, with no app content or error text painted first.
+**Goal:** [Captured for future planning] End-to-end per-event reminders — let the user choose *when* (or whether) to be reminded per event, and make the push scheduler honor that choice instead of a hardcoded lead.
 
-**Root cause** (diagnosed during Phase 03 Gate 2 live verification, 2026-06-07) — `apps/pwa/src/components/CalendarShell.tsx`: the component renders optimistically before auth is known. While `meQuery` (GET `/api/me`) is pending, `isInitialLoading` renders the calendar shell + `SkeletonCalendar`. When `meQuery` resolves as an `opaqueredirect` (unauthenticated — `fetchMe` uses `redirect:'manual'` in `apps/pwa/src/api/client.ts`), it errors and in the same tick (1) the early return `if (meQuery.isError) return <div role="alert">Sign-in required</div>` (~line 187) paints, and (2) a `useEffect` calls `window.location.href='/api/login'`. Because the navigation is async, React paints "Sign-in required" for ~one frame before leaving for Authelia. Net: calendar flash → "Sign-in required" flash → Authelia.
+**Half A — author the VALARM (event form):** The event create/edit form has no UI to set a reminder ("remind me 10 min / 1 hour / 1 day before", or **no reminder**), so the written `.ics` carries no `VALARM` and no reminder can fire — in native clients or via web push. Add a reminder selector (including an explicit "none"), serialize chosen offsets as `VALARM` (TRIGGER) on write-back, and parse existing `VALARM`s on read so edits preserve them. Feeds the Phase 5 web-push requirement (push needs reminder data to notify about).
 
-**Proposed fix:** Gate the app render on auth state — (a) don't render CalendarContent/skeleton until `meQuery.isSuccess`; (b) while unauthenticated and redirecting, render a neutral full-screen "Signing you in…" splash instead of the "Sign-in required" alert; (c) reserve the "Sign-in required" dead-end only for the one-shot-guard fall-through (already bounced through `/api/login` and still failing). Optionally hoist the auth check above the heavy calendar mount.
+**Half B — scheduler honors the provider's value (NEW, surfaced 2026-06-10):** Today `apps/api/src/broker/reminderScheduler.ts` runs a **hardcoded 15-minute** scan for shared timed events (`index.ts:139` "starting in ~15 min"; reminderScheduler header "15-min reminder scan") and never reads the event's actual alarm. So every reminder fires 15 min before regardless of what the event (or the calendar provider) specifies, and an event with **no** alarm still gets a 15-min push. Change the scheduler to read each event's `VALARM` `TRIGGER` (the value written in Half A / set in Fastmail or another native client) and fire at that lead — and fire **nothing** when the event has no alarm. The current fixed 15-min window/dedup logic (catch-up scan, per-uid exactly-once — see quick 260610-hbu) must be generalized to a variable per-event lead.
+
+**Boundary:** preserve the reminder scheduler's resilience guarantees (catch-up on a missed tick, per-uid exactly-once dedup). This makes the lead per-event/variable rather than constant; it is not a rewrite of the scan/dedup design.
+
+**Severity:** medium — feature gap surfaced during Phase 03 Gate 2 testing; Half B surfaced 2026-06-10. Tags: phase-03, phase-05, calendar, write-back, reminders, valarm, push, scheduler, phase-05-dependency.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+> **Promoted into v1.1 Phase 11 (Per-Event Reminders) — CAL-13/CAL-14/NOTIF-04/05/06.** Backlog entry retained for history.
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.10: Admin Settings / Administration section — manage app passwords + designate the shared calendar via UI (BACKLOG)
+
+**Goal:** [Captured for future planning] Add an in-app **Settings/Administration** section, gated to an administrator role, for configuration that today requires manual backend/DB steps:
+
+- **View/update per-member Fastmail app passwords** (stored encrypted via `APP_PASSWORD_ENCRYPTION_KEY`, existing crypto path) — rotate or re-enter a member's credential and re-trigger sync.
+- **Designate which synced calendar is the "shared" calendar** by toggling `calendars.is_shared` from the UI. Today this is a manual DB write: e.g. `UPDATE calendars SET is_shared=1 WHERE id=<row>` — done by hand on 2026-06-10 to mark the "FamilySync" calendar (id 10) shared after the poller synced it (D-16). The admin should pick the shared calendar from a list of synced collections instead of relying on a backend process. (The poller's upsert already leaves `is_shared` untouched, so a UI-set flag persists.)
+
+**Context:** Motivated by the manual D-16 resolution (2026-06-10). **Related:** 999.5 (per-member first-login app-password onboarding) — this is the ongoing admin-managed counterpart; and 999.11 (initial setup wizard) — bootstrap-time vs. ongoing config. Tags: admin, settings, calendar, app-passwords, D-16.
+
+> **Promoted into v1.1 Phase 10 (Admin Role & Settings) — ADMIN-01/ADMIN-02/ADMIN-03.** Backlog entry retained for history.
 
-**Severity:** low / cosmetic, but hits every unauthenticated cold load and the wife's first impression. Tags: phase-03, ux-polish, auth.
 **Requirements:** TBD
 **Plans:** 0 plans
 
@@ -245,15 +120,20 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.3: Redirect to sign-in on session timeout instead of hanging (BACKLOG)
+### Phase 999.11: Initial setup wizard — first-run config of env vars, app passwords, DB connection (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.
+**Goal:** [Captured for future planning] Add a first-run **setup wizard** that walks the administrator through defining all bootstrap configuration instead of hand-editing `.env` / `docker-compose.yml`:
 
-**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.
+- **App environment variables:** OIDC client id/secret/issuer/redirect URI + external URL, session signing secret (`OIDC_AUTH_SECRET`), `APP_PASSWORD_ENCRYPTION_KEY`, and the **VAPID keypair** (subject + public + private).
+- **MariaDB connection:** host/port/user/password/db, with a connectivity test.
+- **First Fastmail app password** for the initial member, encrypted on save.
 
-**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.
+Wizard should **validate inputs before completing** — e.g. VAPID private key decodes to 32 bytes AND pairs with the public key, OIDC discovery resolves, DB connects, app-password reaches CalDAV.
+
+**Context:** Motivated by setup friction observed 2026-06-10 — a VAPID private key truncated on paste into `.env` silently broke push (`setVapidDetails failed — 32 bytes`), and `DB_HOST` / dev overrides must currently be set by hand. A guided + validated wizard would have caught these. **Related:** 999.10 (ongoing admin Settings) and 999.5 (member onboarding). Tags: onboarding, setup, install, env, vapid, mariadb, oidc.
+
+> **Promoted into v1.1 Phase 12 (Initial Setup Wizard) — SETUP-01/02/03/04.** Backlog entry retained for history.
 
-**Severity:** high — hits any long-lived tab (the wife leaving the PWA open). Tags: phase-03, auth, ux.
 **Requirements:** TBD
 **Plans:** 0 plans
 
@@ -261,11 +141,22 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.4: Event-creation notification/reminder (VALARM) options (BACKLOG)
+### Phase 999.12: Assistant-driven mobile-browser UI testing (mobile viewport + authed PWA) (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).
+**Goal:** [Captured for future planning] Give the assistant a way to validate UI/UX changes in a **mobile** browser experience, not just desktop Chromium. Today `playwright-cli` drives a desktop viewport, and the prod stack enforces OIDC (Authelia) so the authed PWA can't be reached headlessly — which is exactly why a string of mobile-only defects this milestone (silent Android notifications, the dead "How to enable" link, iOS/Android session-cookie persistence, install/standalone behaviour) could only be found by the operator on real devices, not by the assistant.
+
+**What this needs (any subset):**
+
+- **Mobile viewport + UA emulation** in the browser harness (e.g. Playwright device descriptors — iPhone/Pixel viewport, touch, mobile user-agent) so layout, tap targets, and responsive behaviour can be checked.
+- **An authenticated entry path for automated runs** so the assistant can reach the real PWA past Authelia — e.g. a reusable saved storage-state/cookie, a test-only bypass on a non-prod host, or driving the Authelia login once and reusing the session. (Note: this overlaps the existing `DEV_AUTH_BYPASS`, but that only works on the host-side dev stack, not the prod-mode PWA that has the real service worker. A mobile, authed, SW-enabled target is the gap.)
+- Optionally: a documented way to point the harness at the Pangolin HTTPS URL with a persisted session, and/or remote-debug a real device.
+
+**Boundary:** genuinely device-only behaviour (iOS-Safari standalone push, real APNs/FCM delivery, OS notification-channel importance) still needs a human — this item is about everything SHORT of that (responsive layout, tap flows, in-page notification UI states, auth redirects) which a mobile-emulated authed browser *could* cover but currently can't.
+
+**Context:** Surfaced 2026-06-10 during Phase 5 UAT — repeated mobile-only bugs were caught only by the operator because the assistant had no mobile, authenticated browser to test in. **Related:** [[feedback-playwright-verify]] (use playwright-cli over manual verification — this extends it to mobile/authed). Tags: testing, playwright, mobile, pwa, oidc, dx.
+
+> **Promoted into v1.1 Phase 7 (Mobile Test Harness) — TEST-01/TEST-02.** v1.1 scopes the `DEV_AUTH_BYPASS` dev-build path; the prod-SW authed-mobile target stays deferred. Backlog entry retained for history.
 
-**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
 
@@ -273,21 +164,22 @@ 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)
+### Phase 999.13: Reduce event write-back latency to the calendar provider (outbox drain) (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.
+**Goal:** [Captured for future planning] Calendar create/edit/delete writes are enqueue-only (`calendarOutbox`, 202 optimistic-accept; D-12/D-05 — no Fastmail call in the route) and flushed to Fastmail by `runOutboxDrain` on a **15-second `setInterval`** (`apps/api/src/broker/outboxWorker.ts`). So a change can take up to ~15s to land in Fastmail (and longer to reflect back in the app, which depends on the separate 5-min poller). Reduce that perceived sync delay so edits feel near-immediate.
 
-**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.
+**Options to weigh when picking this up:**
 
-**Scope to decide when promoted:**
+- **Event-driven drain (preferred):** trigger an outbox drain immediately after a successful enqueue (in-process signal, or Redis pub/sub which is already available) so the write fires within ~1s instead of waiting for the next tick — keep the 15s `setInterval` as a fallback/retry sweep. Must preserve the existing per-row etag/412 handling and the rapid-successive-edit ordering (see outboxWorker comments ~L312 — each edit carries its enqueue-time etag).
+- **Shorter interval:** simplest, but more idle DB polling; a floor (e.g. 3–5s) trades latency for load.
+- **Faster read-back too:** the user also sees latency from the 5-min poller reflecting the change back. Consider invalidating/short-poll after a local write, or optimistic UI already covering it — confirm whether the perceived delay is the write (15s) or the read-back (5min).
 
-- 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.
+**Boundary:** the optimistic 202 + outbox durability design (create-before-delete, drain concurrency guard, fresh-etag-before-PUT) must be preserved — this is a latency tune, not a rewrite of the write path.
+
+**Context:** Surfaced 2026-06-10. Tags: calendar, write-back, outbox, latency, redis, performance.
+
+> **Promoted into v1.1 Phase 9 (Faster Write-Back) — CAL-15.** In-process EventEmitter chosen (not Redis); the drain is single-process by design. Backlog entry retained for history.
 
-**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
 
@@ -295,11 +187,24 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.6: All-day events should stand out visually (BACKLOG)
+### Phase 999.14: Gitea CI — full regression on PR to main + build/publish Docker image (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.
+**Goal:** [Captured for future planning] The repo is committed against a self-hosted Gitea instance with a registered Actions runner, but there is no CI yet (no `.gitea/workflows/` or `.github/workflows/`). Two things should run automatically: (1) **full regression** on every PR targeting `main` — gating the merge; (2) **build the app's Docker image and publish it** to the Gitea container registry.
+
+**Options / decisions to make when picking this up:**
+
+- **Test scope:** "full regression" = lint + typecheck + unit + the API integration tests. Integration tests need a real MariaDB (see [[api-integration-test-db]]) — the workflow must spin up a MariaDB service container, bind it, and set `DB_HOST=127.0.0.1` + `.env` creds. The PWA build/test also runs.
+- **Monorepo:** pnpm workspace (`apps/api`, `apps/pwa`, shared). Cache the pnpm store.
+- **Docker images:** only `apps/api/Dockerfile` exists today — there is no PWA Dockerfile yet. Decide one image (API) vs. also building/serving the PWA. Tag scheme + when to publish (only on merge to `main`? on tags? per-PR?).
+- **Registry auth:** push to the Gitea registry using the runner's Gitea-provided token or a dedicated package-write token.
+- Gitea Actions are GitHub-Actions-compatible syntax but run on the self-hosted runner — confirm runner labels and available images, and that Actions is enabled, before authoring.
+
+**Likely shape:** a `.gitea/workflows/ci.yml` — `on: pull_request` (to `main`) → install (pnpm), lint, typecheck, unit, API integration vs. a `mariadb` service container, PWA build; `on: push` to `main`/tag → `docker build apps/api/Dockerfile`, login, push tagged image.
+
+**Context:** Promoted from STATE.md pending todo (`.planning/todos/pending/2026-06-10-gitea-ci-regression-and-docker-publish.md`), surfaced 2026-06-10. Tags: tooling, ci, gitea, docker, mariadb, monorepo.
+
+> **Promoted into v1.1 Phase 8 (Gitea CI) — CI-01/CI-02.** v1.1 also extends CI-01 to run the Phase 7 mobile harness as a UI-regression step (CI brings up the dev stack in the runner). Backlog entry retained for history.
 
-**Context** (surfaced 2026-06-07, Gate 2 live testing). Tags: phase-03, ui, calendar, ux-polish.
 **Requirements:** TBD
 **Plans:** 0 plans
 
@@ -307,13 +212,22 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.7: Event form — auto-advance end when start moves; keep duration sane (BACKLOG)
+### Phase 999.15: Desktop e2e coverage — add a Desktop Playwright profile + desktop-safe specs (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.
+**Goal:** [Captured for future planning] The Playwright harness (`apps/pwa/playwright.config.ts`) defines only **mobile** device profiles — `iphone` (iPhone 14 / WebKit) and `pixel` (Pixel 7 / Chromium), both with touch and a mobile viewport. The Phase 8 CI regression gate runs `pnpm test:e2e`, so it currently validates the **mobile experience only**. Add desktop coverage so the regression gate exercises the desktop layout/flows as well.
 
-**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.
+**Options / decisions to make when picking this up:**
+
+- **Add a Desktop profile:** a new `desktop` project in `playwright.config.ts` (e.g. `devices['Desktop Chrome']`, no `hasTouch`, wide viewport). Optionally a Desktop WebKit/Safari profile too — but the family's Apple member is already covered on mobile Safari via `iphone`; Desktop Chrome is likely sufficient for a shared/wall browser.
+- **Spec-compat pass (the real work):** the existing e2e specs were authored for mobile — they may assume touch gestures, a mobile nav/drawer, or mobile-only layout. Each spec needs review/adjustment so it passes (or is appropriately skipped) on a no-touch, wide-viewport desktop. This is harness/spec work, not CI plumbing.
+- **Gating choice:** decide whether desktop runs block the merge immediately, or run advisory (non-blocking) until the specs are confirmed desktop-safe.
+
+**Boundary:** Phase 8 deliberately reused the Phase 7 harness **unchanged** (CI owns only stack bring-up + readiness waits, not spec content), which is why this was deferred. Once a Desktop project is added to the config, Phase 8 CI picks it up automatically via `pnpm test:e2e` — no CI changes needed beyond whatever runtime/wait the desktop profile requires.
+
+**Context:** Deferred from Phase 8 (Gitea CI) planning, 2026-06-11 — user wants both mobile and desktop validated, but desktop needs a config addition + spec review that is out of Phase 8's CI-plumbing scope. Tags: testing, playwright, e2e, desktop, harness, ci.
+
+> **Promoted into v1.1 Phase 14 (Desktop E2E Coverage) — 2026-06-11.** Backlog entry retained for history.
 
-**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
 
@@ -321,11 +235,23 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.8: Recurrence bound (repeat-until / count) + recurring create polish (BACKLOG)
+### Phase 999.16: Wire a real linter (ESLint) so the CI lint gate actually fails on violations (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).
+**Goal:** [Captured for future planning] The Phase 8 CI `fast-checks` job runs `pnpm lint`, but **no linter exists** in the repo — the root `lint` script is `pnpm -r --if-present lint`, which finds no package-level lint script and exits 0. The lint gate is a hollow placeholder that can never fail. Wire up a real linter so it runs and gates merges on lint violations. (`typecheck`/tsc already gates type errors meanwhile.)
+
+**Options / decisions to make when picking this up:**
+
+- **Tooling:** ESLint flat config (`eslint.config.js`) with `typescript-eslint`; add React + react-hooks plugins for `apps/pwa`. Add `eslint` (+ plugins) as devDeps and a `lint` script to `apps/api` and `apps/pwa` — `pnpm -r --if-present lint` then picks them up automatically, no CI change needed.
+- **Rule strictness:** pick a baseline (recommended vs strict-type-checked). Stricter = more upfront violations to fix.
+- **Violation cleanup (the real work):** the first run surfaces existing violations across both apps. Decide per-rule: fix, downgrade to warn, or disable. The gate must end green.
+- **Gating choice:** blocking on merge immediately, or advisory (warn-only) until the codebase is clean.
+
+**Boundary:** Phase 8 deliberately scoped lint wiring out (CI-plumbing-only); it shipped the gate slot wired to auto-activate once a package `lint` script lands. This item is that follow-up.
+
+**Context:** Raised during Phase 8 execution, 2026-06-11 — user noted the `--if-present` lint step "didn't fix the linter, just made it so it didn't have to exist to proceed" and wants a lint gate that actually fails. Tags: ci, lint, eslint, typescript-eslint, quality, gitea.
+
+> **Promoted into v1.1 Phase 13 (Real Lint Gate / ESLint) — 2026-06-11.** Backlog entry retained for history.
 
-**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
 
@@ -333,11 +259,51 @@ Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
 
-### Phase 999.9: Edit a recurring series (whole-series edit) (BACKLOG)
+### Phase 999.18: Update dependencies as found during CI (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.
+**Goal:** [Captured for future planning] When the CI dependency-audit gate (Phase 16) surfaces outdated or vulnerable packages, bump them rather than letting the report accumulate. Establish a lightweight, recurring "act on the CI dependency report" loop so the two-person household app doesn't drift onto stale/CVE-bearing deps. Scope is the upkeep workflow (review → bump → verify gate green), not a one-time audit.
+
+**Context:** Captured 2026-06-13 during Phase 10 work. Companion to the audit *reporting* shipped in Phase 16 (CI Dependency Audit) — that phase makes outdated/vulnerable deps *visible*; this item is the standing follow-through to *resolve* what it finds. Tags: ci, dependencies, maintenance, security, upkeep.
+
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.19: Dev user exercises full app functionality without syncing to a real calendar (BACKLOG)
+
+**Goal:** [Captured for future planning] Let the `DEV_AUTH_BYPASS` dev user (currently hardcoded `DEV_USER` id 1 in `apps/api/src/auth/devBypass.ts`) exercise the full app — create/edit/delete events, set per-event reminders, manage lists — against a local/in-app calendar store, WITHOUT requiring a connected Fastmail/CalDAV provider and WITHOUT writing anything to a real calendar. Today the dev user has no `member_credentials` row and no `calendars`, so `writable-calendars` is empty and `POST /api/events/create` returns `422 "No writable calendar found for user"` — making hands-on UAT of event/reminder features impossible in dev. Options to explore: seed the dev user a fake local calendar + short-circuit the outbox/CalDAV write path under dev-bypass (no Fastmail round-trip), or a dev-only in-memory calendar provider. Must stay strictly dev-only (same hard `NODE_ENV !== 'production'` guard) and never ship in production images.
+
+**Context:** Captured 2026-06-14 during Phase 11 (Per-Event Reminders) UAT. The reminder picker and backend were verified via automated tests + a route-mocked playwright smoke, but the operator could not manually create an event to see reminders end-to-end because no provider is connected in the dev DB (`needsProviderSetup: true`). This is a recurring dev-testability friction (see MEMORY: "Dev user 1 has no calendars"). Tags: dev-tooling, dev-bypass, testability, calendars, outbox, uat.
+
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.20: PWA dark mode / theming — ship a full dark theme + light/dark/system switch (BACKLOG)
+
+**Goal:** [Captured for future planning] Ship a complete dark theme for the PWA plus a light/dark/system theme switch. **Phase 17 lays the token-architecture groundwork** — it restructures `apps/pwa/src/styles/tokens.css` from a single light `:root` into a themeable semantic-token layer that can be swapped via `data-theme` / `prefers-color-scheme`, with light staying the default and only-shipped theme. This backlog item is the follow-through that consumes that seam: author the actual dark palette values (including the Schedule-X `--sx-color-*` calendar overrides at the bottom of tokens.css), wire `prefers-color-scheme`, add a persisted in-app toggle in the /admin or Settings surface (light / dark / system), and verify both themes render cleanly across every route (calendar, lists, admin, settings sheet, login) via `playwright-cli` + the Phase 7 `layout.spec` profiles.
+
+**Context:** Deferred out of Phase 17 (2026-06-17) during `/gsd-discuss-phase 17` to keep that phase scoped to phone-layout polish + branding assets. Phase 17's token restructure is the explicit enabling groundwork, so this should be cheap to pick up afterward. Related: Phase 17 (UI Optimization & Polish — the groundwork), 999.21 (modern styling refresh). Tags: pwa, theming, dark-mode, tokens, accessibility, settings, prefers-color-scheme.
+
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.21: PWA modern visual styling refresh — contemporary look across the app (BACKLOG)
+
+**Goal:** [Captured for future planning] A broader "more modern, visually appealing" styling pass across the PWA — beyond the bounded in-system polish of Phase 17. Candidate scope: a contemporary refresh of high-visibility surfaces (login, calendar shell, event form, lists, admin), revisiting elevation/shadows, radii, spacing rhythm, typography scale, and control states, potentially reworking specific component layouts. Explicitly **flagged for a future milestone**, not v1.1 — it is a visual-overhaul track with real redesign risk and should be scoped/sequenced on its own rather than bolted onto a polish phase. Best sequenced after the Phase 17 token groundwork and 999.20 (dark mode) so the refresh is theme-aware from the start.
+
+**Context:** Deferred out of Phase 17 (2026-06-17) during `/gsd-discuss-phase 17`. The user scoped Phase 17 to layout polish + branding (logo/favicon/icon assets) + theme-token groundwork, and routed the open-ended styling refresh here for a future milestone to avoid an unbounded redesign inside a polish phase. Related: Phase 17 (the polish baseline), 999.20 (dark mode / theming). Tags: pwa, ui, styling, redesign, design-system, future-milestone.
 
-**Context** (surfaced 2026-06-07, Gate 2 live testing). Tags: phase-03, recurrence, event-form, caldav.
 **Requirements:** TBD
 **Plans:** 0 plans
 

.planning/STATE.md

@@ -1,64 +1,128 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.0
-milestone_name: milestone
-status: executing
-stopped_at: Phase 4 UI-SPEC approved
-last_updated: "2026-06-09T14:25:21.889Z"
-last_activity: 2026-06-09 -- Phase 04 planning complete
+milestone: v1.1
+milestone_name: Operability & Polish
+current_phase: null
+status: Awaiting next milestone
+stopped_at: v1.1 milestone shipped & archived
+last_updated: "2026-06-19T01:58:30.566Z"
+last_activity: 2026-06-18
+last_activity_desc: Milestone v1.1 completed and archived
 progress:
-  total_phases: 15
-  completed_phases: 3
-  total_plans: 21
-  completed_plans: 21
-  percent: 20
+  total_phases: 20
+  completed_phases: 20
+  total_plans: 57
+  completed_plans: 57
+  percent: 100
+current_phase_name: Awaiting next milestone
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-06-07)
+See: .planning/PROJECT.md (updated 2026-06-18 after v1.1 milestone)
 
 **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 04 — Shared Lists + Live Sync (entry gate: SSE-over-Pangolin smoke test, D-14)
+**Current focus:** Planning next milestone — run `/gsd-new-milestone`
 
 ## Current Position
 
-Phase: 4
-Plan: Not started
-Status: Ready to execute
-Last activity: 2026-06-09 -- Phase 04 planning complete
+Phase: Milestone v1.1 complete
+Plan: —
+Status: Awaiting next milestone
+Last activity: 2026-06-19 — Milestone v1.1 completed and archived
 
-Progress: [█████░░░░░] 50% (3 of 6 phases)
+### ✅ Resolved Checkpoint — Phase 15 Plan 15-03 Task 2 (human-action)
+
+Done 2026-06-12. Gitea branch protection on `main` now requires EXACTLY `CI / fast-checks (pull_request)` + `CI / gate (pull_request)`; `CI / api` + `CI / harness` removed from required checks (verified via `tea api repos/luckberg/familysync/branch_protections`).
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 17
+- Total plans completed: 69
 - Average duration: -
 - Total execution time: 0 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
-| 02 | 5 | - | - |
-| 03 | 12 | - | - |
+| ----- | ----- | ----- | -------- |
+| 02    | 5     | -     | -        |
+| 03    | 12    | -     | -        |
+| 07    | 4     | -     | -        |
+| 13 | 3 | - | - |
+| 14 | 1 | - | - |
+| 15 | 3 | - | - |
+| 09 | 2 | - | - |
+| 16 | 6 | - | - |
+| 10 | 4 | - | - |
+| 11 | 5 | - | - |
+| 12 | 7 | - | - |
+| 19 | 5 | - | - |
+| 17 | 6 | - | - |
+| 20 | 3 | - | - |
 
 **Recent Trend:**
 
 - Last 5 plans: -
 - Trend: -
 
-*Updated after each plan completion*
+_Updated after each plan completion_
 | Phase 03 P01 | 45 | 5 tasks | 8 files |
 | Phase 03 P03-02 | 4 | 2 tasks | 2 files |
 | Phase 03 P03-03 | 7 | 3 tasks | 2 files |
 | Phase 03 P03-07 | 5 | 2 tasks | 7 files |
 | Phase 03 P03-04 | 15 | 2 tasks | 3 files |
 | Phase 03 P03-05 | 6 | 3 tasks | 6 files |
+| Phase 04 P01 | 65 | 4 tasks | 17 files |
+| Phase 04 P03 | 12 | 2 tasks | 9 files |
+| Phase 04 P04 | 11 | 2 tasks | 10 files |
+| Phase 04 P05 | 10 | 2 tasks | 4 files |
+| Phase 04 P06 | 11 | 2 tasks | 7 files |
+| Phase 04 P07 | 6 | 2 tasks | 4 files |
+| Phase 05 P01 | 20 | 4 tasks | 15 files |
+| Phase 05 P02 | 5 | 1 tasks | 1 files |
+| Phase 05 P03 | 5 | - tasks | - files |
+| Phase 05 P04 | 11 | 3 tasks | 9 files |
+| Phase 05 P05 | 8 | 2 tasks | 4 files |
+| Phase 05 P06 | 6 | 1 tasks | 2 files |
+| Phase 05 P08 | 9 | 3 tasks | 7 files |
+| Phase 05 P07 | 8 | 1 tasks | 4 files |
+| Phase 06-ux-polish P01 | 2 | 2 tasks | 2 files |
+| Phase 06-ux-polish P02 | 8 | 2 tasks | 4 files |
+| Phase 06-ux-polish P03 | 11 | 2 tasks | 3 files |
+| Phase 06-ux-polish P04 | 5 | 2 tasks | 2 files |
+| Phase 06-ux-polish P05 | 35 | 4 tasks | 6 files |
+| Phase 06-ux-polish P06 | 45 | 4 tasks | 5 files |
+| Phase 07 P01 | 310 | 3 tasks | 7 files |
+| Phase 07 P02 | 196 | 2 tasks | 4 files |
+| Phase 07-mobile-test-harness P03 | 480 | 2 tasks | 2 files |
+| Phase 07-mobile-test-harness P04 | 22 | 2 tasks | 2 files |
+| Phase 13 P01 | 8 | 2 tasks | 7 files |
+| Phase 13-real-lint-gate-eslint P02 | 90 | 2 tasks | 31 files |
+| Phase 13-real-lint-gate-eslint P03 | 10 | 3 tasks | 399 files |
+| Phase 09-faster-write-back P01 | 341 | 3 tasks | 3 files |
+| Phase 16 P01 | 188 | 3 tasks | 4 files |
+| Phase 16-ci-dependency-audit-and-security-checks P02 | 25 | 3 tasks | 5 files |
+| Phase 16-ci-dependency-audit-and-security-checks P03 | 2 | 2 tasks | 5 files |
+| Phase 16 P04 | 45 | 4 tasks | 3 files |
+| Phase 16 P05 | 7 | 2 tasks | 1 files |
+| Phase 10-admin-role-settings P01 | 265 | - tasks | - files |
+| Phase 10-admin-role-settings P02 | 700 | 3 tasks | 6 files |
+| Phase 10-admin-role-settings P03 | 720 | 3 tasks | 6 files |
+| Phase 10-admin-role-settings P04 | 1315 | 3 tasks | 8 files |
+| Phase 11-per-event-reminders P11-04 | 60 | 3 tasks | 4 files |
+| Phase 18-auto-timezone-detection-and-ability-to-change-timezone P01 | 2 | 2 tasks | 2 files |
+| Phase 18 P02 | 3 | 2 tasks | 2 files |
+| Phase 18 P03 | 28 | 2 tasks | 4 files |
+| Phase 18 P04 | 15 | 3 tasks | 3 files |
+| Phase 12 P01 | 8 | 4 tasks | 10 files |
+| Phase 12 P02 | 15 | 3 tasks | 6 files |
+| Phase 12 P03 | 8 | 1 tasks | 2 files |
+| Phase 12 P06 | 8 | 2 tasks tasks | 3 files files |
+| Phase 20 P03 | 10 | 3 tasks | 3 files |
 
 ## Accumulated Context
 
@@ -67,6 +131,20 @@ Progress: [█████░░░░░] 50% (3 of 6 phases)
 Decisions are logged in PROJECT.md Key Decisions table.
 Recent decisions affecting current work:
 
+- D-07-CJS-IMPORT (2026-06-15, 12-01): web-push is CJS — ESM scripts must use default import then destructure (`import webpush from '...'; const { generateVAPIDKeys } = webpush`). Named ESM export form fails at Node 22 (SyntaxError).
+- D-07-BACKFILL (2026-06-15, 12-01): 0002 migration appends `UPDATE users SET claimed=true WHERE oidc_iss IS NOT NULL` — prevents first-login-claims (D-08) matching pre-existing OIDC users.
+- D-07-NULL-UNIQUE (2026-06-15, 12-01): kept uniq_oidc_identity unchanged — MariaDB NULL+NULL pairs are DISTINCT in unique indexes, correctly allowing multiple unclaimed wizard rows.
+- D-13-ESLint-PIN (2026-06-11, 13-01): eslint pinned to 9.39.4 — ESLint 10 breaks eslint-plugin-react@7.37.5 at runtime ("getFilename is not a function", jsx-eslint#3977). Unpin when plugin releases ESLint 10 support.
+- D-13-JSX-SCOPE (2026-06-11, 13-01): react/react-in-jsx-scope disabled explicitly — flat.recommended enables it at error; PWA uses jsx:react-jsx (React 19 automatic transform), React import not required in JSX files.
+- D-PROBE-01 (2026-06-11, 08-01): runs-on must be ubuntu-latest — runner has no self-hosted label; all downstream ci.yml workflows use ubuntu-latest.
+- D-PROBE-02 (2026-06-11, 08-01): Docker-executor confirmed (/.dockerenv present); services: works; DB_HOST=mariadb in all downstream jobs.
+- D-PROBE-03 (2026-06-11, 08-01): No mysql CLI in runner image — DB readiness uses healthcheck.sh --connect --innodb_initialized or Node mysql2 wait; no mysql shell-out.
+- D-PROBE-04 (2026-06-11, 08-01): actions/cache@v4 timed out — skip cache in Plans 02/03 critical path; best-effort with continue-on-error if used.
+- D-PROBE-05 (2026-06-11, 08-01): Playwright WebKit + Chromium deps install cleanly (exit 0); Phase-7 harness CI-feasible.
+- D-PROBE-06 (2026-06-11, 08-01): ChristopherHX/gitea-upload-artifact@v4 works — MUST use this fork; actions/upload-artifact@v4 broken on Gitea.
+- D-PROBE-07 (2026-06-11, 08-01): ${GITHUB_SHA:0:7} produces 7 chars — D-04 publish tag expression valid.
+- D-PROBE-08 (2026-06-11, 08-01): GITEA_REGISTRY_PAT deferred to Plan 04; PAT not exercised in probe.
+- D-PAT-NAMING (2026-06-11, 08-04): Gitea runner silently drops secrets with the `GITEA_` prefix (reserved namespace). Secret renamed from GITEA_REGISTRY_PAT → REGISTRY_PAT in both repo secret and ci.yml (commit 73eecf7). Use REGISTRY_PAT in any future registry operations.
 - CAL-08 RESOLVED → GO (Phase 1): per-member Fastmail app password reaches all of that account's calendars; no cross-account ACL needed. Unified view stands; no shared-only fallback. See CAL-08-DECISION.md.
 - D-14 (2026-06-04): Phase 1 Gate 2 (live Authelia/Pangolin) deferred. SSE-over-Pangolin smoke = hard gate before Phase 4; live AUTH smoke incl. iOS standalone-PWA folded into Phase 3. Phases 2–3 build behind a dev-auth bypass. Tracked in 01-HUMAN-UAT.md + docs/deployment.md.
 - D-15 (2026-06-04): Validate real topology via local Newt connector + test subdomain through Pangolin (Mode A), not an Unraid deploy; Unraid reserved for go-live.
@@ -86,16 +164,68 @@ Recent decisions affecting current work:
 - [Phase ?]: D-01 calendar default: last-used URL from localStorage (eventForm.lastCalendarUrl), first writable calendar as fallback
 - [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
+- [Phase ?]: Phase 4 Plan 1
+- [Phase ?]: D-04 GET scoped: two-select + Set union (owner + list_shares); ListDeleteDialog props-driven to preserve calendarStore dialog; zValidator returns 400 not 422 per existing convention
+- [Phase 04-04]: listItemsRouter separate from listsRouter, mounted at /api/list-items for PATCH/DELETE item routes per RESEARCH architecture diagram
+- [Phase 04-04]: Uncheck rank recomputed to active-bottom (generateKeyBetween(lastActiveRank, null)) in same DB write (Open Question 2 resolved)
+- [Phase 04-04]: Delete-wins no-rollback: deleteMutation has no onError handler; item removal from cache is final (D-09)
+- [Phase ?]: LIST-04: SSE connection lives in ListDetail (not hoisted to Lists route); Phase 5 push will own session lifecycle
+- [Phase 04-07]: D-04-07-collation: Drizzle 0.45.x has no first-class collation option on varchar; used customType to emit varchar(255) COLLATE utf8mb4_bin for list_items.rank — keeps schema-as-code + generate+migrate workflow
+- [Phase 04-07]: D-04-07-guard: isShared owner-only guard placed after access check, before updateValues construction; mirrors DELETE handler idiom (if !access.isOwner → 403)
+- [Phase ?]: VAPID config is env-injected at runtime via docker-compose.yml environment block; no key baked into image (Phase 5 D-transposability)
+- [Phase ?]: dispatchPush uses sub.id (not a separate dbRowId argument) — 2-arg signature matches existing test
+- [Phase ?]: coalesceListPush dispatch signature is (listId, actorId, count) — test scaffold canonical; richer payload deferred to Plan 05-05 caller
+- [Phase ?]: notifyListChange fires for all list/item mutations except reorder (position) and list-create per D-01
+- [Phase ?]: D-05-06-crossjoin: Drizzle cross-join in reminderScheduler pairs shared events with all pushSubscriptions; grouping by uid post-join ensures full fan-out per deduped event (reminderScheduler.ts)
+- [Phase ?]: D-03 actor exclusion: ne() at DB level + filter() in application code (defence-in-depth for eventChangeDispatcher tests)
+- [Phase ?]: D-08: hasRrule derived from event.isRecurring() in expand.ts — no DB query change needed; captured once before branch
+- [Phase 06-04]: @keyframes pulse added globally to tokens.css; redundant local spin redefinition removed from PushPermissionPrompt.tsx — all sync-animation consumers now resolve from the global stylesheet (D-13)
+- [Phase 06-05]: TanStack Query v5 global error handler: QueryCache({onError})/MutationCache({onError}) constructor pattern; defaultOptions.onError removed in v5 (NOT used); confirmed via Context7 /tanstack/query
+- [Phase 06-05]: AuthSplash state machine: loading/redirecting/dead-end; CalendarContent renders only on meQuery.isSuccess (D-10); sessionExpired flag via Zustand + global QueryCache/MutationCache onError (D-11); one-shot redirect guard re-armed only on explicit user tap
+- [Phase 06-06]: Schedule-X all-day CSS: .sx**all-day-event does not exist in v4.6.0; real selectors are .sx**date-grid-event (week/day) + .sx**month-grid-event:not(:has(.sx**month-grid-event-time)) (month); --sx-color-primary-container remapped as fallback
+- [Phase 06]: Phase-level UX fixes (surfaced during UAT, not in any single plan): AppNav made persistent across routes — nav no longer disappears on /lists (commits 6070437 RED + 051874b fix); BottomTabBar hidden on desktop — no longer overlaps sidebar Settings affordance (commits 740e342 RED + 089b53d fix)
+- [Phase ?]: D-04-SCHEDULE-X-LOCATOR: Used .sx-react-calendar-wrapper CSS class to assert Schedule-X grid — no semantic role on outer wrapper div
+- [Phase ?]: D-04-EMPTY-NETWORK-SIM: Lists empty state simulated via page.route to 200 empty array — preserves seeded DB for parallel workers (D-06 / T-07-11)
+- [Phase ?]: D-13-08: Prettier reformat committed as isolated mechanical diff; CI Format check step added to fast-checks job
+- [Phase ?]: D-07 (16-01): ENV NODE_ENV=production baked into production Dockerfile stage — engages devBypass.ts hard guard so DEV_AUTH_BYPASS never injects in production
+- [Phase ?]: D-08 (16-01): assertNotDevBypassInProduction() boot guard — first statement in isMainModule(), exits non-zero when NODE_ENV=production AND DEV_AUTH_BYPASS=true; unit-tested
+- [Phase ?]: D-03-SEC-VERSION: Pinned eslint-plugin-security@3.0.1 over 4.0.1 — stable, flat-config compatible with ESLint 9.39.4, more bake time
+- [Phase ?]: D-03-OBJ-INJECT: detect-object-injection disabled globally in eslint-plugin-security block — all hits were numeric loop indices / schema-derived keys; zod guards real API input; 14 of 15 rules remain at error
+- [Phase ?]: D-04-ALLOWLIST: crypto.test.ts TEST_KEY allowlisted by path — human-verified Vitest beforeAll synthetic AES-256-GCM fixture; 4th [[allowlists]] block in .gitleaks.toml
+- [Phase ?]: D-04-BASELINE: gitleaks full-history baseline is empty [] after allowlisting — 613 commits / 23 MB scanned clean; PR-diff scans in 16-05 start from provably clean state
+- [Phase ?]: D-12-security-job: gitleaks runs unconditionally, pnpm audit/outdated code-gated at step level
+- [Phase ?]: D-14-gate-security: security wired into gate with individual needs.security.result==success check (not success-or-skipped, Gitea #31007)
+- [Phase ?]: D-MIGRATION-10-01: v1.1 DB migration applied via direct mysql2 DDL (drizzle-kit migrate silently failed due to journal hash mismatch with legacy tracking; hash recorded in __drizzle_migrations for forward compatibility)
+- [Phase ?]: D-10-02-aggregate-limit1: Drizzle COUNT aggregate uses .limit(1) for mock-chain compatibility
+- [Phase ?]: isAdmin drives nav visibility; real boundary is server-side
+- [Phase ?]: Single bottom sheet component handles all credential entry flows
+- [Phase ?]: No X button on SetupBanner; cleared by needsProviderSetup=false from /api/me refetch
+- [Phase ?]: D-CLIENT-TYPES: reminderLeadMinutes required on CalendarOccurrence, optional on CreateEventPayload (absent=no-change D-08)
+- [Phase ?]: D-PAYLOAD-ABSENT: __custom__ unchanged → field omitted from payload; server hasOwnProperty check preserves original VALARM (D-08)
+- [Phase ?]: D-NULL-FALLBACK: occurrence.reminderLeadMinutes===null mapped to None; occurrence cannot distinguish absolute/multi-VALARM from no-reminder; rely on server-side preserve (absent payload)
+- [Phase ?]: D-05/18-03: three all-day broker sites now route through getHouseholdTimezone(db)
+- [Phase ?]: D-12-03-EMAIL-GREP (2026-06-15, 12-03): claims.email in deriveDisplayName is display-name only; claim branch has zero email refs; D-10 upheld
+- [Phase 12-06]: D-12-06-VAPID-EQ: validate/vapid compares submitted PUBLIC key (app_config.vapid_public_key) to process.env.VAPID_PUBLIC_KEY; mismatched/absent 400s. Private key stays env-only, never compared/returned (T-12-06).
+- [Phase 12-06]: D-12-06-DBNAME: GET /api/setup/status returns non-secret dbName from process.env.DB_NAME only; no DB_HOST/DB_USER/DB_PASSWORD in any response.
 
 ### 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.
+- Phase 6 complete (2026-06-10): all 6 plans executed + 2 phase-level UX fixes (AppNav persistence + BottomTabBar desktop hide). Residual device-only checkpoints documented above.
+- Backlog reviewed (2026-06-10, /gsd-review-backlog): removed 6 stale duplicates (999.2/3/6/7/8/9 — already promoted into Phase 6) from the Backlog section + deleted the 999.2 dir; kept 999.1/4/5/10/11/12/13; added 999.14 (Gitea CI, promoted from STATE pending todo); archived stale kickoff-new-project todo.
+- **v1.1 roadmap created (2026-06-10):** 6 phases (7–12), continuing v1.0 numbering. 17/17 requirements mapped, no orphans. Promotions: 999.13→Faster Write-Back (CAL-15), 999.10→Admin Role & Settings (ADMIN-01/02/03), 999.11→Setup Wizard (SETUP-01/02/03/04), 999.4→Per-Event Reminders (CAL-13/14 + NOTIF-04/05/06), 999.14→Gitea CI (CI-01/02), 999.12→Mobile Test Harness (TEST-01/02). The v1.1 DB migration (users.is_admin, calendar_events.reminder_lead_minutes, app_config) is folded into the Admin phase (per ARCHITECTURE.md ordering), not a standalone migration phase; the reminders + wizard phases consume it. Backlog 999.5 (self-service onboarding) and 999.1 (provider abstraction) stay deferred — ADMIN-01 covers the admin-managed credential gap in the interim.
+- **v1.1 roadmap reordered (2026-06-10):** same 6 phases / 17 mappings, new order/numbering. Phase 7 = Mobile Test Harness (was 12), Phase 8 = Gitea CI (was 11), Phase 9 = Faster Write-Back (was 7), Phase 10 = Admin Role & Settings (was 8, carries the DB migration), Phase 11 = Per-Event Reminders (was 10), Phase 12 = Initial Setup Wizard (was 9). **Phase 8 (CI) scope extended:** the PR regression now also runs the Phase 7 mobile harness as a UI-regression step, bringing up the dev stack (API + PWA dev servers + MariaDB service container + DEV_AUTH_BYPASS) in the runner — so **Phase 8 now depends on Phase 7**. New critical path: **7 → 8** (CI consumes the harness); **9** independent; **10 → 11** and **10 → 12** (admin migration precedes reminders + wizard). Parallelizable once prerequisites met: 9 anytime; 11 and 12 in parallel after 10; 7 then 8.
+- **Phase 16 added (2026-06-12, /gsd-phase):** CI Dependency Audit, Security Checks & Image Hygiene — extend the Phase 8 Gitea CI workflow with outdated-dependency reporting (`pnpm outdated`), a vulnerability audit (`pnpm audit` at a chosen severity), and a baseline of additional security checks (secret scan / image scan). User requested a 16 integer phase (not a decimal insert) — they've been running independent/CI phases ahead of the admin chain. **Depends on Phase 8; independent of the admin chain (10–12).** Scope still needs definition — run /gsd-discuss-phase 16. Milestone window now Phases 7–16.
+- **Backlog 999.17 folded into Phase 16 + removed (2026-06-12, /gsd-phase):** the dev/prod image-boundary item (confine `DEV_AUTH_BYPASS` to dev via build/boot-time enforcement; ensure no `.env`/secrets/encryption keys/`DEV_USER` seed/family data ship in published images; CI assertion in the publish job) was pulled into Phase 16 — shared CI surface and overlapping secret/image scanning made a separate phase redundant. The 999.17 backlog entry + its phase dir were **deleted** (not retained-for-history) since the scope now lives in an active phase; this also clears the recycled-number collision with Phase 15's historical "promoted from 999.17" provenance (the markdown-lint item that became Phase 15 had reused 999.17 first).
+- **Phase 18 added (2026-06-13, /gsd-phase):** Auto timezone detection and ability to change timezone — let the app auto-detect the household timezone and allow changing it. User invoked `/gsd-phase --insert 18` but Phase 18 didn't exist (17 was the last integer phase), so after confirmation it was added as an integer phase at the end of the milestone, not a decimal insert. Motivated by the Phase 11 all-day-reminder dependency on a correct server `TZ` (all-day reminders fire at 9 AM local, computed from `process.env.TZ`). Scope still needs definition — run /gsd-discuss-phase 18. Milestone window now Phases 7–18.
+- **Phase 20 added (2026-06-18, /gsd-phase):** Admin Member Editor & Form Declutter — replace the per-member-row action buttons (Rotate/Add credential + Reset password) with a single edit affordance (click member name or an edit button) opening a member-detail editor for all of a member's details (display name, local-login password, Fastmail/CalDAV app password) with clear non-jargon labels that retire "Rotate"; and collapse the "Add member" form behind a single trigger by default. Seeded by a UX gripe during Phase 17 verification that "Rotate" for the app password is unintuitive. Client-side AdminPage + CredentialSheet rework over existing `/api/admin` endpoints; no new authorization boundary. Scope still needs definition — run /gsd-discuss-phase 20. Milestone window now Phases 7–20.
 
 ### 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.)
-- **REQUIREMENTS.md traceability gap** — phase.complete flagged 6 REQ-IDs in the body missing from the Traceability table: CAL-09, CAL-10, CAL-11, CAL-12, DISP-01, DISP-02. Add them to keep traceability in sync (likely Phase 4/5/display requirements).
+- ~~**Fix `docs/deployment.md` local-dev command**~~ DONE 2026-06-10 (quick 260610-czd) — added a "Running locally (host-side, no Docker)" subsection with the correct two-terminal command (`set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev` + `pnpm --filter @familysync/pwa dev`). `--env-file` deliberately NOT baked into the dev script (root `.env` sets `DB_HOST=mariadb`; auto-load would break host-side dev).
+- ~~**REQUIREMENTS.md traceability gap**~~ DONE 2026-06-10 (gsd-fast) — added the 6 deferred REQ-IDs to the Traceability table: CAL-09…CAL-12 (v1.x, Deferred), DISP-01/DISP-02 (v2, Deferred). v1 coverage stays 20/20; deferred IDs tracked separately.
 - **DST spring-forward spot-check (Phase 2)** — recurring/DST is implemented and code-verified (VTIMEZONE before expansion + local display TZ), and operator approved general times; navigating to March 2026 to eyeball the spring-forward transition is a recommended future spot-check.
+- ~~**Gitea CI — regression on PR to main + Docker build/publish**~~ PROMOTED TO BACKLOG 999.14 → now **v1.1 Phase 8** (Gitea CI, CI-01/CI-02). Detail retained in pending todo `2026-06-10-gitea-ci-regression-and-docker-publish.md`. Scope extended in the reorder: CI also runs the Phase 7 mobile harness as a UI-regression step.
 
 ### Blockers/Concerns
 
@@ -104,28 +234,54 @@ Recent decisions affecting current work:
 - 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.
+- Phase 06 residual device-only items (not drivable in desktop Chromium): (1) PushPermissionPrompt spinner visible only in an installed iOS/standalone PWA — code-confirmed uses global @keyframes spin; spot-check at go-live. (2) iOS-Safari standalone cold-load and Authelia redirect — per 06-VALIDATION.md Manual-Only table; not yet verified. (3) Dev-bypass user (id 1) has no CalDAV credential/calendars; live event-create via the form requires user 2 or a dev-seed fix before go-live testing.
+- **v1.1 Phase 7 (Mobile Test Harness):** DEV_AUTH_BYPASS user 1 has no CalDAV credential/calendars — the harness verifies layout/flows, not live event-create. Confirm SW-block + bypass strategy before the first test (PITFALLS 14/15). These specs become Phase 8's CI UI-regression step, so structure them to run headlessly against a runner-hosted dev stack.
+- **v1.1 Phase 8 (Gitea CI):** Unraid Gitea runner Docker-socket/Node/pnpm state unknown — runner-probe is the first CI task (PITFALLS 12); MariaDB 11 readiness uses `healthcheck.sh --connect`, not `mysqladmin ping` (removed in MariaDB 11). NEW: the harness step brings up the API + PWA dev servers in the runner — added startup/readiness races on top of the MariaDB race; the step must wait for **both** dev servers to be ready before launching Playwright. Depends on Phase 7.
 
 ### Quick Tasks Completed
 
-| # | Description | Date | Commit | Directory |
-|---|-------------|------|--------|-----------|
-| 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/) |
+| #          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Date       | Commit  | Status   | Directory                                                                                                           |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| 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/) |
+| 260610-cr8 | Adopt drizzle generate+migrate workflow, retire db:push on MariaDB — removed db:push script + repointed deployment.md to migrate with anti-push warning; dry-verified no destructive diff                                                                                                                                                                                                                                                                                                                            | 2026-06-10 | 1a95d81 | Verified | [260610-cr8-adopt-drizzle-generate-migrate-workflow-](./quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/) |
+| 260610-czd | Fix docs/deployment.md local-dev command — added "Running locally (host-side, no Docker)" subsection with correct env-sourced two-terminal run command (Phase 2 UAT gap)                                                                                                                                                                                                                                                                                                                                             | 2026-06-10 | 39e2ee0 |          | [260610-czd-fix-docs-deployment-md-local-dev-command](./quick/260610-czd-fix-docs-deployment-md-local-dev-command/) |
+| 260610-hbu | Phase 5 reminder scheduler resilience (UAT Test 1 gap) — catch-up scan `(now, now+16min]` + per-uid exactly-once dedup so a missed/late cron tick no longer drops a reminder; lead-accurate body; also fixes pre-existing cross-tick double-fire. 10/10 reminder tests pass                                                                                                                                                                                                                                          | 2026-06-10 | 19d92c6 | Verified | [260610-hbu-make-phase-5-reminder-scheduler-resilien](./quick/260610-hbu-make-phase-5-reminder-scheduler-resilien/) |
+| 260610-i4x | Replace node-cron with setInterval in all 3 broker workers (poller/outbox/reminder) — node-cron 4.2.1 skipped EVERY scheduled execution in the long-running API process ("missed execution" each tick), so reminders/poll/outbox never fired on schedule. setInterval fires reliably (verified). 91 broker tests pass                                                                                                                                                                                                | 2026-06-10 | d9efbc1 | Verified | [260610-i4x-replace-node-cron-with-setinterval-in-ba](./quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/) |
+| 260610-jlp | Fix broken "How to enable" link in notifications-blocked UI (Phase 5 UAT Test 4) — extracted InstructionSheet into a shared component; SettingsSheet "How to enable" now opens the OS-step instructions instead of just closing the sheet. 187 pwa tests pass, build green                                                                                                                                                                                                                                           | 2026-06-10 | f82837c | Verified | [260610-jlp-fix-broken-how-to-enable-link-in-notific](./quick/260610-jlp-fix-broken-how-to-enable-link-in-notific/) |
+| 260610-k1z | Persist OIDC session cookie (AUTH-02) — @hono/oidc-auth 1.8.3 sets a session-scoped `oidc-auth` cookie (no maxAge) so it died on PWA/browser close → re-login almost every return (both devices). Added persistSessionCookie middleware re-issuing the cookie with maxAge(=OIDC_AUTH_EXPIRES)+SameSite=Lax, ONLY when a valid session exists (no resurrection guard). NOT an Authelia/refresh issue. 14 auth tests pass                                                                                              | 2026-06-10 | 8343fad | Verified | [260610-k1z-persist-oidc-session-cookie-with-maxage-](./quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/) |
+| 260610-ka9 | Fix silent Android push (Phase 5 UAT Test 4) — SW showNotification had only {body,tag,data} → Android Chromium/Edge showed them silently. Added icon/badge/renotify:true/vibrate; generalized re-enable instructions to Chrome-or-Edge. iOS unaffected. Build emits sw.js with renotify; 187 pwa tests pass                                                                                                                                                                                                          | 2026-06-10 | c864fc4 | Verified | [260610-ka9-fix-silent-android-push-notifications-en](./quick/260610-ka9-fix-silent-android-push-notifications-en/) |
+| 260611-ozt | Split publish job into standalone .gitea/workflows/publish.yml (on: push→main only, no redundant event-guard if:; MILESTONE env moved with it) and strip it + the push trigger from ci.yml — kills the orphaned `CI / publish (pull_request)` pending status (phase-8 code-review WR-01). name:CI + fast-checks/api/harness job ids held stable so the required branch-protection contexts stay valid. Documented the release model in README "Publishing / Releases" + publish.yml header. Both YAML validated (yq) | 2026-06-11 | 92353e1 |          | [260611-ozt-split-publish-job-into-standalone-gitea-](./quick/260611-ozt-split-publish-job-into-standalone-gitea-/) |
+| 260611-tfc | Fix WR-01 (13-REVIEW): apps/pwa/src/sw.ts notificationclick openWindow fallback was unreachable when client.focus() rejects (window closed between matchAll/focus) or client.navigate() resolves null — chained a navigate-result check + a .catch, both falling through to self.clients.openWindow(url). lint/format:check/typecheck green, build emits sw.js, 191/191 pwa tests | 2026-06-12 | af78ccc | Verified | [260611-tfc-fix-wr-01-sw-ts-notificationclick-openwi](./quick/260611-tfc-fix-wr-01-sw-ts-notificationclick-openwi/) |
+| 260613-dmw | Exclude `.gitea/**` from the CI `changes` `code` paths-filter so workflow-only PRs skip the heavy api/harness jobs (treated like docs) while fast-checks + gate still run. Single `- '!.gitea/**'` negation appended after the yml/yaml globs (index 11 vs 5). Rides along on the Phase 16 branch / PR #15. | 2026-06-13 | 2d329a9 |  | [260613-dmw-exclude-gitea-workflow-config-changes-fr](./quick/260613-dmw-exclude-gitea-workflow-config-changes-fr/) |
+| 260613-fp9 | `.gitea`/`.planning`-only pushes to main no longer trigger the Docker publish — added `paths-ignore: ['.gitea/**', '.planning/**']` under `on.push` in `.gitea/workflows/publish.yml` (skips only when EVERY changed file matches; mixed code+docs pushes still publish). `.dockerignore` already excludes `.planning` so the image is byte-identical. Done in isolated worktree (phase-10 agent held main tree). | 2026-06-13 | cd5a88c | | [260613-fp9-gitea-and-planning-pushes-should-not-tri](./quick/260613-fp9-gitea-and-planning-pushes-should-not-tri/) |
+| 260613-ndv | Isolate local apps/api integration tests to a dedicated `familysync_test` DB so test runs stop polluting the dev `familysync` DB. New CI-gated vitest globalSetup root-provisions (CREATE DATABASE + GRANT) + migrates + truncate-resets `familysync_test` each run; `vitest.config.ts` forces `DB_NAME=familysync_test` for local workers (no-op under CI, so CI's `familysync` service DB + db:migrate are untouched). Verified: dev `familysync` users stays 3 across a run, `familysync_test` resets (186→93, not doubled), 244/244 tests pass (flaky list_shares timeout gone), typecheck 0. Branch off main. | 2026-06-13 | 07d5161 | Verified | [260613-ndv-wire-apps-api-integration-tests-to-a-ded](./quick/260613-ndv-wire-apps-api-integration-tests-to-a-ded/) |
+| 260618-smr | Remove unused Redis service and all references — Redis confirmed unused at runtime (no ioredis/redis client import, no `REDIS_*` env, not a dependency in any package.json). Dropped the `redis` service from both compose files and cleaned all references in CLAUDE.md, README.md, and docs/* + e2e config. Kept the in-memory-vs-Redis design-rationale comments (D-12/D-18) in listEmitter/reminderScheduler/linkNonceStore/localAuth. `docker compose config` parses clean (0 redis); `format:check` green. Branch off main. | 2026-06-18 | 0b42666 | Verified | [260618-smr-remove-unused-redis-service-and-referenc](./quick/260618-smr-remove-unused-redis-service-and-referenc/) |
+| 260618-tg2 | Persistent CI dependency caches — point all 4 CI `pnpm install` steps at a host-mounted `/pnpm-store` (`--store-dir /pnpm-store --prefer-offline`) and persist Playwright browsers via `PLAYWRIGHT_BROWSERS_PATH=/ms-playwright` on the harness job; added BuildKit `--mount=type=cache` to all 3 Dockerfile install stages + `DOCKER_BUILDKIT=1` on the publish build. Avoids `actions/cache` (D-PROBE-04 timeout). In-repo only — requires act_runner `config.yaml` `container.options` host mounts (manual host change). Verdaccio deferred. Branch off main. | 2026-06-18 | 6e93e24 | Verified | [260618-tg2-persistent-ci-dependency-caches-pnpm-sto](./quick/260618-tg2-persistent-ci-dependency-caches-pnpm-sto/) |
 
 ## Deferred Items
 
-| Category | Item | Status | Deferred At |
-|----------|------|--------|-------------|
-| Calendar | Single-occurrence recurring edit (RECURRENCE-ID) | v1.x | Roadmap |
-| Calendar | "This and following" recurring edit | v1.x | Roadmap |
-| Calendar | Apple Calendar native subscribe URL docs | v1.x | Roadmap |
-| Calendar | Secondary timezone display toggle | v1.x | Roadmap |
-| Display | Wall-display / kiosk dashboard | v2 | PROJECT.md |
-| Calendar | Mark shared-family calendar `is_shared=1` — operator must first create a "Family" calendar on the primary Fastmail account + share it, let the poller sync it, then run `UPDATE calendars SET is_shared=1 WHERE id=<new row>`. Until then the shared color lane is empty (correct). | Phase 2 (deferred, D-16) | 2026-06-05 |
+| Category      | Item                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Status                            | Deferred At             |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------- |
+| Calendar      | Single-occurrence recurring edit (RECURRENCE-ID)                                                                                                                                                                                                                                                                                                                                                                                                                                  | v1.x                              | Roadmap                 |
+| Calendar      | "This and following" recurring edit                                                                                                                                                                                                                                                                                                                                                                                                                                               | v1.x                              | Roadmap                 |
+| Calendar      | Apple Calendar native subscribe URL docs                                                                                                                                                                                                                                                                                                                                                                                                                                          | v1.x                              | Roadmap                 |
+| Calendar      | Secondary timezone display toggle                                                                                                                                                                                                                                                                                                                                                                                                                                                 | v1.x                              | Roadmap                 |
+| Display       | Wall-display / kiosk dashboard                                                                                                                                                                                                                                                                                                                                                                                                                                                    | v2                                | PROJECT.md              |
+| Reminders     | Multiple reminders per event (2× VALARM)                                                                                                                                                                                                                                                                                                                                                                                                                                          | v1.2                              | v1.1 REQUIREMENTS.md    |
+| Onboarding    | Self-service member app-password setup (999.5) — v1.1 covers admin-managed (ADMIN-01)                                                                                                                                                                                                                                                                                                                                                                                             | Backlog                           | v1.1 roadmap            |
+| Calendar      | Provider abstraction (999.1) — Fastmail as one of several backends                                                                                                                                                                                                                                                                                                                                                                                                                | Backlog                           | v1.1 roadmap            |
+| Setup         | Wizard re-run / reconfigure flow after first setup                                                                                                                                                                                                                                                                                                                                                                                                                                | Backlog                           | v1.1 REQUIREMENTS.md    |
+| Notifications | **Android event-change push delivery (Phase 5 UAT Test 4)** — confirm member B's Android device receives a non-silent "A updated an event" push after member A edits a shared event. Blocking bugs already fixed + deployed (quick 260610-jlp how-to-enable link, 260610-ka9 silent-notification options); server-side FCM delivery proven (FCM 201). Remaining: on-device confirmation + operator raises the Edge/Android notification-channel importance. See 05-UAT.md Test 4. | Phase 6 verification              | 2026-06-10              |
+| ~~Calendar~~  | ~~Mark shared-family calendar `is_shared=1`~~ **RESOLVED 2026-06-10** — operator created the "FamilySync" calendar on the primary Fastmail account; poller synced it as calendars.id=10 (user 2); ran `UPDATE calendars SET is_shared=1 WHERE id=10`. Shared color lane now populated; Phase 5 reminders now fire on its events. Poller upsert does not touch is_shared, so the flag persists. (ADMIN-02 in v1.1 Phase 10 replaces this manual step with a UI toggle.)            | ~~Phase 2 (deferred, D-16)~~ DONE | 2026-06-05 → 2026-06-10 |
 
 ## Session Continuity
 
-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
+Last session: 2026-06-18T21:40:44.704Z
+Stopped at: Phase 20 UI-SPEC approved
+Resume file: .planning/phases/20-admin-member-editor-form-declutter/20-UI-SPEC.md
+
+## Operator Next Steps
+
+- Start the next milestone with /gsd-new-milestone

.planning/codebase/ARCHITECTURE.md

@@ -1,4 +1,5 @@
 <!-- refreshed: 2026-06-09 -->
+
 # Architecture
 
 **Analysis Date:** 2026-06-09
@@ -50,53 +51,56 @@
          └─ 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` |
+| 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). 
+**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)
@@ -107,6 +111,7 @@
 ## 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)
@@ -114,6 +119,7 @@
 - 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
@@ -122,6 +128,7 @@
 - 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
@@ -129,6 +136,7 @@
 - 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
@@ -137,6 +145,7 @@
 - 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
@@ -159,6 +168,7 @@
 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
@@ -200,6 +210,7 @@
    - 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)
@@ -208,26 +219,31 @@
 ## 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)
@@ -235,36 +251,43 @@
 ## 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
+- 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
@@ -319,4 +342,4 @@
 
 ---
 
-*Architecture analysis: 2026-06-09*
+_Architecture analysis: 2026-06-09_

.planning/codebase/CONCERNS.md

@@ -5,6 +5,7 @@
 ## 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.
@@ -12,6 +13,7 @@
 - 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.
@@ -19,12 +21,14 @@
 - 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.
@@ -35,12 +39,14 @@
 ## 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.
@@ -51,18 +57,21 @@
 ## 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.
@@ -73,18 +82,21 @@
 ## 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.
@@ -95,16 +107,19 @@
 ## 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.
@@ -114,16 +129,19 @@
 ## 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).
@@ -133,16 +151,19 @@
 ## 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.
@@ -152,12 +173,14 @@
 ## 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.
@@ -168,30 +191,35 @@
 ## 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).
@@ -202,16 +230,19 @@
 ## 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.
@@ -221,12 +252,14 @@
 ## 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).
@@ -238,16 +271,19 @@
 ## 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.
@@ -255,4 +291,4 @@
 
 ---
 
-*Concerns audit: 2026-06-09*
+_Concerns audit: 2026-06-09_

.planning/codebase/CONVENTIONS.md

@@ -5,6 +5,7 @@
 ## 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/`)
@@ -12,12 +13,14 @@
 - 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()`
@@ -26,6 +29,7 @@
 - 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'`
@@ -33,6 +37,7 @@
 - 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
@@ -44,6 +49,7 @@
 ## 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"`)
@@ -51,21 +57,23 @@
 - 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 devUser = c.get('user') as { id: number } | undefined;
+  if (devUser) return devUser.id;
 
-  const auth = await getAuth(c)
-  if (!auth) return null
+  const auth = await getAuth(c);
+  if (!auth) return null;
 
-  const iss = (auth.iss as string | undefined) ?? ''
-  const sub = auth.sub ?? ''
+  const iss = (auth.iss as string | undefined) ?? '';
+  const sub = auth.sub ?? '';
   // ...
 }
 ```
@@ -73,6 +81,7 @@ async function resolveUserId(c: Context): Promise<number | null> {
 ## 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)
@@ -80,10 +89,12 @@ async function resolveUserId(c: Context): Promise<number | null> {
 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
@@ -105,6 +116,7 @@ import '../auth/devBypass.js'                     // Side-effect import (last)
 **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
@@ -112,6 +124,7 @@ import '../auth/devBypass.js'                     // Side-effect import (last)
 - 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)
@@ -136,28 +149,30 @@ eventsRouter.get('/', zValidator('query', eventsQuerySchema), async (c) => {
 ```
 
 **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')
+    throw new Error('GET /api/me: authentication required');
   }
 
   if (!res.ok) {
-    throw new Error(`GET /api/me failed: ${res.status}`)
+    throw new Error(`GET /api/me failed: ${res.status}`);
   }
 
-  return res.json() as Promise<MeResponse>
+  return res.json() as Promise<MeResponse>;
 }
 ```
 
@@ -166,6 +181,7 @@ export async function fetchMe(): Promise<MeResponse> {
 **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 ...')`
@@ -173,19 +189,21 @@ export async function fetchMe(): Promise<MeResponse> {
 - 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.')
+  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}`)
-})
+  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)
@@ -193,11 +211,13 @@ serve({ fetch: app.fetch, port: 3000 }, (info) => {
 - 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.
@@ -217,16 +237,19 @@ export const COLOR_PALETTE: string[] = [...]
 **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,
@@ -253,22 +276,26 @@ export async function upsertUser(
 ## 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'
+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
@@ -276,12 +303,14 @@ export { oidcAuthMiddleware, processOAuthCallback, getAuth } from '@hono/oidc-au
 - 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',
@@ -298,24 +327,27 @@ export const calendarEvents = mysqlTable(
     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.
@@ -327,4 +359,4 @@ export const calendarEvents = mysqlTable(
 
 ---
 
-*Convention analysis: 2026-06-09*
+_Convention analysis: 2026-06-09_

.planning/codebase/INTEGRATIONS.md

@@ -5,6 +5,7 @@
 ## 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)
@@ -14,6 +15,7 @@
   - 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)
@@ -27,6 +29,7 @@
 ## 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)
@@ -37,12 +40,14 @@
   - 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
@@ -51,6 +56,7 @@
 ## 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)
@@ -59,6 +65,7 @@
   - 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
@@ -67,14 +74,17 @@
 ## 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
@@ -83,15 +93,18 @@
 ## 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
@@ -100,6 +113,7 @@
 ## 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)
@@ -109,18 +123,21 @@
 - 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
@@ -128,6 +145,7 @@
   - 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
@@ -135,12 +153,14 @@
 ## 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
@@ -148,9 +168,10 @@
   - 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*
+_Integration audit: 2026-06-09_

.planning/codebase/STACK.md

@@ -5,20 +5,24 @@
 ## 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
@@ -26,16 +30,19 @@
 ## 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
@@ -44,45 +51,55 @@
 - @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
@@ -91,15 +108,18 @@
 ## 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)
+
+- `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
@@ -110,6 +130,7 @@
 ## Platform Requirements
 
 **Development:**
+
 - Node.js 22 LTS
 - pnpm 11.5.1
 - Docker + Docker Compose (for local MariaDB + Redis)
@@ -118,6 +139,7 @@
 - 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
@@ -127,4 +149,4 @@
 
 ---
 
-*Stack analysis: 2026-06-09*
+_Stack analysis: 2026-06-09_

.planning/codebase/STRUCTURE.md

@@ -93,12 +93,14 @@ familysync/
 ## 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
@@ -107,6 +109,7 @@ familysync/
 - **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
@@ -114,103 +117,104 @@ familysync/
 - **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 |
-|------|---------|
+| 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 |
+| `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 |
+| 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 |
+| 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 |
+| 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 |
+| 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()` |
+| 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` |
+| 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` |
+| 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 |
+| 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:**
 
@@ -241,6 +245,7 @@ familysync/
 ## 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)
@@ -248,26 +253,30 @@ familysync/
 - 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*
+_Structure analysis: 2026-06-09_

.planning/codebase/TESTING.md

@@ -5,16 +5,19 @@
 ## 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
@@ -30,14 +33,17 @@ 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
@@ -76,39 +82,41 @@ apps/pwa/src/
 ## Test Structure
 
 **Suite Organization:**
+
 ```typescript
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+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')
-    
+    const { app } = await import('../src/index.js');
+
     // Act
-    const res = await app.request('/health')
-    
+    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)
-  })
+    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'))
+    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')
+    const { app } = await import('../src/index.js');
+    const res = await app.request('/health');
 
     // Assert
-    expect(res.status).toBe(503)
-  })
-})
+    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()`
@@ -120,25 +128,27 @@ describe('GET /health', () => {
 **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)
+const mockFetch = vi.mocked(fetch);
 mockFetch.mockResolvedValueOnce({
   ok: true,
   json: async () => ({ uid: 'test-uid' }),
-} as Response)
+} as Response);
 
 // Call the function under test
-await createEvent(payload)
+await createEvent(payload);
 
 // Assert the mock was called correctly
 expect(mockFetch).toHaveBeenCalledWith(
@@ -147,27 +157,30 @@ expect(mockFetch).toHaveBeenCalledWith(
     method: 'POST',
     credentials: 'include',
   }),
-)
+);
 ```
 
 **Global Stubs (Frontend):**
+
 ```typescript
 beforeEach(() => {
-  vi.stubGlobal('fetch', vi.fn())
-})
+  vi.stubGlobal('fetch', vi.fn());
+});
 
 afterEach(() => {
-  vi.unstubAllGlobals()
-})
+  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
@@ -181,7 +194,7 @@ 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')
+const rawVevent = readFileSync(join(FIXTURES, 'weekly-dst.ics'), 'utf8');
 
 // Use in test
 const occurrences = expandOccurrences(
@@ -194,7 +207,7 @@ const occurrences = expandOccurrences(
   'Alice',
   '#4A90D9',
   false,
-)
+);
 ```
 
 **Test Data (Frontend):**
@@ -205,14 +218,25 @@ 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 },
+      {
+        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)
+} 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.)
 
@@ -221,10 +245,12 @@ vi.mocked(fetch).mockResolvedValueOnce({
 **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
@@ -233,38 +259,43 @@ 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)
+  } as Response);
 
-  const { createEvent } = await import('./client.js')
-  const result = await createEvent(payload)
+  const { createEvent } = await import('./client.js');
+  const result = await createEvent(payload);
 
-  expect(result).toEqual({ uid: 'returned-uid' })
-})
+  expect(result).toEqual({ uid: 'returned-uid' });
+});
 ```
 
 **Error Testing:**
+
 ```typescript
 it('throws on non-ok response', async () => {
   vi.mocked(fetch).mockResolvedValueOnce({
@@ -274,7 +305,7 @@ it('throws on non-ok response', async () => {
   } as Response)
 
   const { createEvent } = await import('./client.js')
-  
+
   await expect(
     createEvent({ title: '', ... })
   ).rejects.toThrow()
@@ -282,78 +313,89 @@ it('throws on non-ok response', async () => {
 ```
 
 **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 { 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')
+  const { app } = await import('../src/index.js');
+  const res = await app.request('/health');
 
-  expect(res.status).toBe(503)
-})
+  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 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,
-    )
+      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]')
+      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'))
+    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
-  })
-})
+    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()
+    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')
-  })
-})
+    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: {
@@ -362,12 +404,13 @@ export default defineConfig({
     setupFiles: ['./src/test-setup.ts'],
     env: { TZ: 'UTC' },
   },
-})
+});
 ```
 
 **Example (from `apps/pwa/src/test-setup.ts`):**
+
 ```typescript
-import '@testing-library/jest-dom'
+import '@testing-library/jest-dom';
 
 Object.defineProperty(window, 'matchMedia', {
   writable: true,
@@ -376,25 +419,28 @@ Object.defineProperty(window, 'matchMedia', {
     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*
+_Testing analysis: 2026-06-09_

.planning/config.json

@@ -90,6 +90,13 @@
     "enabled": true
   },
   "graphify": {
-    "enabled": true
+    "enabled": true,
+    "auto_update": true
+  },
+  "mempalace": {
+    "enabled": true,
+    "wing": "familysync",
+    "recall_on_discuss": true,
+    "mirror_kg": true
   }
 }

.planning/debug/write-path-event-bugs.md

@@ -4,7 +4,7 @@ status: resolved
 trigger: "Phase 03 Gate 2 Part D — created events have wrong time (4h off) and attach to the wrong user's calendar; poller creates duplicate calendar rows"
 created: 2026-06-07
 updated: 2026-06-08
-phase: "03-event-write-back-pwa-install"
+phase: '03-event-write-back-pwa-install'
 branch: gsd/v1.0-milestone
 ---
 
@@ -15,6 +15,7 @@ branch: gsd/v1.0-milestone
 Two distinct, confirmed write-path bugs found during live Gate 2 Part D testing.
 
 ### BUG A — Event times written 4 hours off (local serialized as UTC)
+
 - **Expected:** Create an event for 9:00–10:00am local (operator is in America/Toronto, EDT = UTC−4) → it displays at 9:00–10:00am.
 - **Actual:** It displays at 5:00–6:00am (−4h).
 - **Confirmed evidence:** the stored VEVENT for the created event is:
@@ -27,25 +28,28 @@ Two distinct, confirmed write-path bugs found during live Gate 2 Part D testing.
 - **Acceptance:** 9am local in → stored as UTC-correct (or TZID) → round-trips → displays 9am local. Add a regression test.
 
 ### BUG B — Created events attach to the wrong user's calendar; poller creates duplicate calendar rows
+
 - **Expected:** user 2 (real OIDC, id=2) creates an event → it belongs to user 2's calendar; the poller maintains exactly one calendar row per (userId, collection URL).
 - **Actual:** the event landed on `calendar_id=1` (owned by user 1, the obsolete spike identity "Dev User", `oidc_iss='spike://cal-08'`). The poller created a NEW calendar row for user 2's "Calendar" collection on every poll.
 - **Confirmed evidence (DB):** `calendars` has FOUR rows for the same Fastmail collection URL ending `/2180A37A-806E-11EB-872C-AE53E9CB9923/`:
   - id=1 → user_id=1 (508 events)
   - id=2, id=4, id=5 → user_id=2 (0 events each) — duplicates created across polls
   - id=3 → user_id=2 "USA Holidays" (32 events, different URL — synced fine)
-  All "Calendar" events (508) sit under id=1; user 2's "Calendar" rows have 0 events.
+    All "Calendar" events (508) sit under id=1; user 2's "Calendar" rows have 0 events.
 - **Investigate:**
   - `apps/api/src/broker/poller.ts` — loops `davCalendars`, looks up the stored calendar via `eq(calendars.url, davCal.url)` WITHOUT a `userId` predicate → cross-user match (finds user 1's row). Strong candidate for the core defect.
   - `apps/api/src/broker/sync.ts` — calendar upsert (the `.values({` calls ~line 42 and ~105): how it matches/creates the calendar row (is it idempotent on (userId, url)? does it produce duplicates?), and how the event-cache upsert resolves `calendarId` (unique key is (calendarId, uid)) — events end up under the wrong calendarId.
 - **Acceptance:** exactly one calendar row per (userId, url); a user's created event syncs back under THAT user's calendar row; no duplicate rows accumulate across polls. Add regression test(s).
 
 ## Out of scope (tracked separately — do NOT fix here)
+
 - `GET /api/events` missing `userId`/`isShared` filter (returns all users' events).
 - `me.ts` blank `displayName`/`oidc_iss` (OIDC claim extraction).
 - Non-animated "Syncing" toast (UI polish).
 - Stale spike data cleanup (user 1 + calendar id=1 + 508 events) — data, not code; relates to BUG B but handle after the code fix.
 
 ## Environment
+
 - Stack running via `docker compose` (production target). Write path works end-to-end (outbox dispatches to Fastmail). These are LOGIC bugs, not infra.
 - DB access: `docker compose exec -T mariadb mariadb -ufamilysync -p"$(grep -E '^DB_PASSWORD' .env | cut -d= -f2)" familysync -e "..."`
 - Tests: `pnpm --filter @familysync/api exec vitest run` ; `pnpm --filter @familysync/pwa exec vitest run`. TDD mode is ON.
@@ -71,11 +75,13 @@ next_action: none — root cause confirmed and fixed for both bugs; regression t
 ## Resolution
 
 ### BUG A — write-path timezone serialization
+
 - **root_cause:** `EventForm.handleSubmit` sent timed start/end as a naive local wall-clock string (`${date}T${time}:00`, no UTC offset). The outbox worker then ran `new Date(thatString)`, which Node parses in the API container's local timezone (UTC in Docker) — so 09:00 America/Toronto was treated as 09:00 UTC. `buildVeventString` (`ICAL.Time.fromJSDate(d, true)`) then emitted `DTSTART:...090000Z`, displaying back as 05:00 EDT (−4h).
 - **fix:** Added `apps/pwa/src/lib/eventDateTime.ts` (`serializeEventDateTime`/`localWallClockToUtcIso`). The PWA now converts timed events to an unambiguous UTC instant in the browser (where the operator's zone is known) via `new Date(localParts).toISOString()`; the worker's `new Date(utcIso)` is now container-timezone-independent. All-day events stay `YYYY-MM-DD` DATE strings (D-13). Wired into `EventForm.handleSubmit`. No backend change needed.
 - **regression test:** `apps/pwa/src/lib/eventDateTime.test.ts` (5 cases): timed → UTC `Z` instant, round-trips to the same local wall clock, equals `new Date(localParts).toISOString()` (not passthrough), all-day stays a DATE string.
 
 ### BUG B — wrong-calendar attach + duplicate calendar rows
+
 - **root_cause:** Two faults compounding. (1) `calendars` had NO unique key on `url` (only a non-unique `idx_calendars_user_id`), so the `onDuplicateKeyUpdate` in `syncCalendar`'s calendar upsert never fired → every poll inserted a fresh row for user 2's collection. (2) Both `poller.ts` (ctag lookup) and `sync.ts` (post-upsert id select) matched on `url` alone. Because the two members share ONE Fastmail account (D-16), the same collection URL exists for both; the url-only query returned the lowest-id row (user 1's id=1), so user 2's events were cached under `calendarId=1`.
 - **fix:**
   - `apps/api/src/db/schema.ts`: added composite `unique('uniq_calendar_user_url').on(t.userId, t.url)` so the calendar upsert is idempotent per (userId, url).
@@ -85,6 +91,7 @@ next_action: none — root cause confirmed and fixed for both bugs; regression t
 - **regression tests:** `poller.test.ts` + `sync.test.ts` each assert the calendar predicate is scoped to `(user_id, url)` (verified non-vacuous: fails against the buggy url-only predicate); `sync.test.ts` asserts the calendar upsert uses `onDuplicateKeyUpdate`.
 
 ### Verification
+
 - API tests: 98/98 pass. PWA tests: 140/140 pass. `tsc --noEmit` clean for both packages.
 - Live DB post-migration: `calendars` = id1(user1, stale spike data, out-of-scope), id2(user2 Calendar), id3(user2 USA Holidays); `uniq_calendar_user_url` present.
 - NOT done here (per scope guardrails / broken playwright daemon): image rebuild + tunnel re-test, and stale spike data cleanup (user 1 / calendar id=1 / 508 events). Orchestrator owns these.

.planning/intel/API-SURFACE.md

@@ -2,6 +2,8 @@
 
 > Generated from `.planning/intel/api-map.json`. Do not edit by hand.
 
+> **Warning:** api-map.json is stale (>24 hours old). Data below may be out of date.
+
 ## `GET /health`
 
 - **method:** GET
@@ -102,4 +104,95 @@
 - **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.
+- **description:** SSE smoke-test endpoint for Pangolin tunnel validation.
+
+## `GET /api/sse/lists`
+
+- **method:** GET
+- **path:** /api/sse/lists
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/routes/sse.ts
+- **response:** text/event-stream — events: item:added | item:updated | item:deleted | list:updated | list:deleted, plus heartbeat every 30s
+- **description:** Scoped live-list fan-out stream (LIST-04, D-04). Subscribes only to list channels accessible to the caller (owner + shares). Event payload triggers client-side query invalidation (D-10). 30s keepalive heartbeat for Pangolin tunnel.
+
+## `GET /api/lists`
+
+- **method:** GET
+- **path:** /api/lists
+- **auth:** oidcAuthMiddleware
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { lists: [{ id, name, isShared, ownerId, activeCount, doneCount, createdAt, updatedAt }] }
+- **description:** Scoped list index. Returns only lists the caller owns or has a list_shares row for (T-04-02, D-04). Includes per-list item counts.
+
+## `POST /api/lists`
+
+- **method:** POST
+- **path:** /api/lists
+- **auth:** oidcAuthMiddleware
+- **body:** { name: string, isShared?: boolean (default true) }
+- **file:** apps/api/src/routes/lists.ts
+- **response:** 201 { id, name, isShared, ownerId, activeCount, doneCount, createdAt, updatedAt }
+- **description:** Create a named list. isShared=true (default) auto-inserts list_shares for all other members (D-01/D-02). Shares are server-managed only — no client shares endpoint (T-04-08).
+
+## `PATCH /api/lists/:id`
+
+- **method:** PATCH
+- **path:** /api/lists/:id
+- **auth:** oidcAuthMiddleware
+- **params:** id (path)
+- **body:** { name?: string, isShared?: boolean } — at least one field required
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { id, name, isShared, ownerId, createdAt, updatedAt }
+- **description:** Update name and/or isShared. Caller must be owner or sharee. isShared mutations owner-only (T-04-07/T-04-08). Visibility change reconciles list_shares (false→true inserts; true→false deletes all non-owner shares).
+
+## `DELETE /api/lists/:id`
+
+- **method:** DELETE
+- **path:** /api/lists/:id
+- **auth:** oidcAuthMiddleware
+- **params:** id (path)
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { id }
+- **description:** Owner-only delete. Cascade via FK onDelete:cascade removes items and shares. Non-owner sharees receive 403.
+
+## `GET /api/lists/:id/items`
+
+- **method:** GET
+- **path:** /api/lists/:id/items
+- **auth:** oidcAuthMiddleware
+- **params:** id (path)
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { items: [{ id, listId, text, checked, rank, createdAt, updatedAt }] }
+- **description:** Returns all items for the list ordered by rank ASC. Access-gated: owner or sharee only (T-04-05).
+
+## `POST /api/lists/:id/items`
+
+- **method:** POST
+- **path:** /api/lists/:id/items
+- **auth:** oidcAuthMiddleware
+- **params:** id (path)
+- **body:** { text: string (1..500) }
+- **file:** apps/api/src/routes/lists.ts
+- **response:** 201 { id, listId, text, checked, rank, createdAt, updatedAt }
+- **description:** Add item to list. Rank assigned via rankForAppend(lastActiveRank) — appends after last unchecked item. Access-gated (T-04-05). publishListEvent item:added fan-out.
+
+## `PATCH /api/list-items/:itemId`
+
+- **method:** PATCH
+- **path:** /api/list-items/:itemId
+- **auth:** oidcAuthMiddleware
+- **params:** itemId (path)
+- **body:** exactly one of: { checked: boolean } | { text: string } | { position: string }
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { id, listId, text, checked, rank, createdAt, updatedAt }
+- **description:** Per-field last-write-wins item update (D-08). Exactly one field enforced by Zod (T-04-07). uncheck (checked:false) recomputes rank to active-bottom. 404 if item missing (T-04-09, no upsert). publishListEvent item:updated fan-out.
+
+## `DELETE /api/list-items/:itemId`
+
+- **method:** DELETE
+- **path:** /api/list-items/:itemId
+- **auth:** oidcAuthMiddleware
+- **params:** itemId (path)
+- **file:** apps/api/src/routes/lists.ts
+- **response:** { id }
+- **description:** Delete item instantly (D-06). Delete-wins semantics (D-09): no rollback path. Access-gated: owner or sharee. publishListEvent item:deleted fan-out.

.planning/intel/api-map.json

@@ -1,8 +1,8 @@
 {
   "_meta": {
-    "updated_at": "2026-06-09T00:00:00Z",
-    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
-    "version": 1
+    "updated_at": "2026-06-09T18:56:37.459Z",
+    "commit": "99f59c3999f4ef992f01ef8f8a38c1d86d2f2a0f",
+    "version": 3
   },
   "entries": {
     "GET /health": {
@@ -94,7 +94,89 @@
       "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."
+      "description": "SSE smoke-test endpoint for Pangolin tunnel validation."
+    },
+    "GET /api/sse/lists": {
+      "method": "GET",
+      "path": "/api/sse/lists",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/routes/sse.ts",
+      "response": "text/event-stream — events: item:added | item:updated | item:deleted | list:updated | list:deleted, plus heartbeat every 30s",
+      "description": "Scoped live-list fan-out stream (LIST-04, D-04). Subscribes only to list channels accessible to the caller (owner + shares). Event payload triggers client-side query invalidation (D-10). 30s keepalive heartbeat for Pangolin tunnel."
+    },
+    "GET /api/lists": {
+      "method": "GET",
+      "path": "/api/lists",
+      "auth": "oidcAuthMiddleware",
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ lists: [{ id, name, isShared, ownerId, activeCount, doneCount, createdAt, updatedAt }] }",
+      "description": "Scoped list index. Returns only lists the caller owns or has a list_shares row for (T-04-02, D-04). Includes per-list item counts."
+    },
+    "POST /api/lists": {
+      "method": "POST",
+      "path": "/api/lists",
+      "auth": "oidcAuthMiddleware",
+      "body": "{ name: string, isShared?: boolean (default true) }",
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "201 { id, name, isShared, ownerId, activeCount, doneCount, createdAt, updatedAt }",
+      "description": "Create a named list. isShared=true (default) auto-inserts list_shares for all other members (D-01/D-02). Shares are server-managed only — no client shares endpoint (T-04-08)."
+    },
+    "PATCH /api/lists/:id": {
+      "method": "PATCH",
+      "path": "/api/lists/:id",
+      "auth": "oidcAuthMiddleware",
+      "params": ["id (path)"],
+      "body": "{ name?: string, isShared?: boolean } — at least one field required",
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ id, name, isShared, ownerId, createdAt, updatedAt }",
+      "description": "Update name and/or isShared. Caller must be owner or sharee. isShared mutations owner-only (T-04-07/T-04-08). Visibility change reconciles list_shares (false→true inserts; true→false deletes all non-owner shares)."
+    },
+    "DELETE /api/lists/:id": {
+      "method": "DELETE",
+      "path": "/api/lists/:id",
+      "auth": "oidcAuthMiddleware",
+      "params": ["id (path)"],
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ id }",
+      "description": "Owner-only delete. Cascade via FK onDelete:cascade removes items and shares. Non-owner sharees receive 403."
+    },
+    "GET /api/lists/:id/items": {
+      "method": "GET",
+      "path": "/api/lists/:id/items",
+      "auth": "oidcAuthMiddleware",
+      "params": ["id (path)"],
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ items: [{ id, listId, text, checked, rank, createdAt, updatedAt }] }",
+      "description": "Returns all items for the list ordered by rank ASC. Access-gated: owner or sharee only (T-04-05)."
+    },
+    "POST /api/lists/:id/items": {
+      "method": "POST",
+      "path": "/api/lists/:id/items",
+      "auth": "oidcAuthMiddleware",
+      "params": ["id (path)"],
+      "body": "{ text: string (1..500) }",
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "201 { id, listId, text, checked, rank, createdAt, updatedAt }",
+      "description": "Add item to list. Rank assigned via rankForAppend(lastActiveRank) — appends after last unchecked item. Access-gated (T-04-05). publishListEvent item:added fan-out."
+    },
+    "PATCH /api/list-items/:itemId": {
+      "method": "PATCH",
+      "path": "/api/list-items/:itemId",
+      "auth": "oidcAuthMiddleware",
+      "params": ["itemId (path)"],
+      "body": "exactly one of: { checked: boolean } | { text: string } | { position: string }",
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ id, listId, text, checked, rank, createdAt, updatedAt }",
+      "description": "Per-field last-write-wins item update (D-08). Exactly one field enforced by Zod (T-04-07). uncheck (checked:false) recomputes rank to active-bottom. 404 if item missing (T-04-09, no upsert). publishListEvent item:updated fan-out."
+    },
+    "DELETE /api/list-items/:itemId": {
+      "method": "DELETE",
+      "path": "/api/list-items/:itemId",
+      "auth": "oidcAuthMiddleware",
+      "params": ["itemId (path)"],
+      "file": "apps/api/src/routes/lists.ts",
+      "response": "{ id }",
+      "description": "Delete item instantly (D-06). Delete-wins semantics (D-09): no rollback path. Access-gated: owner or sharee. publishListEvent item:deleted fan-out."
     }
   }
 }

.planning/intel/arch-decisions.json

@@ -1,14 +1,18 @@
 {
   "_meta": {
-    "updated_at": "2026-06-09T00:00:00Z",
-    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
-    "version": 1
+    "updated_at": "2026-06-09T18:56:37.788Z",
+    "commit": "99f59c3999f4ef992f01ef8f8a38c1d86d2f2a0f",
+    "version": 3
   },
   "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/"]
+      "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",
@@ -58,12 +62,55 @@
     "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"]
+      "files": ["apps/pwa/src/lib/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"]
+    },
+    "lists-storage-mariadb-not-caldav": {
+      "title": "Lists stored in MariaDB, not CalDAV (Phase 4)",
+      "decision": "Named lists and items are app-owned data in MariaDB (lists, list_items, list_shares tables), not pushed to Fastmail. CalDAV is exclusively for calendar events.",
+      "files": ["apps/api/src/db/schema.ts", "apps/api/src/routes/lists.ts"]
+    },
+    "D-01-D-02-list-sharing": {
+      "title": "D-01/D-02 list sharing via join table (member-count-agnostic)",
+      "decision": "isShared=true (default) triggers auto-insert of list_shares rows for all other users at create/patch time. Shares are server-managed only — no client-writable shares endpoint (T-04-08). list_shares join table is member-count-agnostic for future N-member expansion.",
+      "files": ["apps/api/src/routes/lists.ts", "apps/api/src/db/schema.ts"]
+    },
+    "D-04-scoped-sse-fan-out": {
+      "title": "D-04 scoped SSE fan-out — per-list channels, not global",
+      "decision": "GET /api/sse/lists resolves the caller's accessible list IDs via getAccessibleListIds, then subscribes one listEmitter channel per ID. Private lists of other members are never delivered. In-memory EventEmitter singleton (D-18) — no Redis; single-process, no replicas.",
+      "files": [
+        "apps/api/src/routes/sse.ts",
+        "apps/api/src/lib/listEmitter.ts",
+        "apps/api/src/lib/listAccess.ts"
+      ]
+    },
+    "D-08-per-field-lww-patch": {
+      "title": "D-08 per-field last-write-wins PATCH for list items",
+      "decision": "PATCH /api/list-items/:itemId accepts exactly one field (checked | text | position). Zod enforces single-field constraint. Prevents one client's stale read overwriting concurrent updates to other fields.",
+      "files": ["apps/api/src/routes/lists.ts"]
+    },
+    "D-13-fractional-rank": {
+      "title": "D-13 fractional-indexing rank for list item ordering",
+      "decision": "list_items.rank is a varchar(255) COLLATE utf8mb4_bin using fractional-indexing strings. A single drag-reorder writes only the moved item's rank (one-row write). utf8mb4_bin collation required so uppercase-prefixed ranks (e.g. 'Zz') sort before lowercase (e.g. 'a0'), matching JS string order.",
+      "files": [
+        "apps/api/src/db/schema.ts",
+        "apps/api/src/lib/rank.ts",
+        "apps/pwa/src/routes/ListDetail.tsx"
+      ]
+    },
+    "D-10-D-11-D-12-sse-resilience": {
+      "title": "D-10/D-11/D-12 SSE resilience: invalidate-not-patch, bounded backoff, polling fallback",
+      "decision": "D-10: SSE events carry minimal { type, listId } payload; client full-refetches via TanStack Query invalidation rather than patching cache from event payload. D-11: useListSSE implements bounded backoff (250ms→8s cap, MAX_ATTEMPTS then give-up). D-12: 30s polling fallback always active in ListDetail as safety net.",
+      "files": ["apps/pwa/src/hooks/useListSSE.ts", "apps/pwa/src/routes/ListDetail.tsx"]
+    },
+    "react-router-spa-shell": {
+      "title": "react-router BrowserRouter SPA shell with BottomTabBar",
+      "decision": "App.tsx wraps routes in BrowserRouter with declarative Routes. BottomTabBar is a sibling of Routes (not inside) so it persists across navigation. SW navigateFallback covers /lists/* deep-links.",
+      "files": ["apps/pwa/src/App.tsx", "apps/pwa/src/components/BottomTabBar.tsx"]
     }
   }
 }

.planning/intel/dependency-graph.json

@@ -1,8 +1,8 @@
 {
   "_meta": {
-    "updated_at": "2026-06-09T00:00:00Z",
-    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
-    "version": 1
+    "updated_at": "2026-06-09T18:56:37.618Z",
+    "commit": "99f59c3999f4ef992f01ef8f8a38c1d86d2f2a0f",
+    "version": 3
   },
   "entries": {
     "hono": {
@@ -31,14 +31,19 @@
       "type": "production",
       "workspace": "@familysync/api",
       "invocation": "require",
-      "used_by": ["apps/api/src/routes/events.ts"]
+      "used_by": ["apps/api/src/routes/events.ts", "apps/api/src/routes/lists.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/"]
+      "used_by": [
+        "apps/api/src/db/client.ts",
+        "apps/api/src/db/schema.ts",
+        "apps/api/src/routes/",
+        "apps/api/src/lib/listAccess.ts"
+      ]
     },
     "mysql2": {
       "version": "3.22.4",
@@ -59,14 +64,25 @@
       "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"]
+      "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"]
+      "used_by": ["apps/api/src/routes/events.ts", "apps/api/src/routes/lists.ts"]
+    },
+    "fractional-indexing": {
+      "version": "^3.2.0",
+      "type": "production",
+      "workspace": "both (@familysync/api + @familysync/pwa)",
+      "invocation": "require",
+      "used_by": ["apps/api/src/lib/rank.ts", "apps/pwa/src/routes/ListDetail.tsx"]
     },
     "node-cron": {
       "version": "^4.2.1",
@@ -96,6 +112,31 @@
       "invocation": "require",
       "used_by": ["apps/pwa/src/"]
     },
+    "react-router": {
+      "version": "^7.17.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": [
+        "apps/pwa/src/App.tsx",
+        "apps/pwa/src/routes/",
+        "apps/pwa/src/components/BottomTabBar.tsx"
+      ]
+    },
+    "@dnd-kit/core": {
+      "version": "^6.3.1",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/routes/ListDetail.tsx"]
+    },
+    "@dnd-kit/sortable": {
+      "version": "^10.0.0",
+      "type": "production",
+      "workspace": "@familysync/pwa",
+      "invocation": "require",
+      "used_by": ["apps/pwa/src/routes/ListDetail.tsx"]
+    },
     "vite": {
       "version": "8.0.16",
       "type": "development",
@@ -115,14 +156,20 @@
       "type": "production",
       "workspace": "@familysync/pwa",
       "invocation": "require",
-      "used_by": ["apps/pwa/src/App.tsx", "apps/pwa/src/components/"]
+      "used_by": [
+        "apps/pwa/src/App.tsx",
+        "apps/pwa/src/components/",
+        "apps/pwa/src/routes/ListsIndex.tsx",
+        "apps/pwa/src/routes/ListDetail.tsx",
+        "apps/pwa/src/hooks/useListSSE.ts"
+      ]
     },
     "zustand": {
       "version": "5.0.14",
       "type": "production",
       "workspace": "@familysync/pwa",
       "invocation": "require",
-      "used_by": ["apps/pwa/src/store/calendarStore.ts"]
+      "used_by": ["apps/pwa/src/store/calendarStore.ts", "apps/pwa/src/store/listsStore.ts"]
     },
     "@schedule-x/calendar": {
       "version": "4.6.0",

.planning/intel/file-roles.json

@@ -1,8 +1,8 @@
 {
   "_meta": {
-    "updated_at": "2026-06-09T00:00:00Z",
-    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
-    "version": 1
+    "updated_at": "2026-06-09T18:56:37.326Z",
+    "commit": "99f59c3999f4ef992f01ef8f8a38c1d86d2f2a0f",
+    "version": 3
   },
   "entries": {
     "apps/api/src/index.ts": {
@@ -14,6 +14,7 @@
         "./routes/health.js",
         "./routes/me.js",
         "./routes/events.js",
+        "./routes/lists.js",
         "./routes/sse.js",
         "./auth/middleware.js",
         "./auth/devBypass.js",
@@ -42,22 +43,43 @@
       "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"],
+    "apps/api/src/routes/lists.ts": {
+      "exports": ["listsRouter", "listItemsRouter"],
       "imports": [
         "hono",
+        "@hono/zod-validator",
+        "zod",
+        "drizzle-orm",
+        "../db/client.js",
+        "../db/schema.js",
         "../auth/middleware.js",
         "../auth/user.js",
-        "../auth/devBypass.js"
+        "../auth/devBypass.js",
+        "../lib/rank.js",
+        "../lib/listEmitter.js"
       ],
       "type": "module",
-      "notes": "GET /api/me — returns { user: { id, displayName, color } }. Upserts user on first login."
+      "notes": "listsRouter: GET/POST /api/lists, PATCH/DELETE /api/lists/:id, POST/GET /api/lists/:id/items. listItemsRouter: PATCH/DELETE /api/list-items/:itemId. Owner-guard on isShared mutations (T-04-07/T-04-08). Auto-populates list_shares on isShared=true creation (D-01/D-02). publishListEvent fan-out after every mutation."
     },
     "apps/api/src/routes/sse.ts": {
       "exports": ["sseRouter"],
-      "imports": ["hono", "hono/streaming"],
+      "imports": [
+        "hono",
+        "hono/streaming",
+        "../auth/middleware.js",
+        "../auth/user.js",
+        "../auth/devBypass.js",
+        "../lib/listEmitter.js",
+        "../lib/listAccess.js"
+      ],
       "type": "module",
-      "notes": "GET /api/sse/heartbeat — server-sent events smoke-test; 10s interval heartbeat. Phase 4 SSE fan-out to be added."
+      "notes": "GET /api/sse/heartbeat — 10s interval smoke-test. GET /api/sse/lists — scoped live-list fan-out (LIST-04, D-04); subscribes per-accessible-list via subscribeListEvents; 30s keepalive heartbeat."
+    },
+    "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/health.ts": {
       "exports": ["healthRouter"],
@@ -66,10 +88,19 @@
       "notes": "GET /health — unauthenticated. Runs SELECT 1 against DB; returns { ok, db }."
     },
     "apps/api/src/db/schema.ts": {
-      "exports": ["users", "memberCredentials", "calendars", "calendarEvents", "calendarOutbox"],
+      "exports": [
+        "users",
+        "memberCredentials",
+        "calendars",
+        "calendarEvents",
+        "calendarOutbox",
+        "lists",
+        "listShares",
+        "listItems"
+      ],
       "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."
+      "notes": "Drizzle schema for all 8 MariaDB tables. Phase 4 adds lists, list_shares, list_items. list_items.rank uses varcharBin (COLLATE utf8mb4_bin) for fractional-indexing sort correctness. calendarOutbox status enum: pending|done|failed|dead."
     },
     "apps/api/src/db/client.ts": {
       "exports": ["db"],
@@ -77,6 +108,24 @@
       "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/lib/listEmitter.ts": {
+      "exports": ["publishListEvent", "subscribeListEvents", "ListEvent"],
+      "imports": ["node:events"],
+      "type": "module",
+      "notes": "In-process singleton EventEmitter for list change fan-out (D-18). Per-list channels keyed as list:${listId}. publishListEvent broadcasts; subscribeListEvents returns an unsubscribe fn. Max 200 listeners (T-04-04). Redis swap seam: abstraction boundary is inside this module."
+    },
+    "apps/api/src/lib/listAccess.ts": {
+      "exports": ["getAccessibleListIds"],
+      "imports": ["drizzle-orm", "../db/client.js", "../db/schema.js"],
+      "type": "module",
+      "notes": "getAccessibleListIds(userId): returns deduped list IDs the user owns OR has a list_shares row for. Gate used by SSE endpoint to scope subscriptions (D-04, T-04-02, T-04-03)."
+    },
+    "apps/api/src/lib/rank.ts": {
+      "exports": ["rankForAppend", "rankBetween"],
+      "imports": ["fractional-indexing"],
+      "type": "module",
+      "notes": "Pure helpers wrapping fractional-indexing generateKeyBetween. rankForAppend(lastRank) → rank after last active item. rankBetween(prev, next) → rank between two items. No DB access."
+    },
     "apps/api/src/auth/middleware.ts": {
       "exports": ["oidcAuthMiddleware", "processOAuthCallback", "getAuth"],
       "imports": ["@hono/oidc-auth", "hono"],
@@ -152,13 +201,54 @@
     "apps/pwa/src/App.tsx": {
       "exports": ["default"],
       "imports": [
-        "react",
-        "@tanstack/react-query",
-        "./components/CalendarShell.tsx",
-        "./components/InstallPrompt.tsx"
+        "react-router",
+        "./components/CalendarShell.js",
+        "./routes/ListsIndex.js",
+        "./routes/ListDetail.js",
+        "./components/BottomTabBar.js"
       ],
       "type": "entry-point",
-      "notes": "Root component. Sets up QueryClient, renders CalendarShell + InstallPrompt."
+      "notes": "BrowserRouter shell. Routes: / → /calendar redirect, /calendar → CalendarShell, /lists → ListsIndex, /lists/:listId → ListDetail. BottomTabBar rendered as persistent sibling of Routes."
+    },
+    "apps/pwa/src/routes/ListsIndex.tsx": {
+      "exports": ["ListsIndex"],
+      "imports": ["react", "@tanstack/react-query", "../api/listsClient.js", "../components/"],
+      "type": "module",
+      "notes": "Lists overview route (/lists). TanStack Query ['lists'] → fetchLists. Renders ListCard per list, ListsEmptyState when empty, CreateListSheet for new list, ListDeleteDialog for delete confirmation. Optimistic delete with rollback."
+    },
+    "apps/pwa/src/routes/ListDetail.tsx": {
+      "exports": ["ListDetail"],
+      "imports": [
+        "react",
+        "@tanstack/react-query",
+        "fractional-indexing",
+        "@dnd-kit/core",
+        "@dnd-kit/sortable",
+        "../api/listsClient.js",
+        "../hooks/useListSSE.js",
+        "../components/"
+      ],
+      "type": "module",
+      "notes": "Single list view (/lists/:listId). Splits items into active (!checked, rank ASC) and completed sections. dnd-kit drag-to-reorder with PATCH { position }. useListSSE for live sync (D-10/D-11). 30s polling fallback (D-12). Optimistic check/uncheck + add + delete."
+    },
+    "apps/pwa/src/api/listsClient.ts": {
+      "exports": [
+        "fetchLists",
+        "createList",
+        "patchList",
+        "deleteList",
+        "fetchListItems",
+        "addItem",
+        "patchListItem",
+        "deleteItem",
+        "List",
+        "ListItem",
+        "ListsResponse",
+        "ListItemsResponse"
+      ],
+      "imports": [],
+      "type": "module",
+      "notes": "Typed fetch wrappers for all lists API endpoints. credentials: 'include' for OIDC session cookie. Same opaqueredirect pattern as client.ts."
     },
     "apps/pwa/src/api/client.ts": {
       "exports": [
@@ -172,7 +262,13 @@
       ],
       "imports": [],
       "type": "module",
-      "notes": "Typed fetch wrappers for all API endpoints. Uses credentials: 'include' + redirect: 'manual' for OIDC opaqueredirect detection."
+      "notes": "Typed fetch wrappers for all calendar API endpoints. Uses credentials: 'include' + redirect: 'manual' for OIDC opaqueredirect detection."
+    },
+    "apps/pwa/src/hooks/useListSSE.ts": {
+      "exports": ["useListSSE"],
+      "imports": ["react", "@tanstack/react-query"],
+      "type": "module",
+      "notes": "Bounded-backoff EventSource hook for /api/sse/lists (D-11). Backoff: 250ms→500ms→1s→2s→4s→cap 8s; stops after MAX_ATTEMPTS. withCredentials: true (T-04-01). On open: invalidates ['list', listId] for full refetch (D-10). On event: invalidates relevant query. Polling fallback (D-12) lives in ListDetail."
     },
     "apps/pwa/src/components/CalendarShell.tsx": {
       "exports": ["CalendarShell"],
@@ -195,29 +291,17 @@
       "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"],
+    "apps/pwa/src/components/BottomTabBar.tsx": {
+      "exports": ["BottomTabBar"],
+      "imports": ["react", "react-router", "../store/listsStore.js"],
       "type": "module",
-      "notes": "Create/edit event form. Posts to createEvent/updateEvent. Supports recurrence presets, allDay toggle, calendar picker."
+      "notes": "Phone-only bottom navigation tab bar. Tabs: Calendar (/calendar) and Lists (/lists). Persistent across route changes (rendered outside <Routes>). Visibility controlled by CSS at ≥768px."
     },
-    "apps/pwa/src/components/EventDetailPopover.tsx": {
-      "exports": ["EventDetailPopover"],
-      "imports": ["react", "../api/client.ts"],
+    "apps/pwa/src/store/listsStore.ts": {
+      "exports": ["useListsStore"],
+      "imports": ["zustand"],
       "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."
+      "notes": "Zustand UI-only state for lists surface: activeTab, createListSheetOpen. No server data. Follows calendarStore.ts pattern — no persist, no immer."
     },
     "apps/pwa/src/store/calendarStore.ts": {
       "exports": ["useCalendarStore"],

.planning/intel/stack.json

@@ -1,8 +1,8 @@
 {
   "_meta": {
-    "updated_at": "2026-06-09T00:00:00Z",
-    "commit": "01f7456b81dd55d477d0bd7530df818f61a873c2",
-    "version": 1
+    "updated_at": "2026-06-09T18:56:37.176Z",
+    "commit": "99f59c3999f4ef992f01ef8f8a38c1d86d2f2a0f",
+    "version": 3
   },
   "languages": ["TypeScript", "SQL"],
   "frameworks": ["Hono 4.12.23", "React 19", "Drizzle ORM 0.45.2"],
@@ -19,12 +19,15 @@
   "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)",
+  "cache": "Redis (ioredis — available in infra; not yet wired; in-memory EventEmitter used for Phase 4 list SSE fan-out)",
   "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",
+  "routing": "react-router 7.17.0 (BrowserRouter, /calendar + /lists + /lists/:listId)",
+  "drag_and_drop": "@dnd-kit/core 6.3.1 + @dnd-kit/sortable 10.0.0 (list item reorder)",
+  "fractional_rank": "fractional-indexing 3.2.0 (list item ordering — utf8mb4_bin collation in DB)",
   "content_formats": [
     "TypeScript (source)",
     "SQL (Drizzle migrations)",

.planning/milestones/v1.0-REQUIREMENTS.md

@@ -0,0 +1,139 @@
+# Requirements Archive: v1.0 MVP
+
+**Archived:** 2026-06-10
+**Status:** SHIPPED
+
+For current requirements, see `.planning/REQUIREMENTS.md`.
+
+---
+
+# Requirements: FamilySync
+
+**Defined:** 2026-06-03
+**Core Value:** The household can see and co-edit one color-coded family calendar (shared + each member's personal) and shared lists from a single low-friction PWA — cross-ecosystem, no app store.
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Authentication & Onboarding
+
+> **Given:** Authelia is already deployed and both household members already have Authelia accounts. Auth scope is therefore app-side only — register FamilySync as an OIDC confidential client in Authelia and integrate the login flow. No Authelia deployment, no account provisioning.
+
+- [ ] **AUTH-01**: User can log in through Authelia (OIDC SSO) — no separate FamilySync account or password to create
+- [ ] **AUTH-02**: User stays logged in across sessions so re-authentication is rare (persistent session)
+- [ ] **AUTH-03**: Each member maps to a stable identity (OIDC `iss`+`sub`) and is assigned a consistent per-member color
+
+### Calendar
+
+- [ ] **CAL-01**: App reads the shared family Fastmail calendar via a CalDAV broker token and caches it locally (ctag polling)
+- [x] **CAL-02**: User sees a unified, color-coded calendar that aggregates every accessible calendar into one view
+- [x] **CAL-03**: User can switch between week, month, day, and agenda/list views
+- [x] **CAL-04**: User can create a timed or all-day event, written back to the correct Fastmail calendar
+- [x] **CAL-05**: User can edit an existing event
+- [x] **CAL-06**: User can delete an event
+- [x] **CAL-07**: User can create a recurring event and see all its occurrences expanded correctly (single-occurrence editing deferred to v1.x)
+- [ ] **CAL-08**: Each member's personal Fastmail calendar is overlaid into the unified view — _spike-gated in Phase 1_; if cross-account CalDAV sharing proves infeasible, v1 falls back to shared-family-only and this moves to v1.x
+
+### Lists
+
+- [x] **LIST-01**: User can create and delete named lists (e.g. Groceries, Gift Ideas)
+- [x] **LIST-02**: User can add items to a list, check them off, and delete them
+- [x] **LIST-03**: User can reorder items within a list
+- [x] **LIST-04**: Both members' list edits appear live for the other member without manual refresh
+
+### Notifications
+
+- [x] **NOTIF-01**: User receives a Web Push reminder before an event starts
+- [x] **NOTIF-02**: User receives a Web Push alert when the other member changes a shared list
+- [x] **NOTIF-03**: User receives a Web Push alert when an event is added or changed
+
+### PWA & Install
+
+- [x] **PWA-01**: App is installable to the Home Screen on iPhone and Android (web manifest + service worker, served over HTTPS)
+- [x] **PWA-02**: First-time users get a guided "Add to Home Screen" prompt (prerequisite for iOS Web Push)
+
+## v1.x Requirements
+
+Deferred to a near-term follow-up release. Tracked but not in the v1 roadmap.
+
+### Calendar
+
+- **CAL-09**: User can edit/delete a single occurrence of a recurring event (RECURRENCE-ID / EXDATE)
+- **CAL-10**: User can apply a "this and following" edit to a recurring series
+- **CAL-11**: Documentation for subscribing to the Fastmail calendar natively in Apple Calendar via CalDAV (no new code)
+- **CAL-12**: Secondary-timezone display toggle for travel
+
+## v2 Requirements
+
+### Display
+
+- **DISP-01**: Always-on wall-display / kiosk dashboard view (Skylight-style)
+- **DISP-02**: Upcoming-events / agenda summary widget tuned for the wall display
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep. Anti-features sourced from research (`.planning/research/FEATURES.md`).
+
+| Feature                                       | Reason                                                                       |
+| --------------------------------------------- | ---------------------------------------------------------------------------- |
+| Email features                                | Members keep existing mail clients; never the product's job                  |
+| Self-hosted calendar server (Baikal/Radicale) | Fastmail hosts all calendars via CalDAV; one fewer service                   |
+| Vikunja / external task backend               | Lists live in MariaDB; cross-ecosystem native task sync is impossible anyway |
+| React Native / App Store app                  | PWA delivers app-like UX without publishing overhead                         |
+| PostgreSQL                                    | Not in the stack; MariaDB is the database                                    |
+| Chores / rewards / star system                | No children in the household; lists cover any task need                      |
+| Meal planning / recipe box                    | Separate domain, high cost; grocery list covers the coordination need        |
+| Kids / sub-accounts                           | No children; irrelevant                                                      |
+| AI email-to-event import                      | Requires email access (out of scope) + LLM backend; privacy risk             |
+| RSVP / invite flows (iTIP/iMIP)               | Two people share one calendar; both attend by default                        |
+| Event-level comments / photos                 | Two people can text; adds chat/media storage for ~zero value                 |
+| Activity feed / audit log                     | Obvious with two users                                                       |
+| Multi-household / accounts at scale           | One household, two hardcoded Authelia accounts                               |
+| Ads / monetization                            | Self-hosted; no revenue model                                                |
+| Complex permissions / role tiers              | Two equal partners with identical write access                               |
+| Offline-first with CRDT conflict resolution   | Home WiFi is primary; optimistic updates + retry suffice                     |
+| Grocery delivery integration                  | Third-party dependency; not needed                                           |
+
+## Traceability
+
+| Requirement | Phase   | Status   |
+| ----------- | ------- | -------- |
+| AUTH-01     | Phase 1 | Pending  |
+| AUTH-02     | Phase 1 | Pending  |
+| AUTH-03     | Phase 1 | Pending  |
+| CAL-01      | Phase 1 | Pending  |
+| CAL-08      | Phase 1 | Pending  |
+| CAL-02      | Phase 2 | Complete |
+| CAL-03      | Phase 2 | Complete |
+| CAL-04      | Phase 3 | Complete |
+| CAL-05      | Phase 3 | Complete |
+| CAL-06      | Phase 3 | Complete |
+| CAL-07      | Phase 3 | Complete |
+| PWA-01      | Phase 3 | Complete |
+| PWA-02      | Phase 3 | Complete |
+| LIST-01     | Phase 4 | Complete |
+| LIST-02     | Phase 4 | Complete |
+| LIST-03     | Phase 4 | Complete |
+| LIST-04     | Phase 4 | Complete |
+| NOTIF-01    | Phase 5 | Complete |
+| NOTIF-02    | Phase 5 | Complete |
+| NOTIF-03    | Phase 5 | Complete |
+| CAL-09      | v1.x    | Deferred |
+| CAL-10      | v1.x    | Deferred |
+| CAL-11      | v1.x    | Deferred |
+| CAL-12      | v1.x    | Deferred |
+| DISP-01     | v2      | Deferred |
+| DISP-02     | v2      | Deferred |
+
+**Coverage:**
+
+- v1 requirements: 20 total
+- Mapped to phases: 20
+- Unmapped: 0 ✓
+- Deferred (not in v1 scope): 6 — CAL-09…CAL-12 (v1.x), DISP-01/DISP-02 (v2)
+
+---
+
+_Requirements defined: 2026-06-03_
+_Last updated: 2026-06-10 — added deferred REQ-IDs (CAL-09…CAL-12, DISP-01/02) to traceability table_

.planning/milestones/v1.0-ROADMAP.md

@@ -0,0 +1,410 @@
+# Roadmap: FamilySync
+
+## Overview
+
+FamilySync is built in five phases, each delivering an end-to-end user-observable capability. Phase 1 is both the foundation and the highest-risk gate: OIDC auth must work and the CalDAV broker must prove it can read personal Fastmail calendars before any calendar UI is built. Phases 2–3 complete the calendar. Phase 4 delivers shared lists with live co-edit sync. Phase 5 wires up Web Push notifications. The dependency chain is strict: each phase is a prerequisite for the next, except the lists track (Phase 4) which is independent of the calendar write path.
+
+## Phases
+
+**Phase Numbering:**
+
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+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)
+- [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)
+- [x] **Phase 4: Shared Lists + Live Sync** - Named collaborative lists with item CRUD and real-time SSE co-edit sync (completed 2026-06-09)
+- [x] **Phase 5: Web Push Notifications** - VAPID push for event reminders, event changes, and list-change alerts (completed 2026-06-10; on-device UAT 1/2/5 PASS, T3 dropped as non-gating, T4 Android event-change push deferred to Phase 6 verification — see 05-UAT.md)
+- [x] **Phase 6: UX Polish** - All-day visual distinction, event-form date/recurrence behavior, recurring-series edit, and auth-flow smoothing (completed 2026-06-10)
+
+## Phase Details
+
+### Phase 1: Foundation + Broker Spike
+
+**Goal**: The app stack is running, both members can authenticate, and the CalDAV broker can read Fastmail calendars — with a confirmed go/no-go decision on personal-calendar cross-account sharing
+**Mode:** mvp
+**Depends on**: Nothing (first phase)
+**Requirements**: AUTH-01, AUTH-02, AUTH-03, CAL-01, CAL-08
+**Success Criteria** (what must be TRUE):
+
+1. Both members can reach the app URL, authenticate through Authelia OIDC, and land on the app home page without entering any Fastmail credentials
+2. Sessions persist across browser restarts — neither member is asked to log in again on the next visit
+3. Each member is assigned a stable, distinct display color that does not change between sessions
+4. The broker successfully fetches and caches at least one event from the shared Fastmail calendar via CalDAV PROPFIND/REPORT
+5. The personal-calendar ACL spike produces a documented go/no-go decision: either the broker token sees the wife's personal calendar after Fastmail share+accept, or the fallback strategy (shared-family-only or per-member app password) is chosen and recorded
+
+**Verification status (D-14, 2026-06-04):** Code + **Gate 1** complete. Gate 1 = stack up (`/health` live), CAL-01 proven live (503 real events cached via REPORT), CAL-08 = **GO** (per-member app-password model, see `CAL-08-DECISION.md`). **Gate 2 deferred** — criteria 1/2/3 (live Authelia OIDC login over Pangolin, session persistence, distinct colors in a real browser) and the SSE-over-Pangolin smoke test require the operator's Authelia + Pangolin/Newt infra; tracked in `01-HUMAN-UAT.md` and `docs/deployment.md`. The live AUTH smoke (incl. iOS) is folded into **Phase 3**; the SSE smoke is a hard gate before **Phase 4**. Phases 2–3 develop behind a documented dev-auth bypass.
+
+**Plans**: 4 plans
+Plans:
+
+- [x] 01-01-PLAN.md — Walking skeleton: monorepo scaffold + Docker/MariaDB + Drizzle schema (push) + /health end-to-end slice + Vitest Wave 0 harness
+- [x] 01-02-PLAN.md — Authelia OIDC slice: stable identity (iss+sub) + auto-assigned member color + /api/me + authenticated PWA shell (AUTH-01/02/03)
+- [x] 01-03-PLAN.md — CalDAV broker slice: AES-256-GCM credential encryption + tsdav broker + ical.js sync (all-day DATE) + ctag poller + /api/events (CAL-01)
+- [x] 01-04-PLAN.md — Integration + gate: wire poller/routes, event-proof landing page, CAL-08 spike + go/no-go doc, live Pangolin deploy + SSE smoke test
+
+### Phase 2: Calendar Display
+
+**Goal**: Both members can see a unified, color-coded calendar aggregating all accessible Fastmail calendars across day, week, month, and agenda views — read-only, no write-back yet
+**Mode:** mvp
+**Depends on**: Phase 1
+**Requirements**: CAL-02, CAL-03, CAL-07
+**Success Criteria** (what must be TRUE):
+
+1. Opening the app shows a color-coded calendar where each member's events appear in their assigned color, with shared events distinguishable from personal events
+2. The user can switch between day, week, month, and agenda views and all events render correctly in each view
+3. A recurring event (e.g., weekly meeting) displays all its occurrences correctly in the current view window, including correct behavior across DST boundaries
+4. All-day events (birthdays, holidays) appear as full-day banners on the correct date with no timezone shift
+
+**Plans**: 5 plansPlans:
+**Wave 1**
+
+- [x] 02-01-PLAN.md — Foundation: schema (hasRrule + calendars.isShared, pushed) + dev-auth bypass + PWA vitest/jsdom harness + ICS fixtures + RED test stubs
+
+**Wave 2** _(blocked on Wave 1 completion)_
+
+- [x] 02-02-PLAN.md — Backend slice: expandOccurrences() (VTIMEZONE/DST + all-day + EXDATE) + windowed/joined/zod-validated /api/events + shared-calendar checkpoint (CAL-02/CAL-07)
+- [x] 02-03-PLAN.md — Frontend foundation: CSS token layer + colorUtils + calendarConfig (firstDayOfWeek 0→7) + hydrateEvents (Temporal/PlainDate guard) + Zustand store + windowed fetchEvents
+
+**Wave 3** _(blocked on Wave 2 completion)_
+
+- [x] 02-04-PLAN.md — Vertical slice: CalendarShell mounts Schedule-X, renders real windowed Fastmail events color-coded across all four views (CAL-02/CAL-03)
+
+**Wave 4** _(blocked on Wave 3 completion)_
+
+- [x] 02-05-PLAN.md — UX completion: read-only EventDetailPopover + ColorLegend + nav/toolbar + skeleton/empty/error states + human visual verification
+
+**Gap-closure waves** _(from 03-REVIEW.md — write path was broken end-to-end; Gate 2 / 03-08 is blocked on these)_
+
+- [x] 03-09-PLAN.md — Route layer: align zod schema to client title/start/end contract (CR-01) + real OIDC iss/sub→users.id resolution on all 5 handlers (CR-06) [wave 1]
+- [x] 03-12-PLAN.md — PWA EventForm: edit-mode population + recurrence preselect (WR-03), zone-consistent dates (WR-05), real focus trap (WR-07); PWA-01/02 install assets verified [wave 1]
+- [x] 03-10-PLAN.md — Worker dispatch: build real VEVENT via buildVeventString + all-day DTEND+1 (CR-02/WR-04), fail closed on bad creds (CR-03), backoff index + randomUUID (WR-01/WR-08) [wave 2, after 03-09]
+- [x] 03-11-PLAN.md — Outbox durability: durable create-before-delete (CR-04), drain concurrency guard (CR-05), fresh-etag-before-PUT (WR-02) [wave 3, after 03-10]
+
+**UI hint**: yes
+
+### Phase 3: Event Write-Back + PWA Install
+
+**Goal**: Both members can create, edit, and delete events that are written back to the correct Fastmail calendar, and the app is installable to the iPhone and Android home screens with a guided onboarding flow
+**Mode:** mvp
+**Depends on**: Phase 2
+**Requirements**: CAL-04, CAL-05, CAL-06, CAL-07, PWA-01, PWA-02
+**Success Criteria** (what must be TRUE):
+
+1. A member can create a timed or all-day event (including recurring events) in the app and see it appear in the native Fastmail app within the next sync cycle
+2. A member can edit an existing event's title, time, or description and the change persists correctly in Fastmail
+3. A member can delete an event and it disappears from all views on the next sync
+4. On Android, the app shows a browser install prompt and installs to the home screen; on iOS, the app shows a guided "Add to Home Screen" walkthrough with annotated screenshots that a non-technical user can follow independently
+5. The installed PWA opens full-screen without browser chrome on both iOS and Android
+6. **(Carried from Phase 1 Gate 2, D-14)** Live Authelia OIDC login works over the public Pangolin URL — including the **iOS standalone-PWA** flow: the wife can install to Home Screen and complete login without the redirect breaking out of standalone mode; sessions persist (AUTH-01/02) and members get distinct stable colors (AUTH-03). Verify per `docs/deployment.md` Gate 2 checklist; this is the first real external deploy (local Newt test rig is sufficient — Unraid prod is optional until go-live).
+
+**Plans**: 12 plans (8 original + 4 gap-closure from 03-REVIEW.md)
+Plans:
+**Wave 1**
+
+- [x] 03-01-PLAN.md — Foundation: calendarOutbox table + calendarEvents.objectUrl (pushed), vite-plugin-pwa install + legitimacy gate, sync.ts objectUrl, full Wave 0 RED test scaffold
+
+**Wave 2** _(blocked on Wave 1)_
+
+- [x] 03-02-PLAN.md — TDD: VEVENT builder (vevent.ts, D-13 DATE/DATETIME + RRULE) + tsdav write wrappers (write.ts, D-12 broker boundary)
+- [x] 03-03-PLAN.md — Write API: POST/PATCH/DELETE events + GET sync-status, enqueue-only, D-03 ownership, D-04 edit-as-move pair (CAL-04/05/06/07)
+
+**Wave 3** _(blocked on Wave 2)_
+
+- [x] 03-04-PLAN.md — TDD: outbox worker state machine (D-05/06/07/08 retry/backoff/dead/conflict, edit-as-move ordering) + index.ts wiring
+- [x] 03-05-PLAN.md — Frontend create/edit slice: write client calls + Zustand keys + EventForm (D-01/02/11) + New Event FAB
+- [x] 03-07-PLAN.md — PWA install: VitePWA manifest + auth-safe SW denylist + icons + InstallPrompt (iOS walkthrough + Android prompt) (PWA-01/02)
+
+**Wave 4** _(blocked on Wave 3)_
+
+- [x] 03-06-PLAN.md — Delete + sync feedback: popover Edit/Delete footer + DeleteConfirmationDialog + SyncStateToast polling (D-06/08/09) (CAL-05/06)
+
+**Wave 5** _(blocked on Wave 4)_
+
+- [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
+
+### Phase 4: Shared Lists + Live Sync
+
+**Goal**: Both members can create and manage shared named lists with real-time co-edit sync — edits by one member appear for the other without any manual refresh
+**Mode:** mvp
+**Depends on**: Phase 1
+**⚠️ Entry gate (D-14):** The **SSE-over-Pangolin smoke test** (deferred from Phase 1 Gate 2, issue #1034) MUST pass before building live sync — hold `/api/sse/heartbeat` open 5+ min through the tunnel without it being cut (see `docs/deployment.md`). If it FAILS: fix Pangolin idle-timeout/buffering, or plan a reconnect/polling fallback into this phase before proceeding. Do not build the live-sync layer on an unverified transport.
+**Requirements**: LIST-01, LIST-02, LIST-03, LIST-04
+**Success Criteria** (what must be TRUE):
+
+1. Either member can create a named list (e.g., "Groceries") and delete a list they no longer need
+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
+
+**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**: 7 plans (6 + 1 gap-closure)
+Plans:
+**Wave 1**
+
+- [x] 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)_
+
+- [x] 04-02-PLAN.md — TDD: scoped in-memory fan-out (listEmitter) + getAccessibleListIds access scope — the load-bearing D-04 no-leak primitive (LIST-04)
+- [x] 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)_
+
+- [x] 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)_
+
+- [x] 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)_
+
+- [x] 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)
+
+**Wave 6** _(gap closure — blocked on Waves 2 + 4)_
+
+- [x] 04-07-PLAN.md — Gap closure: migrate list_items.rank to COLLATE utf8mb4_bin (LIST-03 drag-to-top) + owner-only guard on PATCH isShared (T-04-08/T-04-05) — two TDD features (LIST-03)
+
+**UI hint**: yes
+
+### Phase 5: Web Push Notifications
+
+**Goal**: Both members receive timely Web Push alerts for upcoming events, event changes made by the other member, and list changes — reliably on both iOS and Android
+**Mode:** mvp
+**Depends on**: Phase 3, Phase 4
+**Requirements**: NOTIF-01, NOTIF-02, NOTIF-03
+**Success Criteria** (what must be TRUE):
+
+1. A member receives a push notification on their phone approximately 15 minutes before a calendar event starts — delivered to the installed PWA, including on iOS
+2. When the other member adds or changes a calendar event, the first member receives a push notification with the event title and action described in the payload
+3. When the other member modifies a shared list (adds, checks off, or deletes an item), the first member receives a push notification identifying the list and the change
+4. After an extended period of app inactivity, push notifications are still delivered (subscription health-check prevents silent revocation on iOS)
+
+**Plans**: 8 plans (6 waves)
+Plans:
+**Wave 1**
+
+- [x] 05-01-PLAN.md — Foundation: install web-push + workbox deps (legitimacy gate), generate VAPID keypair, push_subscriptions table + calendar_events.title generate+migrate [BLOCKING], Wave-0 RED scaffolds (D-11/D-12)
+
+**Wave 2** _(blocked on Wave 1)_
+
+- [x] 05-02-PLAN.md — TDD: pushDispatcher (VAPID send + dual-format payload + 410/404 prune) (D-11)
+- [x] 05-03-PLAN.md — TDD: pushCoalescer (per-list/actor debounce, generic copy, self-suppress) (D-01/D-02/D-03)
+
+**Wave 3** _(blocked on Wave 2)_
+
+- [x] 05-04-PLAN.md — Subscribe slice (end-to-end): push subscription API + setVapidDetails, generateSW→injectManifest SW migration (push/notificationclick/denylist), usePushSubscription + PushPermissionPrompt (D-08/D-11/D-14)
+
+**Wave 4** _(blocked on Wave 3)_
+
+- [x] 05-05-PLAN.md — NOTIF-02 list-change slice: listChangeDispatcher + hook coalescer into mutations, reorder-silent (D-01/D-02/D-03)
+- [x] 05-06-PLAN.md — TDD: NOTIF-01 reminderScheduler — shared-timed 15-min scan (query-enforced D-05), all-day excl, dedup, empty-set safe (D-05/D-06/D-07)
+
+**Wave 5** _(blocked on Wave 4)_
+
+- [x] 05-07-PLAN.md — TDD: NOTIF-03 eventChangeDispatcher + syncCalendar diff/title/onChanges hook (poller + outbox), meaningful-only, actor-suppressed (D-02/D-03/D-04/D-13)
+
+**Wave 6** _(blocked on Wave 3)_
+
+- [x] 05-08-PLAN.md — Settings + reliability: master toggle (D-09) + silent re-subscribe (D-10) + PermissionDeniedBanner + avatar→Settings sheet
+
+**UI hint**: yes
+
+### 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**: none (all v1 REQ-IDs complete in Phases 1–5; this is a polish phase tracked against backlog items 999.2/3/6/7/8/9 and locked decisions D-01..D-13)
+**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
+
+**Scope** (promoted from backlog, locked 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) deferred to milestone 1.1 (D-01/D-02).
+
+**Plans**: 6 plans (2 waves)
+Plans:
+**Wave 1** _(parallel — exclusive file ownership)_
+
+- [x] 06-01-PLAN.md — TDD: duration-preserving end-tracking math (computeNewTimedEnd/computeNewAllDayEnd) in eventDateTime.ts (D-04)
+- [x] 06-02-PLAN.md — TDD: RRULE UNTIL/COUNT serialization + Zod acceptance + FREQ-persistence regression (vevent/outboxWorker/events route) (D-06/D-07)
+- [x] 06-03-PLAN.md — TDD: hasRrule on CalendarOccurrence + bounded-expansion lock (expand.ts) (D-06/D-08)
+- [x] 06-04-PLAN.md — Spinner/pulse: global @keyframes pulse + remove redundant spin redefinition (D-13)
+- [x] 06-05-PLAN.md — Auth gating slice: SessionExpiredError + AuthSplash + global QueryCache/MutationCache error handler; client.ts type mirrors (D-10/D-11, + D-06/D-08 type carriers)
+
+**Wave 2** _(blocked on 06-01/02/03/05)_
+
+- [x] 06-06-PLAN.md — EventForm integration slice: end-tracking wiring + recurrence-bound control + series-edit prompt + all-day pill (D-03/D-04/D-05/D-06/D-07/D-08/D-09/D-12)
+
+**UI hint**: yes
+
+## Progress
+
+**Execution Order:**
+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 | 12/12          | Complete | 2026-06-07 |
+| 4. Shared Lists + Live Sync       | 6/6            | Complete | 2026-06-09 |
+| 5. Web Push Notifications         | 8/8            | Complete | 2026-06-10 |
+| 6. UX Polish                      | 6/6            | Complete | 2026-06-10 |
+
+## Backlog
+
+### Phase 999.1: Treat Fastmail as one calendar provider; framework supports adding more providers (BACKLOG)
+
+**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:** 3/6 plans executed
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.4: Per-event reminder configuration (VALARM authoring + scheduler honors it) (BACKLOG)
+
+**Goal:** [Captured for future planning] End-to-end per-event reminders — let the user choose _when_ (or whether) to be reminded per event, and make the push scheduler honor that choice instead of a hardcoded lead.
+
+**Half A — author the VALARM (event form):** The event create/edit form has no UI to set a reminder ("remind me 10 min / 1 hour / 1 day before", or **no reminder**), so the written `.ics` carries no `VALARM` and no reminder can fire — in native clients or via web push. Add a reminder selector (including an explicit "none"), serialize chosen offsets as `VALARM` (TRIGGER) on write-back, and parse existing `VALARM`s on read so edits preserve them. Feeds the Phase 5 web-push requirement (push needs reminder data to notify about).
+
+**Half B — scheduler honors the provider's value (NEW, surfaced 2026-06-10):** Today `apps/api/src/broker/reminderScheduler.ts` runs a **hardcoded 15-minute** scan for shared timed events (`index.ts:139` "starting in ~15 min"; reminderScheduler header "15-min reminder scan") and never reads the event's actual alarm. So every reminder fires 15 min before regardless of what the event (or the calendar provider) specifies, and an event with **no** alarm still gets a 15-min push. Change the scheduler to read each event's `VALARM` `TRIGGER` (the value written in Half A / set in Fastmail or another native client) and fire at that lead — and fire **nothing** when the event has no alarm. The current fixed 15-min window/dedup logic (catch-up scan, per-uid exactly-once — see quick 260610-hbu) must be generalized to a variable per-event lead.
+
+**Boundary:** preserve the reminder scheduler's resilience guarantees (catch-up on a missed tick, per-uid exactly-once dedup). This makes the lead per-event/variable rather than constant; it is not a rewrite of the scan/dedup design.
+
+**Severity:** medium — feature gap surfaced during Phase 03 Gate 2 testing; Half B surfaced 2026-06-10. Tags: phase-03, phase-05, calendar, write-back, reminders, valarm, push, scheduler, 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.10: Admin Settings / Administration section — manage app passwords + designate the shared calendar via UI (BACKLOG)
+
+**Goal:** [Captured for future planning] Add an in-app **Settings/Administration** section, gated to an administrator role, for configuration that today requires manual backend/DB steps:
+
+- **View/update per-member Fastmail app passwords** (stored encrypted via `APP_PASSWORD_ENCRYPTION_KEY`, existing crypto path) — rotate or re-enter a member's credential and re-trigger sync.
+- **Designate which synced calendar is the "shared" calendar** by toggling `calendars.is_shared` from the UI. Today this is a manual DB write: e.g. `UPDATE calendars SET is_shared=1 WHERE id=<row>` — done by hand on 2026-06-10 to mark the "FamilySync" calendar (id 10) shared after the poller synced it (D-16). The admin should pick the shared calendar from a list of synced collections instead of relying on a backend process. (The poller's upsert already leaves `is_shared` untouched, so a UI-set flag persists.)
+
+**Context:** Motivated by the manual D-16 resolution (2026-06-10). **Related:** 999.5 (per-member first-login app-password onboarding) — this is the ongoing admin-managed counterpart; and 999.11 (initial setup wizard) — bootstrap-time vs. ongoing config. Tags: admin, settings, calendar, app-passwords, D-16.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.11: Initial setup wizard — first-run config of env vars, app passwords, DB connection (BACKLOG)
+
+**Goal:** [Captured for future planning] Add a first-run **setup wizard** that walks the administrator through defining all bootstrap configuration instead of hand-editing `.env` / `docker-compose.yml`:
+
+- **App environment variables:** OIDC client id/secret/issuer/redirect URI + external URL, session signing secret (`OIDC_AUTH_SECRET`), `APP_PASSWORD_ENCRYPTION_KEY`, and the **VAPID keypair** (subject + public + private).
+- **MariaDB connection:** host/port/user/password/db, with a connectivity test.
+- **First Fastmail app password** for the initial member, encrypted on save.
+
+Wizard should **validate inputs before completing** — e.g. VAPID private key decodes to 32 bytes AND pairs with the public key, OIDC discovery resolves, DB connects, app-password reaches CalDAV.
+
+**Context:** Motivated by setup friction observed 2026-06-10 — a VAPID private key truncated on paste into `.env` silently broke push (`setVapidDetails failed — 32 bytes`), and `DB_HOST` / dev overrides must currently be set by hand. A guided + validated wizard would have caught these. **Related:** 999.10 (ongoing admin Settings) and 999.5 (member onboarding). Tags: onboarding, setup, install, env, vapid, mariadb, oidc.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.12: Assistant-driven mobile-browser UI testing (mobile viewport + authed PWA) (BACKLOG)
+
+**Goal:** [Captured for future planning] Give the assistant a way to validate UI/UX changes in a **mobile** browser experience, not just desktop Chromium. Today `playwright-cli` drives a desktop viewport, and the prod stack enforces OIDC (Authelia) so the authed PWA can't be reached headlessly — which is exactly why a string of mobile-only defects this milestone (silent Android notifications, the dead "How to enable" link, iOS/Android session-cookie persistence, install/standalone behaviour) could only be found by the operator on real devices, not by the assistant.
+
+**What this needs (any subset):**
+
+- **Mobile viewport + UA emulation** in the browser harness (e.g. Playwright device descriptors — iPhone/Pixel viewport, touch, mobile user-agent) so layout, tap targets, and responsive behaviour can be checked.
+- **An authenticated entry path for automated runs** so the assistant can reach the real PWA past Authelia — e.g. a reusable saved storage-state/cookie, a test-only bypass on a non-prod host, or driving the Authelia login once and reusing the session. (Note: this overlaps the existing `DEV_AUTH_BYPASS`, but that only works on the host-side dev stack, not the prod-mode PWA that has the real service worker. A mobile, authed, SW-enabled target is the gap.)
+- Optionally: a documented way to point the harness at the Pangolin HTTPS URL with a persisted session, and/or remote-debug a real device.
+
+**Boundary:** genuinely device-only behaviour (iOS-Safari standalone push, real APNs/FCM delivery, OS notification-channel importance) still needs a human — this item is about everything SHORT of that (responsive layout, tap flows, in-page notification UI states, auth redirects) which a mobile-emulated authed browser _could_ cover but currently can't.
+
+**Context:** Surfaced 2026-06-10 during Phase 5 UAT — repeated mobile-only bugs were caught only by the operator because the assistant had no mobile, authenticated browser to test in. **Related:** [[feedback-playwright-verify]] (use playwright-cli over manual verification — this extends it to mobile/authed). Tags: testing, playwright, mobile, pwa, oidc, dx.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.13: Reduce event write-back latency to the calendar provider (outbox drain) (BACKLOG)
+
+**Goal:** [Captured for future planning] Calendar create/edit/delete writes are enqueue-only (`calendarOutbox`, 202 optimistic-accept; D-12/D-05 — no Fastmail call in the route) and flushed to Fastmail by `runOutboxDrain` on a **15-second `setInterval`** (`apps/api/src/broker/outboxWorker.ts`). So a change can take up to ~15s to land in Fastmail (and longer to reflect back in the app, which depends on the separate 5-min poller). Reduce that perceived sync delay so edits feel near-immediate.
+
+**Options to weigh when picking this up:**
+
+- **Event-driven drain (preferred):** trigger an outbox drain immediately after a successful enqueue (in-process signal, or Redis pub/sub which is already available) so the write fires within ~1s instead of waiting for the next tick — keep the 15s `setInterval` as a fallback/retry sweep. Must preserve the existing per-row etag/412 handling and the rapid-successive-edit ordering (see outboxWorker comments ~L312 — each edit carries its enqueue-time etag).
+- **Shorter interval:** simplest, but more idle DB polling; a floor (e.g. 3–5s) trades latency for load.
+- **Faster read-back too:** the user also sees latency from the 5-min poller reflecting the change back. Consider invalidating/short-poll after a local write, or optimistic UI already covering it — confirm whether the perceived delay is the write (15s) or the read-back (5min).
+
+**Boundary:** the optimistic 202 + outbox durability design (create-before-delete, drain concurrency guard, fresh-etag-before-PUT) must be preserved — this is a latency tune, not a rewrite of the write path.
+
+**Context:** Surfaced 2026-06-10. Tags: calendar, write-back, outbox, latency, redis, performance.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.14: Gitea CI — full regression on PR to main + build/publish Docker image (BACKLOG)
+
+**Goal:** [Captured for future planning] The repo is committed against a self-hosted Gitea instance with a registered Actions runner, but there is no CI yet (no `.gitea/workflows/` or `.github/workflows/`). Two things should run automatically: (1) **full regression** on every PR targeting `main` — gating the merge; (2) **build the app's Docker image and publish it** to the Gitea container registry.
+
+**Options / decisions to make when picking this up:**
+
+- **Test scope:** "full regression" = lint + typecheck + unit + the API integration tests. Integration tests need a real MariaDB (see [[api-integration-test-db]]) — the workflow must spin up a MariaDB service container, bind it, and set `DB_HOST=127.0.0.1` + `.env` creds. The PWA build/test also runs.
+- **Monorepo:** pnpm workspace (`apps/api`, `apps/pwa`, shared). Cache the pnpm store.
+- **Docker images:** only `apps/api/Dockerfile` exists today — there is no PWA Dockerfile yet. Decide one image (API) vs. also building/serving the PWA. Tag scheme + when to publish (only on merge to `main`? on tags? per-PR?).
+- **Registry auth:** push to the Gitea registry using the runner's Gitea-provided token or a dedicated package-write token.
+- Gitea Actions are GitHub-Actions-compatible syntax but run on the self-hosted runner — confirm runner labels and available images, and that Actions is enabled, before authoring.
+
+**Likely shape:** a `.gitea/workflows/ci.yml` — `on: pull_request` (to `main`) → install (pnpm), lint, typecheck, unit, API integration vs. a `mariadb` service container, PWA build; `on: push` to `main`/tag → `docker build apps/api/Dockerfile`, login, push tagged image.
+
+**Context:** Promoted from STATE.md pending todo (`.planning/todos/pending/2026-06-10-gitea-ci-regression-and-docker-publish.md`), surfaced 2026-06-10. Tags: tooling, ci, gitea, docker, mariadb, monorepo.
+**Requirements:** TBD
+**Plans:** 0 plans
+
+Plans:
+
+- [ ] TBD (promote with /gsd-review-backlog when ready)

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-01-PLAN.md

@@ -36,44 +36,44 @@ autonomous: false
 requirements: [CAL-01]
 user_setup:
   - service: mariadb
-    why: "Local stack DB; provisioned via Docker Compose (no external account)"
+    why: 'Local stack DB; provisioned via Docker Compose (no external account)'
     env_vars:
       - name: DB_PASSWORD
-        source: "Choose any strong password; set in .env (consumed by both mariadb and api services)"
+        source: 'Choose any strong password; set in .env (consumed by both mariadb and api services)'
       - name: DB_ROOT_PASSWORD
-        source: "Choose any strong password; set in .env (MariaDB root)"
+        source: 'Choose any strong password; set in .env (MariaDB root)'
 
 must_haves:
   truths:
-    - "docker compose up brings MariaDB healthy and the Hono API serving"
-    - "GET /health returns 200 and proves a real DB round-trip (write then read)"
-    - "The React PWA builds and renders a shell that fetches /health"
-    - "npx drizzle-kit push applies the users/member_credentials/calendars/calendar_events schema to the live MariaDB"
-    - "vitest runs and the Wave 0 test files exist and execute (red or green)"
+    - 'docker compose up brings MariaDB healthy and the Hono API serving'
+    - 'GET /health returns 200 and proves a real DB round-trip (write then read)'
+    - 'The React PWA builds and renders a shell that fetches /health'
+    - 'npx drizzle-kit push applies the users/member_credentials/calendars/calendar_events schema to the live MariaDB'
+    - 'vitest runs and the Wave 0 test files exist and execute (red or green)'
   artifacts:
-    - path: "apps/api/src/db/schema.ts"
-      provides: "Drizzle mysqlTable definitions for users, member_credentials, calendars, calendar_events"
+    - path: 'apps/api/src/db/schema.ts'
+      provides: 'Drizzle mysqlTable definitions for users, member_credentials, calendars, calendar_events'
       contains: "mysqlTable('users'"
-    - path: "apps/api/src/db/client.ts"
-      provides: "drizzle(mysql2 pool) singleton export `db`"
-      exports: ["db"]
-    - path: "apps/api/src/routes/health.ts"
-      provides: "GET /health with real DB read/write"
-    - path: "docker-compose.yml"
-      provides: "api + mariadb + redis services with mariadb healthcheck"
-      contains: "healthcheck"
-    - path: "apps/api/vitest.config.ts"
-      provides: "Node-environment vitest config"
-    - path: "apps/pwa/src/App.tsx"
-      provides: "React shell that fetches /health"
+    - path: 'apps/api/src/db/client.ts'
+      provides: 'drizzle(mysql2 pool) singleton export `db`'
+      exports: ['db']
+    - path: 'apps/api/src/routes/health.ts'
+      provides: 'GET /health with real DB read/write'
+    - path: 'docker-compose.yml'
+      provides: 'api + mariadb + redis services with mariadb healthcheck'
+      contains: 'healthcheck'
+    - path: 'apps/api/vitest.config.ts'
+      provides: 'Node-environment vitest config'
+    - path: 'apps/pwa/src/App.tsx'
+      provides: 'React shell that fetches /health'
   key_links:
-    - from: "apps/api/src/routes/health.ts"
-      to: "apps/api/src/db/client.ts"
-      via: "db query"
-      pattern: "from ['\"].*db/client"
-    - from: "apps/pwa/src/App.tsx"
-      to: "/health"
-      via: "fetch"
+    - from: 'apps/api/src/routes/health.ts'
+      to: 'apps/api/src/db/client.ts'
+      via: 'db query'
+      pattern: 'from [''"].*db/client'
+    - from: 'apps/pwa/src/App.tsx'
+      to: '/health'
+      via: 'fetch'
       pattern: "fetch\\(.*health"
 ---
 
@@ -103,6 +103,7 @@ Output: Running Docker stack, applied DB schema, a green `/health` slice, and th
 </context>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 01)
 
 New files: `package.json` (root workspace), `pnpm-workspace.yaml`, `.gitignore`, `.env.example`, `docker-compose.yml`, `docker-compose.dev.yml`, `apps/api/package.json`, `apps/api/tsconfig.json`, `apps/api/Dockerfile`, `apps/api/drizzle.config.ts`, `apps/api/vitest.config.ts`, `apps/api/src/index.ts`, `apps/api/src/db/schema.ts`, `apps/api/src/db/client.ts`, `apps/api/src/routes/health.ts`, `apps/api/tests/helpers/db.ts`, `apps/api/tests/health.test.ts`, `apps/api/tests/auth/user.test.ts`, `apps/api/tests/broker/crypto.test.ts`, `apps/api/tests/broker/sync.test.ts`, `apps/api/tests/broker/poller.test.ts`, `apps/pwa/package.json`, `apps/pwa/tsconfig.json`, `apps/pwa/vite.config.ts`, `apps/pwa/index.html`, `apps/pwa/src/main.tsx`, `apps/pwa/src/App.tsx`.
@@ -138,6 +139,7 @@ New env vars: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_ROO
     docker-compose.yml per RESEARCH Pattern 6: services `api` (build ./apps/api, env DB_* + placeholders for OIDC/encryption used by later plans, depends_on mariadb service_healthy, port 3000:3000), `mariadb` (image mariadb:11, MARIADB_* env, named volume mariadb_data, healthcheck using healthcheck.sh --connect --innodb_initialized interval 10s retries 5), `redis` (redis:7-alpine, present but unused in Phase 1). docker-compose.dev.yml overrides for local dev (bind mounts, expose mariadb 3306). `.env.example` lists every env var referenced (DB_HOST=mariadb, DB_PORT=3306, DB_USER=familysync, DB_NAME=familysync, DB_PASSWORD, DB_ROOT_PASSWORD, plus OIDC_* and APP_PASSWORD_ENCRYPTION_KEY placeholders for later plans). `.gitignore` excludes node_modules, dist, .env (NEVER commit .env — security: secrets at rest).
 
     Create the Wave 0 test files as RED stubs that import the not-yet-existing modules from later plans, each with `it.todo` or a failing assertion plus a comment naming the plan that fills it: `tests/helpers/db.ts` (Drizzle test-DB fixture against the Docker MariaDB or a throwaway schema), `tests/auth/user.test.ts` (upsertUser color round-robin + identity stability — Plan 02), `tests/broker/crypto.test.ts` (AES-GCM roundtrip + IV uniqueness — Plan 03), `tests/broker/sync.test.ts` (allDay → dtstart_date vs dtstart_utc, UID upsert — Plan 03), `tests/broker/poller.test.ts` (ctag unchanged → no write — Plan 03), `tests/health.test.ts` (GET /health 200 — filled by Task 2 below). Do NOT place fenced code in this plan; follow the patterns in RESEARCH.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm install && pnpm vitest run --reporter=dot; test -f ../../docker-compose.yml && grep -q "healthcheck" ../../docker-compose.yml && grep -q "mariadb:11" ../../docker-compose.yml</automated>
@@ -177,6 +179,7 @@ New env vars: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_ROO
     Fill `tests/health.test.ts` GREEN: mock or use the test-DB fixture to assert GET /health returns 200 `{ ok: true }`.
 
     Update `apps/pwa/src/App.tsx`: a thin shell that fetches `/health` via React Query and renders "stack: up" / "stack: down". This is the one real UI interaction wired to the API for the skeleton.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm vitest run tests/health.test.ts --reporter=verbose && pnpm exec tsc --noEmit</automated>
@@ -211,21 +214,23 @@ New env vars: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_ROO
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| Docker host → MariaDB container | DB credentials cross here; never hardcoded, sourced from .env |
-| .env file → process env | Secrets (DB passwords, later OIDC + encryption key) loaded here; .env never committed |
+| Boundary                        | Description                                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------- |
+| Docker host → MariaDB container | DB credentials cross here; never hardcoded, sourced from .env                         |
+| .env file → process env         | Secrets (DB passwords, later OIDC + encryption key) loaded here; .env never committed |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-01-01 | Information Disclosure | .env with DB + future OIDC/encryption secrets | mitigate | `.gitignore` excludes `.env`; only `.env.example` (no real values) is committed |
-| T-01-02 | Tampering | MariaDB container | mitigate | Dedicated `familysync` DB user (not root) for the app; root password separate and unused by api service |
-| T-01-03 | Elevation of Privilege | /health route | accept | Intentionally unauthenticated and read-mostly; returns no secrets or user data, only `{ ok, db }` |
-| T-01-SC | Tampering | pnpm installs (hono, drizzle, mysql2, tsdav, ical.js, node-cron, react, vite) | accept | All packages reviewed [OK] in RESEARCH § Package Legitimacy Audit (multi-year histories, official repos); no [ASSUMED]/[SUS]/[SLOP] packages |
+| Threat ID | Category               | Component                                                                     | Disposition | Mitigation Plan                                                                                                                              |
+| --------- | ---------------------- | ----------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-01-01   | Information Disclosure | .env with DB + future OIDC/encryption secrets                                 | mitigate    | `.gitignore` excludes `.env`; only `.env.example` (no real values) is committed                                                              |
+| T-01-02   | Tampering              | MariaDB container                                                             | mitigate    | Dedicated `familysync` DB user (not root) for the app; root password separate and unused by api service                                      |
+| T-01-03   | Elevation of Privilege | /health route                                                                 | accept      | Intentionally unauthenticated and read-mostly; returns no secrets or user data, only `{ ok, db }`                                            |
+| T-01-SC   | Tampering              | pnpm installs (hono, drizzle, mysql2, tsdav, ical.js, node-cron, react, vite) | accept      | All packages reviewed [OK] in RESEARCH § Package Legitimacy Audit (multi-year histories, official repos); no [ASSUMED]/[SUS]/[SLOP] packages |
+
 </threat_model>
 
 <verification>
@@ -238,12 +243,13 @@ New env vars: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_ROO
 </verification>
 
 <success_criteria>
+
 - Monorepo scaffold (apps/api + apps/pwa) builds and type-checks
 - Docker stack runs MariaDB (healthy) + Hono API
 - Schema applied to live DB via drizzle-kit push (all four tables present)
 - /health proves a real DB read+write round-trip; React shell renders its result
 - Wave 0 test files exist and run; health test green
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/01-foundation-broker-spike/01-01-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-01-SUMMARY.md

@@ -148,6 +148,7 @@ None — plan executed exactly as specified. One minor pnpm API difference (allo
 ### Auto-fixed Issues
 
 **1. [Rule 3 - Blocking] pnpm 11 allowBuilds syntax**
+
 - **Found during:** Task 1 (pnpm install)
 - **Issue:** `pnpm install` failed with `ERR_PNPM_IGNORED_BUILDS: esbuild@*`. pnpm 11 uses `allowBuilds` map (not `onlyBuiltDependencies` list used in older versions)
 - **Fix:** Set `allowBuilds.esbuild: true` in pnpm-workspace.yaml
@@ -156,6 +157,7 @@ None — plan executed exactly as specified. One minor pnpm API difference (allo
 - **Committed in:** `3f59156` (Task 1 commit)
 
 **2. [Rule 1 - Bug] vi.mock hoisting in health test**
+
 - **Found during:** Task 2 (writing TDD RED test)
 - **Issue:** Placing `vi.mock()` inside `describe()` blocks caused Vitest hoisting warnings; tests used `resetModules` approach which conflicted with hoisting behavior
 - **Fix:** Moved `vi.mock` to module top level; used `vi.mocked().mockRejectedValueOnce()` for per-test override
@@ -164,6 +166,7 @@ None — plan executed exactly as specified. One minor pnpm API difference (allo
 - **Committed in:** `96cda58` (Task 2 feat commit)
 
 **3. [Checkpoint clearing - Blocking] Docker image build broken for pnpm workspace**
+
 - **Found during:** Task 3 (orchestrator bringing up the stack to clear the checkpoint)
 - **Issue:** The original `apps/api/Dockerfile` built from a `./apps/api` context and could not work in a pnpm workspace:
   1. `COPY package.json pnpm-lock.yaml* ./` + `pnpm install --frozen-lockfile` failed (`ERR_PNPM_NO_LOCKFILE`) — the lockfile lives at the repo root, not in `apps/api/`.
@@ -200,6 +203,7 @@ None. The `serveStatic` warning for `./public` in tests is expected (no built PW
 ## Threat Surface Scan
 
 No new threat surface beyond what was planned in the threat model:
+
 - T-01-01: `.env` excluded from git via `.gitignore` ✓
 - T-01-02: `familysync` user (not root) in docker-compose.yml ✓
 - T-01-03: `/health` unauthenticated, returns only `{ok, db}` ✓
@@ -221,5 +225,6 @@ No new threat surface beyond what was planned in the threat model:
 - Commits 3f59156, f31711a, 96cda58: FOUND
 
 ---
-*Phase: 01-foundation-broker-spike*
-*Completed: 2026-06-04 (Tasks 1-2; Task 3 at checkpoint)*
+
+_Phase: 01-foundation-broker-spike_
+_Completed: 2026-06-04 (Tasks 1-2; Task 3 at checkpoint)_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-02-PLAN.md

@@ -3,7 +3,7 @@ phase: 01-foundation-broker-spike
 plan: 02
 type: execute
 wave: 2
-depends_on: ["01-01"]
+depends_on: ['01-01']
 files_modified:
   - apps/api/src/auth/middleware.ts
   - apps/api/src/auth/user.ts
@@ -19,33 +19,33 @@ requirements: [AUTH-01, AUTH-02, AUTH-03]
 must_haves:
   truths:
     - "An unauthenticated request to /api/* is redirected to Authelia's authorize endpoint (302)"
-    - "After login, the OIDC callback upserts a users row keyed by oidc_iss + oidc_sub (never email)"
-    - "Each member is auto-assigned a stable, distinct color from a curated palette on first login; re-login returns the same color"
-    - "Session persists via @hono/oidc-auth refresh-token rotation — no iframe, refresh held backend-side"
+    - 'After login, the OIDC callback upserts a users row keyed by oidc_iss + oidc_sub (never email)'
+    - 'Each member is auto-assigned a stable, distinct color from a curated palette on first login; re-login returns the same color'
+    - 'Session persists via @hono/oidc-auth refresh-token rotation — no iframe, refresh held backend-side'
     - "GET /api/me returns the authenticated user's identity + color"
     - "The PWA shell renders the logged-in member's name and color swatch"
   artifacts:
-    - path: "apps/api/src/auth/user.ts"
-      provides: "upsertUser(oidcIss, oidcSub, displayName) with round-robin color assignment"
-      exports: ["upsertUser", "COLOR_PALETTE"]
-    - path: "apps/api/src/auth/middleware.ts"
-      provides: "oidcAuthMiddleware wiring + getAuth → upsertUser bridge"
-    - path: "apps/api/src/routes/me.ts"
-      provides: "GET /api/me → { user: { id, displayName, color } }"
-      exports: ["meRouter"]
+    - path: 'apps/api/src/auth/user.ts'
+      provides: 'upsertUser(oidcIss, oidcSub, displayName) with round-robin color assignment'
+      exports: ['upsertUser', 'COLOR_PALETTE']
+    - path: 'apps/api/src/auth/middleware.ts'
+      provides: 'oidcAuthMiddleware wiring + getAuth → upsertUser bridge'
+    - path: 'apps/api/src/routes/me.ts'
+      provides: 'GET /api/me → { user: { id, displayName, color } }'
+      exports: ['meRouter']
   key_links:
-    - from: "apps/api/src/routes/me.ts"
-      to: "apps/api/src/auth/user.ts"
-      via: "upsertUser call"
+    - from: 'apps/api/src/routes/me.ts'
+      to: 'apps/api/src/auth/user.ts'
+      via: 'upsertUser call'
       pattern: "upsertUser\\("
-    - from: "apps/api/src/index.ts"
-      to: "@hono/oidc-auth"
-      via: "oidcAuthMiddleware on /api/*"
-      pattern: "oidcAuthMiddleware"
-    - from: "apps/pwa/src/App.tsx"
-      to: "/api/me"
-      via: "React Query fetch"
-      pattern: "api/me"
+    - from: 'apps/api/src/index.ts'
+      to: '@hono/oidc-auth'
+      via: 'oidcAuthMiddleware on /api/*'
+      pattern: 'oidcAuthMiddleware'
+    - from: 'apps/pwa/src/App.tsx'
+      to: '/api/me'
+      via: 'React Query fetch'
+      pattern: 'api/me'
 ---
 
 <objective>
@@ -73,6 +73,7 @@ Output: Working Authelia OIDC login, stable identity + color, /api/me, authentic
 </context>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 02)
 
 New files: `apps/api/src/auth/middleware.ts`, `apps/api/src/auth/user.ts`, `apps/api/src/routes/me.ts`, `apps/pwa/src/api/client.ts`.
@@ -105,6 +106,7 @@ New env vars: `OIDC_AUTH_SECRET`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_
     Create `src/auth/user.ts` exporting `COLOR_PALETTE` (a curated array of >=4 visually-distinct, accessible hex hues per D-06 / Claude's Discretion — e.g. calm blue, warm coral, forest green, soft purple; exact values Claude's choice) and `upsertUser(oidcIss, oidcSub, displayName?)`. Logic per RESEARCH example: SELECT existing by `and(eq(users.oidcIss, oidcIss), eq(users.oidcSub, oidcSub))`; if present return it; else COUNT existing users, assign `COLOR_PALETTE[count % length]`, INSERT, return the new row. Use `$returningId()` then re-select (mysql2 has no RETURNING). Never key on email.
 
     Fill `tests/auth/user.test.ts` GREEN using the test-DB fixture (tests/helpers/db.ts): assert (a) first insert assigns palette[0]; (b) second user assigns palette[1]; (c) re-upsert of user 1 returns the identical row + color and does not create a duplicate; (d) lookup is by iss+sub.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm vitest run tests/auth/user.test.ts --reporter=verbose</automated>
@@ -136,6 +138,7 @@ New env vars: `OIDC_AUTH_SECRET`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_
     PWA: create `apps/pwa/src/api/client.ts` with a typed `fetchMe()` (GET /api/me, credentials: 'include'). Update `App.tsx`: React Query `useQuery(['me'], fetchMe)`; on 401/redirect the browser follows Authelia (full-page). Render the member's displayName and a color swatch using `user.color`. Keep the /health indicator from Plan 01.
 
     Also record the Authelia client registration YAML (from RESEARCH Pattern 1) in the SUMMARY so the operator can paste it into Authelia's configuration.yml — this is the only human-side config (no code change in this repo).
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm exec tsc --noEmit && grep -q "oidcAuthMiddleware" src/index.ts && grep -q "OIDC_AUTH_EXTERNAL_URL" ../../.env.example && grep -q "upsertUser" src/routes/me.ts</automated>
@@ -155,24 +158,26 @@ New env vars: `OIDC_AUTH_SECRET`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| Browser → Pangolin → Hono /api/* | Untrusted client; only authenticated requests cross (OIDC session cookie) |
-| Authelia → /callback | OIDC authorization-code exchange; PKCE + state validate the callback |
-| Hono → Authelia token endpoint | Backend confidential client; client_secret + refresh token never reach the browser |
+| Boundary                          | Description                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| Browser → Pangolin → Hono /api/\* | Untrusted client; only authenticated requests cross (OIDC session cookie)          |
+| Authelia → /callback              | OIDC authorization-code exchange; PKCE + state validate the callback               |
+| Hono → Authelia token endpoint    | Backend confidential client; client_secret + refresh token never reach the browser |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02-01 | Spoofing | OIDC redirect_uri | mitigate | Authelia validates exact match; OIDC_REDIRECT_URI env must equal the registered URI; OIDC_AUTH_EXTERNAL_URL set so Pangolin Host header cannot forge the redirect (Pitfall 1) |
-| T-02-02 | Spoofing | CSRF on /callback | mitigate | @hono/oidc-auth uses PKCE (state + code_verifier); require_pkce true, S256 in Authelia client |
-| T-02-03 | Tampering | OIDC session JWT cookie | mitigate | Cookie signed with OIDC_AUTH_SECRET (32+ char), httpOnly + Secure + SameSite; verified every request |
-| T-02-04 | Information Disclosure | Refresh token / client_secret | mitigate | Backend-only (D-12); never serialized to frontend; not logged; OIDC_CLIENT_SECRET is the plain secret in env, never committed |
-| T-02-05 | Elevation of Privilege | /api/* without auth | mitigate | oidcAuthMiddleware mounted on /api/*; no guest access (ASVS V4) |
-| T-02-06 | Spoofing | Identity confusion via mutable email | mitigate | Identity keyed on oidc_iss + oidc_sub, never email (D-10) |
+| Threat ID | Category               | Component                            | Disposition | Mitigation Plan                                                                                                                                                               |
+| --------- | ---------------------- | ------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-02-01   | Spoofing               | OIDC redirect_uri                    | mitigate    | Authelia validates exact match; OIDC_REDIRECT_URI env must equal the registered URI; OIDC_AUTH_EXTERNAL_URL set so Pangolin Host header cannot forge the redirect (Pitfall 1) |
+| T-02-02   | Spoofing               | CSRF on /callback                    | mitigate    | @hono/oidc-auth uses PKCE (state + code_verifier); require_pkce true, S256 in Authelia client                                                                                 |
+| T-02-03   | Tampering              | OIDC session JWT cookie              | mitigate    | Cookie signed with OIDC_AUTH_SECRET (32+ char), httpOnly + Secure + SameSite; verified every request                                                                          |
+| T-02-04   | Information Disclosure | Refresh token / client_secret        | mitigate    | Backend-only (D-12); never serialized to frontend; not logged; OIDC_CLIENT_SECRET is the plain secret in env, never committed                                                 |
+| T-02-05   | Elevation of Privilege | /api/\* without auth                 | mitigate    | oidcAuthMiddleware mounted on /api/\*; no guest access (ASVS V4)                                                                                                              |
+| T-02-06   | Spoofing               | Identity confusion via mutable email | mitigate    | Identity keyed on oidc_iss + oidc_sub, never email (D-10)                                                                                                                     |
+
 </threat_model>
 
 <verification>
@@ -185,11 +190,12 @@ New env vars: `OIDC_AUTH_SECRET`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_
 </verification>
 
 <success_criteria>
-- AUTH-01: unauthenticated /api/* redirects to Authelia; login lands authenticated (verified live in Plan 04)
+
+- AUTH-01: unauthenticated /api/\* redirects to Authelia; login lands authenticated (verified live in Plan 04)
 - AUTH-02: session persists via backend refresh-token rotation (no iframe)
 - AUTH-03: stable identity (iss+sub) + stable distinct per-member color, asserted by unit tests
 - /api/me returns the member; PWA shell shows name + color
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/01-foundation-broker-spike/01-02-SUMMARY.md` when done. Include the Authelia client registration YAML for the operator.

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-02-SUMMARY.md

@@ -69,7 +69,7 @@ completed: "2026-06-04"
 - **Task 1 (TDD):** Replaced 5 `it.todo` stubs in `tests/auth/user.test.ts` with 6 real tests covering: palette[0] first user, palette[1] second distinct user, idempotent re-upsert (no duplicate insert), identity keyed on iss+sub not email, full row shape. All GREEN.
 - **Task 2:** Wired full OIDC vertical slice:
   - `src/auth/middleware.ts` re-exports oidcAuthMiddleware/processOAuthCallback/getAuth from @hono/oidc-auth
-  - `src/index.ts` updated: /health (public) → /callback → /api/* guarded by oidcAuthMiddleware → /api/me mounted
+  - `src/index.ts` updated: /health (public) → /callback → /api/\* guarded by oidcAuthMiddleware → /api/me mounted
   - `src/routes/me.ts` calls getAuth → upsertUser(iss, sub, email) → returns {user: {id, displayName, color}}
   - `apps/pwa/src/api/client.ts` typed fetchMe() with credentials: 'include'
   - `apps/pwa/src/App.tsx` renders MemberBadge (name + color swatch circle) via useQuery(['me'], fetchMe)
@@ -85,7 +85,7 @@ completed: "2026-06-04"
 - `apps/api/src/auth/user.ts` — `upsertUser` + `COLOR_PALETTE` (6 hex hues)
 - `apps/api/src/auth/middleware.ts` — `oidcAuthMiddleware`, `processOAuthCallback`, `getAuth` re-exports with env var documentation
 - `apps/api/src/routes/me.ts` — `GET /` handler: getAuth → upsertUser → `{user: {id, displayName, color}}`
-- `apps/api/src/index.ts` — updated mount order: /health → /callback → oidcAuthMiddleware on /api/* → /api/me
+- `apps/api/src/index.ts` — updated mount order: /health → /callback → oidcAuthMiddleware on /api/\* → /api/me
 - `apps/pwa/src/api/client.ts` — `fetchMe()` with typed response shape
 - `apps/pwa/src/App.tsx` — `MemberBadge` component with `ColorSwatch`; useQuery(['me'], fetchMe); retains /health indicator
 - `apps/api/tests/auth/user.test.ts` — 6 passing tests (was 5 it.todo stubs)
@@ -127,13 +127,13 @@ identity_providers:
 
 **`.env` values to set before first run:**
 
-| Variable | Value |
-|----------|-------|
-| `OIDC_AUTH_SECRET` | 32+ char random string (e.g. `openssl rand -base64 32`) |
-| `OIDC_ISSUER` | Authelia base URL, e.g. `https://auth.yourdomain.com` |
-| `OIDC_CLIENT_ID` | `familysync` |
-| `OIDC_CLIENT_SECRET` | Plain text secret (same value used with `authelia crypto hash`) |
-| `OIDC_REDIRECT_URI` | `https://familysync.yourdomain.com/callback` |
+| Variable                 | Value                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `OIDC_AUTH_SECRET`       | 32+ char random string (e.g. `openssl rand -base64 32`)                         |
+| `OIDC_ISSUER`            | Authelia base URL, e.g. `https://auth.yourdomain.com`                           |
+| `OIDC_CLIENT_ID`         | `familysync`                                                                    |
+| `OIDC_CLIENT_SECRET`     | Plain text secret (same value used with `authelia crypto hash`)                 |
+| `OIDC_REDIRECT_URI`      | `https://familysync.yourdomain.com/callback`                                    |
 | `OIDC_AUTH_EXTERNAL_URL` | `https://familysync.yourdomain.com` — **mandatory** behind Pangolin (Pitfall 1) |
 
 **Note:** `OIDC_AUTH_EXTERNAL_URL` is not optional behind Pangolin. Without it, `@hono/oidc-auth` constructs the redirect_uri from the internal container `Host` header, which won't match the registered URI in Authelia — login fails with "invalid redirect_uri".
@@ -154,7 +154,7 @@ All surfaces are within the planned threat model (Plan 02 STRIDE register):
 - **T-02-02 (CSRF):** processOAuthCallback uses PKCE (state + code_verifier); Authelia configured with require_pkce: true, S256
 - **T-02-03 (cookie tampering):** @hono/oidc-auth signs cookie with OIDC_AUTH_SECRET; httpOnly + Secure + SameSite enforced by library
 - **T-02-04 (refresh token / client_secret):** backend-only (D-12); getAuth → upsertUser → returns {id, displayName, color} only — no token or credential data in /api/me response
-- **T-02-05 (/api/* without auth):** oidcAuthMiddleware on /api/*; /health public-before-guard
+- **T-02-05 (/api/\* without auth):** oidcAuthMiddleware on /api/\*; /health public-before-guard
 - **T-02-06 (identity confusion):** upsertUser keyed exclusively on oidcIss + oidcSub; no email lookup anywhere in auth path
 
 No new threat surface introduced beyond plan.
@@ -170,5 +170,6 @@ No new threat surface introduced beyond plan.
 - 6 auth/user tests pass: PASSED
 
 ---
-*Phase: 01-foundation-broker-spike*
-*Completed: 2026-06-04*
+
+_Phase: 01-foundation-broker-spike_
+_Completed: 2026-06-04_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-03-PLAN.md

@@ -3,7 +3,7 @@ phase: 01-foundation-broker-spike
 plan: 03
 type: execute
 wave: 2
-depends_on: ["01-01"]
+depends_on: ['01-01']
 files_modified:
   - apps/api/src/broker/crypto.ts
   - apps/api/src/broker/client.ts
@@ -19,40 +19,40 @@ requirements: [CAL-01]
 
 must_haves:
   truths:
-    - "App passwords are encrypted at rest with AES-256-GCM (key from env) and decrypt losslessly; never exposed to the frontend"
-    - "The broker creates a Fastmail CalDAV client (Basic auth, app password) and fetches calendars via PROPFIND"
-    - "syncCalendar parses VEVENTs with ical.js and upserts them into calendar_events, storing all-day events as DATE (dtstart_date) never DATETIME"
+    - 'App passwords are encrypted at rest with AES-256-GCM (key from env) and decrypt losslessly; never exposed to the frontend'
+    - 'The broker creates a Fastmail CalDAV client (Basic auth, app password) and fetches calendars via PROPFIND'
+    - 'syncCalendar parses VEVENTs with ical.js and upserts them into calendar_events, storing all-day events as DATE (dtstart_date) never DATETIME'
     - "The poller skips DB writes when a calendar's ctag is unchanged (sync-token with ctag fallback)"
-    - "GET /api/events returns cached events from MariaDB (never a live Fastmail call per request)"
+    - 'GET /api/events returns cached events from MariaDB (never a live Fastmail call per request)'
   artifacts:
-    - path: "apps/api/src/broker/crypto.ts"
-      provides: "encryptPassword/decryptPassword (AES-256-GCM, key from APP_PASSWORD_ENCRYPTION_KEY)"
-      exports: ["encryptPassword", "decryptPassword"]
-    - path: "apps/api/src/broker/client.ts"
-      provides: "createFastmailClient(email, appPassword) → tsdav DAVClient"
-      exports: ["createFastmailClient"]
-    - path: "apps/api/src/broker/sync.ts"
-      provides: "syncCalendar: REPORT → ical.js → calendar_events upsert"
-      exports: ["syncCalendar"]
-    - path: "apps/api/src/broker/poller.ts"
-      provides: "startBrokerPoller (node-cron 5-min) with ctag change detection"
-      exports: ["startBrokerPoller"]
-    - path: "apps/api/src/routes/events.ts"
-      provides: "GET /api/events → cached events from DB"
-      exports: ["eventsRouter"]
+    - path: 'apps/api/src/broker/crypto.ts'
+      provides: 'encryptPassword/decryptPassword (AES-256-GCM, key from APP_PASSWORD_ENCRYPTION_KEY)'
+      exports: ['encryptPassword', 'decryptPassword']
+    - path: 'apps/api/src/broker/client.ts'
+      provides: 'createFastmailClient(email, appPassword) → tsdav DAVClient'
+      exports: ['createFastmailClient']
+    - path: 'apps/api/src/broker/sync.ts'
+      provides: 'syncCalendar: REPORT → ical.js → calendar_events upsert'
+      exports: ['syncCalendar']
+    - path: 'apps/api/src/broker/poller.ts'
+      provides: 'startBrokerPoller (node-cron 5-min) with ctag change detection'
+      exports: ['startBrokerPoller']
+    - path: 'apps/api/src/routes/events.ts'
+      provides: 'GET /api/events → cached events from DB'
+      exports: ['eventsRouter']
   key_links:
-    - from: "apps/api/src/broker/poller.ts"
-      to: "apps/api/src/broker/crypto.ts"
-      via: "decryptPassword before client creation"
+    - from: 'apps/api/src/broker/poller.ts'
+      to: 'apps/api/src/broker/crypto.ts'
+      via: 'decryptPassword before client creation'
       pattern: "decryptPassword\\("
-    - from: "apps/api/src/broker/sync.ts"
-      to: "apps/api/src/db/client.ts"
-      via: "calendarEvents upsert"
-      pattern: "calendarEvents"
-    - from: "apps/api/src/routes/events.ts"
-      to: "apps/api/src/db/client.ts"
-      via: "cache read (no live CalDAV)"
-      pattern: "from ['\"].*db/client"
+    - from: 'apps/api/src/broker/sync.ts'
+      to: 'apps/api/src/db/client.ts'
+      via: 'calendarEvents upsert'
+      pattern: 'calendarEvents'
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'apps/api/src/db/client.ts'
+      via: 'cache read (no live CalDAV)'
+      pattern: 'from [''"].*db/client'
 ---
 
 <objective>
@@ -80,6 +80,7 @@ Output: crypto helper, broker client/sync/poller, /api/events router, all unit-t
 </context>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 03)
 
 New files: `apps/api/src/broker/crypto.ts`, `apps/api/src/broker/client.ts`, `apps/api/src/broker/sync.ts`, `apps/api/src/broker/poller.ts`, `apps/api/src/routes/events.ts`.
@@ -113,6 +114,7 @@ New env vars: `APP_PASSWORD_ENCRYPTION_KEY` (64-char hex = 32 bytes).
     Add `APP_PASSWORD_ENCRYPTION_KEY` to `.env.example` with a comment showing the generator: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`.
 
     Fill `tests/broker/crypto.test.ts` GREEN: set a fixed test key in the test, assert (a) roundtrip lossless; (b) two encrypts of same plaintext differ; (c) tampering authTag causes decrypt to throw.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm vitest run tests/broker/crypto.test.ts --reporter=verbose</automated>
@@ -149,6 +151,7 @@ New env vars: `APP_PASSWORD_ENCRYPTION_KEY` (64-char hex = 32 bytes).
     Create `src/routes/events.ts` exporting `eventsRouter` (Hono): GET / reads from `calendarEvents` via `db` (cache only — NEVER call Fastmail per request, ARCHITECTURE anti-pattern), returns the rows (id, uid, allDay, dtstart_utc, dtstart_date, raw_vevent or a minimal shape). This router is mounted in Plan 04.
 
     Fill `tests/broker/sync.test.ts` GREEN with a mocked tsdav client returning captured raw VEVENT strings (timed + all-day fixtures — Wave 0 fixture requirement). Assert the dtstart_utc vs dtstart_date split, all_day flag, and UID-upsert idempotency.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm vitest run tests/broker/sync.test.ts --reporter=verbose && pnpm exec tsc --noEmit</automated>
@@ -183,6 +186,7 @@ New env vars: `APP_PASSWORD_ENCRYPTION_KEY` (64-char hex = 32 bytes).
     Create `src/broker/poller.ts` exporting `startBrokerPoller()` (and an internal `runPoll()` exported for tests). Per RESEARCH poller pattern: `schedule('*/5 * * * *', runPoll)` using node-cron v4 (Pitfall 4 — basic 5-field cron API is stable). `runPoll`: select all `memberCredentials`; for each, `decryptPassword`, `createFastmailClient`, `fetchCalendars`; for each davCal, compare `davCal.ctag ?? davCal.syncToken ?? null` to the stored calendars row ctag — if equal and non-null, `continue` (skip); else `syncCalendar`. Make `runPoll` injectable/testable (accept the db + client factory or use module mocks) so the unit test can assert skip-on-unchanged without hitting Fastmail.
 
     Fill `tests/broker/poller.test.ts` GREEN: mock fetchCalendars to return a calendar with a known ctag matching a stored row → assert syncCalendar spy NOT called; then a changed ctag → assert syncCalendar IS called.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm vitest run tests/broker/poller.test.ts --reporter=verbose</automated>
@@ -199,24 +203,26 @@ New env vars: `APP_PASSWORD_ENCRYPTION_KEY` (64-char hex = 32 bytes).
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                         | Description                                                                          |
+| -------------------------------- | ------------------------------------------------------------------------------------ |
 | member_credentials (DB) → broker | App passwords stored encrypted; only broker/crypto.ts decrypts; never leaves backend |
-| Broker → Fastmail CalDAV | Outbound Basic auth over TLS; sole holder of Fastmail I/O |
-| Hono /api/events → browser | Returns only cached event data; never credentials or raw app passwords |
+| Broker → Fastmail CalDAV         | Outbound Basic auth over TLS; sole holder of Fastmail I/O                            |
+| Hono /api/events → browser       | Returns only cached event data; never credentials or raw app passwords               |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-01 | Information Disclosure | Fastmail app password at rest | mitigate | AES-256-GCM with 96-bit IV + auth tag (crypto.ts); key from APP_PASSWORD_ENCRYPTION_KEY env, never committed/logged (ASVS V6) |
-| T-03-02 | Information Disclosure | App password leaking via /api/events | mitigate | events route reads only calendar_events (event data); never joins/returns member_credentials; broker is the only credential reader (D-04) |
-| T-03-03 | Tampering | Encrypted-credential integrity | mitigate | GCM auth tag verified on decrypt; tampered ciphertext throws, never silently used |
-| T-03-04 | Information Disclosure | Credentials in logs | mitigate | No console logging of decrypted passwords or the encryption key in client.ts / poller.ts |
-| T-03-05 | Tampering | Caching client-side event versions | mitigate | Only server-returned objects cached (raw VEVENT verbatim — D-13, Pitfall 14); no write-back in Phase 1 |
-| T-03-SC | Tampering | tsdav / ical.js / node-cron installs | accept | All [OK] in RESEARCH § Package Legitimacy Audit (tsdav 3+ yrs official repo, ical.js Mozilla-maintained, node-cron 8+ yrs); no [ASSUMED]/[SUS]/[SLOP] |
+| Threat ID | Category               | Component                            | Disposition | Mitigation Plan                                                                                                                                       |
+| --------- | ---------------------- | ------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-01   | Information Disclosure | Fastmail app password at rest        | mitigate    | AES-256-GCM with 96-bit IV + auth tag (crypto.ts); key from APP_PASSWORD_ENCRYPTION_KEY env, never committed/logged (ASVS V6)                         |
+| T-03-02   | Information Disclosure | App password leaking via /api/events | mitigate    | events route reads only calendar_events (event data); never joins/returns member_credentials; broker is the only credential reader (D-04)             |
+| T-03-03   | Tampering              | Encrypted-credential integrity       | mitigate    | GCM auth tag verified on decrypt; tampered ciphertext throws, never silently used                                                                     |
+| T-03-04   | Information Disclosure | Credentials in logs                  | mitigate    | No console logging of decrypted passwords or the encryption key in client.ts / poller.ts                                                              |
+| T-03-05   | Tampering              | Caching client-side event versions   | mitigate    | Only server-returned objects cached (raw VEVENT verbatim — D-13, Pitfall 14); no write-back in Phase 1                                                |
+| T-03-SC   | Tampering              | tsdav / ical.js / node-cron installs | accept      | All [OK] in RESEARCH § Package Legitimacy Audit (tsdav 3+ yrs official repo, ical.js Mozilla-maintained, node-cron 8+ yrs); no [ASSUMED]/[SUS]/[SLOP] |
+
 </threat_model>
 
 <verification>
@@ -227,12 +233,13 @@ New env vars: `APP_PASSWORD_ENCRYPTION_KEY` (64-char hex = 32 bytes).
 </verification>
 
 <success_criteria>
+
 - App passwords encrypted at rest (AES-256-GCM), lossless roundtrip, tamper-detecting
 - Broker discovers calendars and syncs VEVENTs into the cache with correct all-day DATE handling
 - Poller skips unchanged calendars (ctag detection)
 - /api/events serves cached events without a live Fastmail call
 - All three unit test files green
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/01-foundation-broker-spike/01-03-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-03-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 01-foundation-broker-spike
-plan: "03"
+plan: '03'
 subsystem: api
 tags: [caldav, ical.js, tsdav, node-cron, aes-256-gcm, drizzle, mariadb, vitest]
 
@@ -46,22 +46,22 @@ key-files:
     - .env.example (APP_PASSWORD_ENCRYPTION_KEY with generator comment)
 
 key-decisions:
-  - "Store dtstartDate as JS Date at T00:00:00Z (not raw string): Drizzle date column expects a Date or null; ical.js toString().slice(0,10) gives the YYYY-MM-DD, appending T00:00:00Z avoids TZ ambiguity"
-  - "Export runPoll separately from startBrokerPoller: lets tests invoke one poll cycle synchronously with vi.mock injected deps, avoiding real cron schedule in tests"
-  - "ctag skip condition: null ctag means first sync (no row stored) → must always sync; only skip when both sides have a non-null matching ctag"
+  - 'Store dtstartDate as JS Date at T00:00:00Z (not raw string): Drizzle date column expects a Date or null; ical.js toString().slice(0,10) gives the YYYY-MM-DD, appending T00:00:00Z avoids TZ ambiguity'
+  - 'Export runPoll separately from startBrokerPoller: lets tests invoke one poll cycle synchronously with vi.mock injected deps, avoiding real cron schedule in tests'
+  - 'ctag skip condition: null ctag means first sync (no row stored) → must always sync; only skip when both sides have a non-null matching ctag'
   - "Per-credential try/catch in runPoll: one corrupted or expired credential must not block other members' calendars from syncing"
-  - "events route imports db but never tsdav or crypto: enforces broker hard boundary (T-03-02)"
+  - 'events route imports db but never tsdav or crypto: enforces broker hard boundary (T-03-02)'
 
 patterns-established:
-  - "Pattern: broker boundary — tsdav and credentials are imported exclusively under apps/api/src/broker/; routes never touch Fastmail I/O"
-  - "Pattern: D-13 dtstart split — use ical.js ICAL.Time.isDate to route all-day vs timed into separate nullable columns"
-  - "Pattern: ctag null-defence — always use davCal.ctag ?? davCal.syncToken ?? null; Fastmail may return either field"
+  - 'Pattern: broker boundary — tsdav and credentials are imported exclusively under apps/api/src/broker/; routes never touch Fastmail I/O'
+  - 'Pattern: D-13 dtstart split — use ical.js ICAL.Time.isDate to route all-day vs timed into separate nullable columns'
+  - 'Pattern: ctag null-defence — always use davCal.ctag ?? davCal.syncToken ?? null; Fastmail may return either field'
 
 requirements-completed: [CAL-01]
 
 # Metrics
 duration: ~multi-session
-completed: "2026-06-04"
+completed: '2026-06-04'
 ---
 
 # Phase 01 Plan 03: CalDAV Broker Slice — Summary
@@ -100,7 +100,7 @@ Each task committed with TDD RED → GREEN cycle:
 - `apps/api/src/broker/crypto.ts` — encryptPassword / decryptPassword using node:crypto aes-256-gcm; 96-bit IV; JSON payload {iv, authTag, ciphertext} as hex
 - `apps/api/src/broker/client.ts` — createFastmailClient(email, appPassword) → tsdav DAVClient; FastmailClient type alias
 - `apps/api/src/broker/sync.ts` — syncCalendar: upserts calendars row, fetches REPORT objects, ical.js parses VEVENTs, upserts calendarEvents with D-13 split; onDuplicateKeyUpdate on calendarId+uid
-- `apps/api/src/broker/poller.ts` — startBrokerPoller (node-cron */5 * * * *) + runPoll (exported for tests); per-credential try/catch
+- `apps/api/src/broker/poller.ts` — startBrokerPoller (node-cron _/5 _ \* \* \*) + runPoll (exported for tests); per-credential try/catch
 - `apps/api/src/routes/events.ts` — eventsRouter GET / reads from db.select().from(calendarEvents); no tsdav import
 - `apps/api/tests/broker/crypto.test.ts` — roundtrip, IV uniqueness, tamper-throws
 - `apps/api/tests/broker/sync.test.ts` — timed dtstart_utc, all-day dtstart_date, same-UID idempotency
@@ -125,6 +125,7 @@ None — the draft poller.ts written by the interrupted agent passed all tests o
 ## User Setup Required
 
 Add to `.env`:
+
 ```
 APP_PASSWORD_ENCRYPTION_KEY=<64-char hex>  # node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
@@ -139,6 +140,7 @@ No external service configuration required for this plan. Live Fastmail integrat
 ## Threat Surface Scan
 
 No new surface beyond the plan's threat model:
+
 - T-03-01: AES-256-GCM with 96-bit IV + auth tag — implemented in crypto.ts
 - T-03-02: /api/events reads cache only, no tsdav import in routes/events.ts
 - T-03-03: GCM auth tag verified on decrypt; tampered ciphertext throws (test asserts this)
@@ -157,5 +159,6 @@ No new surface beyond the plan's threat model:
 ## Self-Check: PASSED
 
 ---
-*Phase: 01-foundation-broker-spike*
-*Completed: 2026-06-04*
+
+_Phase: 01-foundation-broker-spike_
+_Completed: 2026-06-04_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-04-PLAN.md

@@ -3,7 +3,7 @@ phase: 01-foundation-broker-spike
 plan: 04
 type: execute
 wave: 3
-depends_on: ["01-02", "01-03"]
+depends_on: ['01-02', '01-03']
 files_modified:
   - apps/api/src/routes/sse.ts
   - apps/api/src/index.ts
@@ -17,35 +17,35 @@ requirements: [CAL-08, CAL-01, AUTH-01, AUTH-02]
 
 must_haves:
   truths:
-    - "The full app is wired: broker poller starts on boot, /api/events + /api/me + /api/sse are mounted behind OIDC, /health public"
-    - "The landing page shows the logged-in member (name + color) AND one real cached Fastmail event as broker proof"
+    - 'The full app is wired: broker poller starts on boot, /api/events + /api/me + /api/sse are mounted behind OIDC, /health public'
+    - 'The landing page shows the logged-in member (name + color) AND one real cached Fastmail event as broker proof'
     - "A CAL-08 spike confirms Lucas's app password reads BOTH the shared family calendar and his personal calendar; the go/no-go decision is recorded in a committed doc"
-    - "GET /api/sse/heartbeat streams events over the real Pangolin tunnel for 5+ minutes without the proxy closing the stream (smoke test result recorded)"
-    - "Both members can authenticate through Authelia over the public URL and land on the shell (verified live)"
+    - 'GET /api/sse/heartbeat streams events over the real Pangolin tunnel for 5+ minutes without the proxy closing the stream (smoke test result recorded)'
+    - 'Both members can authenticate through Authelia over the public URL and land on the shell (verified live)'
   artifacts:
-    - path: "apps/api/src/routes/sse.ts"
-      provides: "GET /api/sse/heartbeat (streamSSE) — Pangolin pass-through smoke test"
-      exports: ["sseRouter"]
-    - path: "apps/api/src/broker/spike.ts"
-      provides: "CAL-08 spike script: createFastmailClient → fetchCalendars → print URLs"
-    - path: ".planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md"
-      provides: "Documented go/no-go for personal-calendar overlay"
-      contains: "Decision:"
-    - path: "apps/pwa/src/components/EventProof.tsx"
-      provides: "Renders one cached event from /api/events"
+    - path: 'apps/api/src/routes/sse.ts'
+      provides: 'GET /api/sse/heartbeat (streamSSE) — Pangolin pass-through smoke test'
+      exports: ['sseRouter']
+    - path: 'apps/api/src/broker/spike.ts'
+      provides: 'CAL-08 spike script: createFastmailClient → fetchCalendars → print URLs'
+    - path: '.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md'
+      provides: 'Documented go/no-go for personal-calendar overlay'
+      contains: 'Decision:'
+    - path: 'apps/pwa/src/components/EventProof.tsx'
+      provides: 'Renders one cached event from /api/events'
   key_links:
-    - from: "apps/api/src/index.ts"
-      to: "apps/api/src/broker/poller.ts"
-      via: "startBrokerPoller on boot"
+    - from: 'apps/api/src/index.ts'
+      to: 'apps/api/src/broker/poller.ts'
+      via: 'startBrokerPoller on boot'
       pattern: "startBrokerPoller\\(\\)"
-    - from: "apps/api/src/index.ts"
-      to: "apps/api/src/routes/events.ts"
-      via: "app.route /api/events"
-      pattern: "/api/events"
-    - from: "apps/pwa/src/components/EventProof.tsx"
-      to: "/api/events"
-      via: "React Query fetch"
-      pattern: "api/events"
+    - from: 'apps/api/src/index.ts'
+      to: 'apps/api/src/routes/events.ts'
+      via: 'app.route /api/events'
+      pattern: '/api/events'
+    - from: 'apps/pwa/src/components/EventProof.tsx'
+      to: '/api/events'
+      via: 'React Query fetch'
+      pattern: 'api/events'
 ---
 
 <objective>
@@ -75,6 +75,7 @@ Output: fully wired app, landing page with member + event proof, CAL-08 decision
 </context>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 04)
 
 New files: `apps/api/src/routes/sse.ts`, `apps/api/src/broker/spike.ts`, `apps/pwa/src/components/EventProof.tsx`, `.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md`.
@@ -103,6 +104,7 @@ Modified: `apps/api/src/index.ts` (mount events/sse routers, startBrokerPoller o
     Update `src/index.ts` to the final bootstrap (RESEARCH "Hono app bootstrap"): order = `/callback` (processOAuthCallback) → `/health` (public, Plan 01) → `app.use('/api/*', oidcAuthMiddleware())` → `app.route('/api/me', meRouter)` → `app.route('/api/events', eventsRouter)` → `app.route('/api/sse', sseRouter)` → `startBrokerPoller()` → serveStatic(./public) → `serve({ port: 3000 })`. Confirm /health stays before the /api guard.
 
     PWA: add `fetchEvents()` to `src/api/client.ts` (GET /api/events, credentials include). Create `src/components/EventProof.tsx`: React Query `['events']`, render the first event's title/date (parse from the returned shape) or an empty-state "No cached events yet". Update `App.tsx` to render member (name + color, from Plan 02) AND `<EventProof />` together — the single broker-proof landing screen (Claude's Discretion landing page).
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm exec tsc --noEmit && grep -q "startBrokerPoller()" src/index.ts && grep -q "'/api/events'" src/index.ts && grep -q "'/api/sse'" src/index.ts && grep -q "streamSSE" src/routes/sse.ts</automated>
@@ -149,24 +151,26 @@ Modified: `apps/api/src/index.ts` (mount events/sse routers, startBrokerPoller o
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| Public internet → Pangolin → Hono | Untrusted; only authenticated /api/* requests proceed; /health + /callback are the only pre-auth routes |
-| SSE stream (browser ↔ /api/sse) | Long-lived; must remain behind OIDC, must not leak data beyond heartbeat |
-| Spike credential handling | Lucas's app password used once for enumeration; stored encrypted, never logged/committed |
+| Boundary                          | Description                                                                                              |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Public internet → Pangolin → Hono | Untrusted; only authenticated /api/\* requests proceed; /health + /callback are the only pre-auth routes |
+| SSE stream (browser ↔ /api/sse)   | Long-lived; must remain behind OIDC, must not leak data beyond heartbeat                                 |
+| Spike credential handling         | Lucas's app password used once for enumeration; stored encrypted, never logged/committed                 |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-04-01 | Elevation of Privilege | /api/sse/heartbeat | mitigate | Mounted under /api/* behind oidcAuthMiddleware; no unauthenticated SSE access (ASVS V4) |
-| T-04-02 | Information Disclosure | SSE payload | accept | Heartbeat carries only `{ ts, id }` — no user data or secrets |
-| T-04-03 | Spoofing | Same-site session cookie behind Pangolin | mitigate | FamilySync + Authelia share parent domain (Pitfall 1/17); OIDC_AUTH_EXTERNAL_URL set so redirect_uri matches |
-| T-04-04 | Information Disclosure | Fastmail app password during spike | mitigate | Passed via env for one-off enumeration or stored encrypted via Plan 03 crypto; never echoed to logs or committed; spike output prints only calendar URLs/displayNames, never the password |
-| T-04-05 | Tampering | client_secret plain vs hashed | mitigate | Plain secret only in OIDC_CLIENT_SECRET env (Pitfall 7); Authelia YAML holds the pbkdf2-sha512 hash; .env never committed |
-| T-04-SC | Tampering | tsx (dev runner for spike) | accept | tsx is a widely-used TypeScript runner; spike script is dev-only, not shipped in the Docker image |
+| Threat ID | Category               | Component                                | Disposition | Mitigation Plan                                                                                                                                                                           |
+| --------- | ---------------------- | ---------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-04-01   | Elevation of Privilege | /api/sse/heartbeat                       | mitigate    | Mounted under /api/\* behind oidcAuthMiddleware; no unauthenticated SSE access (ASVS V4)                                                                                                  |
+| T-04-02   | Information Disclosure | SSE payload                              | accept      | Heartbeat carries only `{ ts, id }` — no user data or secrets                                                                                                                             |
+| T-04-03   | Spoofing               | Same-site session cookie behind Pangolin | mitigate    | FamilySync + Authelia share parent domain (Pitfall 1/17); OIDC_AUTH_EXTERNAL_URL set so redirect_uri matches                                                                              |
+| T-04-04   | Information Disclosure | Fastmail app password during spike       | mitigate    | Passed via env for one-off enumeration or stored encrypted via Plan 03 crypto; never echoed to logs or committed; spike output prints only calendar URLs/displayNames, never the password |
+| T-04-05   | Tampering              | client_secret plain vs hashed            | mitigate    | Plain secret only in OIDC_CLIENT_SECRET env (Pitfall 7); Authelia YAML holds the pbkdf2-sha512 hash; .env never committed                                                                 |
+| T-04-SC   | Tampering              | tsx (dev runner for spike)               | accept      | tsx is a widely-used TypeScript runner; spike script is dev-only, not shipped in the Docker image                                                                                         |
+
 </threat_model>
 
 <verification>
@@ -179,13 +183,14 @@ Modified: `apps/api/src/index.ts` (mount events/sse routers, startBrokerPoller o
 </verification>
 
 <success_criteria>
+
 - SC1 (AUTH-01): both members authenticate via Authelia over the public URL, land on home, no Fastmail prompt
 - SC2 (AUTH-02): sessions persist across browser restart
 - SC3 (AUTH-03): each member has a stable distinct color
 - SC4 (CAL-01): broker fetched + cached ≥1 real event; shown on the landing page
 - SC5 (CAL-08): go/no-go decision documented in CAL-08-DECISION.md
 - Bonus (D-08): Pangolin SSE pass-through smoke result recorded for Phase 4
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/01-foundation-broker-spike/01-04-SUMMARY.md` when done. Include the SSE smoke-test result and a pointer to CAL-08-DECISION.md.

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-04-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 01-foundation-broker-spike
-plan: "04"
+plan: '04'
 subsystem: integration
 tags: [hono, sse, caldav, react, typescript, pwa, spike, pangolin]
 
@@ -21,12 +21,12 @@ affects:
 # Tech tracking
 tech-stack:
   added:
-    - "hono/streaming (streamSSE) — SSE streaming helper, already a peer dep of hono"
-    - "ical.js@2.2.1 added to apps/pwa (already in apps/api; needed for EventProof summary parsing)"
+    - 'hono/streaming (streamSSE) — SSE streaming helper, already a peer dep of hono'
+    - 'ical.js@2.2.1 added to apps/pwa (already in apps/api; needed for EventProof summary parsing)'
   patterns:
-    - "SSE auth: sseRouter mounted under /api/sse, behind oidcAuthMiddleware — no unauthenticated SSE access (T-04-01)"
-    - "Bootstrap order: /callback → /health (pre-guard) → app.use(/api/*, oidcAuthMiddleware) → /api/me → /api/events → /api/sse → startBrokerPoller → serveStatic"
-    - "Spike pattern: env-var credentials (FASTMAIL_EMAIL, FASTMAIL_APP_PASSWORD) → createFastmailClient → fetchCalendars → print URLs; never log password (T-04-04)"
+    - 'SSE auth: sseRouter mounted under /api/sse, behind oidcAuthMiddleware — no unauthenticated SSE access (T-04-01)'
+    - 'Bootstrap order: /callback → /health (pre-guard) → app.use(/api/*, oidcAuthMiddleware) → /api/me → /api/events → /api/sse → startBrokerPoller → serveStatic'
+    - 'Spike pattern: env-var credentials (FASTMAIL_EMAIL, FASTMAIL_APP_PASSWORD) → createFastmailClient → fetchCalendars → print URLs; never log password (T-04-04)'
     - "EventProof: tries ical.js parse for SUMMARY field; falls back to 'Untitled event' on parse failure — resilient to malformed VEVENT blobs"
 
 key-files:
@@ -42,13 +42,13 @@ key-files:
     - apps/pwa/package.json (added ical.js@2.2.1 dependency)
 
 key-decisions:
-  - "ical.js added to PWA for VEVENT summary parsing in EventProof: EventProof parses rawVevent to extract the SUMMARY field for a human-readable event title; ical.js is already approved and used in the API — the same package at the same version"
-  - "spike.ts uses tsx (dev-only runner) via pnpm exec: tsx is accepted per T-04-SC; spike is not imported by the API or Docker image"
+  - 'ical.js added to PWA for VEVENT summary parsing in EventProof: EventProof parses rawVevent to extract the SUMMARY field for a human-readable event title; ical.js is already approved and used in the API — the same package at the same version'
+  - 'spike.ts uses tsx (dev-only runner) via pnpm exec: tsx is accepted per T-04-SC; spike is not imported by the API or Docker image'
   - "CAL-08-DECISION.md committed as a template now, human-filled after running spike: the file must contain 'Decision:' to satisfy the artifact spec; template pre-populates the structure"
 
 # Metrics
 duration: ~3min (code tasks only; live verification pending)
-completed: "2026-06-04"
+completed: '2026-06-04'
 ---
 
 # Phase 01 Plan 04: Integration + Gate Slice — Summary
@@ -102,6 +102,7 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
    - Fastmail Settings → Privacy & Security → App Passwords → scope: "Mail, Contacts & Calendars"
 
 2. Run the spike:
+
    ```bash
    cd apps/api
    FASTMAIL_EMAIL=lucas@fastmail.com \
@@ -112,6 +113,7 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
 3. Confirm in output: (a) shared family calendar collection URL appears; (b) Lucas's personal calendar URL appears. Record both.
 
 4. To insert the credential into the DB for the broker to use (one-off node script):
+
    ```bash
    # First ensure APP_PASSWORD_ENCRYPTION_KEY is set in .env
    cd apps/api
@@ -124,6 +126,7 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
    ```
 
 5. Start the stack and verify at least one event lands in `calendar_events`:
+
    ```bash
    docker compose exec mariadb mariadb -ufamilysync -p<pw> familysync \
      -e "SELECT id, uid, all_day FROM calendar_events LIMIT 5;"
@@ -145,12 +148,15 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
 **What to do:**
 
 1. Register FamilySync OIDC client in Authelia (see 01-02-SUMMARY.md for full YAML):
+
    ```bash
    authelia crypto hash --sha512 <your-plain-client-secret>
    ```
+
    Add the client block to Authelia's `configuration.yml` and reload.
 
 2. Set env vars in `.env`:
+
    ```
    OIDC_AUTH_SECRET=<openssl rand -base64 32>
    OIDC_ISSUER=https://auth.<domain>
@@ -161,6 +167,7 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
    ```
 
 3. Expose FamilySync through Pangolin under the SAME parent domain as Authelia (same-site cookie requirement — Pitfall 1).
+
    ```bash
    docker compose up -d
    ```
@@ -172,9 +179,11 @@ These are `checkpoint:human-action` tasks that require real infrastructure:
 6. Repeat for second member (wife) → confirm distinct color (AUTH-03).
 
 7. SSE smoke test (D-08) — run from external network with a valid session cookie:
+
    ```bash
    curl -N -b "session=<cookie-value>" https://familysync.<domain>/api/sse/heartbeat
    ```
+
    Keep open 5+ minutes. Record: **PASS** (events keep arriving) or **FAIL** (stream cut by proxy).
 
 8. Record SSE smoke result in SUMMARY (update this file) for Phase 4 transport decision.
@@ -193,6 +202,7 @@ If FAIL: investigate Pangolin idle-timeout config; note for Phase 4.
 ## Deviations from Plan
 
 **[Rule 2 - Missing dependency] ical.js added to PWA for EventProof summary parsing**
+
 - **Found during:** Task 1 (EventProof.tsx implementation)
 - **Issue:** EventProof.tsx parses rawVevent strings using ical.js to extract human-readable SUMMARY. ical.js was only in apps/api; EventProof runs in the browser.
 - **Fix:** Added ical.js@2.2.1 to apps/pwa/package.json. Same package, same version, already approved in the legitimacy audit.
@@ -206,6 +216,7 @@ If FAIL: investigate Pangolin idle-timeout config; note for Phase 4.
 ## Threat Surface Scan
 
 All surfaces within Plan 04 threat model:
+
 - **T-04-01 (SSE auth):** sseRouter mounted under `/api/sse` behind `oidcAuthMiddleware` — confirmed
 - **T-04-02 (SSE payload):** heartbeat carries only `{ ts, id }` — no user data or secrets
 - **T-04-03 (same-site cookies):** operator must expose FamilySync under same parent domain as Authelia — documented in Task 3 steps
@@ -227,5 +238,6 @@ All surfaces within Plan 04 threat model:
 - `pnpm vitest run` 24/24 tests green: PASSED
 
 ---
-*Phase: 01-foundation-broker-spike*
-*Completed (code): 2026-06-04 — Live verification pending*
+
+_Phase: 01-foundation-broker-spike_
+_Completed (code): 2026-06-04 — Live verification pending_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-CONTEXT.md

@@ -16,6 +16,7 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 ## Implementation Decisions
 
 ### Personal-Calendar Access & Spike (CAL-08 gate)
+
 - **D-01:** The wife's personal calendar lives on **Fastmail** (confirmed by user). It is a Fastmail-hosted calendar collection, so the broker can reach it via CalDAV. This removes the iCloud "unreachable" risk entirely.
 - **D-02:** Broker access model = **per-member app passwords**, NOT single-token cross-account share+accept. Each member generates their own Fastmail app password; the broker holds N credentials and reads each account directly. This eliminates the unconfirmed cross-account CalDAV ACL discovery risk — the original highest project risk. The CAL-08 spike therefore simplifies to: confirm an app password reads its own account's shared + personal calendars via PROPFIND/REPORT.
 - **D-03:** Phase 1 proceeds with **only the primary user's (Lucas) app password**. Success criterion #4 (read+cache a real event) is proven against Lucas's personal + the shared family calendar. The wife's app password is added in Phase 2 — Phase 1 is NOT blocked on coordinating with her. CAL-08 is structurally proven (N-credential broker) without her credential present.
@@ -23,13 +24,16 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 - **D-05:** Go/no-go record: since access is per-member app passwords and her calendar is on Fastmail, the expected outcome is GO. The documented fallback (only relevant if a Fastmail app password unexpectedly cannot read a personal calendar) is shared-family-only for v1, moving CAL-08 to v1.x.
 
 ### Member Color Assignment (AUTH-03)
+
 - **D-06:** Each member's color is **auto-assigned from a curated palette on first login** and persisted on the user row (keyed by `oidc_iss + oidc_sub`). Stable across sessions, no settings UI in Phase 1, works for both current members and any future member. Not user-pickable in v1 (a settings color-picker is a deferred idea).
 
 ### Infrastructure & Deployment Scope
+
 - **D-07:** Phase 1 **deploys through the real Pangolin tunnel + Authelia**, not local-only. OIDC redirect URIs, HTTPS, and session cookies are validated in the real topology from day one to avoid a "worked locally, broke in prod" OIDC failure. Ensure FamilySync and Authelia share the same parent domain so Authelia session cookies are same-site (Pitfall 17).
 - **D-08:** Phase 1 **folds in the Pangolin SSE pass-through smoke test** (a trivial long-lived SSE endpoint confirmed over the public URL). De-risks Phase 4 transport choice early (issue #1034). A failure here changes the Phase 4 real-time transport decision; it does NOT block Phase 1's auth/broker success criteria.
 
 ### Locked Upstream (carried forward — do NOT re-litigate)
+
 - **D-09:** CalDAV-only via `tsdav`; broker auth = Fastmail **app password**, never JMAP/API token. Principal URL form `https://caldav.fastmail.com/dav/principals/user/{email}/` (Pitfall 1).
 - **D-10:** Identity = `oidc_iss + oidc_sub` composite key, never email (AUTH-03).
 - **D-11:** **Skip the Authelia `groups` claim** — two equal members; authentication not authorization (Pitfall 16).
@@ -37,29 +41,34 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 - **D-13:** Calendar cache: store raw VEVENT blob + `dtstart_utc`; all-day events as `DATE` / `{date, allDay}` struct, never coerced to DATETIME/UTC (Pitfall 3). Write-through cache invalidation; only cache server-returned objects (Pitfall 14). Use sync-token (WebDAV-Sync) with ctag-poll fallback from day one (Pitfall 4).
 
 ### Claude's Discretion
+
 - **Phase 1 landing page:** a thin authenticated shell that ALSO displays the one cached event as broker proof (not a bare health page, not a real calendar UI). Confirms end-to-end auth + broker in one screen.
 - **Color palette:** a small set of visually-distinct, accessible hues assigned round-robin by join order. Exact values are Claude's choice.
 - **Broker internals:** sync-token vs ctag detection, poll interval (research suggests conservative 5-min / 60s acceptable for v1), Drizzle schema specifics, OIDC middleware wiring, encryption helper implementation.
 - **Stack libraries/versions:** per locked research stack (Hono + Drizzle/mysql2 + tsdav + ical.js + rrule + @hono/oidc-auth).
-</decisions>
+  </decisions>
 
 <canonical_refs>
+
 ## Canonical References
 
 **Downstream agents MUST read these before planning or implementing.**
 
 ### Phase definition & requirements
+
 - `.planning/ROADMAP.md` § "Phase 1: Foundation + Broker Spike" — goal + 5 success criteria (the scope anchor)
 - `.planning/REQUIREMENTS.md` — AUTH-01, AUTH-02, AUTH-03, CAL-01, CAL-08 (full requirement text + traceability)
 - `.planning/PROJECT.md` — constraints, key decisions, household context
 
 ### Research (read before planning — flagged NEEDS research-phase by SUMMARY)
+
 - `.planning/research/SUMMARY.md` — cross-cutting findings; Phase 1 section + confidence assessment
 - `.planning/research/PITFALLS.md` — Phase-1-relevant pitfalls: #1 (CalDAV-only), #3 (all-day DATE), #4 (ETag/sync-token), #7 (personal-cal sharing), #14 (cache double-write), #16 (Authelia groups), #17 (Authelia silent renewal/cookies), #18 (Pangolin WS/SSE)
 - `.planning/research/STACK.md` — locked library versions + import paths
 - `.planning/research/ARCHITECTURE.md` — broker-cache pattern, component layout, MariaDB schema guidance
 
 ### External docs (authoritative)
+
 - Fastmail CalDAV principal URL + app passwords (see SUMMARY/PITFALLS Sources)
 - Authelia OIDC client config — PKCE S256, `client_secret_basic`, response_type `code`, grant types `authorization_code`+`refresh_token` (see CLAUDE.md "Authelia OIDC Integration")
 - Pangolin WebSocket/SSE issue #1034 (referenced in PITFALLS #18)
@@ -67,15 +76,19 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 </canonical_refs>
 
 <code_context>
+
 ## Existing Code Insights
 
 ### Reusable Assets
+
 - None — greenfield repo. Only `.planning/`, generated `CLAUDE.md`, and an empty `README` exist. No source tree yet.
 
 ### Established Patterns
+
 - None established yet. Phase 1 sets the foundational patterns (Docker Compose layout, Drizzle schema/migrations, broker module boundary, OIDC session middleware) that later phases inherit.
 
 ### Integration Points
+
 - Authelia (already deployed, both members have accounts) — register FamilySync as an OIDC confidential client; no Authelia deploy/provisioning.
 - Pangolin/Newt tunnel (already running) — FamilySync gets a public hostname under the same parent domain as Authelia.
 - MariaDB + Redis available in the Unraid stack; no PostgreSQL.
@@ -86,7 +99,7 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 ## Specific Ideas
 
 - The broker module must be a hard boundary: all Fastmail I/O isolated in `broker/`; nothing else imports Fastmail credentials or tsdav directly (architecture note).
-- "No per-member credential juggling" is a core-value phrase, but the user explicitly accepted per-member app passwords as the access model — the juggling avoided is calendar-credential *login* friction for members (they still log in only via Authelia SSO), not broker-side secrets.
+- "No per-member credential juggling" is a core-value phrase, but the user explicitly accepted per-member app passwords as the access model — the juggling avoided is calendar-credential _login_ friction for members (they still log in only via Authelia SSO), not broker-side secrets.
 
 </specifics>
 
@@ -98,11 +111,12 @@ Stand up the FamilySync stack (Docker Compose + MariaDB, deployed through the re
 - **Wife's app password onboarding flow** — the encrypted-credential DB table is built in Phase 1 to support it, but the actual onboarding UX/endpoint is Phase 2 work.
 
 ### Reviewed Todos (not folded)
+
 - "Kick off FamilySync with /gsd:new-project" — stale project-kickoff todo, already completed during initialization; not relevant to Phase 1 scope.
 
 </deferred>
 
 ---
 
-*Phase: 1-Foundation + Broker Spike*
-*Context gathered: 2026-06-04*
+_Phase: 1-Foundation + Broker Spike_
+_Context gathered: 2026-06-04_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-DISCUSSION-LOG.md

@@ -0,0 +1,118 @@
+# Phase 1: Foundation + Broker Spike - 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-04
+**Phase:** 1-Foundation + Broker Spike
+**Areas discussed:** Personal-cal spike & fallback, Member color assignment, Infra validation scope
+
+---
+
+## Area Selection
+
+| Option                        | Selected                        |
+| ----------------------------- | ------------------------------- |
+| Personal-cal spike & fallback | ✓                               |
+| Member color assignment       | ✓                               |
+| Phase 1 landing scope         | (skipped → Claude's discretion) |
+| Infra validation scope        | ✓                               |
+
+---
+
+## Personal-cal spike & fallback
+
+### Where the wife's personal calendar lives
+
+| Option                  | Description                                     | Selected |
+| ----------------------- | ----------------------------------------------- | -------- |
+| Fastmail                | Fastmail-hosted collection; broker can reach it | ✓        |
+| iCloud / Apple Calendar | Broker cannot read; CAL-08 degrades             |          |
+| Not sure yet            | Confirm before spike                            |          |
+| Both / mixed            | Define overlay target                           |          |
+
+**User's choice:** Fastmail
+**Notes:** Removes the iCloud "unreachable" risk; CAL-08 is technically achievable.
+
+### Broker access model
+
+| Option                                    | Description                                          | Selected |
+| ----------------------------------------- | ---------------------------------------------------- | -------- |
+| Single broker token + share               | One token; share+accept per member                   |          |
+| Per-member app passwords                  | Each member's own app password; broker holds N creds | ✓        |
+| Prove single-token, keep per-member ready | Hybrid                                               |          |
+
+**User's choice:** Per-member app passwords
+**Notes:** Eliminates the unconfirmed cross-account CalDAV ACL discovery risk (the project's original highest risk). Spike simplifies to confirming an app password reads its own account.
+
+### Spike credential sequencing
+
+| Option                   | Description                                                  | Selected |
+| ------------------------ | ------------------------------------------------------------ | -------- |
+| Just mine now            | Prove broker with Lucas's app password; wife's added Phase 2 | ✓        |
+| Both before Phase 1 done | Get wife's password too; fully close CAL-08 now              |          |
+
+**User's choice:** Just mine now
+**Notes:** Phase 1 not blocked on coordinating with wife. CAL-08 structurally proven via N-credential broker.
+
+### Credential storage
+
+| Option                      | Description                                                | Selected |
+| --------------------------- | ---------------------------------------------------------- | -------- |
+| DB table, encrypted at rest | Keyed by oidc_sub, key from env; supports later onboarding | ✓        |
+| Env vars / secrets file     | Simple, but redeploy to add/rotate                         |          |
+
+**User's choice:** DB table, encrypted at rest
+**Notes:** Supports adding wife later with no redeploy; backend-only, never exposed to frontend.
+
+---
+
+## Member color assignment
+
+| Option                    | Description                                | Selected |
+| ------------------------- | ------------------------------------------ | -------- |
+| Auto-assign from palette  | Assign on first login, persist on user row | ✓        |
+| User-pickable in settings | Default + settings color-picker            |          |
+| Hardcoded per account     | Fixed color in config per oidc_sub         |          |
+
+**User's choice:** Auto-assign from palette
+**Notes:** No settings UI in Phase 1; stable across sessions; works for future members. Pickable color deferred.
+
+---
+
+## Infra validation scope
+
+### Deployment scope
+
+| Option                    | Description                                            | Selected |
+| ------------------------- | ------------------------------------------------------ | -------- |
+| Deploy through Pangolin   | Real tunnel + Authelia; validate OIDC topology day one | ✓        |
+| Local docker-compose only | Localhost; defer tunnel validation                     |          |
+
+**User's choice:** Deploy through Pangolin
+**Notes:** Avoids "worked locally, broke in prod" OIDC failure; same-parent-domain cookies (Pitfall 17).
+
+### Pangolin SSE smoke test
+
+| Option           | Description                                           | Selected |
+| ---------------- | ----------------------------------------------------- | -------- |
+| Fold it in now   | Trivial SSE endpoint over public URL; de-risk Phase 4 | ✓        |
+| Defer to Phase 4 | Keep Phase 1 strict to its 5 criteria                 |          |
+
+**User's choice:** Fold it in now
+**Notes:** Cheap while stack+tunnel are up; a failure changes Phase 4 transport but does not block Phase 1.
+
+---
+
+## Claude's Discretion
+
+- Phase 1 landing page: thin authenticated shell that also displays the one cached event as broker proof.
+- Color palette: small set of visually-distinct, accessible hues, round-robin by join order.
+- Broker internals (sync-token vs ctag, poll interval), Drizzle schema, OIDC middleware wiring, encryption helper.
+- Stack libraries/versions per locked research stack.
+
+## Deferred Ideas
+
+- User-pickable member color (settings color-picker) — future settings/profile phase.
+- Single-token broker via share+accept — not chosen; alternative on record only.
+- Wife's app-password onboarding UX/endpoint — Phase 2 (the encrypted credential table is built in Phase 1 to support it).

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

@@ -2,8 +2,8 @@
 status: partial
 phase: 01-foundation-broker-spike
 source: [01-VERIFICATION.md]
-started: "2026-06-04"
-updated: "2026-06-04"
+started: '2026-06-04'
+updated: '2026-06-04'
 ---
 
 ## Current Test
@@ -13,19 +13,23 @@ updated: "2026-06-04"
 ## Tests
 
 ### 1. AUTH-01 — Live Authelia OIDC login over the public Pangolin URL
+
 expected: From an external network, opening `https://familysync.<domain>` redirects to Authelia; after logging in as Lucas, the app shell loads showing his name, his assigned color, and one real cached Fastmail event. No Fastmail credentials are entered in the app.
 result: [pending]
 setup: Register the `familysync` OIDC client in Authelia (`require_pkce: true`, `pkce_challenge_method: S256`, `token_endpoint_auth_method: client_secret_basic`, redirect `https://familysync.<domain>/callback`, scopes openid/profile/email). Set OIDC env vars in `.env` — note `OIDC_AUTH_EXTERNAL_URL` is mandatory behind Pangolin. Deploy via `docker compose up -d`.
 
 ### 2. AUTH-02 — Session persists across browser restart
+
 expected: After authenticating, fully close and reopen the browser, revisit the URL → no re-login prompt; the shell loads directly.
 result: [pending]
 
 ### 3. AUTH-03 — Second member gets a distinct color
+
 expected: The wife logs in via Authelia on her device and is assigned a stable color distinct from Lucas's; it does not change on subsequent logins.
 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: 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).
 

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-VALIDATION.md

@@ -0,0 +1,89 @@
+---
+phase: 1
+slug: foundation-broker-spike
+status: planned
+nyquist_compliant: true
+wave_0_complete: false
+created: 2026-06-04
+---
+
+# Phase 1 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property               | Value                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| **Framework**          | vitest (Vite-native, shared backend + frontend per CLAUDE.md)                     |
+| **Config file**        | `apps/api/vitest.config.ts` (environment: node) — created Plan 01 Task 1 (Wave 0) |
+| **Quick run command**  | `pnpm vitest run --reporter=dot`                                                  |
+| **Full suite command** | `pnpm vitest run`                                                                 |
+| **Estimated runtime**  | ~30 seconds                                                                       |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `pnpm vitest run --reporter=dot`
+- **After every plan wave:** Run `pnpm vitest run`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 60 seconds
+
+---
+
+## Per-Task Verification Map
+
+> Mapped to final task IDs. Each phase success criterion maps to at least one automated or manual verification.
+
+| Success Criterion                                 | Requirement             | Plan/Task                                             | Verification approach                                                                                                                                                                                                     | Test Type                                     |
+| ------------------------------------------------- | ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------------------- |
+| SC1 — OIDC login lands on home, no Fastmail creds | AUTH-01                 | 01-02 Task 2 (wiring) + 01-04 Task 3 (live)           | Middleware mounted on /api/\*, /callback wired (tsc/grep); live: unauth /api/me 302→Authelia, login lands on shell                                                                                                        | integration + manual (real Authelia/Pangolin) |
+| SC2 — Sessions persist across browser restart     | AUTH-02                 | 01-02 Task 2 + 01-04 Task 3 (live)                    | Backend refresh-token rotation configured (no iframe); live: close browser, revisit, no re-login                                                                                                                          | integration + manual                          |
+| SC3 — Stable distinct member color                | AUTH-03                 | 01-02 Task 1 (unit) + 01-04 Task 3 (2nd member, live) | Unit: round-robin palette by join order, idempotent re-upsert, identity by iss+sub (`tests/auth/user.test.ts`); live: 2nd member distinct color                                                                           | unit + manual                                 |
+| SC4 — Broker fetches + caches ≥1 real event       | CAL-01                  | 01-03 Task 2/3 (unit) + 01-04 Task 2 (live spike)     | Unit: sync all-day/timed split + UID upsert (`tests/broker/sync.test.ts`), ctag skip (`tests/broker/poller.test.ts`), crypto roundtrip (`tests/broker/crypto.test.ts`); live: ≥1 event row cached + shown on landing page | unit + manual (real Fastmail)                 |
+| SC5 — CAL-08 go/no-go documented                  | CAL-08                  | 01-04 Task 2                                          | Manual spike: app password reads shared + personal collections; `CAL-08-DECISION.md` committed with `Decision: GO                                                                                                         | NO-GO` + fallback                             | manual (decision artifact) |
+| Bonus — Pangolin SSE pass-through                 | D-08 (de-risks Phase 4) | 01-04 Task 1 (endpoint) + Task 3 (smoke)              | `/api/sse/heartbeat` via streamSSE (tsc/grep); live: stream alive 5+ min over public URL, PASS/FAIL recorded                                                                                                              | integration + manual                          |
+
+_Status legend: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky_
+
+---
+
+## Wave 0 Requirements (created in Plan 01 Task 1)
+
+- [ ] `apps/api/vitest.config.ts` — Node-environment vitest config
+- [ ] `apps/api/tests/helpers/db.ts` — Drizzle test-DB fixtures
+- [ ] `apps/api/tests/health.test.ts` — /health 200 (filled Plan 01 Task 2)
+- [ ] `apps/api/tests/auth/user.test.ts` — upsertUser color/identity (filled Plan 02 Task 1)
+- [ ] `apps/api/tests/broker/crypto.test.ts` — AES-GCM roundtrip/IV/tamper (filled Plan 03 Task 1)
+- [ ] `apps/api/tests/broker/sync.test.ts` — all-day DATE split + UID upsert (filled Plan 03 Task 2)
+- [ ] `apps/api/tests/broker/poller.test.ts` — ctag skip detection (filled Plan 03 Task 3)
+- [ ] Fastmail CalDAV fixtures: captured raw VEVENT samples (timed + all-day) for offline parser unit tests
+
+---
+
+## Manual-Only Verifications
+
+| Behavior                                      | Requirement     | Why Manual                                                 | Plan/Task    |
+| --------------------------------------------- | --------------- | ---------------------------------------------------------- | ------------ |
+| Authelia OIDC end-to-end login (both members) | AUTH-01         | Requires real Authelia + Pangolin topology                 | 01-04 Task 3 |
+| Session persistence across restart            | AUTH-02         | Browser-restart behavior not unit-testable                 | 01-04 Task 3 |
+| Real Fastmail event fetch + cache             | CAL-01          | Requires real app password + live calendar                 | 01-04 Task 2 |
+| CAL-08 personal-calendar ACL spike            | CAL-08          | Spike produces a human go/no-go judgement                  | 01-04 Task 2 |
+| Pangolin SSE pass-through smoke test          | D-08            | Idle-timeout behavior only observable over real public URL | 01-04 Task 3 |
+| drizzle-kit push against live MariaDB         | CAL-01 (schema) | Live DB apply; [BLOCKING] gate                             | 01-01 Task 3 |
+
+---
+
+## Validation Sign-Off
+
+- [x] All tasks have an automated verify or a Wave 0 dependency, or are listed under Manual-Only with justification
+- [x] Sampling continuity: no 3 consecutive code tasks without automated verify (each TDD task has a vitest verify; integration tasks have tsc/grep)
+- [x] Wave 0 covers all MISSING references (created in Plan 01 Task 1)
+- [x] No watch-mode flags
+- [x] Feedback latency < 60s
+- [x] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** planner-mapped

.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-VERIFICATION.md

@@ -0,0 +1,203 @@
+---
+phase: 01-foundation-broker-spike
+verified: 2026-06-04T11:45:00Z
+status: human_needed
+score: 10/13 must-haves verified (3 human-pending)
+overrides_applied: 0
+human_verification:
+  - test: 'AUTH-01: Open https://familysync.<domain> from an external network, confirm redirect to Authelia authorize endpoint, log in, land on shell with name + color — no Fastmail credential prompt'
+    expected: 'Browser redirects to Authelia, login succeeds, PWA shell renders member name and color swatch (MemberBadge component)'
+    why_human: 'Requires live Authelia + Pangolin infrastructure not available in this environment; oidcAuthMiddleware only validates at runtime against a real OIDC issuer'
+  - test: 'AUTH-02: Close browser completely after step above, reopen the public URL, confirm no re-login required'
+    expected: 'Session cookie persists; /api/me still returns 200 without re-authenticating; access-token refresh rotation has kept the session alive'
+    why_human: 'Session persistence is enforced by @hono/oidc-auth refresh-token rotation at runtime; cannot verify without real Authelia token endpoint'
+  - test: 'AUTH-03 (cross-member): Log in as the second member (wife) over the same public URL, confirm she receives a visually distinct color from Lucas'
+    expected: "palette[1] (#E8734A warm coral) assigned; both members' MemberBadge components show different colors; identity row for second member present in users table"
+    why_human: 'Requires a second live Authelia account and real browser session; unit tests verify color assignment logic but not end-to-end identity creation for both members'
+  - test: "SSE smoke test (D-08): From external network with a valid session cookie, run 'curl -N https://familysync.<domain>/api/sse/heartbeat' for 5+ minutes, confirm heartbeat events keep arriving"
+    expected: 'Server-sent events arrive every 10 seconds without proxy timeout; stream stays alive through the Pangolin/Newt tunnel for Phase 4 transport decision'
+    why_human: 'Pangolin idle-timeout behavior is network-infrastructure-dependent; only observable over the real tunnel'
+---
+
+# Phase 01: Foundation + Broker Spike — Verification Report
+
+**Phase Goal:** The app stack is running, both members can authenticate through Authelia OIDC, and the CalDAV broker can read Fastmail calendars — with a confirmed go/no-go decision on personal-calendar cross-account sharing.
+**Verified:** 2026-06-04T11:45:00Z
+**Status:** human_needed
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth                                                                                     | Status        | Evidence                                                                                                                                                                                      |
+| --- | ----------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Docker Compose stack starts MariaDB healthy and API serving                               | VERIFIED      | docker-compose.yml has mariadb:11 with healthcheck; api depends_on service_healthy; 01-01-SUMMARY confirms `/health` returned `{"ok":true,"db":"up"}` live                                    |
+| 2   | GET /health returns 200 with real DB round-trip                                           | VERIFIED      | `apps/api/src/routes/health.ts` executes `db.execute(sql'SELECT 1')` before returning `{ok:true,db:"up"}`; health.test.ts 2/2 green                                                           |
+| 3   | Drizzle schema pushed to live MariaDB (4 tables)                                          | VERIFIED      | 01-01-SUMMARY records drizzle-kit push clearing Task 3 checkpoint; all 4 tables listed in SHOW TABLES output                                                                                  |
+| 4   | React PWA fetches /health and renders result                                              | VERIFIED      | `apps/pwa/src/App.tsx` uses `useQuery({queryKey:['health'],queryFn:fetchHealth})` and renders "stack: up/down"                                                                                |
+| 5   | OIDC middleware guards /api/\* and redirects unauthenticated requests (AUTH-01 code path) | VERIFIED      | `apps/api/src/index.ts` line 24: `app.use('/api/*', oidcAuthMiddleware())`; /callback registered before guard; /health before guard                                                           |
+| 6   | upsertUser keyed on oidc_iss + oidc_sub with stable color assignment (AUTH-03)            | VERIFIED      | `apps/api/src/auth/user.ts` SELECT by `and(eq(users.oidcIss,...),eq(users.oidcSub,...))`, never email; COLOR_PALETTE 6 entries; user.test.ts 6/6 green                                        |
+| 7   | GET /api/me returns authenticated member identity + color                                 | VERIFIED      | `apps/api/src/routes/me.ts` calls getAuth → upsertUser → returns `{user:{id,displayName,color}}`; mounted behind oidcAuthMiddleware                                                           |
+| 8   | AES-256-GCM app-password encryption: lossless roundtrip, unique IVs, tamper detection     | VERIFIED      | `apps/api/src/broker/crypto.ts` uses node:crypto aes-256-gcm, 96-bit random IV; crypto.test.ts 5/5 green (roundtrip, IV uniqueness, tamper-throws x2, payload shape)                          |
+| 9   | CalDAV broker reads Fastmail calendars and caches VEVENTs with D-13 all-day DATE handling | VERIFIED      | CAL-08-DECISION.md records live REPORT against Fastmail fetching 503 real events; sync.test.ts 6/6 green confirming timed→dtstart_utc, all-day→dtstart_date, onDuplicateKeyUpdate idempotency |
+| 10  | Broker poller skips DB writes when ctag unchanged                                         | VERIFIED      | `apps/api/src/broker/poller.ts` lines 59-61: skip when `currentCtag !== null && currentCtag === knownCtag`; poller.test.ts 5/5 green                                                          |
+| 11  | CAL-08 go/no-go decision recorded                                                         | VERIFIED      | `CAL-08-DECISION.md` present, committed (0b074cd), contains "Decision: GO" — per-member app-password model proven live; 503 events cached; cross-account ACL concern resolved as moot         |
+| 12  | Both members authenticate live through Authelia over Pangolin (AUTH-01/02)                | HUMAN-PENDING | Code wired (oidcAuthMiddleware, processOAuthCallback, OIDC env vars); live verification requires real Authelia + Pangolin infrastructure                                                      |
+| 13  | Both members have distinct stable colors confirmed in real browser (AUTH-03 cross-member) | HUMAN-PENDING | upsertUser unit-tested for color assignment; live cross-member test requires two real OIDC sessions                                                                                           |
+
+**Score:** 11/13 truths verified (2 human-pending, counted as HUMAN-PENDING not FAILED; see requirements section for SSE smoke test)
+
+---
+
+### Required Artifacts
+
+| Artifact                                                         | Expected                                                       | Status   | Details                                                                                                                                 |
+| ---------------------------------------------------------------- | -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `apps/api/src/db/schema.ts`                                      | 4 mysqlTable defs, D-13 dtstart split, D-10 iss+sub unique key | VERIFIED | All 4 tables; unique('uniq_oidc_identity').on(oidcIss,oidcSub); separate dtstart_utc (timestamp) + dtstart_date (date) + allDay boolean |
+| `apps/api/src/db/client.ts`                                      | drizzle(mysql2 pool) db singleton export                       | VERIFIED | Exports `db = drizzle({client:pool,schema,mode:'default'})`; connectionLimit 10                                                         |
+| `apps/api/src/routes/health.ts`                                  | GET / with real DB round-trip                                  | VERIFIED | SELECT 1 via db.execute; returns 200 or 503; unauthenticated                                                                            |
+| `docker-compose.yml`                                             | api + mariadb:11 (healthcheck) + redis                         | VERIFIED | mariadb healthcheck using healthcheck.sh --connect; api depends_on service_healthy; redis present                                       |
+| `apps/api/src/auth/user.ts`                                      | upsertUser + COLOR_PALETTE                                     | VERIFIED | Exports both; palette 6 entries; SELECT-first idempotent pattern                                                                        |
+| `apps/api/src/auth/middleware.ts`                                | oidcAuthMiddleware re-export                                   | VERIFIED | Re-exports oidcAuthMiddleware, processOAuthCallback, getAuth from @hono/oidc-auth                                                       |
+| `apps/api/src/routes/me.ts`                                      | GET /api/me → {user:{id,displayName,color}}                    | VERIFIED | getAuth → upsertUser → returns user shape; exports meRouter                                                                             |
+| `apps/api/src/broker/crypto.ts`                                  | encryptPassword/decryptPassword (AES-256-GCM)                  | VERIFIED | node:crypto aes-256-gcm, 96-bit IV, JSON {iv,authTag,ciphertext} payload                                                                |
+| `apps/api/src/broker/client.ts`                                  | createFastmailClient → tsdav DAVClient                         | VERIFIED | caldav.fastmail.com, Basic auth, caldav account type                                                                                    |
+| `apps/api/src/broker/sync.ts`                                    | syncCalendar: REPORT → ical.js → upsert                        | VERIFIED | ical.js ICAL.Time.isDate routing, onDuplicateKeyUpdate on calendarId+uid                                                                |
+| `apps/api/src/broker/poller.ts`                                  | startBrokerPoller (node-cron \*/5) + ctag detection            | VERIFIED | schedule('_/5 _ \* \* \*'); ctag skip logic; per-credential try/catch; exports runPoll for tests                                        |
+| `apps/api/src/routes/events.ts`                                  | GET /api/events reads DB cache only                            | VERIFIED | db.select().from(calendarEvents); no tsdav import; exports eventsRouter                                                                 |
+| `apps/api/src/routes/sse.ts`                                     | GET /api/sse/heartbeat (streamSSE)                             | VERIFIED | streamSSE every 10s; exports sseRouter; mounted behind oidcAuthMiddleware                                                               |
+| `apps/api/src/broker/spike.ts`                                   | CAL-08 spike script                                            | VERIFIED | createFastmailClient → fetchCalendars → print URLs; never logs password                                                                 |
+| `.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md` | Decision: GO/NO-GO recorded                                    | VERIFIED | "Decision: GO"; 503 events cached; ctag/syncToken findings recorded                                                                     |
+| `apps/pwa/src/App.tsx`                                           | Renders MemberBadge + EventProof                               | VERIFIED | useQuery(['me']) → MemberBadge; EventProof component rendered                                                                           |
+| `apps/pwa/src/components/EventProof.tsx`                         | Fetches /api/events, renders first event                       | VERIFIED | useQuery(['events'],fetchEvents); renders event SUMMARY + date or empty state                                                           |
+| `apps/api/tests/auth/user.test.ts`                               | 6 passing tests                                                | VERIFIED | 6/6 green (palette[0], palette[1], idempotent, iss+sub identity, full row shape, COLOR_PALETTE validity)                                |
+| `apps/api/tests/broker/crypto.test.ts`                           | 5 passing tests                                                | VERIFIED | 5/5 green                                                                                                                               |
+| `apps/api/tests/broker/sync.test.ts`                             | 6 passing tests                                                | VERIFIED | 6/6 green                                                                                                                               |
+| `apps/api/tests/broker/poller.test.ts`                           | 5 passing tests                                                | VERIFIED | 5/5 green                                                                                                                               |
+| `apps/api/tests/health.test.ts`                                  | 2 passing tests                                                | VERIFIED | 2/2 green                                                                                                                               |
+
+**Artifact total: 22/22 present and substantive.**
+
+---
+
+### Key Link Verification
+
+| From                                     | To                              | Via                                      | Status | Details                                                                          |
+| ---------------------------------------- | ------------------------------- | ---------------------------------------- | ------ | -------------------------------------------------------------------------------- |
+| `apps/api/src/routes/health.ts`          | `apps/api/src/db/client.ts`     | `db.execute()`                           | WIRED  | `import { db } from '../db/client.js'`; execute called in route handler          |
+| `apps/pwa/src/App.tsx`                   | `/health`                       | `fetch('/health')` in fetchHealth        | WIRED  | `fetchHealth` calls `fetch('/health')` inside useQuery                           |
+| `apps/api/src/routes/me.ts`              | `apps/api/src/auth/user.ts`     | `upsertUser(iss, sub, email)`            | WIRED  | `import { upsertUser }` + called in handler body                                 |
+| `apps/api/src/index.ts`                  | `@hono/oidc-auth`               | `oidcAuthMiddleware` on `/api/*`         | WIRED  | `app.use('/api/*', oidcAuthMiddleware())` line 24                                |
+| `apps/pwa/src/App.tsx`                   | `/api/me`                       | React Query via fetchMe                  | WIRED  | `import { fetchMe }` + `useQuery({queryKey:['me'],queryFn:fetchMe})`             |
+| `apps/api/src/broker/poller.ts`          | `apps/api/src/broker/crypto.ts` | `decryptPassword`                        | WIRED  | `import { decryptPassword }` + called before createFastmailClient                |
+| `apps/api/src/broker/sync.ts`            | `apps/api/src/db/client.ts`     | calendarEvents upsert                    | WIRED  | `import { db }` + `db.insert(calendarEvents)...onDuplicateKeyUpdate()`           |
+| `apps/api/src/routes/events.ts`          | `apps/api/src/db/client.ts`     | cache read                               | WIRED  | `import { db }` + `db.select().from(calendarEvents)`                             |
+| `apps/api/src/index.ts`                  | `apps/api/src/broker/poller.ts` | `startBrokerPoller()` on boot            | WIRED  | `import { startBrokerPoller }` + called unconditionally at module level          |
+| `apps/api/src/index.ts`                  | `apps/api/src/routes/events.ts` | `app.route('/api/events', eventsRouter)` | WIRED  | Line 28 in index.ts                                                              |
+| `apps/pwa/src/components/EventProof.tsx` | `/api/events`                   | React Query via fetchEvents              | WIRED  | `import { fetchEvents }` + `useQuery({queryKey:['events'],queryFn:fetchEvents})` |
+
+**All 11 key links WIRED.**
+
+---
+
+### Data-Flow Trace (Level 4)
+
+| Artifact                                  | Data Variable       | Source                                           | Produces Real Data                                                                               | Status  |
+| ----------------------------------------- | ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------- |
+| `apps/pwa/src/App.tsx` (MemberBadge)      | `meQuery.data.user` | `/api/me` → upsertUser → MariaDB `users` table   | Yes — upsertUser does SELECT then INSERT; backed by real DB                                      | FLOWING |
+| `apps/pwa/src/App.tsx` (health indicator) | `healthQuery.data`  | `/health` → db.execute SELECT 1                  | Yes — real DB round-trip                                                                         | FLOWING |
+| `apps/pwa/src/components/EventProof.tsx`  | `events[0]`         | `/api/events` → db.select().from(calendarEvents) | Yes — live Fastmail REPORT cached 503 events into MariaDB (CAL-08-DECISION.md); dev DB populated | FLOWING |
+
+---
+
+### Behavioral Spot-Checks
+
+| Behavior                                       | Command                                                       | Result                                             | Status |
+| ---------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------- | ------ |
+| All 24 unit tests pass                         | `cd apps/api && pnpm vitest run`                              | 24/24 passed, 5 test files                         | PASS   |
+| TypeScript compiles clean (api)                | `cd apps/api && pnpm exec tsc --noEmit`                       | Exit 0, no errors                                  | PASS   |
+| tsdav imported only under broker module        | `grep -rn "import.*tsdav" apps/api/src/`                      | `broker/sync.ts`, `broker/client.ts` only          | PASS   |
+| events route imports no tsdav or broker client | `grep -rn "createFastmailClient\|tsdav" apps/api/src/routes/` | No matches                                         | PASS   |
+| oidcAuthMiddleware mounted on /api/\*          | `grep -n "oidcAuthMiddleware" apps/api/src/index.ts`          | Line 24: `app.use('/api/*', oidcAuthMiddleware())` | PASS   |
+
+---
+
+### Probe Execution
+
+No `scripts/*/tests/probe-*.sh` files declared or found. Task 3 of Plan 01 and Tasks 2+3 of Plan 04 are `checkpoint:human-action` gates that require live infrastructure. These are routed to Human Verification.
+
+---
+
+### Requirements Coverage
+
+| Requirement | Source Plan  | Description                                                                     | Status             | Evidence                                                                                                  |
+| ----------- | ------------ | ------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------- |
+| AUTH-01     | 01-02        | User can log in through Authelia (OIDC SSO)                                     | HUMAN-PENDING      | Code wired: oidcAuthMiddleware on /api/\*, processOAuthCallback on /callback; live Authelia test pending  |
+| AUTH-02     | 01-02        | User stays logged in across sessions                                            | HUMAN-PENDING      | @hono/oidc-auth refresh-token rotation documented in middleware.ts; live session persistence test pending |
+| AUTH-03     | 01-02        | Stable iss+sub identity + consistent per-member color                           | PARTIALLY VERIFIED | Unit-tested fully (6 tests); live cross-member color check pending human verification                     |
+| CAL-01      | 01-01, 01-03 | Broker reads shared Fastmail calendar via CalDAV, caches locally (ctag polling) | VERIFIED           | CAL-08-DECISION.md: 503 real events cached live via REPORT; poller ctag-detection unit tested             |
+| CAL-08      | 01-04        | Personal calendar spike go/no-go                                                | VERIFIED           | CAL-08-DECISION.md: Decision GO; per-member app-password model proven; no fallback needed                 |
+
+---
+
+### Anti-Patterns Found
+
+| File       | Pattern | Severity | Impact |
+| ---------- | ------- | -------- | ------ |
+| None found | —       | —        | —      |
+
+No TBD/FIXME/XXX markers in source files. No `return null` or `return []` stubs in non-test production code. No hardcoded empty values flowing to rendering. No console.log of credentials or encryption key in broker code.
+
+The one notable "pending" marker is in `CAL-08-DECISION.md` history — the initial template had `Decision: [PENDING]` but was overwritten by commit `0b074cd` with the live GO decision. Current state is fully filled.
+
+---
+
+### Human Verification Required
+
+#### 1. AUTH-01 — Authelia OIDC Login (Member 1: Lucas)
+
+**Test:** From an external network (not the Docker host), open `https://familysync.<domain>`. Confirm the browser is redirected to Authelia's authorize endpoint. Log in with Lucas's Authelia credentials. Confirm landing on the PWA shell showing MemberBadge (name + color swatch).
+**Expected:** Successful redirect to Authelia, login completes, PWA renders `MemberBadge` with Lucas's display name and assigned hex color (`#4A90D9` if first user). No separate FamilySync login, no Fastmail credential prompt.
+**Why human:** oidcAuthMiddleware contacts the real OIDC issuer at runtime; OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI, OIDC_AUTH_EXTERNAL_URL must all be set and Authelia must have the client registered (YAML in 01-02-SUMMARY.md).
+
+---
+
+#### 2. AUTH-02 — Session Persistence Across Browser Restart
+
+**Test:** After AUTH-01 passes, close the browser completely (not just the tab). Reopen `https://familysync.<domain>`. Confirm no Authelia login prompt appears — the PWA loads directly to the authenticated shell.
+**Expected:** Session cookie survives browser restart; @hono/oidc-auth refresh-token rotation silently renews the access token; `/api/me` returns 200 without re-authentication.
+**Why human:** Session cookie persistence and refresh-token rotation require live interaction with Authelia's token endpoint over time.
+
+---
+
+#### 3. AUTH-03 — Cross-Member Distinct Color (Member 2: Wife)
+
+**Test:** Log in as the second member (wife) at `https://familysync.<domain>`. Confirm she lands on the PWA shell with a MemberBadge showing a **different** color from Lucas.
+**Expected:** palette[1] (`#E8734A` warm coral) assigned to wife's account; both members' shells display visually distinct color swatches; wife's `users` row is present in MariaDB with a different `color` value.
+**Why human:** Requires a second live Authelia account and a real second browser session to trigger upsertUser for the second member.
+
+---
+
+#### 4. SSE Smoke Test — Pangolin Pass-Through (D-08)
+
+**Test:** From an external network with a valid authenticated session cookie, run: `curl -N -b "session=<cookie>" https://familysync.<domain>/api/sse/heartbeat`. Keep the connection open for 5+ minutes.
+**Expected:** Heartbeat events (`{"ts":"...","id":0}`, `{"ts":"...","id":1}`, ...) arrive every 10 seconds without the stream being cut. Result is PASS (SSE viable for Phase 4 real-time list sync) or FAIL (Pangolin idle-timeout needs configuration).
+**Why human:** Pangolin/Newt proxy idle-timeout behavior is network-infrastructure-dependent and can only be observed over the real tunnel. The sseRouter code is verified; tunnel compatibility is the open question.
+
+---
+
+## Gaps Summary
+
+No gaps (no must-haves are FAILED or MISSING). All code artifacts are present, substantive, and wired. All 24 unit tests pass. TypeScript is clean. The CAL-08 GO decision is recorded from a live run.
+
+The 4 human verification items are classified as HUMAN-PENDING (code implemented, live operator confirmation required), not as failures. This is the expected terminal state for a phase whose Plans 01-04 included `checkpoint:human-action` tasks requiring real Authelia + Pangolin infrastructure that is not available in the dev environment.
+
+The 01-04 SUMMARY explicitly notes "Code-complete. Live verification (CAL-08 spike + Authelia login + Pangolin SSE smoke) pending human action." CAL-08 was subsequently cleared (commit `0b074cd`). AUTH-01/02/03 live tests and SSE smoke remain pending.
+
+---
+
+_Verified: 2026-06-04T11:45:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/milestones/v1.0-phases/01-foundation-broker-spike/CAL-08-DECISION.md

@@ -30,19 +30,19 @@ displayName, ctag, syncToken). It never logs the password.
 
 ### Calendars Discovered
 
-| displayName | URL | ctag returned? | syncToken returned? |
-|-------------|-----|----------------|---------------------|
-| Calendar | `https://caldav.fastmail.com/dav/calendars/user/me@lucasberger.ca/2180A37A-806E-11EB-872C-AE53E9CB9923/` | yes (`1615249618-218118`) | yes (`data:,1615249618-218118`) |
+| displayName  | URL                                                                                                      | ctag returned?            | syncToken returned?             |
+| ------------ | -------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------- |
+| Calendar     | `https://caldav.fastmail.com/dav/calendars/user/me@lucasberger.ca/2180A37A-806E-11EB-872C-AE53E9CB9923/` | yes (`1615249618-218118`) | yes (`data:,1615249618-218118`) |
 | USA Holidays | `https://caldav.fastmail.com/dav/calendars/user/me@lucasberger.ca/2da291bc-7962-4a0e-94bc-7bb135c90d6e/` | yes (`1635037263-211516`) | yes (`data:,1635037263-211516`) |
 
 ### Questions Resolved
 
-| Question | Finding |
-|----------|---------|
-| Does one Fastmail app password see all of that account's calendars? | **Yes** — a single app password (scope "Mail, Contacts & Calendars") enumerated every collection owned by the account via PROPFIND. |
+| Question                                                                             | Finding                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Does one Fastmail app password see all of that account's calendars?                  | **Yes** — a single app password (scope "Mail, Contacts & Calendars") enumerated every collection owned by the account via PROPFIND.                                                                                                          |
 | Does the broker need cross-account ACL sharing to read a member's personal calendar? | **No** — under the locked design (D-09) each member supplies their own app password; the broker stores one encrypted credential per member and aggregates. Cross-account ACL sharing (the original CAL-08 risk) is not on the critical path. |
-| Which change-detection field does Fastmail use — ctag or syncToken? | **Both** are returned. The poller uses ctag as the primary change signal with syncToken available as a fallback (matches the SKELETON poller design). |
-| Can the broker actually fetch + cache real events (CAL-01)? | **Yes** — a live REPORT against the `Calendar` collection fetched and cached **503 events** into `calendar_events`, with correct D-13 handling (timed events → `dtstart_utc` set, `dtstart_date` null, `all_day` false). |
+| Which change-detection field does Fastmail use — ctag or syncToken?                  | **Both** are returned. The poller uses ctag as the primary change signal with syncToken available as a fallback (matches the SKELETON poller design).                                                                                        |
+| Can the broker actually fetch + cache real events (CAL-01)?                          | **Yes** — a live REPORT against the `Calendar` collection fetched and cached **503 events** into `calendar_events`, with correct D-13 handling (timed events → `dtstart_utc` set, `dtstart_date` null, `all_day` false).                     |
 
 ---
 
@@ -53,7 +53,7 @@ displayName, ctag, syncToken). It never logs the password.
 **Rationale:** The personal-calendar read path is proven end-to-end against live Fastmail. A
 single app password reaches every calendar owned by its account, and the broker successfully
 fetched and cached real events (CAL-01). The original CAL-08 worry — whether the broker token
-could see *another member's* personal calendar via Fastmail cross-account share+accept — is
+could see _another member's_ personal calendar via Fastmail cross-account share+accept — is
 moot: the project already locked the **per-member app-password** model (D-09), where each
 member contributes their own credential. That model is validated here. The wife's personal
 calendar is reached the same way (her own app password), onboarded in Phase 2.

.planning/milestones/v1.0-phases/01-foundation-broker-spike/SKELETON.md

@@ -0,0 +1,56 @@
+# Walking Skeleton — FamilySync
+
+**Phase:** 1
+**Generated:** 2026-06-04
+
+## Capability Proven End-to-End
+
+A member reaches the app over the real Pangolin tunnel, authenticates through Authelia (OIDC SSO), and lands on a single screen showing their name, their auto-assigned color, and one real event read from their Fastmail calendar via the CalDAV broker — proving Browser → Hono API → MariaDB cache → Fastmail all work together in the production topology.
+
+## Architectural Decisions
+
+| Decision            | Choice                                                                                                               | Rationale                                                                                                                |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Monorepo            | pnpm workspace, `apps/api` + `apps/pwa`                                                                              | Shared TypeScript, single repo; matches RESEARCH recommended structure                                                   |
+| Backend framework   | Hono 4.12.23 on Node 22 (@hono/node-server)                                                                          | Locked in CLAUDE.md; Web-Standards-native, built-in streamSSE, RPC type sharing                                          |
+| Data layer          | MariaDB 11 + Drizzle ORM 0.45.2 via mysql2 3.22.4                                                                    | Locked stack; no PostgreSQL; type-safe SQL, no binary engine (vs Prisma)                                                 |
+| Schema apply        | `drizzle-kit push` against live MariaDB                                                                              | Greenfield Phase 1; push is the [BLOCKING] gate before verification (Drizzle types come from schema.ts, not the live DB) |
+| Auth                | Authelia OIDC via @hono/oidc-auth 1.8.3 (authorization-code + PKCE S256, client_secret_basic)                        | Authelia already deployed; backend confidential client holds refresh token (D-12), no iframe                             |
+| Identity            | `oidc_iss + oidc_sub` composite key, never email                                                                     | D-10 — email is mutable in Authelia                                                                                      |
+| Member color        | Auto-assigned round-robin from a curated accessible palette, persisted on the user row                               | D-06 — stable across sessions, no settings UI in v1                                                                      |
+| Calendar access     | CalDAV via tsdav 2.2.2; per-member Fastmail app passwords                                                            | D-02/D-09 — JMAP unavailable on Fastmail; per-member app passwords eliminate cross-account ACL risk                      |
+| Credential storage  | AES-256-GCM (node:crypto), key from `APP_PASSWORD_ENCRYPTION_KEY` env, backend-only                                  | D-04 — encrypted at rest, never exposed to frontend                                                                      |
+| Calendar cache      | `calendar_events`: raw VEVENT blob + `dtstart_utc` (timed) / `dtstart_date` (all-day) split; ctag/sync-token polling | D-13 — all-day never coerced to DATETIME (Pitfall 3); cache-first reads                                                  |
+| Background sync     | node-cron 4 every 5 min, ctag change detection                                                                       | RESEARCH poller pattern; sync-token with ctag fallback from day one                                                      |
+| Real-time transport | SSE (`streamSSE`); WebSocket rejected                                                                                | Pangolin WS upgrade known-broken (issue #1034); SSE smoke-tested in Phase 1 to de-risk Phase 4                           |
+| Frontend            | Vite 8 + React 19; TanStack Query (server state) + Zustand (UI state)                                                | Locked stack; React Query owns server data, Zustand UI-only                                                              |
+| Deployment target   | Docker Compose on Unraid, public via Pangolin/Newt tunnel (same parent domain as Authelia)                           | D-07 — validate real OIDC/HTTPS/cookie topology from day one                                                             |
+| Directory layout    | `apps/api/src/{auth,broker,db,routes}`; broker is a hard module boundary                                             | RESEARCH structure; only `broker/` imports tsdav + Fastmail credentials                                                  |
+
+## Stack Touched in Phase 1
+
+- [x] Project scaffold (pnpm workspace, Hono + Vite, tsconfig, Dockerfile, Vitest) — Plan 01
+- [x] Routing — `/health` (public), `/callback`, `/api/me`, `/api/events`, `/api/sse/heartbeat` — Plans 01/02/03/04
+- [x] Database — real read AND write: `/health` round-trip (Plan 01) + broker event cache upsert + `/api/events` read (Plan 03) — schema applied via `drizzle-kit push` (Plan 01)
+- [x] UI — React shell fetches `/health`, `/api/me` (member + color), and `/api/events` (EventProof) — Plans 01/02/04
+- [x] Deployment — full stack through the real Pangolin tunnel; Authelia login + SSE smoke test verified live — Plan 04
+
+## Out of Scope (Deferred to Later Slices)
+
+- Calendar UI / views (day/week/month/agenda) — Phase 2
+- Wife's app password onboarding flow + her credential — Phase 2 (encrypted credential table built now to support it)
+- Event write-back (create/edit/delete) to Fastmail — Phase 3
+- PWA manifest + service worker + guided iOS install — Phase 3
+- Shared lists + live SSE co-edit sync (the SSE _transport_ is only smoke-tested here) — Phase 4
+- Web Push notifications (VAPID) — Phase 5
+- User-pickable color picker (settings UI) — deferred, v1.x
+- Single-occurrence recurring edits — never in v1
+
+## Subsequent Slice Plan
+
+Each later phase adds one vertical slice on top of this skeleton without altering its architectural decisions:
+
+- Phase 2: Unified color-coded read-only calendar (day/week/month/agenda) over the confirmed broker; add wife's credential
+- Phase 3: Event write-back (CRUD) to Fastmail + PWA install (manifest, service worker, guided iOS onboarding)
+- Phase 4: Shared named lists with item CRUD + real-time SSE co-edit sync (uses the SSE transport proven here)
+- Phase 5: VAPID Web Push for event reminders, event changes, and list changes (iOS subscription health-check)

.planning/milestones/v1.0-phases/02-calendar-display/.continue-here.md

@@ -21,6 +21,7 @@ One uncommitted file: `.planning/config.json` (this session's settings changes).
 <completed_work>
 
 This session:
+
 - Phase 2 RESEARCH.md + Nyquist VALIDATION.md written and committed (a707f8d)
 - PATTERNS.md written — 23 files classified, 19 analogs from Phase 1 code (5e14413)
 - 5 PLAN.md files created in 4 waves; plan-checker PASSED iteration 2 (fc4cc2c)
@@ -28,7 +29,7 @@ This session:
 - Backlog item 999.1 added — "treat Fastmail as a calendar provider, support more" (8bd52c6)
 - GSD config changed via /gsd-config: Adaptive profile, TDD on, per-milestone branching,
   auto-advance on; saved as global defaults (~/.gsd/defaults.json). **config.json uncommitted.**
-</completed_work>
+  </completed_work>
 
 <remaining_work>
 
@@ -39,7 +40,7 @@ This session:
     foundation: tokens, colorUtils, calendarConfig, hydrateEvents, Zustand store) — no file overlap
   - Wave 3: 02-04 — CalendarShell renders REAL windowed Fastmail events, color-coded, 4 views
   - Wave 4: 02-05 — EventDetailPopover + ColorLegend + nav/toolbar + skeleton/empty/error + human verify
-</remaining_work>
+    </remaining_work>
 
 <decisions_made>
 
@@ -51,13 +52,14 @@ This session:
 - Shared-family calendar identified via a `calendars.is_shared` column + operator checkpoint
   (chosen over fragile displayName matching).
 - This-session GSD config: Adaptive profile, TDD on, per-milestone branching, auto-advance on.
-</decisions_made>
+  </decisions_made>
 
 <blockers>
 - None. Clean pause between plan and execute.
 </blockers>
 
 ## Required Reading (in order)
+
 1. `.planning/phases/02-calendar-display/02-01-PLAN.md` … `02-05-PLAN.md` — the plans to execute
 2. `.planning/phases/02-calendar-display/02-RESEARCH.md` — DST/VTIMEZONE, Schedule-X Temporal,
    firstDayOfWeek 0→7, has_rrule pre-filter (the landmines)
@@ -65,6 +67,7 @@ This session:
 4. `.planning/phases/02-calendar-display/02-PATTERNS.md` — analog files in the Phase 1 codebase
 
 ## Critical Anti-Patterns (do NOT repeat these)
+
 - Do NOT skip the `[BLOCKING] npx drizzle-kit push` task in Wave 1 (02-01). Build/types pass
   without it because TS types come from config, not the live DB → false-positive verification.
 - Do NOT stamp `String(occ.calendarId)` as the Schedule-X calendarId — use isShared/ownerUserId.
@@ -72,6 +75,7 @@ This session:
   UTC (keep them as 'YYYY-MM-DD' / Temporal.PlainDate).
 
 ## Infrastructure State
+
 - Branch: `main`. git.branching_strategy is now `milestone` — execute may create a milestone branch.
 - Phase 1 shipped: apps/api + apps/pwa, MariaDB via docker-compose. No background processes running.
 - TDD is ON globally now, but Phase 2 plans were written PRE-TDD — they carry no TDD gates.

.planning/milestones/v1.0-phases/02-calendar-display/02-01-PLAN.md

@@ -26,32 +26,32 @@ user_setup: []
 
 must_haves:
   truths:
-    - "Drizzle schema has an indexed hasRrule boolean on calendar_events and an isShared boolean on calendars, both pushed to the live MariaDB"
-    - "PWA test runner (vitest + jsdom + @testing-library/react) executes and a smoke test passes"
-    - "Dev-auth bypass middleware injects a fixed dev user only when DEV_AUTH_BYPASS=true AND NODE_ENV!=production"
-    - "Failing-but-present test stubs exist for expand, events route, hydrateEvents, and calendarConfig (Wave 0 RED state) with concrete behavioral assertions, not bare failing imports"
+    - 'Drizzle schema has an indexed hasRrule boolean on calendar_events and an isShared boolean on calendars, both pushed to the live MariaDB'
+    - 'PWA test runner (vitest + jsdom + @testing-library/react) executes and a smoke test passes'
+    - 'Dev-auth bypass middleware injects a fixed dev user only when DEV_AUTH_BYPASS=true AND NODE_ENV!=production'
+    - 'Failing-but-present test stubs exist for expand, events route, hydrateEvents, and calendarConfig (Wave 0 RED state) with concrete behavioral assertions, not bare failing imports'
   artifacts:
-    - path: "apps/api/src/db/schema.ts"
-      provides: "hasRrule + isShared columns + idx_calendar_events_has_rrule index"
-      contains: "has_rrule"
-    - path: "apps/api/src/auth/devBypass.ts"
-      provides: "devAuthBypass() middleware with hard production guard"
-      exports: ["devAuthBypass"]
-    - path: "apps/pwa/vitest.config.ts"
-      provides: "jsdom-environment vitest config for PWA"
-      contains: "jsdom"
-    - path: "apps/api/tests/fixtures/weekly-dst.ics"
-      provides: "DST-spanning weekly RRULE fixture for CAL-07 tests"
+    - path: 'apps/api/src/db/schema.ts'
+      provides: 'hasRrule + isShared columns + idx_calendar_events_has_rrule index'
+      contains: 'has_rrule'
+    - path: 'apps/api/src/auth/devBypass.ts'
+      provides: 'devAuthBypass() middleware with hard production guard'
+      exports: ['devAuthBypass']
+    - path: 'apps/pwa/vitest.config.ts'
+      provides: 'jsdom-environment vitest config for PWA'
+      contains: 'jsdom'
+    - path: 'apps/api/tests/fixtures/weekly-dst.ics'
+      provides: 'DST-spanning weekly RRULE fixture for CAL-07 tests'
       min_lines: 10
   key_links:
-    - from: "apps/api/src/index.ts"
-      to: "apps/api/src/auth/devBypass.ts"
+    - from: 'apps/api/src/index.ts'
+      to: 'apps/api/src/auth/devBypass.ts'
       via: "app.use('/api/*', devAuthBypass()) before oidcAuthMiddleware"
-      pattern: "devAuthBypass"
-    - from: "apps/pwa/package.json"
-      to: "vitest"
-      via: "test script + devDependencies"
-      pattern: "\"test\".*vitest"
+      pattern: 'devAuthBypass'
+    - from: 'apps/pwa/package.json'
+      to: 'vitest'
+      via: 'test script + devDependencies'
+      pattern: '"test".*vitest'
 ---
 
 <objective>
@@ -113,6 +113,7 @@ RED test stubs with concrete behavioral contracts.
     Create three ICS fixtures under `apps/api/tests/fixtures/`: `weekly-dst.ics` (VEVENT with `DTSTART;TZID=America/New_York:20260301T100000`, `RRULE:FREQ=WEEKLY`, and a full `VTIMEZONE` block for America/New_York with both STANDARD and DAYLIGHT subcomponents so DST rules are present), `allday-birthday.ics` (VEVENT with `DTSTART;VALUE=DATE:20260615`, yearly RRULE, no DTEND), `exdate-series.ics` (weekly VEVENT with one `EXDATE` line removing a single occurrence). These must be valid VCALENDAR strings parseable by ICAL.parse.
 
     Create the four RED test stubs with the CONCRETE behavioral assertions described in <behavior> above — each must encode its real contract (the DST wall-clock assertion in expand.test.ts; the 'shared'/String(ownerUserId) calendarId routing assertion in hydrateEvents.test.ts), not merely a failing import. Each test imports the not-yet-existing module (`../../src/broker/expand.js`, etc.) so the file fails to resolve / the assertion fails — that is the intended RED state. Per the Nyquist rule, mark each `<automated>` for the modules they cover as satisfied here. Use the describe/it patterns from poller.test.ts and health.test.ts. Load fixtures with `readFileSync` relative to the test file. Do NOT implement expand.ts, the route changes, hydrateEvents.ts, or calendarConfig.ts in this task — only the stubs that later plans turn green.
+
   </action>
   <verify>
     <automated>cd apps/api && grep -q "has_rrule" src/db/schema.ts && grep -q "is_shared" src/db/schema.ts && grep -q "idx_calendar_events_has_rrule" src/db/schema.ts && echo SCHEMA_OK</automated>
@@ -156,6 +157,7 @@ RED test stubs with concrete behavioral contracts.
     In `apps/api/src/index.ts`, mount `app.use('/api/*', devAuthBypass())` on the line immediately BEFORE the existing `app.use('/api/*', oidcAuthMiddleware())`. The bypass is a no-op when inactive, so production behavior is unchanged.
 
     Add `DEV_AUTH_BYPASS` to `.env.example` with a comment: `# DEV ONLY — injects a fixed dev user, skips Authelia. Hard-disabled when NODE_ENV=production. NEVER set in prod.` Extend `docs/deployment.md` dev-auth-bypass section to note the NODE_ENV production hard guard and that the production Docker Compose must not set DEV_AUTH_BYPASS.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm test -- tests/auth/devBypass.test.ts</automated>
@@ -197,20 +199,22 @@ RED test stubs with concrete behavioral contracts.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| browser → /api/* | OIDC-gated; dev-auth bypass replaces the gate in dev only |
-| CI/prod env → app config | DEV_AUTH_BYPASS env var could leak into production |
+| Boundary                 | Description                                               |
+| ------------------------ | --------------------------------------------------------- |
+| browser → /api/\*        | OIDC-gated; dev-auth bypass replaces the gate in dev only |
+| CI/prod env → app config | DEV_AUTH_BYPASS env var could leak into production        |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02-01 | Elevation of privilege | devAuthBypass() | mitigate | Hard `NODE_ENV === 'production'` guard as the FIRST conditional, before reading DEV_AUTH_BYPASS; .env.example warning; prod compose must not set the flag (Pitfall 7) |
-| T-02-02 | Tampering | drizzle-kit push | accept | Local dev DB; push reviewed; no untrusted input. Operator runs push against own MariaDB |
-| T-02-SC | Tampering | pnpm installs (vitest, @testing-library/*, jsdom) | mitigate | All packages are mainstream, audited in RESEARCH §Package Legitimacy (Approved); no [ASSUMED]/[SUS] packages in this plan |
+| Threat ID | Category               | Component                                          | Disposition | Mitigation Plan                                                                                                                                                       |
+| --------- | ---------------------- | -------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-02-01   | Elevation of privilege | devAuthBypass()                                    | mitigate    | Hard `NODE_ENV === 'production'` guard as the FIRST conditional, before reading DEV_AUTH_BYPASS; .env.example warning; prod compose must not set the flag (Pitfall 7) |
+| T-02-02   | Tampering              | drizzle-kit push                                   | accept      | Local dev DB; push reviewed; no untrusted input. Operator runs push against own MariaDB                                                                               |
+| T-02-SC   | Tampering              | pnpm installs (vitest, @testing-library/\*, jsdom) | mitigate    | All packages are mainstream, audited in RESEARCH §Package Legitimacy (Approved); no [ASSUMED]/[SUS] packages in this plan                                             |
+
 </threat_model>
 
 <verification>
@@ -221,16 +225,19 @@ RED test stubs with concrete behavioral contracts.
 </verification>
 
 <success_criteria>
+
 - Schema columns added, pushed, and verified against the live DB
 - PWA test runner operational
 - Dev-auth bypass green with production hard guard
 - ICS fixtures parse; RED stubs in place for later waves with concrete DST + calendarId-routing contracts
-</success_criteria>
+  </success_criteria>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 01)
 
 New symbols/files created here (exclude from drift verification):
+
 - `calendar_events.hasRrule` Drizzle column + `idx_calendar_events_has_rrule` index
 - `calendars.isShared` Drizzle column
 - `devAuthBypass` (function) — apps/api/src/auth/devBypass.ts
@@ -240,7 +247,7 @@ New symbols/files created here (exclude from drift verification):
 - apps/api/tests/fixtures/{weekly-dst,allday-birthday,exdate-series}.ics
 - apps/api/tests/broker/expand.test.ts, apps/api/tests/routes/events.test.ts, apps/api/tests/auth/devBypass.test.ts (new test files)
 - apps/pwa/src/lib/hydrateEvents.test.ts, apps/pwa/src/lib/calendarConfig.test.ts (new test files)
-</artifacts_produced>
+  </artifacts_produced>
 
 <output>
 Create `.planning/phases/02-calendar-display/02-01-SUMMARY.md` when done

.planning/milestones/v1.0-phases/02-calendar-display/02-01-SUMMARY.md

@@ -1,17 +1,25 @@
 ---
 phase: 02-calendar-display
-plan: "01"
+plan: '01'
 subsystem: api-schema, api-auth, pwa-test
 tags: [schema-migration, dev-auth, test-harness, ics-fixtures, red-stubs]
 dependency_graph:
   requires: [01-foundation-broker-spike]
-  provides: [calendar_events.hasRrule, calendars.isShared, devAuthBypass, pwa-vitest-jsdom, ics-fixtures, red-test-stubs]
+  provides:
+    [
+      calendar_events.hasRrule,
+      calendars.isShared,
+      devAuthBypass,
+      pwa-vitest-jsdom,
+      ics-fixtures,
+      red-test-stubs,
+    ]
   affects: [02-02, 02-03, 02-04, 02-05]
 tech_stack:
   added:
     - vitest@^4.1.8 (PWA devDependency)
-    - "@testing-library/react@^16.3.0 (PWA devDependency)"
-    - "@testing-library/jest-dom@^6.6.3 (PWA devDependency)"
+    - '@testing-library/react@^16.3.0 (PWA devDependency)'
+    - '@testing-library/jest-dom@^6.6.3 (PWA devDependency)'
     - jsdom@^26.1.0 (PWA devDependency)
   patterns:
     - Drizzle boolean column + index pattern (hasRrule, isShared)
@@ -36,12 +44,12 @@ key_files:
     - .env.example
     - docs/deployment.md
 decisions:
-  - "Applied ALTER TABLE directly instead of drizzle-kit push due to non-TTY interactive prompt — false-positive int(11) vs int type warning on existing rows"
-  - "devAuthBypass evaluates env vars at call time (process start) not request time — intentional so auth mode is fixed for the lifetime of the process"
-  - "RED test stubs reference not-yet-built modules to ensure compile-time failure (concrete RED state), not just assertion failure"
+  - 'Applied ALTER TABLE directly instead of drizzle-kit push due to non-TTY interactive prompt — false-positive int(11) vs int type warning on existing rows'
+  - 'devAuthBypass evaluates env vars at call time (process start) not request time — intentional so auth mode is fixed for the lifetime of the process'
+  - 'RED test stubs reference not-yet-built modules to ensure compile-time failure (concrete RED state), not just assertion failure'
 metrics:
-  duration: "8m 25s"
-  completed: "2026-06-05"
+  duration: '8m 25s'
+  completed: '2026-06-05'
   tasks_completed: 3
   files_created: 10
   files_modified: 5
@@ -56,6 +64,7 @@ Horizontal foundation for Phase 2 calendar slice: two schema columns pushed to l
 ### Schema Changes (Task 1)
 
 Added to `apps/api/src/db/schema.ts`:
+
 - `calendarEvents.hasRrule`: `boolean('has_rrule').default(false).notNull()` — pre-filter flag for recurring event masters (RESEARCH.md §Pitfall 5)
 - `calendarEvents`: new index `idx_calendar_events_has_rrule` matching style of `idx_calendar_events_dtstart_utc`
 - `calendars.isShared`: `boolean('is_shared').default(false).notNull()` — operator-marked shared-family calendar flag
@@ -72,6 +81,7 @@ Both columns pushed to live MariaDB (503-event cache intact). `SHOW COLUMNS` con
 ### ICS Fixtures (Task 1)
 
 Three fixtures created at `apps/api/tests/fixtures/`:
+
 - `weekly-dst.ics`: weekly VEVENT at `DTSTART;TZID=America/New_York:20260301T100000` with full VTIMEZONE block (STANDARD + DAYLIGHT subcomponents for March 2026 EST→EDT transition)
 - `allday-birthday.ics`: `DTSTART;VALUE=DATE:20260615` with `RRULE:FREQ=YEARLY`, no DTEND — pure DATE type
 - `exdate-series.ics`: `RRULE:FREQ=WEEKLY;COUNT=5` with `EXDATE;TZID=America/New_York:20260615T090000` — exactly one occurrence excluded
@@ -83,6 +93,7 @@ All three fixtures parse via `ICAL.parse()` without throwing.
 Four test stubs with concrete behavioral contracts (not bare failing imports):
 
 **expand.test.ts**: Three behavioral contracts —
+
 1. DST wall-clock: every occurrence in March 2026 window has `T10:00:00` in the ISO start string, regardless of EST/EDT offset. Tests both pre-transition (2026-03-01) and post-transition (2026-03-15) occurrences.
 2. All-day: `allDay:true` and `start === '2026-06-15'` (no `T` component)
 3. EXDATE: length === 4 (not 5), June 15 occurrence absent
@@ -98,6 +109,7 @@ All RED stubs fail at import resolution (module not built yet) — correct RED s
 ### Dev-Auth Bypass (Task 2)
 
 Created `apps/api/src/auth/devBypass.ts`:
+
 - Exports `devAuthBypass(): MiddlewareHandler`
 - First conditional is `NODE_ENV === 'production'` — hard guard (T-02-01 mitigation)
 - Returns no-op passthrough when production OR bypass flag unset
@@ -115,6 +127,7 @@ All three devBypass.test.ts cases pass: production guard, unset-flag passthrough
 ### Auto-fixed Issues
 
 **1. [Rule 3 - Blocker] drizzle-kit push replaced with direct ALTER TABLE**
+
 - **Found during:** Task 3
 - **Issue:** `drizzle-kit push` emitted a non-TTY interactive prompt. The "data-loss" warnings were false positives — MariaDB stores int as `int(11)` display width but drizzle-kit 0.31.x sees this as a type change on existing rows. The prompt cannot be auto-confirmed without TTY.
 - **Fix:** Applied the two actual new columns directly via `ALTER TABLE calendar_events ADD COLUMN IF NOT EXISTS has_rrule tinyint(1) NOT NULL DEFAULT 0` and `ALTER TABLE calendars ADD COLUMN IF NOT EXISTS is_shared tinyint(1) NOT NULL DEFAULT 0`, plus the index. Outcome is identical to what drizzle-kit push would have done for the new columns.
@@ -125,6 +138,7 @@ All three devBypass.test.ts cases pass: production guard, unset-flag passthrough
 ## Known Stubs
 
 The following test stubs are intentionally RED (modules not yet built):
+
 - `apps/api/tests/broker/expand.test.ts` — awaits `apps/api/src/broker/expand.ts` (Plan 02)
 - `apps/api/tests/routes/events.test.ts` — awaits evolved `apps/api/src/routes/events.ts` (Plan 02)
 - `apps/pwa/src/lib/hydrateEvents.test.ts` — awaits `apps/pwa/src/lib/hydrateEvents.ts` (Plan 03)
@@ -139,6 +153,7 @@ No new threat surface introduced beyond what is already in the plan's threat mod
 ## Self-Check: PASSED
 
 Files created:
+
 - [x] apps/api/src/auth/devBypass.ts — FOUND
 - [x] apps/pwa/vitest.config.ts — FOUND
 - [x] apps/api/tests/fixtures/weekly-dst.ics — FOUND
@@ -151,10 +166,12 @@ Files created:
 - [x] apps/pwa/src/lib/calendarConfig.test.ts — FOUND
 
 Commits:
+
 - [x] 75252eb — Task 1 feat
 - [x] 8bd44b3 — Task 2 feat
 
 DB state:
+
 - [x] SHOW COLUMNS FROM calendar_events LIKE 'has_rrule' — returns 1 row
 - [x] SHOW COLUMNS FROM calendars LIKE 'is_shared' — returns 1 row
 - [x] 503 events intact

.planning/milestones/v1.0-phases/02-calendar-display/02-02-PLAN.md

@@ -3,7 +3,7 @@ phase: 02-calendar-display
 plan: 02
 type: execute
 wave: 2
-depends_on: ["02-01"]
+depends_on: ['02-01']
 files_modified:
   - apps/api/src/broker/expand.ts
   - apps/api/src/routes/events.ts
@@ -15,27 +15,27 @@ user_setup: []
 
 must_haves:
   truths:
-    - "GET /api/events?start=&end= returns a flat array of concrete occurrences (no recurring masters, no raw VCALENDAR blobs) windowed to the requested date range"
-    - "Each occurrence carries the owner member color (from users.color) or the shared-family rose, plus an isShared flag, an ownerUserId, and the DB calendarId"
-    - "Recurring events are expanded server-side with VTIMEZONE registered before expansion so DST occurrences keep correct wall-clock time"
+    - 'GET /api/events?start=&end= returns a flat array of concrete occurrences (no recurring masters, no raw VCALENDAR blobs) windowed to the requested date range'
+    - 'Each occurrence carries the owner member color (from users.color) or the shared-family rose, plus an isShared flag, an ownerUserId, and the DB calendarId'
+    - 'Recurring events are expanded server-side with VTIMEZONE registered before expansion so DST occurrences keep correct wall-clock time'
     - "All-day occurrences are returned with allDay:true and a 'YYYY-MM-DD' start (no timezone shift) — single local timezone for v1 (D-10)"
-    - "EXDATE-excluded occurrences are omitted from the expansion"
-    - "Invalid or missing start/end query params are rejected (zod) before any SQL runs; window capped at 90 days"
+    - 'EXDATE-excluded occurrences are omitted from the expansion'
+    - 'Invalid or missing start/end query params are rejected (zod) before any SQL runs; window capped at 90 days'
   artifacts:
-    - path: "apps/api/src/broker/expand.ts"
-      provides: "expandOccurrences() — ICAL.RecurExpansion + VTIMEZONE registration + allDay split → CalendarOccurrence[]"
-      exports: ["expandOccurrences", "CalendarOccurrence"]
-    - path: "apps/api/src/routes/events.ts"
-      provides: "windowed /api/events with calendarEvents→calendars→users join, hasRrule pre-filter, zod validation"
-      contains: "zValidator"
+    - path: 'apps/api/src/broker/expand.ts'
+      provides: 'expandOccurrences() — ICAL.RecurExpansion + VTIMEZONE registration + allDay split → CalendarOccurrence[]'
+      exports: ['expandOccurrences', 'CalendarOccurrence']
+    - path: 'apps/api/src/routes/events.ts'
+      provides: 'windowed /api/events with calendarEvents→calendars→users join, hasRrule pre-filter, zod validation'
+      contains: 'zValidator'
   key_links:
-    - from: "apps/api/src/routes/events.ts"
-      to: "apps/api/src/broker/expand.ts"
-      via: "expandOccurrences() called per recurring/timed row"
-      pattern: "expandOccurrences"
-    - from: "apps/api/src/routes/events.ts"
-      to: "users.color"
-      via: "innerJoin calendars→users, select color + isShared + users.id"
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'apps/api/src/broker/expand.ts'
+      via: 'expandOccurrences() called per recurring/timed row'
+      pattern: 'expandOccurrences'
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'users.color'
+      via: 'innerJoin calendars→users, select color + isShared + users.id'
       pattern: "users\\.color"
 ---
 
@@ -102,6 +102,7 @@ shared-family calendar (open question A3) — the operator marks it.
     7. Use rrule ONLY as a fallback if ICAL.RecurExpansion cannot parse a given RRULE — do not import it on the primary path (D-09).
 
     Turn the Plan 01 RED expand.test.ts stub green against the three fixtures.
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm test -- tests/broker/expand.test.ts</automated>
@@ -145,6 +146,7 @@ shared-family calendar (open question A3) — the operator marks it.
     For each row, derive `color = row.isShared ? '#F25C7A' : row.userColor` and `isShared = row.isShared`, then call `expandOccurrences(row.rawVevent, windowStartDate, windowEndDate, { calendarId, calendarName: row.displayName, ownerUserId: row.userId, color, isShared })`. The `ownerUserId: row.userId` field is load-bearing — the client routes calendar color by it. Flatten all results into one array. Wrap the DB+expansion body in try/catch returning 503 on DB error (health.ts pattern). Return `c.json({ occurrences })`.
 
     Turn the Plan 01 RED events.test.ts stub green (mock db.select chain following the health.test.ts vi.mock pattern; assert color field, isShared, ownerUserId, and 400 on bad params).
+
   </action>
   <verify>
     <automated>cd apps/api && pnpm test -- tests/routes/events.test.ts</automated>
@@ -184,21 +186,23 @@ shared-family calendar (open question A3) — the operator marks it.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| browser → /api/events | start/end query params are untrusted input crossing into SQL |
-| cached VEVENT → expansion | rawVevent originates from Fastmail; parsed by ical.js |
+| Boundary                  | Description                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| browser → /api/events     | start/end query params are untrusted input crossing into SQL |
+| cached VEVENT → expansion | rawVevent originates from Fastmail; parsed by ical.js        |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02b-01 | Tampering | start/end query params | mitigate | zod ISO-date regex validation before SQL; Drizzle parameterized queries (no string interpolation) |
-| T-02b-02 | Denial of service | unwindowed/overwide fetch | mitigate | start+end required (zod); window hard-capped at 90 days; hasRrule index prevents full-table scan |
-| T-02b-03 | Information disclosure | cross-account calendar leakage | mitigate | Route is behind oidcAuthMiddleware (Phase 1); each member's own credential fetched their own collections; no other-account ACL path exists (CAL-08-DECISION) |
-| T-02b-04 | Tampering | malformed rawVevent | accept | expandOccurrences try/catch returns [] on parse failure; matches sync.ts resilience; no crash |
+| Threat ID | Category               | Component                      | Disposition | Mitigation Plan                                                                                                                                              |
+| --------- | ---------------------- | ------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| T-02b-01  | Tampering              | start/end query params         | mitigate    | zod ISO-date regex validation before SQL; Drizzle parameterized queries (no string interpolation)                                                            |
+| T-02b-02  | Denial of service      | unwindowed/overwide fetch      | mitigate    | start+end required (zod); window hard-capped at 90 days; hasRrule index prevents full-table scan                                                             |
+| T-02b-03  | Information disclosure | cross-account calendar leakage | mitigate    | Route is behind oidcAuthMiddleware (Phase 1); each member's own credential fetched their own collections; no other-account ACL path exists (CAL-08-DECISION) |
+| T-02b-04  | Tampering              | malformed rawVevent            | accept      | expandOccurrences try/catch returns [] on parse failure; matches sync.ts resilience; no crash                                                                |
+
 </threat_model>
 
 <verification>
@@ -208,20 +212,22 @@ shared-family calendar (open question A3) — the operator marks it.
 </verification>
 
 <success_criteria>
+
 - /api/events returns windowed, color-tagged, DST-correct, all-day-safe, EXDATE-aware occurrences
 - Each occurrence carries ownerUserId + isShared for client-side color routing
 - Bad/oversized windows rejected with 400
 - Shared-family calendar marked and verified end-to-end
-</success_criteria>
+  </success_criteria>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 02)
 
 - `expandOccurrences` (function) + `CalendarOccurrence` (interface) — apps/api/src/broker/expand.ts
 - Evolved `eventsRouter` GET / handler with `{ occurrences }` response shape — apps/api/src/routes/events.ts
 - `eventsQuerySchema` (zod) for start/end validation
 - New JSON contract field set: id, uid, calendarId, calendarName, ownerUserId, color, isShared, title, start, end, allDay, location, description
-</artifacts_produced>
+  </artifacts_produced>
 
 <output>
 Create `.planning/phases/02-calendar-display/02-02-SUMMARY.md` when done

.planning/milestones/v1.0-phases/02-calendar-display/02-02-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 02-calendar-display
-plan: "02"
+plan: '02'
 subsystem: api-expansion, api-events
 tags: [recurrence-expansion, dst-correctness, windowed-query, color-join, zod-validation]
 dependency_graph:
@@ -22,12 +22,12 @@ key_files:
     - apps/api/src/routes/events.ts
     - apps/api/tests/routes/events.test.ts
 decisions:
-  - "ICAL.TimezoneService.register(timezone, name) arg order: first arg is Timezone object, second is optional name string — inverted from research pseudocode which incorrectly placed tzid first"
-  - "events.test.ts needed @hono/oidc-auth mock — oidcAuthMiddleware throws HTTP 500 when OIDC env vars are absent, blocking all route tests; added passthrough mock as Rule 3 fix"
-  - "Task 3 (shared-family calendar marking) deferred by operator: id=1 is the operator personal calendar, dedicated shared Family calendar does not exist yet — is_shared stays false for all current rows"
+  - 'ICAL.TimezoneService.register(timezone, name) arg order: first arg is Timezone object, second is optional name string — inverted from research pseudocode which incorrectly placed tzid first'
+  - 'events.test.ts needed @hono/oidc-auth mock — oidcAuthMiddleware throws HTTP 500 when OIDC env vars are absent, blocking all route tests; added passthrough mock as Rule 3 fix'
+  - 'Task 3 (shared-family calendar marking) deferred by operator: id=1 is the operator personal calendar, dedicated shared Family calendar does not exist yet — is_shared stays false for all current rows'
 metrics:
-  duration: "22m"
-  completed: "2026-06-05"
+  duration: '22m'
+  completed: '2026-06-05'
   tasks_completed: 2
   tasks_deferred: 1
   files_created: 1
@@ -45,6 +45,7 @@ Server-side recurrence expansion with DST-correct VTIMEZONE registration, all-da
 New file exporting `CalendarOccurrence` interface and `expandOccurrences()` function.
 
 **Interface `CalendarOccurrence`** — carries all fields the Schedule-X frontend needs:
+
 - `id`: `${uid}::${startIso}` stable identity
 - `ownerUserId`: load-bearing client field; Schedule-X calendarId = `isShared ? 'shared' : String(ownerUserId)`
 - `isShared`: from calendar row, stamped on every occurrence from meta
@@ -52,6 +53,7 @@ New file exporting `CalendarOccurrence` interface and `expandOccurrences()` func
 - `allDay`, `color`, `calendarId`, `calendarName`, `uid`, `title`, `location`, `description`
 
 **Implementation contracts met:**
+
 1. `ICAL.parse()` in try/catch — malformed input returns `[]` without throwing
 2. VTIMEZONE registration loop runs before `new ICAL.RecurExpansion(...)` — mandatory for DST correctness (Pitfall 3)
 3. Non-recurring: single occurrence check against [windowStart, windowEnd)
@@ -61,6 +63,7 @@ New file exporting `CalendarOccurrence` interface and `expandOccurrences()` func
 7. No `import ... 'rrule'` anywhere in expand.ts
 
 **Test results (expand.test.ts — 3/3 green):**
+
 - DST: `T10:00:00` present in every March 2026 occurrence across EST→EDT boundary
 - All-day: `allDay:true`, `start === '2026-06-15'`, no `T` in string
 - EXDATE: 4 occurrences returned (not 5), June 15 absent
@@ -70,6 +73,7 @@ New file exporting `CalendarOccurrence` interface and `expandOccurrences()` func
 Rewrote `eventsRouter.get('/')` from raw table dump to display-ready windowed endpoint.
 
 **Zod validation:**
+
 - `eventsQuerySchema`: `start` and `end` each required, validated as `/^\d{4}-\d{2}-\d{2}$/`
 - `zValidator('query', eventsQuerySchema)` — 400 returned automatically on schema failure
 - Post-schema: 90-day window cap returns 400 if span exceeds limit (T-02b-02 DoS guard)
@@ -79,6 +83,7 @@ Rewrote `eventsRouter.get('/')` from raw table dump to display-ready windowed en
 
 **WHERE pre-filter (RESEARCH.md Open Q3 / Pitfall 5):**
 Three-branch OR covering:
+
 1. `hasRrule=1 AND dtstartUtc < windowEnd` — recurring masters from any date
 2. `hasRrule=0 AND dtstartUtc IN [windowStart, windowEnd)` — non-recurring timed events
 3. `dtstartDate IN [start, end)` — all-day events (DATE comparison)
@@ -92,6 +97,7 @@ Three-branch OR covering:
 **Broker-boundary invariant preserved:** No tsdav / createFastmailClient import.
 
 **Test results (events.test.ts — 4/4 green):**
+
 - 400 on missing start
 - 400 on missing end
 - 400 on malformed date
@@ -114,12 +120,14 @@ The `calendars.is_shared` column exists (added in Plan 01, default false). The r
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] ICAL.TimezoneService.register() argument order**
+
 - **Found during:** Task 1 typecheck
 - **Issue:** Research pseudocode showed `register(tzid, timezone)` but the actual API is `register(timezone, name?)` — tzid-first call causes TS2345 type error
 - **Fix:** Swapped to `register(new ICAL.Timezone({ component: vtz, tzid }), tzid)`
 - **Files modified:** apps/api/src/broker/expand.ts
 
 **2. [Rule 3 - Blocker] @hono/oidc-auth throws 500 in test environment**
+
 - **Found during:** Task 2 (events test execution)
 - **Issue:** `oidcAuthMiddleware()` calls `throw new HTTPException(500, ...)` when `OIDC_AUTH_SECRET` env var is absent. The RED stub's test imports `app` from `src/index.js` which mounts `oidcAuthMiddleware`, so all `/api/events` requests get 500 before reaching the route handler.
 - **Fix:** Added `vi.mock('@hono/oidc-auth', ...)` passthrough mock to events.test.ts, making `oidcAuthMiddleware` a no-op in the test environment. Same pattern works for future route tests that use app.request().
@@ -141,16 +149,20 @@ No new threat surface beyond the plan's threat model.
 ## Self-Check: PASSED
 
 Files created:
+
 - [x] apps/api/src/broker/expand.ts — FOUND
 
 Files modified:
+
 - [x] apps/api/src/routes/events.ts — FOUND
 - [x] apps/api/tests/routes/events.test.ts — FOUND
 
 Commits:
+
 - [x] 6736194 — feat(02-02): expandOccurrences Task 1
 - [x] 9ee26c0 — feat(02-02): windowed events route Task 2
 
 Test suite:
+
 - [x] pnpm --filter @familysync/api test — 34/34 passed
 - [x] pnpm --filter @familysync/api typecheck — clean

.planning/milestones/v1.0-phases/02-calendar-display/02-03-PLAN.md

@@ -3,7 +3,7 @@ phase: 02-calendar-display
 plan: 03
 type: execute
 wave: 2
-depends_on: ["02-01"]
+depends_on: ['02-01']
 files_modified:
   - apps/pwa/src/styles/tokens.css
   - apps/pwa/src/styles/tokens.ts
@@ -24,40 +24,40 @@ user_setup: []
 
 must_haves:
   truths:
-    - "A CSS custom-property token layer (the clean theme) defines all colors, spacing, typography, breakpoints from UI-SPEC; no hard-coded hex/px will be needed by components — tuned to stay legible/informational at tablet distance, not ultra-minimal (D-03)"
-    - "Schedule-X --sx-color-* vars are mapped to project tokens so no Schedule-X default colors bleed through"
-    - "colorUtils derives Schedule-X lightColors (main/container/onContainer) from a member hex"
+    - 'A CSS custom-property token layer (the clean theme) defines all colors, spacing, typography, breakpoints from UI-SPEC; no hard-coded hex/px will be needed by components — tuned to stay legible/informational at tablet distance, not ultra-minimal (D-03)'
+    - 'Schedule-X --sx-color-* vars are mapped to project tokens so no Schedule-X default colors bleed through'
+    - 'colorUtils derives Schedule-X lightColors (main/container/onContainer) from a member hex'
     - "calendarConfig translates WEEK_START_DAY=0 (Sunday/JS) to Schedule-X firstDayOfWeek=7 (Temporal Sunday) and builds the per-calendar config keyed by String(userId) + 'shared'"
-    - "hydrateEvents converts all-day occurrences to Temporal.PlainDate and timed occurrences to Temporal.ZonedDateTime"
+    - 'hydrateEvents converts all-day occurrences to Temporal.PlainDate and timed occurrences to Temporal.ZonedDateTime'
     - "hydrateEvents routes each event's Schedule-X calendarId to 'shared' (isShared) or String(ownerUserId), matching the userId-keyed calendars config — never String(calendarId)"
-    - "calendarStore (Zustand) holds selectedView (persisted per breakpoint group), selectedDate, openEventId, calendarRange — no server data"
-    - "fetchEvents(start,end) calls the windowed /api/events with credentials:include and returns OccurrencesResponse"
+    - 'calendarStore (Zustand) holds selectedView (persisted per breakpoint group), selectedDate, openEventId, calendarRange — no server data'
+    - 'fetchEvents(start,end) calls the windowed /api/events with credentials:include and returns OccurrencesResponse'
   artifacts:
-    - path: "apps/pwa/src/styles/tokens.css"
-      provides: "clean-theme CSS custom properties + Schedule-X var overrides"
-      contains: "--color-shared-family"
-    - path: "apps/pwa/src/lib/calendarConfig.ts"
-      provides: "WEEK_START_DAY, firstDayOfWeek translation, buildCalendarConfig()"
-      exports: ["WEEK_START_DAY", "buildCalendarConfig"]
-    - path: "apps/pwa/src/lib/hydrateEvents.ts"
-      provides: "hydrateEvents() ISO→Temporal with all-day PlainDate guard + isShared/ownerUserId calendarId routing"
-      exports: ["hydrateEvents"]
-    - path: "apps/pwa/src/store/calendarStore.ts"
-      provides: "Zustand UI-state store with localStorage view persistence"
-      exports: ["useCalendarStore"]
+    - path: 'apps/pwa/src/styles/tokens.css'
+      provides: 'clean-theme CSS custom properties + Schedule-X var overrides'
+      contains: '--color-shared-family'
+    - path: 'apps/pwa/src/lib/calendarConfig.ts'
+      provides: 'WEEK_START_DAY, firstDayOfWeek translation, buildCalendarConfig()'
+      exports: ['WEEK_START_DAY', 'buildCalendarConfig']
+    - path: 'apps/pwa/src/lib/hydrateEvents.ts'
+      provides: 'hydrateEvents() ISO→Temporal with all-day PlainDate guard + isShared/ownerUserId calendarId routing'
+      exports: ['hydrateEvents']
+    - path: 'apps/pwa/src/store/calendarStore.ts'
+      provides: 'Zustand UI-state store with localStorage view persistence'
+      exports: ['useCalendarStore']
   key_links:
-    - from: "apps/pwa/src/main.tsx"
-      to: "temporal-polyfill/global"
-      via: "import before any Schedule-X mount"
-      pattern: "temporal-polyfill/global"
-    - from: "apps/pwa/src/lib/calendarConfig.ts"
-      to: "apps/pwa/src/lib/colorUtils.ts"
-      via: "deriveScheduleXColors() for lightColors"
-      pattern: "deriveScheduleXColors"
-    - from: "apps/pwa/src/lib/hydrateEvents.ts"
-      to: "apps/pwa/src/lib/calendarConfig.ts"
+    - from: 'apps/pwa/src/main.tsx'
+      to: 'temporal-polyfill/global'
+      via: 'import before any Schedule-X mount'
+      pattern: 'temporal-polyfill/global'
+    - from: 'apps/pwa/src/lib/calendarConfig.ts'
+      to: 'apps/pwa/src/lib/colorUtils.ts'
+      via: 'deriveScheduleXColors() for lightColors'
+      pattern: 'deriveScheduleXColors'
+    - from: 'apps/pwa/src/lib/hydrateEvents.ts'
+      to: 'apps/pwa/src/lib/calendarConfig.ts'
       via: "calendarId = isShared ? 'shared' : String(ownerUserId) matches buildCalendarConfig keys"
-      pattern: "ownerUserId"
+      pattern: 'ownerUserId'
 ---
 
 <objective>
@@ -109,6 +109,7 @@ windowed fetchEvents, updated main.tsx, Schedule-X deps installed.
     Create `apps/pwa/src/styles/index.css` importing tokens.css, plus a minimal global reset (box-sizing border-box, body font-family var, margin 0) — no third-party reset library.
 
     Update `apps/pwa/src/main.tsx`: as the FIRST three imports (before React), add `import 'temporal-polyfill/global'`, `import '@schedule-x/theme-default/dist/index.css'`, `import './styles/index.css'` (in that order — Temporal must register before any Schedule-X usage, and token overrides must come after the Schedule-X default CSS so they win). Leave the QueryClientProvider tree intact.
+
   </action>
   <verify>
     <automated>cd apps/pwa && grep -q "temporal-polyfill/global" src/main.tsx && grep -q "@schedule-x/theme-default/dist/index.css" src/main.tsx && grep -q "./styles/index.css" src/main.tsx && echo MAIN_IMPORTS_OK</automated>
@@ -143,6 +144,7 @@ windowed fetchEvents, updated main.tsx, Schedule-X deps installed.
     Create `apps/pwa/src/lib/colorUtils.ts` exporting `hexToContainer(hex)` (main at 15% opacity blended over #FFFFFF → returns a hex/rgb string), `hexToOnContainer(hex)` (main darkened 40%), and `deriveScheduleXColors(main)` returning `{ main, container, onContainer }`. Implement the math inline (no third-party color lib per RESEARCH Don't-Hand-Roll note — it's simple enough). Write colorUtils.test.ts asserting the derivations for a known hex.
 
     Create `apps/pwa/src/lib/calendarConfig.ts` exporting `export const WEEK_START_DAY = 0` with the inline comment that Schedule-X uses 7=Sunday, a translation `const sxFirstDay = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY` exposed as an exported `SX_FIRST_DAY_OF_WEEK`, the view factory list (`createViewDay`, `createViewWeek`, `createViewMonthGrid`, `createViewMonthAgenda` from @schedule-x/calendar), and `buildCalendarConfig(members: MemberCalendarConfig[])` returning `{ calendars }` keyed by String(userId) plus a reserved `'shared'` entry using deriveScheduleXColors('#F25C7A'). Per-member entries use deriveScheduleXColors(member.color). The `String(userId)` + `'shared'` key scheme here is the routing contract hydrateEvents (Task 3) must match — keep them aligned. Limit usage to the confirmed Schedule-X API surface (Pitfall 6). Turn the Plan 01 RED calendarConfig.test.ts green (it asserts the 0→7 translation).
+
   </action>
   <verify>
     <automated>cd apps/pwa && pnpm test -- src/lib/colorUtils.test.ts src/lib/calendarConfig.test.ts</automated>
@@ -187,6 +189,7 @@ windowed fetchEvents, updated main.tsx, Schedule-X deps installed.
     Create `apps/pwa/src/store/calendarStore.ts` exporting `useCalendarStore` (Zustand `create`) with state: `selectedView:string`, `selectedDate:string`, `openEventId:string|null`, `calendarRange:{start:string;end:string}` and setters. selectedView is initialized from localStorage keyed by breakpoint group (`window.matchMedia('(max-width:767px)').matches ? 'phone' : 'tablet-desktop'`), defaulting to 'month-agenda' on phone / 'month-grid' on tablet-desktop (D-05); setSelectedView writes back to localStorage under `calendarView.{group}`. calendarRange defaults to the current month ± 1 week (do NOT depend on Schedule-X onRangeUpdate for the first fetch — A4/Open Q2). Server events NEVER enter this store. Add `zustand` to apps/pwa deps if not already present.
 
     In `apps/pwa/src/api/client.ts`, REPLACE the old unwindowed `fetchEvents()` and its `CalendarEvent`/`EventsResponse` types with: `CalendarOccurrence` interface (mirror the server contract — include calendarId, ownerUserId, isShared so hydrateEvents can route), `OccurrencesResponse { occurrences: CalendarOccurrence[] }`, and `fetchEvents(start:string, end:string): Promise<OccurrencesResponse>` calling `/api/events?start=${start}&end=${end}` with `credentials:'include'` and the same `if(!res.ok) throw` pattern as fetchMe. Note: EventProof.tsx referenced the old fetchEvents — leave EventProof for Plan 05 to remove; if the type change breaks its build, update EventProof minimally to compile (it is replaced in Plan 05).
+
   </action>
   <verify>
     <automated>cd apps/pwa && pnpm test -- src/lib/hydrateEvents.test.ts</automated>
@@ -207,20 +210,22 @@ windowed fetchEvents, updated main.tsx, Schedule-X deps installed.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| localStorage → store init | persisted view string read at startup |
+| Boundary                    | Description                                     |
+| --------------------------- | ----------------------------------------------- |
+| localStorage → store init   | persisted view string read at startup           |
 | server JSON → hydrateEvents | occurrence strings parsed into Temporal objects |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02c-01 | Tampering | localStorage selectedView | accept | UI-only state; an invalid stored view falls back to the D-05 default; no security impact (single-device, two-person app) |
-| T-02c-02 | Tampering | hydrateEvents string parsing | accept | Temporal.from throws on malformed input surfaced as a React Query error, not a security boundary; data already passed server zod validation |
-| T-02c-SC | Tampering | @schedule-x/*, temporal-polyfill, lucide-react, zustand installs | mitigate | All Approved in RESEARCH §Package Legitimacy (mainstream, no postinstall); pinned versions; no [ASSUMED]/[SUS] |
+| Threat ID | Category  | Component                                                         | Disposition | Mitigation Plan                                                                                                                             |
+| --------- | --------- | ----------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-02c-01  | Tampering | localStorage selectedView                                         | accept      | UI-only state; an invalid stored view falls back to the D-05 default; no security impact (single-device, two-person app)                    |
+| T-02c-02  | Tampering | hydrateEvents string parsing                                      | accept      | Temporal.from throws on malformed input surfaced as a React Query error, not a security boundary; data already passed server zod validation |
+| T-02c-SC  | Tampering | @schedule-x/\*, temporal-polyfill, lucide-react, zustand installs | mitigate    | All Approved in RESEARCH §Package Legitimacy (mainstream, no postinstall); pinned versions; no [ASSUMED]/[SUS]                              |
+
 </threat_model>
 
 <verification>
@@ -230,26 +235,28 @@ windowed fetchEvents, updated main.tsx, Schedule-X deps installed.
 </verification>
 
 <success_criteria>
+
 - Clean-theme token layer + Schedule-X overrides present (D-01/D-02)
 - firstDayOfWeek 0→7 translation encoded; per-calendar config built from member colors
 - All-day Temporal PlainDate guard in place
 - hydrateEvents calendarId routes by isShared/ownerUserId to match buildCalendarConfig keys
 - Zustand UI store + windowed fetchEvents ready for Plan 04
-</success_criteria>
+  </success_criteria>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 03)
 
-- CSS custom properties: --color-*, --space-*, --text-*, --font-family-base, --bp-*, --sx-color-* overrides (tokens.css)
+- CSS custom properties: --color-_, --space-_, --text-_, --font-family-base, --bp-_, --sx-color-\* overrides (tokens.css)
 - token object export (tokens.ts); styles/index.css global reset
 - `hexToContainer`, `hexToOnContainer`, `deriveScheduleXColors` (colorUtils.ts)
 - `WEEK_START_DAY`, `SX_FIRST_DAY_OF_WEEK`, `buildCalendarConfig`, `MemberCalendarConfig` (calendarConfig.ts)
 - `hydrateEvents`, `ScheduleXEvent` (hydrateEvents.ts) — calendarId routed by isShared/ownerUserId
 - `useCalendarStore` Zustand store + CalendarStore state shape (calendarStore.ts)
 - `fetchEvents(start,end)`, `CalendarOccurrence`, `OccurrencesResponse` (client.ts — replaces old unwindowed versions)
-- @schedule-x/* + temporal-polyfill + lucide-react + zustand dependencies
+- @schedule-x/\* + temporal-polyfill + lucide-react + zustand dependencies
 - main.tsx Temporal-polyfill-first import block
-</artifacts_produced>
+  </artifacts_produced>
 
 <output>
 Create `.planning/phases/02-calendar-display/02-03-SUMMARY.md` when done

.planning/milestones/v1.0-phases/02-calendar-display/02-03-SUMMARY.md

@@ -66,11 +66,13 @@ CSS custom-property token layer with Schedule-X overrides, hex-blend color utili
 ### Task 1: Schedule-X Stack + Token Layer + main.tsx Import Order
 
 **Installed packages** in `apps/pwa`:
+
 - `@schedule-x/calendar@4.6.0`, `@schedule-x/react@4.1.0`, `@schedule-x/theme-default@4.6.0`
 - `@schedule-x/event-modal@4.6.0`, `@schedule-x/events-service@4.6.0`
 - `temporal-polyfill@0.3.2`, `lucide-react@1.17.0`
 
 **`apps/pwa/src/styles/tokens.css`** — CSS custom properties declaring:
+
 - Surface/border/text palette: `--color-surface`, `--color-surface-dim`, `--color-surface-raised`, `--color-border`, `--color-border-subtle`, `--color-text-primary/secondary/muted`, `--color-focus-ring`, `--color-overlay`
 - Calendar colors: `--color-member-0..5` + `--color-shared-family: #F25C7A` + `--color-destructive`
 - Spacing scale: `--space-1..12` (multiples of 4px)
@@ -84,6 +86,7 @@ CSS custom-property token layer with Schedule-X overrides, hex-blend color utili
 **`apps/pwa/src/styles/index.css`** — imports tokens.css + minimal global reset.
 
 **`apps/pwa/src/main.tsx`** — updated with load-bearing import order:
+
 1. `import 'temporal-polyfill/global'` (must be first)
 2. `import '@schedule-x/theme-default/dist/index.css'` (SX layout CSS)
 3. `import './styles/index.css'` (token overrides win cascade)
@@ -91,11 +94,13 @@ CSS custom-property token layer with Schedule-X overrides, hex-blend color utili
 ### Task 2: colorUtils + calendarConfig — RED Stubs Turned GREEN
 
 **`apps/pwa/src/lib/colorUtils.ts`** exports:
+
 - `hexToContainer(hex)` — alpha blends at 15% opacity over white
 - `hexToOnContainer(hex)` — darkens 40% (channel multiply by 0.6)
 - `deriveScheduleXColors(main)` returning `{ main, container, onContainer }`
 
 **`apps/pwa/src/lib/calendarConfig.ts`** exports:
+
 - `WEEK_START_DAY = 0` (JS Sunday convention)
 - `SX_FIRST_DAY_OF_WEEK = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY`
 - `buildCalendarConfig(members)` returning `{ firstDayOfWeek: 7, calendars }` with `'shared'` (rose) + per-member entries keyed by `String(userId)`
@@ -105,6 +110,7 @@ CSS custom-property token layer with Schedule-X overrides, hex-blend color utili
 ### Task 3: hydrateEvents + calendarStore + windowed fetchEvents — RED Stubs Turned GREEN
 
 **`apps/pwa/src/lib/hydrateEvents.ts`**:
+
 - `allDay:true` uses `Temporal.PlainDate.from(occ.start)` (guards all-day date shift)
 - `allDay:false` uses `Temporal.ZonedDateTime.from(occ.start/end)`
 - `calendarId = occ.isShared ? 'shared' : String(occ.ownerUserId)` — never `String(occ.calendarId)`
@@ -113,11 +119,13 @@ CSS custom-property token layer with Schedule-X overrides, hex-blend color utili
 `hydrateEvents.test.ts` (Plan 01 RED stubs) — all 4 assertions now GREEN.
 
 **`apps/pwa/src/store/calendarStore.ts`** Zustand store:
+
 - `selectedView` — from localStorage per breakpoint group; D-05 defaults
 - `calendarRange` — month ± 7-day buffer for initial TanStack Query key
 - `openEventId`, `selectedDate` — UI-only, not persisted
 
 **`apps/pwa/src/api/client.ts`**:
+
 - Added `CalendarOccurrence`, `OccurrencesResponse`, `fetchEvents(start, end)`
 - Kept deprecated `CalendarEvent`, `EventsResponse`, `fetchEventsLegacy()` for EventProof.tsx (removed Plan 05)
 
@@ -131,6 +139,7 @@ tsc --noEmit: clean (0 errors)
 ```
 
 All Wave 1 RED stubs are GREEN:
+
 - `calendarConfig.test.ts` — 4/4 pass
 - `hydrateEvents.test.ts` — 4/4 pass
 - `colorUtils.test.ts` — 10/10 pass
@@ -140,6 +149,7 @@ All Wave 1 RED stubs are GREEN:
 ### Auto-fixed Issues
 
 **1. [Rule 2 - Missing Critical Functionality] Added temporal-polyfill/global to hydrateEvents.test.ts**
+
 - **Found during:** Task 3 test run
 - **Issue:** Plan 01 RED stub lacked `import 'temporal-polyfill/global'`; jsdom has no native Temporal
 - **Fix:** Added as first import in `hydrateEvents.test.ts`
@@ -147,6 +157,7 @@ All Wave 1 RED stubs are GREEN:
 - **Commit:** f377d7c
 
 **2. [Rule 2 - Missing Critical Functionality] Added fetchEventsLegacy() to preserve EventProof**
+
 - **Found during:** Task 3 — updating client.ts
 - **Issue:** EventProof.tsx called no-arg `fetchEvents()` and used `CalendarEvent` fields not on `CalendarOccurrence`
 - **Fix:** Added `fetchEventsLegacy()` (deprecated) + updated EventProof to use it; plan says it is replaced in Plan 05
@@ -164,6 +175,7 @@ No new threat surface beyond the plan's threat model. All packages pre-approved
 ## Self-Check: PASSED
 
 Files created:
+
 - [x] apps/pwa/src/styles/tokens.css
 - [x] apps/pwa/src/styles/tokens.ts
 - [x] apps/pwa/src/styles/index.css
@@ -174,6 +186,7 @@ Files created:
 - [x] apps/pwa/src/store/calendarStore.ts
 
 Commits:
+
 - [x] 0911a23 — Task 1: Schedule-X stack + token layer + main.tsx
 - [x] 43554f4 — Task 2: colorUtils + calendarConfig; calendarConfig stubs GREEN
 - [x] f377d7c — Task 3: hydrateEvents + calendarStore + windowed fetchEvents; all stubs GREEN

.planning/milestones/v1.0-phases/02-calendar-display/02-04-PLAN.md

@@ -3,7 +3,7 @@ phase: 02-calendar-display
 plan: 04
 type: execute
 wave: 3
-depends_on: ["02-02", "02-03"]
+depends_on: ['02-02', '02-03']
 files_modified:
   - apps/pwa/src/components/CalendarShell.tsx
   - apps/pwa/src/App.tsx
@@ -14,32 +14,32 @@ user_setup: []
 
 must_haves:
   truths:
-    - "Opening the app renders a Schedule-X calendar populated with REAL windowed Fastmail occurrences fetched from /api/events"
+    - 'Opening the app renders a Schedule-X calendar populated with REAL windowed Fastmail occurrences fetched from /api/events'
     - "Events render in their owner's member color; shared-family events render in the reserved rose color (D-06)"
-    - "The user can switch between day, week, month, and agenda views and events render in each (D-04)"
-    - "Recurring events show all in-window occurrences; all-day events appear as full-day banners on the correct date with no shift"
-    - "The visible window drives the TanStack Query key; navigating to a new window refetches"
-    - "Default view is agenda on phone and month on tablet/desktop (D-05)"
+    - 'The user can switch between day, week, month, and agenda views and events render in each (D-04)'
+    - 'Recurring events show all in-window occurrences; all-day events appear as full-day banners on the correct date with no shift'
+    - 'The visible window drives the TanStack Query key; navigating to a new window refetches'
+    - 'Default view is agenda on phone and month on tablet/desktop (D-05)'
   artifacts:
-    - path: "apps/pwa/src/components/CalendarShell.tsx"
-      provides: "Schedule-X calendar wired to TanStack Query + hydrateEvents + Zustand range"
+    - path: 'apps/pwa/src/components/CalendarShell.tsx'
+      provides: 'Schedule-X calendar wired to TanStack Query + hydrateEvents + Zustand range'
       min_lines: 60
-    - path: "apps/pwa/src/App.tsx"
-      provides: "renders CalendarShell as the app root (replaces EventProof landing)"
-      contains: "CalendarShell"
+    - path: 'apps/pwa/src/App.tsx'
+      provides: 'renders CalendarShell as the app root (replaces EventProof landing)'
+      contains: 'CalendarShell'
   key_links:
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "/api/events"
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: '/api/events'
       via: "useQuery(['events',start,end]) → fetchEvents"
-      pattern: "fetchEvents"
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "Schedule-X eventsService"
-      via: "eventsService.set(hydrateEvents(data.occurrences))"
-      pattern: "hydrateEvents"
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "apps/pwa/src/store/calendarStore.ts"
-      via: "calendarRange drives query key; onRangeUpdate updates it"
-      pattern: "useCalendarStore"
+      pattern: 'fetchEvents'
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: 'Schedule-X eventsService'
+      via: 'eventsService.set(hydrateEvents(data.occurrences))'
+      pattern: 'hydrateEvents'
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: 'apps/pwa/src/store/calendarStore.ts'
+      via: 'calendarRange drives query key; onRangeUpdate updates it'
+      pattern: 'useCalendarStore'
 ---
 
 <objective>
@@ -95,6 +95,7 @@ Output: CalendarShell.tsx wired to the full data pipeline; App.tsx renders it; a
     Render `<ScheduleXCalendar calendarApp={calendar} />` filling the available space. Use token-based styling only (className/var(--token)) — no hard-coded hex/px (Phase 2 rule). The AppNav/ViewToolbar/ColorLegend/popover chrome is Plan 05; CalendarShell here may render a minimal toolbar placeholder or rely on Schedule-X's built-in controls so the four views are switchable and verifiable now.
 
     Update `apps/pwa/src/App.tsx`: replace the EventProof landing content with `<CalendarShell />` as the app root. Migrate any remaining hard-coded hex/px in App.tsx to tokens (Phase 2 rule). Leave the meQuery sign-in-required error branch intact for unauthenticated state.
+
   </action>
   <verify>
     <automated>cd apps/pwa && grep -q "ScheduleXCalendar" src/components/CalendarShell.tsx && grep -q "hydrateEvents" src/components/CalendarShell.tsx && grep -q "queryKey: \['events'" src/components/CalendarShell.tsx && grep -q "CalendarShell" src/App.tsx && echo SHELL_WIRED</automated>
@@ -143,18 +144,20 @@ Output: CalendarShell.tsx wired to the full data pipeline; App.tsx renders it; a
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                           | Description                                        |
+| ---------------------------------- | -------------------------------------------------- |
 | /api/events JSON → calendar render | server occurrences rendered into the DOM via React |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02d-01 | Tampering (XSS) | event title/location/description in render | mitigate | React JSX default escaping; never dangerouslySetInnerHTML for event fields (carried into Plan 05 popover) |
-| T-02d-02 | Information disclosure | events from another member's account | accept | API already enforces auth + per-credential scoping (Plan 02 / CAL-08-DECISION); client renders only what the authed endpoint returns |
+| Threat ID | Category               | Component                                  | Disposition | Mitigation Plan                                                                                                                      |
+| --------- | ---------------------- | ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| T-02d-01  | Tampering (XSS)        | event title/location/description in render | mitigate    | React JSX default escaping; never dangerouslySetInnerHTML for event fields (carried into Plan 05 popover)                            |
+| T-02d-02  | Information disclosure | events from another member's account       | accept      | API already enforces auth + per-credential scoping (Plan 02 / CAL-08-DECISION); client renders only what the authed endpoint returns |
+
 </threat_model>
 
 <verification>
@@ -164,19 +167,21 @@ Output: CalendarShell.tsx wired to the full data pipeline; App.tsx renders it; a
 </verification>
 
 <success_criteria>
+
 - Real Fastmail occurrences render color-coded across day/week/month/agenda (CAL-02, CAL-03)
 - Recurring + all-day occurrences render correctly in-window (CAL-07 display)
 - Window navigation refetches via TanStack Query
-</success_criteria>
+  </success_criteria>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 04)
 
 - `CalendarShell` (React component) — apps/pwa/src/components/CalendarShell.tsx
 - App.tsx now renders CalendarShell as root (EventProof landing removed from render path)
 - CalendarShell.test.tsx (CAL-03 render smoke)
 - Schedule-X eventsService + eventModal plugin instances + useCalendarApp config in CalendarShell
-</artifacts_produced>
+  </artifacts_produced>
 
 <output>
 Create `.planning/phases/02-calendar-display/02-04-SUMMARY.md` when done

.planning/milestones/v1.0-phases/02-calendar-display/02-04-SUMMARY.md

@@ -1,12 +1,12 @@
 ---
 phase: 02-calendar-display
-plan: "04"
+plan: '04'
 subsystem: pwa-calendar-shell
 tags: [schedule-x, tanstack-query, zustand, hydrate-events, temporal, calendar-shell, smoke-test]
 dependency_graph:
-  requires: ["02-02", "02-03"]
+  requires: ['02-02', '02-03']
   provides: [CalendarShell, App-root-calendar, CAL-03-smoke-test]
-  affects: ["02-05"]
+  affects: ['02-05']
 tech_stack:
   added: []
   patterns:
@@ -24,13 +24,13 @@ key_files:
     - apps/pwa/src/App.tsx
     - apps/pwa/vitest.config.ts
 decisions:
-  - "CalendarShell callbacks nested under config.callbacks per CalendarConfigExternal type (not top-level)"
-  - "DateRange.start/end are Temporal.ZonedDateTime; extracted to ISO date via .toPlainDate().toString() for Zustand"
-  - "test-setup.ts as vitest setupFiles for window.matchMedia polyfill — calendarStore creates Zustand store at module load time before test polyfills run"
-  - "App.tsx simplified to single-line wrapper; EventProof and health probe removed from render path"
+  - 'CalendarShell callbacks nested under config.callbacks per CalendarConfigExternal type (not top-level)'
+  - 'DateRange.start/end are Temporal.ZonedDateTime; extracted to ISO date via .toPlainDate().toString() for Zustand'
+  - 'test-setup.ts as vitest setupFiles for window.matchMedia polyfill — calendarStore creates Zustand store at module load time before test polyfills run'
+  - 'App.tsx simplified to single-line wrapper; EventProof and health probe removed from render path'
 metrics:
-  duration: "~12m"
-  completed: "2026-06-05"
+  duration: '~12m'
+  completed: '2026-06-05'
   tasks_completed: 2
   files_created: 3
   files_modified: 2
@@ -45,6 +45,7 @@ Schedule-X CalendarShell component wired to TanStack Query windowed fetch, hydra
 ### Task 1: CalendarShell + App.tsx
 
 **`apps/pwa/src/components/CalendarShell.tsx`** (186 lines):
+
 - `useCalendarApp(config, [eventsService, eventModal])` with all four view factories: `createViewDay`, `createViewWeek`, `createViewMonthGrid`, `createViewMonthAgenda`
 - `defaultView` from Zustand persisted view (D-05 defaults: phone→month-agenda, tablet-desktop→month-grid already encoded in store)
 - `firstDayOfWeek: SX_FIRST_DAY_OF_WEEK` (7 = Sunday, Temporal convention) — Pitfall 1 guard
@@ -61,6 +62,7 @@ Schedule-X CalendarShell component wired to TanStack Query windowed fetch, hydra
 ### Task 2: CalendarShell Render Smoke Test (CAL-03)
 
 **`apps/pwa/src/components/CalendarShell.test.tsx`** (6 tests):
+
 - Render-without-throw smoke (validates `@schedule-x/react@4.1.0` ↔ `@schedule-x/calendar@4.6.0` import compatibility — Pitfall 6)
 - `ScheduleXCalendar` mounts with non-null `calendarApp`
 - `hydrateEvents` called with both timed + all-day occurrences; `eventsService.set()` called with hydrated events
@@ -87,6 +89,7 @@ vite build: clean (474.27 kB, built in 395ms)
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] CalendarCallbacks nested under config.callbacks — not top-level**
+
 - **Found during:** Task 1 — tsc reported `onRangeUpdate` not in `CalendarConfigExternal`
 - **Issue:** Research pattern (RESEARCH.md Pattern 4) showed `onRangeUpdate` at the top level of the config object. The actual type (`CalendarConfigExternal extends Partial<ReducedCalendarConfigInternal>`) carries `callbacks?: CalendarCallbacks` where `CalendarCallbacks` contains `onRangeUpdate` and `onEventClick`. They must be nested under `config.callbacks`.
 - **Fix:** Moved `onRangeUpdate` and `onEventClick` into `callbacks: { ... }` in the `useCalendarApp` config
@@ -94,6 +97,7 @@ vite build: clean (474.27 kB, built in 395ms)
 - **Commit:** b79f649
 
 **2. [Rule 3 - Blocking] window.matchMedia not defined in jsdom**
+
 - **Found during:** Task 2 — test run crashed at Zustand store initialisation
 - **Issue:** `calendarStore.ts` calls `window.matchMedia` inside `readPersistedView()` which runs at `create()` time — i.e. at module load, before any test-file-level polyfill runs. Inline `Object.defineProperty` in the test file is too late.
 - **Fix:** Created `src/test-setup.ts` with the polyfill; added `setupFiles: ['./src/test-setup.ts']` to `vitest.config.ts`
@@ -107,15 +111,18 @@ None — CalendarShell fetches real windowed data from `/api/events`, hydrates t
 ## Threat Flags
 
 No new threat surface beyond the plan's threat model.
+
 - T-02d-01 (XSS): CalendarShell uses React JSX default escaping for all event field rendering — no `dangerouslySetInnerHTML`. Carried to Plan 05 popover.
 
 ## Self-Check: PASSED
 
 Files created:
+
 - [x] apps/pwa/src/components/CalendarShell.tsx
 - [x] apps/pwa/src/components/CalendarShell.test.tsx
 - [x] apps/pwa/src/test-setup.ts
 
 Commits:
+
 - [x] b79f649 — Task 1: CalendarShell + App.tsx
 - [x] f0af43c — Task 2: CalendarShell smoke test

.planning/milestones/v1.0-phases/02-calendar-display/02-05-PLAN.md

@@ -3,7 +3,7 @@ phase: 02-calendar-display
 plan: 05
 type: execute
 wave: 4
-depends_on: ["02-04"]
+depends_on: ['02-04']
 files_modified:
   - apps/pwa/src/components/EventDetailPopover.tsx
   - apps/pwa/src/components/ColorLegend.tsx
@@ -20,30 +20,30 @@ user_setup: []
 
 must_haves:
   truths:
-    - "Tapping any event opens a read-only detail popover (title, date/time, location, description, calendar name + owner color) built for Phase 3 reuse as the edit surface"
+    - 'Tapping any event opens a read-only detail popover (title, date/time, location, description, calendar name + owner color) built for Phase 3 reuse as the edit surface'
     - "A color legend (member → color, plus 'Family' rose row) is always visible so ownership is decodable"
-    - "Initial load shows a shimmer skeleton; a successful fetch with zero events shows the empty state; a failed fetch shows the error state with a working Retry"
-    - "All chrome (AppNav, ViewToolbar, legend) is token-styled with 44px minimum touch targets and is keyboard/focus accessible"
-    - "The popover never renders event fields via dangerouslySetInnerHTML (XSS guard) and traps focus with Escape-to-close"
+    - 'Initial load shows a shimmer skeleton; a successful fetch with zero events shows the empty state; a failed fetch shows the error state with a working Retry'
+    - 'All chrome (AppNav, ViewToolbar, legend) is token-styled with 44px minimum touch targets and is keyboard/focus accessible'
+    - 'The popover never renders event fields via dangerouslySetInnerHTML (XSS guard) and traps focus with Escape-to-close'
   artifacts:
-    - path: "apps/pwa/src/components/EventDetailPopover.tsx"
-      provides: "read-only event detail popover; Phase-3-reusable edit surface; focus trap + XSS-safe"
-      exports: ["EventDetailPopover"]
-    - path: "apps/pwa/src/components/ColorLegend.tsx"
-      provides: "always-visible member→color legend with Family row"
-      exports: ["ColorLegend"]
-    - path: "apps/pwa/src/components/SkeletonCalendar.tsx"
-      provides: "shimmer loading skeleton (month + agenda variants)"
-      exports: ["SkeletonCalendar"]
+    - path: 'apps/pwa/src/components/EventDetailPopover.tsx'
+      provides: 'read-only event detail popover; Phase-3-reusable edit surface; focus trap + XSS-safe'
+      exports: ['EventDetailPopover']
+    - path: 'apps/pwa/src/components/ColorLegend.tsx'
+      provides: 'always-visible member→color legend with Family row'
+      exports: ['ColorLegend']
+    - path: 'apps/pwa/src/components/SkeletonCalendar.tsx'
+      provides: 'shimmer loading skeleton (month + agenda variants)'
+      exports: ['SkeletonCalendar']
   key_links:
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "apps/pwa/src/components/EventDetailPopover.tsx"
-      via: "customComponents.eventModal + openEventId from Zustand"
-      pattern: "EventDetailPopover"
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "SkeletonCalendar | EmptyState | error state"
-      via: "TanStack Query isLoading/empty/isError branches"
-      pattern: "SkeletonCalendar"
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: 'apps/pwa/src/components/EventDetailPopover.tsx'
+      via: 'customComponents.eventModal + openEventId from Zustand'
+      pattern: 'EventDetailPopover'
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: 'SkeletonCalendar | EmptyState | error state'
+      via: 'TanStack Query isLoading/empty/isError branches'
+      pattern: 'SkeletonCalendar'
 ---
 
 <objective>
@@ -98,6 +98,7 @@ EventProof removed; human-verify checkpoint.
     Wire into CalendarShell: pass `customComponents={{ eventModal: EventDetailPopover }}` to `<ScheduleXCalendar>`, and ensure the event-click path sets openEventId so the popover opens. Keep the eventsService/eventModal plugin wiring from Plan 04.
 
     Write `EventDetailPopover.test.tsx` (jsdom): renders an event's fields as text, Escape triggers close, and asserts no dangerouslySetInnerHTML usage (render a title containing an HTML-looking string and assert it appears escaped as text).
+
   </action>
   <verify>
     <automated>cd apps/pwa && pnpm test -- src/components/EventDetailPopover.test.tsx</automated>
@@ -134,6 +135,7 @@ EventProof removed; human-verify checkpoint.
     In CalendarShell, render AppNav + ViewToolbar + ColorLegend chrome around `<ScheduleXCalendar>` (grid is the primary focal point per reviewer note). Branch on the events query: `isLoading` (initial) → SkeletonCalendar; success + `occurrences.length === 0` → EmptyState; `isError` (after retry:2) → error state replacing the grid with heading "Couldn't load events", body "Check your connection and try again.", and a "Retry" button calling `queryClient.refetchQueries({ queryKey: ['events'] })`. All token-styled.
 
     Delete `apps/pwa/src/components/EventProof.tsx` and remove any remaining imports/references to it (Plan 04 removed it from the render path; confirm the file and its imports are gone).
+
   </action>
   <verify>
     <automated>cd apps/pwa && grep -q "SkeletonCalendar" src/components/CalendarShell.tsx && grep -q "EmptyState" src/components/CalendarShell.tsx && grep -q "Couldn't load events" src/components/CalendarShell.tsx && grep -q "ColorLegend" src/components/CalendarShell.tsx && echo STATES_WIRED</automated>
@@ -174,18 +176,20 @@ EventProof removed; human-verify checkpoint.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                   | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
 | event fields → popover DOM | title/location/description rendered into the popover |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-02e-01 | Tampering (XSS) | EventDetailPopover event fields | mitigate | Plain-text JSX children only; no dangerouslySetInnerHTML; test asserts HTML-looking title renders escaped |
-| T-02e-02 | Denial of service | Retry button hammering /api/events | accept | Manual user action, retry:2 backoff already on the query; two-person self-hosted app, negligible risk |
+| Threat ID | Category          | Component                          | Disposition | Mitigation Plan                                                                                           |
+| --------- | ----------------- | ---------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
+| T-02e-01  | Tampering (XSS)   | EventDetailPopover event fields    | mitigate    | Plain-text JSX children only; no dangerouslySetInnerHTML; test asserts HTML-looking title renders escaped |
+| T-02e-02  | Denial of service | Retry button hammering /api/events | accept      | Manual user action, retry:2 backoff already on the query; two-person self-hosted app, negligible risk     |
+
 </threat_model>
 
 <verification>
@@ -195,14 +199,16 @@ EventProof removed; human-verify checkpoint.
 </verification>
 
 <success_criteria>
+
 - Color-coded events + legend decode ownership (criterion 1)
 - All four views render events correctly (criterion 2)
 - Recurring occurrences correct incl. DST (criterion 3)
 - All-day events as full-day banners with no shift (criterion 4)
 - Tap-to-expand popover + skeleton/empty/error states polished and accessible
-</success_criteria>
+  </success_criteria>
 
 <artifacts_produced>
+
 ## Artifacts this phase produces (Plan 05)
 
 - `EventDetailPopover` (React component, Phase-3-reusable edit surface) — EventDetailPopover.tsx
@@ -210,7 +216,7 @@ EventProof removed; human-verify checkpoint.
 - CalendarShell: chrome + loading/empty/error branches + customComponents.eventModal wiring
 - EventProof.tsx DELETED (Phase 1 proof component retired)
 - EventDetailPopover.test.tsx
-</artifacts_produced>
+  </artifacts_produced>
 
 <output>
 Create `.planning/phases/02-calendar-display/02-05-SUMMARY.md` when done

.planning/milestones/v1.0-phases/02-calendar-display/02-05-SUMMARY.md

@@ -56,6 +56,7 @@ Read-only EventDetailPopover (XSS-safe, accessible, Phase-3-reusable), always-vi
 ### Task 1: EventDetailPopover + CalendarShell wiring (TDD)
 
 **`apps/pwa/src/components/EventDetailPopover.tsx`** (259 lines):
+
 - Resolves open event by `openEventId` (Zustand) from TanStack Query `['events']` cache using `queryClient.getQueriesData`
 - Dual-mode: standalone (primary, driven by Zustand) + `customComponents.eventModal` prop from Schedule-X
 - Renders title (heading), date/time, location (with MapPin icon when present), description (max-4-lines scroll), calendar name + color swatch footer
@@ -67,6 +68,7 @@ Read-only EventDetailPopover (XSS-safe, accessible, Phase-3-reusable), always-vi
 - Wired in CalendarShell: `customComponents={{ eventModal: EventDetailPopover }}` AND rendered standalone after the layout
 
 **`apps/pwa/src/components/EventDetailPopover.test.tsx`** (192 lines, TDD RED → GREEN):
+
 - TDD RED commit: tests written first, failing because file missing
 - GREEN commit: implementation makes all 12 tests pass
 - Tests: title/location/description/calendarName render as text; heading role; Escape/close-button/backdrop all call `setOpenEventId(null)`; null openEventId renders nothing
@@ -77,31 +79,37 @@ Read-only EventDetailPopover (XSS-safe, accessible, Phase-3-reusable), always-vi
 ### Task 2: Chrome components, state branches, EventProof retired
 
 **`apps/pwa/src/components/ColorLegend.tsx`**:
+
 - One row per member: 12px color circle (`aria-label="{name}: {hex}"`) + display name
 - "Family" row always rendered last using `--color-shared-family` (#F25C7A)
 - Font: 13px label weight, `--color-text-secondary`
 
 **`apps/pwa/src/components/AppNav.tsx`**:
+
 - Phone: 48px top bar — "FamilySync" display text left, user avatar right with `aria-label` + `title` per reviewer note
 - Tablet/desktop: 240px left sidebar — app name + "Calendars" section header + `<ColorLegend>`
 
 **`apps/pwa/src/components/ViewToolbar.tsx`**:
+
 - Today | ‹ | › | Day | Week | Month | Agenda
 - 44px min-height on all buttons; keyboard-activatable
 - Active view: `rgba(74, 144, 217, 0.12)` surface tint (NOT accent color) per UI-SPEC 60/30/10 rule
 - Navigation via `calendarApp.$app.calendarState.setRange()` / `setView()` (internal Schedule-X API)
 
 **`apps/pwa/src/components/SkeletonCalendar.tsx`**:
+
 - Month variant: 6×7 grid of shimmer cells + 7-col header
 - Agenda variant: 4 date-group blocks, 2–3 rows each at 60–90% widths
 - `aria-busy="true"`, `aria-label="Loading calendar"` on root
 - Shimmer: `@keyframes shimmer` from tokens.css, `background-size: 200% 100%`, 1.5s infinite
 
 **`apps/pwa/src/components/EmptyState.tsx`**:
+
 - `CalendarDays` lucide icon (32px, `--color-text-muted`)
 - Heading "Nothing here" + body "No events in this period. Try a different date or switch views." per UI-SPEC copywriting
 
 **`apps/pwa/src/components/CalendarShell.tsx`** (major refactor):
+
 - Phone: AppNav top bar → ViewToolbar → calendar content → ColorLegend below
 - Tablet/desktop: AppNav sidebar (240px) + main area (ViewToolbar → calendar content)
 - State branches: `isInitialLoading` → `SkeletonCalendar`; `isEventsError` → "Couldn't load events" + "Check your connection" + **Retry** button calling `queryClient.refetchQueries({ queryKey: ['events'] })`; `isEmptyResult` → `EmptyState`; success+data → `ScheduleXCalendar`
@@ -125,6 +133,7 @@ vite build: clean (490.30 kB, 827ms)
 ### Auto-fixed Issues
 
 **1. [Rule 3 - Blocking] @testing-library/jest-dom not imported in test-setup.ts**
+
 - **Found during:** Task 1 GREEN phase — `toHaveTextContent` threw "Invalid Chai property"
 - **Issue:** `@testing-library/jest-dom` extends Vitest/Chai's `expect` with DOM matchers. It was installed (in devDependencies) but never imported in `src/test-setup.ts`, so matchers were not registered.
 - **Fix:** Added `import '@testing-library/jest-dom'` to `src/test-setup.ts`
@@ -132,6 +141,7 @@ vite build: clean (490.30 kB, 827ms)
 - **Commit:** 3eebfbf (bundled with Task 1 GREEN commit)
 
 **2. [Rule 1 - Bug] CalendarShell.test.tsx: synchronous getByTestId fails after loading state added**
+
 - **Found during:** Task 2 verification — existing CalendarShell smoke test failed
 - **Issue:** The test did `screen.getByTestId('schedule-x-calendar')` synchronously, but CalendarShell now shows SkeletonCalendar while loading. The calendar element only appears after queries resolve.
 - **Fix:** Changed to `await screen.findByTestId('schedule-x-calendar')` (async, waits for element)
@@ -139,6 +149,7 @@ vite build: clean (490.30 kB, 827ms)
 - **Commit:** 216ddce (bundled with Task 2 commit)
 
 **3. [Rule 1 - Bug] ViewToolbar: CalendarApp.setDate/decrementRange/incrementRange/setView don't exist on public API**
+
 - **Found during:** Task 2 tsc check — 4 type errors
 - **Issue:** `CalendarApp` class only exposes `render`, `destroy`, `setTheme`, `getTheme`, and `events` (EventsFacade). Navigation methods (`setRange`, `setView`) live on the internal `$app.calendarState` (a `CalendarAppSingleton` property).
 - **Fix:** Changed `calendarApp` prop type to `any`, accessed internal state via `calendarApp.$app.calendarState` with runtime null-guards. Navigation uses `Temporal.Now.plainDateISO()` for today and `ZonedDateTime.until().days` for range inference.
@@ -156,6 +167,7 @@ None — all components render from live data (TanStack Query cache) or accurate
 ## Threat Flags
 
 T-02e-01 mitigated:
+
 - EventDetailPopover: title, description, location, calendarName all rendered as plain-text JSX children
 - Test asserts `<script>alert("xss")</script>` in title → `heading.innerHTML` does NOT contain `<script>`, textContent DOES contain the literal string
 - Test asserts `<b>Bold</b>` in description → `descEl.innerHTML` does NOT contain `<b>`
@@ -169,6 +181,7 @@ The plan gates on operator visual verification. The automated tasks (1 and 2) ar
 ## Self-Check: PASSED
 
 Files created:
+
 - [x] apps/pwa/src/components/EventDetailPopover.tsx
 - [x] apps/pwa/src/components/EventDetailPopover.test.tsx
 - [x] apps/pwa/src/components/ColorLegend.tsx
@@ -178,9 +191,11 @@ Files created:
 - [x] apps/pwa/src/components/EmptyState.tsx
 
 Files deleted:
+
 - [x] apps/pwa/src/components/EventProof.tsx (confirmed ABSENT)
 
 Commits:
+
 - [x] 433fb9f — TDD RED: EventDetailPopover test
 - [x] 3eebfbf — feat: EventDetailPopover + CalendarShell wiring
 - [x] 216ddce — feat: Task 2 chrome + states + EventProof retired

.planning/milestones/v1.0-phases/02-calendar-display/02-CONTEXT.md

@@ -21,6 +21,7 @@ until >2 members), single-occurrence recurring edits (v1.x).
 ## Implementation Decisions
 
 ### Theming architecture (the load-bearing decision)
+
 - **D-01:** Build a **design-token layer** — color, spacing, density, and typography expressed
   as CSS custom properties + a small theme object — and build the UI exclusively against those
   tokens. No hard-coded colors/spacing in components.
@@ -33,12 +34,14 @@ until >2 members), single-occurrence recurring edits (v1.x).
   see [[project-familysync]] / PROJECT.md Out-of-Scope note on wall display.)
 
 ### Views & default
+
 - **D-04:** Provide all four views: **day, week, month, agenda** (CAL-03).
 - **D-05:** **Device-adaptive default view:** phone → **Agenda** (lowest friction for the
   non-technical iPhone member); tablet/desktop → **Month** (spatial overview, closest to the v2
   display). Remember the last-used view per device.
 
 ### Color & ownership legibility
+
 - **D-06:** **Per-member color fill** using the color already assigned on the user row in Phase 1
   (6-color palette already scales as members are added); the **shared-family calendar gets one
   reserved, distinct color**. This is the "whose is this" signal and must read at a glance.
@@ -47,12 +50,14 @@ until >2 members), single-occurrence recurring edits (v1.x).
   as the future display theme) — a 2-person household doesn't need it yet.
 
 ### Event detail density
+
 - **D-08:** **Informational + tap-to-expand.** Month = colored bars with the event title (not bare
   dots); Week/Day = time + title; Agenda = time + title + location. Tapping any event opens a
   **read-only detail popover** (title, time, location, description) — this popover is intended to
   be **reused as the edit surface in Phase 3**, so build it with that in mind.
 
 ### Recurrence / time (carried forward — not re-discussed)
+
 - **D-09:** Recurring events are **expanded server-side** (`CALDAV:expand` / broker emits concrete
   occurrences for the requested window) — locked in STATE/CLAUDE. The client renders occurrences;
   it does not run rrule expansion itself for the primary path.
@@ -60,6 +65,7 @@ until >2 members), single-occurrence recurring edits (v1.x).
   already in the schema). Secondary-timezone display toggle is deferred to v1.x.
 
 ### Claude's Discretion
+
 - Week start day (Sunday vs Monday): default **Sunday** (US locale — the account has a "USA
   Holidays" calendar); expose as a token/config so it's trivial to flip. Planner/researcher may
   confirm.
@@ -71,23 +77,27 @@ until >2 members), single-occurrence recurring edits (v1.x).
 - Skeleton/loading and empty states: build them, polished enough for the "slick" constraint.
 
 ### Dev-auth bypass (from D-14, project-level)
+
 - `/api/*` is OIDC-gated, but live Authelia is deferred (D-14). Plan a **documented dev-auth
   bypass** (e.g., an env-flagged middleware that injects a fixed dev user) so Phase 2 UI can be
   built and tested locally without a live OIDC provider. Must be off by default / impossible in
   production builds.
-</decisions>
+  </decisions>
 
 <canonical_refs>
+
 ## Canonical References
 
 **Downstream agents MUST read these before planning or implementing.**
 
 ### Project decisions & scope
+
 - `.planning/PROJECT.md` — core value, constraints, Key Decisions incl. D-14/D-15; wall-display is v2 (informs D-02/D-03).
 - `.planning/ROADMAP.md` §"Phase 2: Calendar Display" — goal + success criteria; §Phase 3/4 for scope boundaries.
-- `.planning/REQUIREMENTS.md` — CAL-02 (unified color-coded view), CAL-03 (day/week/month/agenda), and the recurring-event *display* portion of CAL-07.
+- `.planning/REQUIREMENTS.md` — CAL-02 (unified color-coded view), CAL-03 (day/week/month/agenda), and the recurring-event _display_ portion of CAL-07.
 
 ### Phase 1 foundation this builds on
+
 - `.planning/phases/01-foundation-broker-spike/01-03-SUMMARY.md` — broker API surface (syncCalendar, poller), event cache shape.
 - `.planning/phases/01-foundation-broker-spike/01-04-SUMMARY.md` — index.ts route wiring, `/api/events`, `/api/me`.
 - `.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md` — per-member app-password model (how multiple members' calendars aggregate).
@@ -95,26 +105,30 @@ until >2 members), single-occurrence recurring edits (v1.x).
 - `apps/api/src/db/schema.ts` — `users.color`, `calendars.userId`, `calendarEvents` (dtstartUtc/dtstartDate/allDay/rawVevent) — the D-13 split the display relies on.
 - `CLAUDE.md` — locked stack (React 19, Vite, TanStack Query, Zustand, ical.js, rrule), CalDAV/expand guidance, iOS constraints.
 - `docs/deployment.md` — dev-auth bypass context lives alongside Gate 2 (D-14).
-</canonical_refs>
+  </canonical_refs>
 
 <code_context>
+
 ## Existing Code Insights
 
 ### Reusable Assets
+
 - `apps/pwa/src/api/client.ts` — typed fetch client (`fetchMe`, `credentials: 'include'`); extend with a typed `fetchEvents(range)`.
 - `apps/pwa/src/components/EventProof.tsx` — proof-of-concept that already fetches `/api/events` and parses a VEVENT; the calendar replaces/absorbs it.
 - `apps/pwa/src/App.tsx` — member badge (name + color via `/api/me`); the per-member color source for D-06.
 - `apps/pwa/src/main.tsx` — `QueryClientProvider` already set up (TanStack Query is the server-state owner).
 
 ### Established Patterns
+
 - Server state → TanStack Query; UI-only state (selected date, current view) → Zustand (locked; do not put events in Zustand).
 - Broker is the ONLY Fastmail I/O boundary; `/api/events` reads the MariaDB cache only (no tsdav in routes) — recurrence expansion belongs server-side near the broker/route, never a direct Fastmail call from the UI.
 - Hono app exported from `index.ts` without auto-starting (testable); add display-oriented endpoints there.
 
 ### Integration Points
+
 - `/api/events` must evolve from "raw row dump" to a display-ready shape: expanded occurrences within a requested date window, parsed title/time/location, all-day flag, and member color / shared-vs-personal indicator (join calendarEvents → calendars → users.color). This is the main backend work of Phase 2.
 - Dev-auth bypass middleware sits in front of `/api/*` (see D-14).
-</code_context>
+  </code_context>
 
 <specifics>
 ## Specific Ideas
@@ -122,7 +136,7 @@ until >2 members), single-occurrence recurring edits (v1.x).
 - "Clean theme now, switch to **Skylight style** later" — Skylight = large, glanceable, high-contrast family dashboard. It's the reference for the future display theme; the token layer (D-01) exists to make that swap cheap.
 - The **real end goal is a tablet wall-display** — legibility and information density are first-class even in v1's clean theme (D-03).
 - Theme/aesthetic reference target: Apple/Fantastical-style clean for v1.
-</specifics>
+  </specifics>
 
 <deferred>
 ## Deferred Ideas
@@ -133,10 +147,11 @@ until >2 members), single-occurrence recurring edits (v1.x).
 - **Single-occurrence / "this and following" recurring edits** — v1.x; Phase 3 does create + whole-series only.
 
 ### Reviewed Todos (not folded)
+
 - `kickoff-new-project.md` ("Kick off FamilySync with /gsd:new-project") — matched only on generic keywords (date/requirements/phase); a stale project-bootstrap todo, not Phase 2 scope.
-</deferred>
+  </deferred>
 
 ---
 
-*Phase: 2-Calendar Display*
-*Context gathered: 2026-06-04*
+_Phase: 2-Calendar Display_
+_Context gathered: 2026-06-04_

.planning/milestones/v1.0-phases/02-calendar-display/02-DISCUSSION-LOG.md

@@ -15,11 +15,11 @@ Initial framing (pick one aesthetic) was reformulated after the user clarified t
 **modular** approach: start clean, but be able to switch to a Skylight/tablet "display" theme
 later as family members are added — the real end goal being a **legible tablet wall-display**.
 
-| Option | Description | Selected |
-|--------|-------------|----------|
-| Token layer + clean theme only | Design tokens (CSS vars + theme object); ship only clean; future display theme = token swap; no switcher UI yet | ✓ |
-| Token layer + two themes + toggle now | Build clean + first-cut display theme + runtime toggle now | |
-| Hardcode clean, refactor later | No abstraction; retrofit theming at v2 | |
+| Option                                | Description                                                                                                     | Selected |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- |
+| Token layer + clean theme only        | Design tokens (CSS vars + theme object); ship only clean; future display theme = token swap; no switcher UI yet | ✓        |
+| Token layer + two themes + toggle now | Build clean + first-cut display theme + runtime toggle now                                                      |          |
+| Hardcode clean, refactor later        | No abstraction; retrofit theming at v2                                                                          |          |
 
 **User's choice:** Token layer + clean theme only.
 **Notes:** Claude flagged that building two themes + a switcher now is v2 gold-plating (wall-display
@@ -29,41 +29,43 @@ model must scale past two members.
 
 ## Default view & per-device
 
-| Option | Description | Selected |
-|--------|-------------|----------|
-| Phone→Agenda, Tablet/Desktop→Month | Device-adaptive default; remember last-used per device | ✓ |
-| Month everywhere | Consistent grid; cramped on phone | |
-| Agenda everywhere | List-first; underuses tablet/desktop | |
+| Option                             | Description                                            | Selected |
+| ---------------------------------- | ------------------------------------------------------ | -------- |
+| Phone→Agenda, Tablet/Desktop→Month | Device-adaptive default; remember last-used per device | ✓        |
+| Month everywhere                   | Consistent grid; cramped on phone                      |          |
+| Agenda everywhere                  | List-first; underuses tablet/desktop                   |          |
 
 **User's choice:** Phone→Agenda, Tablet/Desktop→Month.
 
 ## Color & shared-vs-personal
 
-| Option | Description | Selected |
-|--------|-------------|----------|
-| Per-member fill + reserved shared color | Phase-1 member colors; shared calendar gets one distinct color | ✓ |
-| Per-member fill + shared marked by icon | Icon instead of reserved color | |
-| Per-calendar color | Hue per Fastmail collection, member secondary | |
+| Option                                  | Description                                                    | Selected |
+| --------------------------------------- | -------------------------------------------------------------- | -------- |
+| Per-member fill + reserved shared color | Phase-1 member colors; shared calendar gets one distinct color | ✓        |
+| Per-member fill + shared marked by icon | Icon instead of reserved color                                 |          |
+| Per-calendar color                      | Hue per Fastmail collection, member secondary                  |          |
 
 **User's choice:** Per-member fill + reserved shared color.
 **Notes:** Per-member show/hide filter deferred until >2 members; a color legend is shown.
 
 ## Event detail density
 
-| Option | Description | Selected |
-|--------|-------------|----------|
-| Informational + tap-to-expand | Bars w/ title (month), time+title (week/day), +location (agenda); read-only popover reused for Phase 3 edit | ✓ |
-| Minimal | Dots + agenda titles, no popover | |
-| Maximal inline | time+title+location everywhere | |
+| Option                        | Description                                                                                                 | Selected |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- |
+| Informational + tap-to-expand | Bars w/ title (month), time+title (week/day), +location (agenda); read-only popover reused for Phase 3 edit | ✓        |
+| Minimal                       | Dots + agenda titles, no popover                                                                            |          |
+| Maximal inline                | time+title+location everywhere                                                                              |          |
 
 **User's choice:** Informational + tap-to-expand.
 
 ## Claude's Discretion
+
 - Rendering library choice (must be token-styleable, headless-friendly, all 4 views, server-expanded occurrences, good iOS touch) — researcher decides.
 - Week start day — default Sunday (US locale), exposed as a token.
 - Skeleton/loading + empty states — build, polished for the "slick" constraint.
 
 ## Deferred Ideas
+
 - Tablet/wall-display kiosk mode + Skylight display theme + runtime theme-switcher — v2.
 - Per-member show/hide filter — when membership > 2.
 - Secondary timezone toggle — v1.x.

.planning/milestones/v1.0-phases/02-calendar-display/02-HUMAN-UAT.md

@@ -13,18 +13,22 @@ updated: 2026-06-05
 ## Tests
 
 ### 1. Color-coded rendering
+
 expected: Each member's events appear in their assigned color; ColorLegend shows members; shared events distinguishable (rose).
 result: passed — operator confirmed personal events in member blue + legend. Shared/rose lane intentionally empty per D-16 (no shared Fastmail calendar created yet); code path verified.
 
 ### 2. All four views render + grid scrolls
+
 expected: Day/Week/Month/Agenda each render events; week/day time-grid scrolls without clipping; weekday headers + hour labels legible.
 result: passed — operator confirmed after fixing the height/scroll chain and label contrast.
 
 ### 3. Recurring events across DST
+
 expected: A weekly event shows all occurrences in-window and stays at the correct local wall-clock across the March 2026 spring-forward.
 result: passed — operator confirmed recurring events display at correct local time (e.g. "Small group @ 6PM" Thursdays at 5:45 PM, incl. June 11). DST spring-forward (March 2026) is implemented (VTIMEZONE registered before RecurExpansion; local display timezone) — recommended as a future spot-check if not explicitly navigated.
 
 ### 4. All-day banners — no date shift
+
 expected: All-day events appear as full-day banners on the exact correct date.
 result: passed — operator confirmed; all-day path uses Temporal.PlainDate ('YYYY-MM-DD'), never ZonedDateTime.
 

.planning/milestones/v1.0-phases/02-calendar-display/02-PATTERNS.md

@@ -8,31 +8,31 @@
 
 ## File Classification
 
-| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
-|-------------------|------|-----------|----------------|---------------|
-| `apps/api/src/db/schema.ts` | model | CRUD | self (modify) | exact |
-| `apps/api/src/broker/expand.ts` | utility | transform | `apps/api/src/broker/sync.ts` | role-match |
-| `apps/api/src/routes/events.ts` | route | request-response | self (modify) + `apps/api/src/routes/me.ts` | exact |
-| `apps/api/src/auth/devBypass.ts` | middleware | request-response | `apps/api/src/auth/middleware.ts` | role-match |
-| `apps/api/src/index.ts` | config | request-response | self (modify) | exact |
-| `apps/api/tests/broker/expand.test.ts` | test | transform | `apps/api/tests/broker/poller.test.ts` | role-match |
-| `apps/api/tests/routes/events.test.ts` | test | request-response | `apps/api/tests/health.test.ts` | role-match |
-| `apps/pwa/vitest.config.ts` | config | — | `apps/api/vitest.config.ts` | role-match |
-| `apps/pwa/src/styles/tokens.css` | utility | — | none | no analog |
-| `apps/pwa/src/styles/tokens.ts` | utility | — | none | no analog |
-| `apps/pwa/src/styles/index.css` | utility | — | none | no analog |
-| `apps/pwa/src/lib/calendarConfig.ts` | utility | transform | `apps/pwa/src/api/client.ts` | partial |
-| `apps/pwa/src/lib/hydrateEvents.ts` | utility | transform | `apps/pwa/src/api/client.ts` | partial |
-| `apps/pwa/src/lib/colorUtils.ts` | utility | transform | `apps/pwa/src/App.tsx` (ColorSwatch) | partial |
-| `apps/pwa/src/store/calendarStore.ts` | store | event-driven | none | no analog |
-| `apps/pwa/src/components/CalendarShell.tsx` | component | request-response | `apps/pwa/src/App.tsx` | role-match |
-| `apps/pwa/src/components/EventDetailPopover.tsx` | component | request-response | `apps/pwa/src/App.tsx` (MemberBadge) | partial |
-| `apps/pwa/src/components/AppNav.tsx` | component | — | `apps/pwa/src/App.tsx` | partial |
-| `apps/pwa/src/components/ViewToolbar.tsx` | component | event-driven | `apps/pwa/src/App.tsx` | partial |
-| `apps/pwa/src/components/ColorLegend.tsx` | component | — | `apps/pwa/src/App.tsx` (MemberBadge) | partial |
-| `apps/pwa/src/components/SkeletonCalendar.tsx` | component | — | `apps/pwa/src/App.tsx` (loading state) | partial |
-| `apps/pwa/src/api/client.ts` | utility | request-response | self (modify) | exact |
-| `apps/pwa/src/main.tsx` | config | — | self (modify) | exact |
+| New/Modified File                                | Role       | Data Flow        | Closest Analog                              | Match Quality |
+| ------------------------------------------------ | ---------- | ---------------- | ------------------------------------------- | ------------- |
+| `apps/api/src/db/schema.ts`                      | model      | CRUD             | self (modify)                               | exact         |
+| `apps/api/src/broker/expand.ts`                  | utility    | transform        | `apps/api/src/broker/sync.ts`               | role-match    |
+| `apps/api/src/routes/events.ts`                  | route      | request-response | self (modify) + `apps/api/src/routes/me.ts` | exact         |
+| `apps/api/src/auth/devBypass.ts`                 | middleware | request-response | `apps/api/src/auth/middleware.ts`           | role-match    |
+| `apps/api/src/index.ts`                          | config     | request-response | self (modify)                               | exact         |
+| `apps/api/tests/broker/expand.test.ts`           | test       | transform        | `apps/api/tests/broker/poller.test.ts`      | role-match    |
+| `apps/api/tests/routes/events.test.ts`           | test       | request-response | `apps/api/tests/health.test.ts`             | role-match    |
+| `apps/pwa/vitest.config.ts`                      | config     | —                | `apps/api/vitest.config.ts`                 | role-match    |
+| `apps/pwa/src/styles/tokens.css`                 | utility    | —                | none                                        | no analog     |
+| `apps/pwa/src/styles/tokens.ts`                  | utility    | —                | none                                        | no analog     |
+| `apps/pwa/src/styles/index.css`                  | utility    | —                | none                                        | no analog     |
+| `apps/pwa/src/lib/calendarConfig.ts`             | utility    | transform        | `apps/pwa/src/api/client.ts`                | partial       |
+| `apps/pwa/src/lib/hydrateEvents.ts`              | utility    | transform        | `apps/pwa/src/api/client.ts`                | partial       |
+| `apps/pwa/src/lib/colorUtils.ts`                 | utility    | transform        | `apps/pwa/src/App.tsx` (ColorSwatch)        | partial       |
+| `apps/pwa/src/store/calendarStore.ts`            | store      | event-driven     | none                                        | no analog     |
+| `apps/pwa/src/components/CalendarShell.tsx`      | component  | request-response | `apps/pwa/src/App.tsx`                      | role-match    |
+| `apps/pwa/src/components/EventDetailPopover.tsx` | component  | request-response | `apps/pwa/src/App.tsx` (MemberBadge)        | partial       |
+| `apps/pwa/src/components/AppNav.tsx`             | component  | —                | `apps/pwa/src/App.tsx`                      | partial       |
+| `apps/pwa/src/components/ViewToolbar.tsx`        | component  | event-driven     | `apps/pwa/src/App.tsx`                      | partial       |
+| `apps/pwa/src/components/ColorLegend.tsx`        | component  | —                | `apps/pwa/src/App.tsx` (MemberBadge)        | partial       |
+| `apps/pwa/src/components/SkeletonCalendar.tsx`   | component  | —                | `apps/pwa/src/App.tsx` (loading state)      | partial       |
+| `apps/pwa/src/api/client.ts`                     | utility    | request-response | self (modify)                               | exact         |
+| `apps/pwa/src/main.tsx`                          | config     | —                | self (modify)                               | exact         |
 
 ---
 
@@ -43,6 +43,7 @@
 **Analog:** self
 
 **Add to `calendarEvents` table — Drizzle column pattern** (lines 84–105 of current file):
+
 ```typescript
 // New columns to add — follow existing column declaration style exactly:
 hasRrule: boolean('has_rrule').default(false).notNull(),
@@ -56,6 +57,7 @@ index('idx_calendar_events_has_rrule').on(t.hasRrule),
 ```
 
 **Import pattern** (lines 1–11 of existing schema.ts):
+
 ```typescript
 import {
   mysqlTable,
@@ -67,7 +69,7 @@ import {
   boolean,
   index,
   unique,
-} from 'drizzle-orm/mysql-core'
+} from 'drizzle-orm/mysql-core';
 ```
 
 ---
@@ -77,55 +79,57 @@ import {
 **Analog:** `apps/api/src/broker/sync.ts`
 
 **Imports pattern** (lines 1–8 of sync.ts):
+
 ```typescript
-import ICAL from 'ical.js'
-import { eq } from 'drizzle-orm'
-import { db } from '../db/client.js'
-import { calendars, calendarEvents } from '../db/schema.js'
+import ICAL from 'ical.js';
+import { eq } from 'drizzle-orm';
+import { db } from '../db/client.js';
+import { calendars, calendarEvents } from '../db/schema.js';
 ```
 
 **ICAL.parse + Component pipeline pattern** (lines 78–91 of sync.ts):
+
 ```typescript
-let parsed: ReturnType<typeof ICAL.parse>
+let parsed: ReturnType<typeof ICAL.parse>;
 try {
-  parsed = ICAL.parse(obj.data as string)
+  parsed = ICAL.parse(obj.data as string);
 } catch {
   // Malformed VCALENDAR — skip but do not crash the sync
-  continue
+  continue;
 }
 
-const comp = new ICAL.Component(parsed)
-const vevent = comp.getFirstSubcomponent('vevent')
-if (!vevent) continue
+const comp = new ICAL.Component(parsed);
+const vevent = comp.getFirstSubcomponent('vevent');
+if (!vevent) continue;
 
-const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time | null
+const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time | null;
 ```
 
 **allDay detection pattern** (lines 88–98 of sync.ts):
+
 ```typescript
 // D-13 / Pitfall #3: isDate=true → DATE column; isDate=false → TIMESTAMP column
-const allDay: boolean = dtstart?.isDate ?? false
+const allDay: boolean = dtstart?.isDate ?? false;
 ```
 
 **Error handling pattern** (lines 75–78 of sync.ts):
+
 ```typescript
 try {
-  parsed = ICAL.parse(obj.data as string)
+  parsed = ICAL.parse(obj.data as string);
 } catch {
-  continue  // malformed VCALENDAR — skip silently
+  continue; // malformed VCALENDAR — skip silently
 }
 ```
 
 **VTIMEZONE registration — must come before RecurExpansion** (from RESEARCH.md Pattern 1):
+
 ```typescript
 // CRITICAL: Register VTIMEZONE before constructing ICAL.RecurExpansion
 for (const vtz of comp.getAllSubcomponents('vtimezone')) {
-  const tzid = vtz.getFirstPropertyValue('tzid') as string
+  const tzid = vtz.getFirstPropertyValue('tzid') as string;
   if (tzid && !ICAL.TimezoneService.has(tzid)) {
-    ICAL.TimezoneService.register(
-      tzid,
-      new ICAL.Timezone({ component: vtz, tzid }),
-    )
+    ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component: vtz, tzid }));
   }
 }
 ```
@@ -137,40 +141,43 @@ for (const vtz of comp.getAllSubcomponents('vtimezone')) {
 **Analog:** `apps/api/src/routes/me.ts` + current `events.ts`
 
 **Route file structure pattern** (lines 1–29 of me.ts):
-```typescript
-import { Hono } from 'hono'
-import { getAuth } from '../auth/middleware.js'
-import { upsertUser } from '../auth/user.js'
 
-export const meRouter = new Hono()
+```typescript
+import { Hono } from 'hono';
+import { getAuth } from '../auth/middleware.js';
+import { upsertUser } from '../auth/user.js';
+
+export const meRouter = new Hono();
 
 meRouter.get('/', async (c) => {
-  const auth = await getAuth(c)
+  const auth = await getAuth(c);
   if (!auth) {
-    return c.json({ error: 'Unauthorized' }, 401)
+    return c.json({ error: 'Unauthorized' }, 401);
   }
   // ... business logic
-  return c.json({ user: { id, displayName, color } })
-})
+  return c.json({ user: { id, displayName, color } });
+});
 ```
 
 **Zod query param validation pattern** — follow `@hono/zod-validator` (from CLAUDE.md stack; no existing example yet — planner must scaffold):
+
 ```typescript
-import { zValidator } from '@hono/zod-validator'
-import { z } from 'zod'
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
 
 const eventsQuerySchema = z.object({
   start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
   end: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-})
+});
 
 eventsRouter.get('/', zValidator('query', eventsQuerySchema), async (c) => {
-  const { start, end } = c.req.valid('query')
+  const { start, end } = c.req.valid('query');
   // ...
-})
+});
 ```
 
 **Drizzle join pattern** (from sync.ts lines 59, 99 + schema.ts foreign key pattern):
+
 ```typescript
 // Pattern: db.select().from(table).where(eq(...)).limit(1)
 // For join: db.select().from(calendarEvents)
@@ -180,13 +187,14 @@ eventsRouter.get('/', zValidator('query', eventsQuerySchema), async (c) => {
 ```
 
 **Error handling pattern** (lines 16–26 of health.ts):
+
 ```typescript
 try {
   // ...
-  return c.json({ ok: true, db: 'up' })
+  return c.json({ ok: true, db: 'up' });
 } catch (err) {
-  console.error('[health] DB round-trip failed:', err)
-  return c.json({ ok: false, db: 'down' }, 503)
+  console.error('[health] DB round-trip failed:', err);
+  return c.json({ ok: false, db: 'down' }, 503);
 }
 ```
 
@@ -197,27 +205,29 @@ try {
 **Analog:** `apps/api/src/auth/middleware.ts`
 
 **Middleware export pattern** (lines 24–26 of middleware.ts):
+
 ```typescript
 // middleware.ts uses re-export; devBypass.ts uses named function export
-export { oidcAuthMiddleware, processOAuthCallback, getAuth } from '@hono/oidc-auth'
+export { oidcAuthMiddleware, processOAuthCallback, getAuth } from '@hono/oidc-auth';
 ```
 
 **Hono middleware handler signature** (from Hono docs + RESEARCH.md Pattern 5):
+
 ```typescript
-import type { MiddlewareHandler } from 'hono'
+import type { MiddlewareHandler } from 'hono';
 
 export function devAuthBypass(): MiddlewareHandler {
   // Hard production guard FIRST — before reading any env var
   if (process.env.NODE_ENV === 'production') {
-    return async (_c, next) => next()
+    return async (_c, next) => next();
   }
   if (process.env.DEV_AUTH_BYPASS !== 'true') {
-    return async (_c, next) => next()
+    return async (_c, next) => next();
   }
   return async (c, next) => {
-    c.set('user', DEV_USER)
-    await next()
-  }
+    c.set('user', DEV_USER);
+    await next();
+  };
 }
 ```
 
@@ -228,27 +238,29 @@ export function devAuthBypass(): MiddlewareHandler {
 **Analog:** self
 
 **Middleware mount order pattern** (lines 14–29 of index.ts):
+
 ```typescript
 // OIDC callback BEFORE auth guard (T-02-02)
-app.get('/callback', (c) => processOAuthCallback(c))
+app.get('/callback', (c) => processOAuthCallback(c));
 
 // Unauthenticated routes BEFORE the guard
-app.route('/health', healthRouter)
+app.route('/health', healthRouter);
 
 // Auth guard on /api/*
-app.use('/api/*', oidcAuthMiddleware())
+app.use('/api/*', oidcAuthMiddleware());
 
 // Protected routes after guard
-app.route('/api/me', meRouter)
-app.route('/api/events', eventsRouter)
+app.route('/api/me', meRouter);
+app.route('/api/events', eventsRouter);
 ```
 
 **Dev bypass mount pattern** — devBypass must be mounted BEFORE oidcAuthMiddleware:
+
 ```typescript
 // In dev: swap oidcAuthMiddleware for devAuthBypass when bypass is active
 // The bypass short-circuits the OIDC redirect entirely
-app.use('/api/*', devAuthBypass())  // no-op passthrough when NODE_ENV=production or flag not set
-app.use('/api/*', oidcAuthMiddleware())
+app.use('/api/*', devAuthBypass()); // no-op passthrough when NODE_ENV=production or flag not set
+app.use('/api/*', oidcAuthMiddleware());
 // Note: devAuthBypass sets c.set('user', DEV_USER) so oidcAuthMiddleware is still called
 // but getAuth(c) will find the injected user. See RESEARCH.md Pattern 5 for alternate approach.
 ```
@@ -260,45 +272,49 @@ app.use('/api/*', oidcAuthMiddleware())
 **Analog:** `apps/api/tests/broker/poller.test.ts`
 
 **Test file structure** (lines 1–14 of poller.test.ts):
+
 ```typescript
-import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest'
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 
 // vi.mock hoisted to module top by Vitest
 vi.mock('../../src/broker/sync.js', () => ({
   syncCalendar: mockSyncCalendar,
-}))
+}));
 ```
 
 **describe/it/expect pattern** (lines 71–121 of poller.test.ts):
+
 ```typescript
 describe('broker poller — runPoll', () => {
   beforeEach(() => {
-    vi.clearAllMocks()
+    vi.clearAllMocks();
     // reset arrays and mock implementations
-  })
+  });
 
   it('skips syncCalendar when ctag is unchanged', async () => {
-    const { runPoll } = await import('../../src/broker/poller.js')
+    const { runPoll } = await import('../../src/broker/poller.js');
     // arrange
-    await runPoll()
+    await runPoll();
     // assert
-    expect(mockSyncCalendar).not.toHaveBeenCalled()
-  })
-})
+    expect(mockSyncCalendar).not.toHaveBeenCalled();
+  });
+});
 ```
 
 **Error resilience test pattern** (lines 176–195 of poller.test.ts):
+
 ```typescript
 it('handles decryptPassword failure gracefully without crashing the poller', async () => {
-  ;(decryptPassword as Mock).mockImplementationOnce(() => {
-    throw new Error('Decryption failed')
-  })
-  await expect(runPoll()).resolves.not.toThrow()
-  expect(mockSyncCalendar).not.toHaveBeenCalled()
-})
+  (decryptPassword as Mock).mockImplementationOnce(() => {
+    throw new Error('Decryption failed');
+  });
+  await expect(runPoll()).resolves.not.toThrow();
+  expect(mockSyncCalendar).not.toHaveBeenCalled();
+});
 ```
 
 **Fixture files** — create in `apps/api/tests/fixtures/` (new directory):
+
 - `weekly-dst.ics` — weekly RRULE spanning March DST (America/New_York)
 - `allday-birthday.ics` — DATE-type annual event, no DTEND
 - `exdate-series.ics` — weekly series with one EXDATE
@@ -310,24 +326,25 @@ it('handles decryptPassword failure gracefully without crashing the poller', asy
 **Analog:** `apps/api/tests/health.test.ts`
 
 **Route test pattern** (lines 1–38 of health.test.ts):
+
 ```typescript
-import { describe, it, expect, vi } from 'vitest'
+import { describe, it, expect, vi } from 'vitest';
 
 vi.mock('../src/db/client.js', () => ({
   db: {
     execute: vi.fn().mockResolvedValue([[{ '1': 1 }]]),
   },
-}))
+}));
 
 describe('GET /health', () => {
   it('returns 200 with { ok: true, db: "up" } when DB round-trip succeeds', async () => {
-    const { app } = await import('../src/index.js')
-    const res = await app.request('/health')
-    expect(res.status).toBe(200)
-    const body = await res.json() as { ok: boolean; db: string }
-    expect(body.ok).toBe(true)
-  })
-})
+    const { app } = await import('../src/index.js');
+    const res = await app.request('/health');
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean; db: string };
+    expect(body.ok).toBe(true);
+  });
+});
 ```
 
 **app.request() pattern for Hono route tests** — use `app.request('/api/events?start=2026-06-01&end=2026-07-01')` following the same import-in-test pattern.
@@ -340,14 +357,14 @@ describe('GET /health', () => {
 
 ```typescript
 // Copy this exactly, add jsdom environment for React:
-import { defineConfig } from 'vitest/config'
+import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    environment: 'jsdom',  // differs from API (node)
+    environment: 'jsdom', // differs from API (node)
     globals: true,
   },
-})
+});
 ```
 
 ---
@@ -357,32 +374,38 @@ export default defineConfig({
 **Analog:** self
 
 **Existing function pattern to copy** (lines 22–34 of client.ts):
+
 ```typescript
 export async function fetchMe(): Promise<MeResponse> {
   const res = await fetch('/api/me', {
     credentials: 'include',
-  })
+  });
   if (!res.ok) {
-    throw new Error(`GET /api/me failed: ${res.status}`)
+    throw new Error(`GET /api/me failed: ${res.status}`);
   }
-  return res.json() as Promise<MeResponse>
+  return res.json() as Promise<MeResponse>;
 }
 ```
 
 **New `fetchEvents` must follow same shape:**
+
 ```typescript
 // Replace the existing fetchEvents (no-window version) with a windowed version:
-export interface CalendarOccurrence { /* from shared types */ }
-export interface OccurrencesResponse { occurrences: CalendarOccurrence[] }
+export interface CalendarOccurrence {
+  /* from shared types */
+}
+export interface OccurrencesResponse {
+  occurrences: CalendarOccurrence[];
+}
 
 export async function fetchEvents(start: string, end: string): Promise<OccurrencesResponse> {
   const res = await fetch(`/api/events?start=${start}&end=${end}`, {
     credentials: 'include',
-  })
+  });
   if (!res.ok) {
-    throw new Error(`GET /api/events failed: ${res.status}`)
+    throw new Error(`GET /api/events failed: ${res.status}`);
   }
-  return res.json() as Promise<OccurrencesResponse>
+  return res.json() as Promise<OccurrencesResponse>;
 }
 ```
 
@@ -393,23 +416,26 @@ export async function fetchEvents(start: string, end: string): Promise<Occurrenc
 **Analog:** `apps/pwa/src/api/client.ts` (typed transform pattern)
 
 **Interface definition pattern** (lines 12–16 of client.ts):
+
 ```typescript
 export interface MeUser {
-  id: number
-  displayName: string | null
-  color: string
+  id: number;
+  displayName: string | null;
+  color: string;
 }
 ```
 
 **Function export pattern** (lines 22–34 of client.ts):
+
 ```typescript
 export async function fetchMe(): Promise<MeResponse> { ... }
 // → hydrateEvents follows same: export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent[]
 ```
 
 **Temporal polyfill import** — must be registered before any Temporal usage:
+
 ```typescript
-import 'temporal-polyfill/global'  // registers Temporal on globalThis; import in main.tsx first
+import 'temporal-polyfill/global'; // registers Temporal on globalThis; import in main.tsx first
 ```
 
 ---
@@ -419,14 +445,16 @@ import 'temporal-polyfill/global'  // registers Temporal on globalThis; import i
 **Analog:** `apps/pwa/src/api/client.ts` (typed constants + factory function)
 
 **Exported constant pattern** (lines 12–16 of client.ts as reference for typed exports):
+
 ```typescript
-export const WEEK_START_DAY = 0  // 0 = Sunday; Schedule-X uses 7 = Sunday (translate before passing)
+export const WEEK_START_DAY = 0; // 0 = Sunday; Schedule-X uses 7 = Sunday (translate before passing)
 ```
 
 **Key translation note** — document inline per RESEARCH.md:
+
 ```typescript
 // WEEK_START_DAY=0 (JS/date-fns Sunday) → Schedule-X firstDayOfWeek=7 (Temporal Sunday)
-const sxFirstDay = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY
+const sxFirstDay = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY;
 ```
 
 ---
@@ -436,6 +464,7 @@ const sxFirstDay = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY
 **Analog:** `apps/pwa/src/App.tsx` (ColorSwatch inline style, lines 18–34)
 
 **Color inline style pattern to extend** (lines 18–34 of App.tsx):
+
 ```typescript
 function ColorSwatch({ color }: { color: string }) {
   return (
@@ -451,15 +480,20 @@ function ColorSwatch({ color }: { color: string }) {
 ```
 
 **Target function signatures:**
+
 ```typescript
 // container = main hex at 15% opacity blended over white
-export function hexToContainer(hex: string): string  // returns CSS hex or rgba
+export function hexToContainer(hex: string): string; // returns CSS hex or rgba
 
 // onContainer = main hex darkened 40%
-export function hexToOnContainer(hex: string): string
+export function hexToOnContainer(hex: string): string;
 
 // convenience: all three for Schedule-X lightColors
-export function deriveScheduleXColors(main: string): { main: string; container: string; onContainer: string }
+export function deriveScheduleXColors(main: string): {
+  main: string;
+  container: string;
+  onContainer: string;
+};
 ```
 
 ---
@@ -471,14 +505,14 @@ export function deriveScheduleXColors(main: string): { main: string; container:
 ```typescript
 // State shape from UI-SPEC § State Management Contract:
 interface CalendarStore {
-  selectedView: string                    // persisted in localStorage per breakpointGroup
-  selectedDate: string                    // ISO string; not persisted
-  openEventId: string | null              // null = popover closed
-  calendarRange: { start: string; end: string }  // drives TanStack Query key
-  setSelectedView: (view: string) => void
-  setSelectedDate: (date: string) => void
-  setOpenEventId: (id: string | null) => void
-  setCalendarRange: (range: { start: string; end: string }) => void
+  selectedView: string; // persisted in localStorage per breakpointGroup
+  selectedDate: string; // ISO string; not persisted
+  openEventId: string | null; // null = popover closed
+  calendarRange: { start: string; end: string }; // drives TanStack Query key
+  setSelectedView: (view: string) => void;
+  setSelectedDate: (date: string) => void;
+  setOpenEventId: (id: string | null) => void;
+  setCalendarRange: (range: { start: string; end: string }) => void;
 }
 ```
 
@@ -489,26 +523,29 @@ interface CalendarStore {
 **Analog:** `apps/pwa/src/App.tsx`
 
 **TanStack Query usage pattern** (lines 58–63 of App.tsx):
+
 ```typescript
 const meQuery = useQuery({
   queryKey: ['me'],
   queryFn: fetchMe,
   retry: false,
   staleTime: 5 * 60 * 1000,
-})
+});
 ```
 
 **Events query — extend this pattern:**
+
 ```typescript
 const eventsQuery = useQuery({
   queryKey: ['events', start, end],
   queryFn: () => fetchEvents(start, end),
   retry: 2,
   staleTime: 5 * 60 * 1000,
-})
+});
 ```
 
 **Loading/error conditional render pattern** (lines 77–92 of App.tsx):
+
 ```typescript
 {meQuery.isLoading && (
   <div style={{ color: '#666', marginBottom: '1rem' }}>Loading...</div>
@@ -522,6 +559,7 @@ const eventsQuery = useQuery({
 ```
 
 **Component file structure** (App.tsx overall shape):
+
 - Inline interfaces at top
 - Sub-components declared before default export
 - Default export is the root component
@@ -534,6 +572,7 @@ const eventsQuery = useQuery({
 **Analog:** `apps/pwa/src/App.tsx` (MemberBadge component, lines 36–55)
 
 **Component prop interface pattern** (lines 36–38 of App.tsx):
+
 ```typescript
 function MemberBadge({ user }: { user: MeUser }) {
   return (
@@ -541,15 +580,17 @@ function MemberBadge({ user }: { user: MeUser }) {
 ```
 
 **Target interface:**
+
 ```typescript
 interface EventDetailPopoverProps {
-  eventId: string | null     // null = closed
-  onClose: () => void
+  eventId: string | null; // null = closed
+  onClose: () => void;
   // event data resolved from Zustand openEventId → TanStack Query cache lookup
 }
 ```
 
 **Accessibility pattern** from UI-SPEC:
+
 - Focus trap while open; Escape closes
 - Close button: `aria-label="Close"`; min 44px touch target
 - Never use `dangerouslySetInnerHTML` for event title/description (XSS guard)
@@ -561,6 +602,7 @@ interface EventDetailPopoverProps {
 **Analog:** `apps/pwa/src/App.tsx` loading state (lines 77–80)
 
 **Loading pattern to replace:**
+
 ```typescript
 {meQuery.isLoading && (
   <div style={{ color: '#666', marginBottom: '1rem' }}>Loading...</div>
@@ -568,17 +610,23 @@ interface EventDetailPopoverProps {
 ```
 
 **Skeleton shimmer approach** — CSS animation, no third-party library:
+
 ```css
 /* In tokens.css or inline: */
 @keyframes shimmer {
-  0% { background-position: -200% 0; }
-  100% { background-position: 200% 0; }
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
 }
 /* Apply: background: linear-gradient(90deg, var(--color-surface-dim), var(--color-border-subtle), var(--color-surface-dim));
    background-size: 200% 100%; animation: shimmer 1.5s infinite; */
 ```
 
 **aria-busy pattern** per UI-SPEC:
+
 ```tsx
 <div aria-busy="true" aria-label="Loading calendar">
   {/* shimmer placeholders */}
@@ -592,6 +640,7 @@ interface EventDetailPopoverProps {
 **Analog:** self
 
 **Current structure** (lines 1–21 of main.tsx):
+
 ```typescript
 import React from 'react'
 import ReactDOM from 'react-dom/client'
@@ -617,10 +666,11 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 ```
 
 **Add before all other imports** (Temporal polyfill must be first):
+
 ```typescript
-import 'temporal-polyfill/global'          // registers Temporal on globalThis FIRST
-import '@schedule-x/theme-default/dist/index.css'  // Schedule-X layout engine CSS
-import './styles/tokens.css'               // token overrides (must come after SX CSS)
+import 'temporal-polyfill/global'; // registers Temporal on globalThis FIRST
+import '@schedule-x/theme-default/dist/index.css'; // Schedule-X layout engine CSS
+import './styles/tokens.css'; // token overrides (must come after SX CSS)
 ```
 
 ---
@@ -628,91 +678,112 @@ import './styles/tokens.css'               // token overrides (must come after S
 ## Shared Patterns
 
 ### Authentication Guard (all API routes)
+
 **Source:** `apps/api/src/index.ts` lines 24–29
+
 ```typescript
-app.use('/api/*', oidcAuthMiddleware())
-app.route('/api/me', meRouter)
-app.route('/api/events', eventsRouter)
+app.use('/api/*', oidcAuthMiddleware());
+app.route('/api/me', meRouter);
+app.route('/api/events', eventsRouter);
 ```
+
 **Apply to:** All new/modified route files. Dev bypass mounts before this, not instead.
 
 ### Hono Route Error Handling
+
 **Source:** `apps/api/src/routes/health.ts` lines 16–26
+
 ```typescript
 try {
-  await db.execute(sql`SELECT 1`)
-  return c.json({ ok: true, db: 'up' })
+  await db.execute(sql`SELECT 1`);
+  return c.json({ ok: true, db: 'up' });
 } catch (err) {
-  console.error('[health] DB round-trip failed:', err)
-  return c.json({ ok: false, db: 'down' }, 503)
+  console.error('[health] DB round-trip failed:', err);
+  return c.json({ ok: false, db: 'down' }, 503);
 }
 ```
+
 **Apply to:** `routes/events.ts` — wrap the windowed query + expansion in try/catch, return 503 on DB error.
 
 ### Drizzle Upsert Pattern
+
 **Source:** `apps/api/src/broker/sync.ts` lines 39–56
+
 ```typescript
 await db
   .insert(calendars)
   .values({ ... })
   .onDuplicateKeyUpdate({ set: { ... } })
 ```
+
 **Apply to:** Any schema migration that adds columns — upsert pattern unchanged.
 
 ### D-13 allDay Discrimination
+
 **Source:** `apps/api/src/broker/sync.ts` lines 88–98
+
 ```typescript
-const allDay: boolean = dtstart?.isDate ?? false
+const allDay: boolean = dtstart?.isDate ?? false;
 // dtstartDate: for all-day, convert YYYY-MM-DD → Date at midnight UTC
 const dtstartDateValue: Date | null =
-  allDay && dtstart ? new Date(dtstart.toString().slice(0, 10) + 'T00:00:00Z') : null
-const dtstartUtcValue: Date | null = !allDay && dtstart ? dtstart.toJSDate() : null
+  allDay && dtstart ? new Date(dtstart.toString().slice(0, 10) + 'T00:00:00Z') : null;
+const dtstartUtcValue: Date | null = !allDay && dtstart ? dtstart.toJSDate() : null;
 ```
+
 **Apply to:** `broker/expand.ts` — preserve the same discrimination when building CalendarOccurrence output. All-day `start` field must be `'YYYY-MM-DD'` (not a datetime string). Timed `start` must be a timezone-offset ISO string.
 
 ### TanStack Query Usage
+
 **Source:** `apps/pwa/src/App.tsx` lines 58–70
+
 ```typescript
 const meQuery = useQuery({
   queryKey: ['me'],
   queryFn: fetchMe,
   retry: false,
   staleTime: 5 * 60 * 1000,
-})
+});
 ```
+
 **Apply to:** All data-fetching components. Events query uses `retry: 2`. Server data never enters Zustand.
 
 ### Fetch Client with Credentials
+
 **Source:** `apps/pwa/src/api/client.ts` lines 22–34
+
 ```typescript
-const res = await fetch('/api/me', { credentials: 'include' })
+const res = await fetch('/api/me', { credentials: 'include' });
 if (!res.ok) {
-  throw new Error(`GET /api/me failed: ${res.status}`)
+  throw new Error(`GET /api/me failed: ${res.status}`);
 }
-return res.json() as Promise<MeResponse>
+return res.json() as Promise<MeResponse>;
 ```
+
 **Apply to:** All new `client.ts` functions (`fetchEvents`). The `credentials: 'include'` is required for the OIDC session cookie.
 
 ### CSS Token Usage in Components
+
 **Source:** `apps/pwa/src/App.tsx` lines 37–55 (inline style approach)
+
 ```typescript
 style={{
   background: '#f0f9ff',       // ← Phase 1: hardcoded
   border: `2px solid ${user.color}`,
 }}
 ```
+
 **Apply to (Phase 2 rule):** Replace all hardcoded hex/px values with `var(--token-name)` CSS custom properties. The existing App.tsx hardcoded values must also be migrated. No hardcoded colors in any Phase 2 component.
 
 ---
 
 ## No Analog Found
 
-| File | Role | Data Flow | Reason |
-|------|------|-----------|--------|
-| `apps/pwa/src/styles/tokens.css` | utility | — | No CSS token layer exists; Phase 2 introduces it from scratch |
-| `apps/pwa/src/styles/tokens.ts` | utility | — | No TypeScript token mirror exists |
-| `apps/pwa/src/styles/index.css` | utility | — | No global CSS exists; current App.tsx uses inline styles only |
-| `apps/pwa/src/store/calendarStore.ts` | store | event-driven | No Zustand store exists in codebase yet; first Zustand usage |
+| File                                  | Role    | Data Flow    | Reason                                                        |
+| ------------------------------------- | ------- | ------------ | ------------------------------------------------------------- |
+| `apps/pwa/src/styles/tokens.css`      | utility | —            | No CSS token layer exists; Phase 2 introduces it from scratch |
+| `apps/pwa/src/styles/tokens.ts`       | utility | —            | No TypeScript token mirror exists                             |
+| `apps/pwa/src/styles/index.css`       | utility | —            | No global CSS exists; current App.tsx uses inline styles only |
+| `apps/pwa/src/store/calendarStore.ts` | store   | event-driven | No Zustand store exists in codebase yet; first Zustand usage  |
 
 ---
 

.planning/milestones/v1.0-phases/02-calendar-display/02-RESEARCH.md

@@ -7,6 +7,7 @@
 ---
 
 <user_constraints>
+
 ## User Constraints (from CONTEXT.md)
 
 ### Locked Decisions
@@ -37,18 +38,20 @@
 - Per-member show/hide filter (add when membership > 2).
 - Secondary timezone display toggle (v1.x).
 - Single-occurrence / "this and following" recurring edits (v1.x).
-</user_constraints>
+  </user_constraints>
 
 ---
 
 <phase_requirements>
+
 ## Phase Requirements
 
-| ID | Description | Research Support |
-|----|-------------|------------------|
-| CAL-02 | User sees a unified, color-coded calendar that aggregates every accessible calendar into one view | §Backend: /api/events evolution; §Frontend: Schedule-X calendars config with per-calendar lightColors |
-| CAL-03 | User can switch between week, month, day, and agenda/list views | §Schedule-X Views; all four views confirmed in @schedule-x/calendar v4.6.0 |
-| CAL-07 | User can create a recurring event and see all its occurrences expanded correctly (display portion only — creation is Phase 3) | §Recurrence expansion pipeline; §DST correctness; §All-day event handling |
+| ID     | Description                                                                                                                   | Research Support                                                                                      |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| CAL-02 | User sees a unified, color-coded calendar that aggregates every accessible calendar into one view                             | §Backend: /api/events evolution; §Frontend: Schedule-X calendars config with per-calendar lightColors |
+| CAL-03 | User can switch between week, month, day, and agenda/list views                                                               | §Schedule-X Views; all four views confirmed in @schedule-x/calendar v4.6.0                            |
+| CAL-07 | User can create a recurring event and see all its occurrences expanded correctly (display portion only — creation is Phase 3) | §Recurrence expansion pipeline; §DST correctness; §All-day event handling                             |
+
 </phase_requirements>
 
 ---
@@ -67,18 +70,18 @@ All-day event correctness is already partially solved by the D-13 schema split (
 
 ## Architectural Responsibility Map
 
-| Capability | Primary Tier | Secondary Tier | Rationale |
-|------------|-------------|----------------|-----------|
-| Event storage and polling | API / Backend | — | Phase 1 broker owns all Fastmail I/O; routes read MariaDB cache |
-| Recurrence expansion | API / Backend | — | Server expands to concrete occurrences for the requested window; client renders, never expands (D-09) |
-| All-day / timed discrimination | API / Backend | — | D-13 schema split already done in Phase 1; route must preserve and expose the distinction |
-| Color and ownership join | API / Backend | — | `calendars.userId → users.color` join lives closest to the data; frontend just reads the color hex |
-| Temporal object construction | Frontend (PWA) | — | Server sends plain strings; client converts to `Temporal.ZonedDateTime` / `Temporal.PlainDate` before Schedule-X |
-| Calendar rendering (views) | Frontend (PWA) | — | Schedule-X renders day/week/month/agenda in the browser |
-| Token layer / theming | Frontend (PWA) | — | CSS custom properties + TS token object; Schedule-X `--sx-color-*` vars overridden |
-| View state, selected date, open popover | Frontend (PWA) — Zustand | — | UI-only state; never server data |
-| Event list caching and re-fetch | Frontend (PWA) — TanStack Query | — | Cache key = `['events', start, end]`; invalidated on range change |
-| Dev-auth bypass | API / Backend | — | Env-flagged middleware injecting fixed user; never active in production |
+| Capability                              | Primary Tier                    | Secondary Tier | Rationale                                                                                                        |
+| --------------------------------------- | ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Event storage and polling               | API / Backend                   | —              | Phase 1 broker owns all Fastmail I/O; routes read MariaDB cache                                                  |
+| Recurrence expansion                    | API / Backend                   | —              | Server expands to concrete occurrences for the requested window; client renders, never expands (D-09)            |
+| All-day / timed discrimination          | API / Backend                   | —              | D-13 schema split already done in Phase 1; route must preserve and expose the distinction                        |
+| Color and ownership join                | API / Backend                   | —              | `calendars.userId → users.color` join lives closest to the data; frontend just reads the color hex               |
+| Temporal object construction            | Frontend (PWA)                  | —              | Server sends plain strings; client converts to `Temporal.ZonedDateTime` / `Temporal.PlainDate` before Schedule-X |
+| Calendar rendering (views)              | Frontend (PWA)                  | —              | Schedule-X renders day/week/month/agenda in the browser                                                          |
+| Token layer / theming                   | Frontend (PWA)                  | —              | CSS custom properties + TS token object; Schedule-X `--sx-color-*` vars overridden                               |
+| View state, selected date, open popover | Frontend (PWA) — Zustand        | —              | UI-only state; never server data                                                                                 |
+| Event list caching and re-fetch         | Frontend (PWA) — TanStack Query | —              | Cache key = `['events', start, end]`; invalidated on range change                                                |
+| Dev-auth bypass                         | API / Backend                   | —              | Env-flagged middleware injecting fixed user; never active in production                                          |
 
 ---
 
@@ -86,17 +89,17 @@ All-day event correctness is already partially solved by the D-13 schema split (
 
 ### Core (all versions verified against npm registry 2026-06-04)
 
-| Library | Version | Purpose | Why Standard |
-|---------|---------|---------|--------------|
-| `@schedule-x/calendar` | 4.6.0 | Calendar engine (views, Temporal-based event model) | Selected in UI-SPEC; active maintenance; last published 2026-05-12 |
-| `@schedule-x/react` | 4.1.0 | React adapter (`useCalendarApp`, `ScheduleXCalendar`) | Official React adapter; peer-requires `@schedule-x/calendar ^3.1.0 \|\| ^4.0.0`; 4.6.0 satisfies this |
-| `@schedule-x/theme-default` | 4.6.0 | Default CSS layout; overridden by project tokens | Required for Schedule-X internal layout engine; all colors are token-overridden |
-| `@schedule-x/event-modal` | 4.6.0 | `createEventModalPlugin()` for custom `eventModal` component | Required to replace default modal with `EventDetailPopover` |
-| `@schedule-x/events-service` | 4.6.0 | `createEventsServicePlugin()` for dynamic event updates | Required to update events after TanStack Query fetches new window |
-| `temporal-polyfill` | 0.3.2 | `Temporal` global polyfill for browsers without native support | `@schedule-x/calendar` peer-requires `temporal-polyfill@0.3.0`; 0.3.2 satisfies |
-| `lucide-react` | 1.17.0 | Icon library (CalendarDays, X, MapPin, ChevronLeft/Right) | Specified in UI-SPEC; tree-shakeable; active maintenance |
-| `ical.js` | 2.2.1 | VEVENT parse + `ICAL.RecurExpansion` for recurrence | Already in both `apps/api` and `apps/pwa`; Phase 1 pattern established |
-| `rrule` | 2.8.1 | RRULE string parsing (used only if `ICAL.RecurExpansion` is insufficient) | Already in project stack per CLAUDE.md; last pub 2023-11-10 — treat as stable |
+| Library                      | Version | Purpose                                                                   | Why Standard                                                                                          |
+| ---------------------------- | ------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `@schedule-x/calendar`       | 4.6.0   | Calendar engine (views, Temporal-based event model)                       | Selected in UI-SPEC; active maintenance; last published 2026-05-12                                    |
+| `@schedule-x/react`          | 4.1.0   | React adapter (`useCalendarApp`, `ScheduleXCalendar`)                     | Official React adapter; peer-requires `@schedule-x/calendar ^3.1.0 \|\| ^4.0.0`; 4.6.0 satisfies this |
+| `@schedule-x/theme-default`  | 4.6.0   | Default CSS layout; overridden by project tokens                          | Required for Schedule-X internal layout engine; all colors are token-overridden                       |
+| `@schedule-x/event-modal`    | 4.6.0   | `createEventModalPlugin()` for custom `eventModal` component              | Required to replace default modal with `EventDetailPopover`                                           |
+| `@schedule-x/events-service` | 4.6.0   | `createEventsServicePlugin()` for dynamic event updates                   | Required to update events after TanStack Query fetches new window                                     |
+| `temporal-polyfill`          | 0.3.2   | `Temporal` global polyfill for browsers without native support            | `@schedule-x/calendar` peer-requires `temporal-polyfill@0.3.0`; 0.3.2 satisfies                       |
+| `lucide-react`               | 1.17.0  | Icon library (CalendarDays, X, MapPin, ChevronLeft/Right)                 | Specified in UI-SPEC; tree-shakeable; active maintenance                                              |
+| `ical.js`                    | 2.2.1   | VEVENT parse + `ICAL.RecurExpansion` for recurrence                       | Already in both `apps/api` and `apps/pwa`; Phase 1 pattern established                                |
+| `rrule`                      | 2.8.1   | RRULE string parsing (used only if `ICAL.RecurExpansion` is insufficient) | Already in project stack per CLAUDE.md; last pub 2023-11-10 — treat as stable                         |
 
 ### No New Backend Dependencies Needed
 
@@ -119,20 +122,20 @@ pnpm add @schedule-x/calendar@4.6.0 @schedule-x/react@4.1.0 @schedule-x/theme-de
 
 slopcheck was not available at research time. All packages below were verified via official documentation or established source repos. No packages flagged as suspicious by manual review.
 
-| Package | Registry | Age | Source Repo | Postinstall | Disposition |
-|---------|----------|-----|-------------|-------------|-------------|
-| `@schedule-x/calendar` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
-| `@schedule-x/react` | npm | 2+ yrs | github.com/schedule-x/react | none | Approved |
-| `@schedule-x/theme-default` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
-| `@schedule-x/event-modal` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
-| `@schedule-x/events-service` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
-| `temporal-polyfill` | npm | 2+ yrs | github.com/fullcalendar/temporal-polyfill | none | Approved |
-| `lucide-react` | npm | 4+ yrs | github.com/lucide-icons/lucide | none | Approved |
+| Package                      | Registry | Age    | Source Repo                               | Postinstall | Disposition |
+| ---------------------------- | -------- | ------ | ----------------------------------------- | ----------- | ----------- |
+| `@schedule-x/calendar`       | npm      | 2+ yrs | github.com/schedule-x/schedule-x          | none        | Approved    |
+| `@schedule-x/react`          | npm      | 2+ yrs | github.com/schedule-x/react               | none        | Approved    |
+| `@schedule-x/theme-default`  | npm      | 2+ yrs | github.com/schedule-x/schedule-x          | none        | Approved    |
+| `@schedule-x/event-modal`    | npm      | 2+ yrs | github.com/schedule-x/schedule-x          | none        | Approved    |
+| `@schedule-x/events-service` | npm      | 2+ yrs | github.com/schedule-x/schedule-x          | none        | Approved    |
+| `temporal-polyfill`          | npm      | 2+ yrs | github.com/fullcalendar/temporal-polyfill | none        | Approved    |
+| `lucide-react`               | npm      | 4+ yrs | github.com/lucide-icons/lucide            | none        | Approved    |
 
 **Packages removed due to slopcheck [SLOP] verdict:** none
 **Packages flagged as suspicious [SUS]:** none
 
-*slopcheck was unavailable at research time. All packages are tagged [VERIFIED: npm registry] based on official source repos confirmed via npm view. Planner should add `checkpoint:human-verify` before install if extra caution is warranted — this two-person household app is self-hosted with no third-party attack surface for these well-established packages.*
+_slopcheck was unavailable at research time. All packages are tagged [VERIFIED: npm registry] based on official source repos confirmed via npm view. Planner should add `checkpoint:human-verify` before install if extra caution is warranted — this two-person household app is self-hosted with no third-party attack surface for these well-established packages._
 
 ---
 
@@ -222,23 +225,23 @@ apps/
 ```typescript
 // apps/api/src/broker/expand.ts
 // Source: https://github.com/kewisch/ical.js/wiki/Common-Use-Cases
-import ICAL from 'ical.js'
+import ICAL from 'ical.js';
 
 export interface CalendarOccurrence {
-  id: string          // `${uid}::${dtstart_iso}` — stable identity for Schedule-X
-  uid: string
-  calendarId: number
-  calendarName: string
-  ownerUserId: number
-  color: string       // hex from users.color or shared-family constant
-  isShared: boolean   // true when calendar is the shared-family calendar
-  title: string
-  start: string       // ISO 8601 with timezone offset: '2026-06-15T10:00:00+02:00[America/Toronto]'
-                      // for all-day: 'DATE:2026-06-15' — use a distinct format so client knows
-  end: string
-  allDay: boolean
-  location: string | null
-  description: string | null
+  id: string; // `${uid}::${dtstart_iso}` — stable identity for Schedule-X
+  uid: string;
+  calendarId: number;
+  calendarName: string;
+  ownerUserId: number;
+  color: string; // hex from users.color or shared-family constant
+  isShared: boolean; // true when calendar is the shared-family calendar
+  title: string;
+  start: string; // ISO 8601 with timezone offset: '2026-06-15T10:00:00+02:00[America/Toronto]'
+  // for all-day: 'DATE:2026-06-15' — use a distinct format so client knows
+  end: string;
+  allDay: boolean;
+  location: string | null;
+  description: string | null;
 }
 
 export function expandOccurrences(
@@ -251,24 +254,24 @@ export function expandOccurrences(
   color: string,
   isShared: boolean,
 ): CalendarOccurrence[] {
-  const parsed = ICAL.parse(rawVevent)
-  const comp = new ICAL.Component(parsed)
+  const parsed = ICAL.parse(rawVevent);
+  const comp = new ICAL.Component(parsed);
 
   // CRITICAL: Register VTIMEZONE components before RecurExpansion
   // Without this, RecurExpansion uses UTC and DST transitions produce wrong wall-clock times
   for (const vtimezone of comp.getAllSubcomponents('vtimezone')) {
-    const tzid = vtimezone.getFirstPropertyValue('tzid') as string
+    const tzid = vtimezone.getFirstPropertyValue('tzid') as string;
     if (tzid && !ICAL.TimezoneService.has(tzid)) {
-      ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component: vtimezone, tzid }))
+      ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component: vtimezone, tzid }));
     }
   }
 
-  const vevent = comp.getFirstSubcomponent('vevent')
-  if (!vevent) return []
+  const vevent = comp.getFirstSubcomponent('vevent');
+  if (!vevent) return [];
 
-  const event = new ICAL.Event(vevent)
-  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time
-  const uid = event.uid
+  const event = new ICAL.Event(vevent);
+  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time;
+  const uid = event.uid;
 
   // Non-recurring event: single occurrence check
   if (!event.isRecurring()) {
@@ -276,19 +279,19 @@ export function expandOccurrences(
   }
 
   // Recurring event: use RecurExpansion
-  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart })
-  const rangeStart = ICAL.Time.fromJSDate(windowStart, /* useUtc */ false)
-  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, /* useUtc */ false)
+  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart });
+  const rangeStart = ICAL.Time.fromJSDate(windowStart, /* useUtc */ false);
+  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, /* useUtc */ false);
 
-  const occurrences: CalendarOccurrence[] = []
-  let next: ICAL.Time | null
+  const occurrences: CalendarOccurrence[] = [];
+  let next: ICAL.Time | null;
 
   while ((next = expand.next()) && next.compare(rangeEnd) < 0) {
-    if (next.compare(rangeStart) < 0) continue
+    if (next.compare(rangeStart) < 0) continue;
     // Build occurrence, compute end from duration
     // ...
   }
-  return occurrences
+  return occurrences;
 }
 ```
 
@@ -303,19 +306,19 @@ export function expandOccurrences(
 ```typescript
 // apps/pwa/src/lib/hydrateEvents.ts
 // Source: https://schedule-x.dev/docs/calendar/events
-import 'temporal-polyfill/global'  // registers Temporal on globalThis
-import type { CalendarOccurrence } from '@familysync/shared'  // server type
+import 'temporal-polyfill/global'; // registers Temporal on globalThis
+import type { CalendarOccurrence } from '@familysync/shared'; // server type
 
 export interface ScheduleXEvent {
-  id: string
-  title: string
-  start: Temporal.ZonedDateTime | Temporal.PlainDate
-  end: Temporal.ZonedDateTime | Temporal.PlainDate
-  calendarId: string  // must be string matching the key in calendars config
-  location?: string
-  description?: string
+  id: string;
+  title: string;
+  start: Temporal.ZonedDateTime | Temporal.PlainDate;
+  end: Temporal.ZonedDateTime | Temporal.PlainDate;
+  calendarId: string; // must be string matching the key in calendars config
+  location?: string;
+  description?: string;
   // custom business fields pass through
-  _familySync?: { uid: string; color: string; isShared: boolean }
+  _familySync?: { uid: string; color: string; isShared: boolean };
 }
 
 export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent[] {
@@ -325,11 +328,11 @@ export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent
       return {
         id: occ.id,
         title: occ.title,
-        start: Temporal.PlainDate.from(occ.start),  // occ.start is 'YYYY-MM-DD'
+        start: Temporal.PlainDate.from(occ.start), // occ.start is 'YYYY-MM-DD'
         end: Temporal.PlainDate.from(occ.end),
         calendarId: String(occ.calendarId),
         _familySync: { uid: occ.uid, color: occ.color, isShared: occ.isShared },
-      }
+      };
     }
     // Timed: use ZonedDateTime from the offset-aware ISO string the server returns
     return {
@@ -341,8 +344,8 @@ export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent
       location: occ.location ?? undefined,
       description: occ.description ?? undefined,
       _familySync: { uid: occ.uid, color: occ.color, isShared: occ.isShared },
-    }
-  })
+    };
+  });
 }
 ```
 
@@ -357,51 +360,54 @@ import {
   createViewWeek,
   createViewMonthGrid,
   createViewMonthAgenda,
-} from '@schedule-x/calendar'
-import { createEventsServicePlugin } from '@schedule-x/events-service'
-import { createEventModalPlugin } from '@schedule-x/event-modal'
+} from '@schedule-x/calendar';
+import { createEventsServicePlugin } from '@schedule-x/events-service';
+import { createEventModalPlugin } from '@schedule-x/event-modal';
 
-export const WEEK_START_DAY = 0  // 0 = Sunday in project convention; Schedule-X uses 7 = Sunday
+export const WEEK_START_DAY = 0; // 0 = Sunday in project convention; Schedule-X uses 7 = Sunday
 
 // Schedule-X v4 firstDayOfWeek: Temporal numbering — 1=Mon, 7=Sun
 // Must translate from project convention (0=Sun) to Schedule-X (7=Sun)
 function toSXWeekStart(dayConvention: number): number {
-  return dayConvention === 0 ? 7 : dayConvention
+  return dayConvention === 0 ? 7 : dayConvention;
 }
 
 export interface MemberCalendarConfig {
-  id: string        // String(users.id)
-  name: string      // users.displayName
-  color: string     // users.color hex
+  id: string; // String(users.id)
+  name: string; // users.displayName
+  color: string; // users.color hex
 }
 
 export function buildCalendarConfig(members: MemberCalendarConfig[]) {
-  const calendars: Record<string, { colorName: string; lightColors: { main: string; container: string; onContainer: string } }> = {}
+  const calendars: Record<
+    string,
+    { colorName: string; lightColors: { main: string; container: string; onContainer: string } }
+  > = {};
 
   // Shared-family calendar: reserved rose color
   calendars['shared'] = {
     colorName: 'shared',
     lightColors: deriveScheduleXColors('#F25C7A'),
-  }
+  };
 
   // Per-member calendars keyed by String(userId)
   for (const m of members) {
     calendars[m.id] = {
       colorName: `member-${m.id}`,
       lightColors: deriveScheduleXColors(m.color),
-    }
+    };
   }
 
-  return { calendars }
+  return { calendars };
 }
 
 // UI-SPEC color derivation: container = main at 15% opacity over white, onContainer = main darkened 40%
 function deriveScheduleXColors(main: string) {
   return {
     main,
-    container: hexWithOpacity(main, 0.15),   // CSS rgba computed over #FFFFFF
+    container: hexWithOpacity(main, 0.15), // CSS rgba computed over #FFFFFF
     onContainer: darkenHex(main, 0.4),
-  }
+  };
 }
 ```
 
@@ -467,7 +473,7 @@ function CalendarShell() {
 // apps/api/src/auth/devBypass.ts
 // Active ONLY when DEV_AUTH_BYPASS=true AND NODE_ENV !== 'production'
 // Injects a fixed dev user into the request context so oidcAuthMiddleware is skipped
-import type { MiddlewareHandler } from 'hono'
+import type { MiddlewareHandler } from 'hono';
 
 const DEV_USER = {
   id: 1,
@@ -475,21 +481,21 @@ const DEV_USER = {
   oidcSub: 'dev-user',
   displayName: 'Dev User',
   color: '#4A90D9',
-}
+};
 
 export function devAuthBypass(): MiddlewareHandler {
   if (process.env.NODE_ENV === 'production') {
     // Hard guard — never active in production regardless of env flag
-    return async (_c, next) => next()
+    return async (_c, next) => next();
   }
   if (process.env.DEV_AUTH_BYPASS !== 'true') {
-    return async (_c, next) => next()
+    return async (_c, next) => next();
   }
   // Inject fixed dev user into Hono context (replaces getAuth(c) result)
   return async (c, next) => {
-    c.set('user', DEV_USER)
-    await next()
-  }
+    c.set('user', DEV_USER);
+    await next();
+  };
 }
 ```
 
@@ -509,14 +515,14 @@ Mount in `index.ts` BEFORE `oidcAuthMiddleware` on `/api/*` when bypass is activ
 
 ## Don't Hand-Roll
 
-| Problem | Don't Build | Use Instead | Why |
-|---------|-------------|-------------|-----|
-| Recurring event expansion with EXDATE | Custom RRULE iterator | `ICAL.RecurExpansion` | RecurExpansion handles RDATE, EXDATE, RECURRENCE-ID in one integrated iterator |
-| All four calendar views | Custom React grid | `@schedule-x/calendar` views | Day/week/month/agenda correctly handling overlap, all-day banners, and touch is 3-6 weeks of work |
-| Custom event modal | Custom DOM overlay | `createEventModalPlugin` + `customComponents.eventModal` | Schedule-X positions the modal relative to the event; re-use in Phase 3 is built-in |
-| VTIMEZONE DST tables | Custom offset lookup | `ICAL.TimezoneService.register()` from parsed VTIMEZONE | The VTIMEZONE component in the ICS already contains the correct DST rules for the calendar's timezone |
-| Calendar color derivation | Manual CSS computation | `colorUtils.ts` utility function (small, one-file) | The 15%/darken derivation is simple enough to implement inline; no third-party needed |
-| iCalendar string parsing | Custom VCALENDAR parser | `ICAL.parse()` + `ICAL.Component` | VCALENDAR has pathological edge cases (folded lines, UTF-8 encoded params, VTIMEZONE nesting) |
+| Problem                               | Don't Build             | Use Instead                                              | Why                                                                                                   |
+| ------------------------------------- | ----------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Recurring event expansion with EXDATE | Custom RRULE iterator   | `ICAL.RecurExpansion`                                    | RecurExpansion handles RDATE, EXDATE, RECURRENCE-ID in one integrated iterator                        |
+| All four calendar views               | Custom React grid       | `@schedule-x/calendar` views                             | Day/week/month/agenda correctly handling overlap, all-day banners, and touch is 3-6 weeks of work     |
+| Custom event modal                    | Custom DOM overlay      | `createEventModalPlugin` + `customComponents.eventModal` | Schedule-X positions the modal relative to the event; re-use in Phase 3 is built-in                   |
+| VTIMEZONE DST tables                  | Custom offset lookup    | `ICAL.TimezoneService.register()` from parsed VTIMEZONE  | The VTIMEZONE component in the ICS already contains the correct DST rules for the calendar's timezone |
+| Calendar color derivation             | Manual CSS computation  | `colorUtils.ts` utility function (small, one-file)       | The 15%/darken derivation is simple enough to implement inline; no third-party needed                 |
+| iCalendar string parsing              | Custom VCALENDAR parser | `ICAL.parse()` + `ICAL.Component`                        | VCALENDAR has pathological edge cases (folded lines, UTF-8 encoded params, VTIMEZONE nesting)         |
 
 **Key insight:** Calendar view rendering that handles overlap, drag handle exclusion zones, DST, all-day banners, and touch gestures for iOS correctly is multi-month work. Schedule-X exists precisely for this.
 
@@ -603,63 +609,60 @@ Mount in `index.ts` BEFORE `oidcAuthMiddleware` on `/api/*` when bypass is activ
 ```typescript
 // Source: https://github.com/kewisch/ical.js/wiki/Common-Use-Cases
 // Source: https://kewisch.github.io/ical.js/api/
-import ICAL from 'ical.js'
+import ICAL from 'ical.js';
 
 function expandVeventOccurrences(
   rawVcalendar: string,
   windowStart: Date,
   windowEnd: Date,
 ): Array<{ dtstart: Date; dtend: Date; allDay: boolean }> {
-  const parsed = ICAL.parse(rawVcalendar)
-  const comp = new ICAL.Component(parsed)
+  const parsed = ICAL.parse(rawVcalendar);
+  const comp = new ICAL.Component(parsed);
 
   // Step 1: Register all VTIMEZONE components in this VCALENDAR.
   // Must happen BEFORE constructing ICAL.RecurExpansion.
   for (const vtz of comp.getAllSubcomponents('vtimezone')) {
-    const tzid = vtz.getFirstPropertyValue('tzid') as string
+    const tzid = vtz.getFirstPropertyValue('tzid') as string;
     if (tzid && !ICAL.TimezoneService.has(tzid)) {
-      ICAL.TimezoneService.register(
-        tzid,
-        new ICAL.Timezone({ component: vtz, tzid }),
-      )
+      ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component: vtz, tzid }));
     }
   }
 
-  const vevent = comp.getFirstSubcomponent('vevent')
-  if (!vevent) return []
+  const vevent = comp.getFirstSubcomponent('vevent');
+  if (!vevent) return [];
 
-  const event = new ICAL.Event(vevent)
-  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time
-  const allDay = dtstart.isDate
+  const event = new ICAL.Event(vevent);
+  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time;
+  const allDay = dtstart.isDate;
 
-  const results: Array<{ dtstart: Date; dtend: Date; allDay: boolean }> = []
-  const rangeStart = ICAL.Time.fromJSDate(windowStart, false)
-  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, false)
+  const results: Array<{ dtstart: Date; dtend: Date; allDay: boolean }> = [];
+  const rangeStart = ICAL.Time.fromJSDate(windowStart, false);
+  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, false);
 
   if (!event.isRecurring()) {
     if (dtstart.compare(rangeStart) >= 0 && dtstart.compare(rangeEnd) < 0) {
-      const dtend = vevent.getFirstPropertyValue('dtend') as ICAL.Time | null
+      const dtend = vevent.getFirstPropertyValue('dtend') as ICAL.Time | null;
       results.push({
         dtstart: dtstart.toJSDate(),
         dtend: (dtend ?? dtstart).toJSDate(),
         allDay,
-      })
+      });
     }
-    return results
+    return results;
   }
 
   // RecurExpansion handles RRULE + RDATE + EXDATE internally
-  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart })
-  let next: ICAL.Time | null
+  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart });
+  let next: ICAL.Time | null;
   while ((next = expand.next()) && next.compare(rangeEnd) < 0) {
-    if (next.compare(rangeStart) < 0) continue
+    if (next.compare(rangeStart) < 0) continue;
     // Compute end using the original event's duration
-    const duration = event.duration
-    const occEnd = next.clone()
-    occEnd.addDuration(duration)
-    results.push({ dtstart: next.toJSDate(), dtend: occEnd.toJSDate(), allDay })
+    const duration = event.duration;
+    const occEnd = next.clone();
+    occEnd.addDuration(duration);
+    results.push({ dtstart: next.toJSDate(), dtend: occEnd.toJSDate(), allDay });
   }
-  return results
+  return results;
 }
 ```
 
@@ -671,10 +674,14 @@ function expandVeventOccurrences(
 // The client must use Temporal.PlainDate — NOT ZonedDateTime
 
 // WRONG (shifts date in negative-offset timezones):
-{ start: Temporal.ZonedDateTime.from('2026-06-15T00:00:00Z') }
+{
+  start: Temporal.ZonedDateTime.from('2026-06-15T00:00:00Z');
+}
 
 // CORRECT:
-{ start: Temporal.PlainDate.from('2026-06-15') }
+{
+  start: Temporal.PlainDate.from('2026-06-15');
+}
 ```
 
 ### Schedule-X CSS Token Override Pattern
@@ -689,7 +696,7 @@ function expandVeventOccurrences(
 
 :root {
   /* Map Schedule-X color vars to project tokens */
-  --sx-color-primary: var(--color-member-0);  /* current user's color */
+  --sx-color-primary: var(--color-member-0); /* current user's color */
   --sx-color-on-primary: #ffffff;
   --sx-color-surface: var(--color-surface);
   --sx-color-on-surface: var(--color-text-primary);
@@ -712,9 +719,9 @@ function expandVeventOccurrences(
 ```typescript
 // apps/api/src/routes/events.ts — current implementation
 eventsRouter.get('/', async (c) => {
-  const events = await db.select().from(calendarEvents)  // no window, no join, no expansion
-  return c.json({ events })
-})
+  const events = await db.select().from(calendarEvents); // no window, no join, no expansion
+  return c.json({ events });
+});
 ```
 
 ### Target state (Phase 2)
@@ -722,14 +729,14 @@ eventsRouter.get('/', async (c) => {
 ```typescript
 // apps/api/src/routes/events.ts — evolved
 eventsRouter.get('/', async (c) => {
-  const { start, end } = c.req.query()
+  const { start, end } = c.req.query();
   // Zod-validate start/end as ISO dates
   // SQL: calendarEvents JOIN calendars JOIN users
   //   WHERE (dtstartUtc BETWEEN start AND end) OR (dtstartDate BETWEEN start AND end)
   //      OR event.hasRrule (to catch recurring masters whose window occurrence may differ)
   // For each row: call expandOccurrences(rawVevent, windowStart, windowEnd, ...)
   // Return: { occurrences: CalendarOccurrence[] }
-})
+});
 ```
 
 **SQL pre-filter strategy:** The SQL `WHERE` must also include events with an RRULE property that _started before_ the window, because a weekly meeting created 3 years ago can still have occurrences in the current window. Include a `hasRrule` boolean column (can be added via migration) or parse `rawVevent` in the expansion step and skip in-memory if no occurrences fall in window. The simpler approach: include all events where `dtstartUtc < windowEnd` (no lower bound) OR `dtstartDate < windowEnd`, then let `expandOccurrences` handle the window check. Add a schema migration to add a `hasRrule` boolean indexed column to `calendarEvents` to avoid scanning all historical events on every request.
@@ -740,14 +747,15 @@ eventsRouter.get('/', async (c) => {
 
 ## State of the Art
 
-| Old Approach | Current Approach | When Changed | Impact |
-|--------------|------------------|--------------|--------|
-| Schedule-X ISO string events `"YYYY-MM-DD HH:MM"` | `Temporal.ZonedDateTime` / `Temporal.PlainDate` | Schedule-X v3 (2024) | Server must return parseable strings; client must hydrate |
-| `react-big-calendar` (moment/date-fns) | Schedule-X (Temporal-based) | 2024 ecosystem shift | react-big-calendar's CSS is hard to override; Schedule-X CSS tokens are first-class |
-| `FullCalendar` open-source | Schedule-X (fully MIT) | 2024 for self-hosted | FullCalendar premium features are commercial; Schedule-X is fully open |
-| rrule-only recurrence expansion | `ICAL.RecurExpansion` (higher-level) | ical.js 1.x+ | RecurExpansion integrates RRULE + RDATE + EXDATE; no separate EXDATE handling needed |
+| Old Approach                                      | Current Approach                                | When Changed         | Impact                                                                               |
+| ------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| Schedule-X ISO string events `"YYYY-MM-DD HH:MM"` | `Temporal.ZonedDateTime` / `Temporal.PlainDate` | Schedule-X v3 (2024) | Server must return parseable strings; client must hydrate                            |
+| `react-big-calendar` (moment/date-fns)            | Schedule-X (Temporal-based)                     | 2024 ecosystem shift | react-big-calendar's CSS is hard to override; Schedule-X CSS tokens are first-class  |
+| `FullCalendar` open-source                        | Schedule-X (fully MIT)                          | 2024 for self-hosted | FullCalendar premium features are commercial; Schedule-X is fully open               |
+| rrule-only recurrence expansion                   | `ICAL.RecurExpansion` (higher-level)            | ical.js 1.x+         | RecurExpansion integrates RRULE + RDATE + EXDATE; no separate EXDATE handling needed |
 
 **Deprecated/outdated:**
+
 - `react-big-calendar`: Not deprecated per se, but the CSS override story is significantly worse for a token-based design system. The UI-SPEC already rejected it.
 - Schedule-X v2 ISO string format: Removed in v3. Any tutorial older than mid-2024 using string dates is wrong.
 
@@ -757,36 +765,36 @@ eventsRouter.get('/', async (c) => {
 
 ### Test Framework
 
-| Property | Value |
-|----------|-------|
-| Framework | Vitest (already configured in `apps/api/vitest.config.ts`) |
-| Config file | `apps/api/vitest.config.ts` (exists); `apps/pwa` has no test setup — needs Wave 0 |
-| Quick run command | `pnpm --filter @familysync/api test` |
-| Full suite command | `pnpm -r test` (workspace-wide) |
+| Property           | Value                                                                             |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Framework          | Vitest (already configured in `apps/api/vitest.config.ts`)                        |
+| Config file        | `apps/api/vitest.config.ts` (exists); `apps/pwa` has no test setup — needs Wave 0 |
+| Quick run command  | `pnpm --filter @familysync/api test`                                              |
+| Full suite command | `pnpm -r test` (workspace-wide)                                                   |
 
 ### Phase Requirements → Test Map
 
-| Req ID | Behavior | Test Type | Automated Command | File Exists? |
-|--------|----------|-----------|-------------------|-------------|
-| CAL-02 (color) | Events returned with correct `color` field from `users.color` | unit | `pnpm --filter @familysync/api test -- tests/routes/events.test.ts` | ❌ Wave 0 |
-| CAL-02 (aggregation) | Events from multiple calendars (multiple users) returned in single response | unit | same file | ❌ Wave 0 |
-| CAL-03 (views) | Schedule-X renders without error with all four views configured | smoke | `pnpm --filter @familysync/pwa test -- calendar.spec.tsx` | ❌ Wave 0 |
-| CAL-07 (recurrence) | `expandOccurrences()` returns correct occurrences for weekly RRULE in a 30-day window | unit | `pnpm --filter @familysync/api test -- tests/broker/expand.test.ts` | ❌ Wave 0 |
-| CAL-07 (DST) | `expandOccurrences()` with America/New_York RRULE across March DST boundary returns correct wall-clock times | unit | same file | ❌ Wave 0 |
-| CAL-07 (all-day) | `expandOccurrences()` for all-day event returns `allDay: true` and `start: 'YYYY-MM-DD'` with no time component | unit | same file | ❌ Wave 0 |
-| CAL-07 (EXDATE) | `expandOccurrences()` excludes EXDATE occurrences from expansion | unit | same file | ❌ Wave 0 |
-| CAL-07 (Temporal) | `hydrateEvents()` converts all-day occurrences to `Temporal.PlainDate` and timed to `Temporal.ZonedDateTime` | unit | `pnpm --filter @familysync/pwa test -- lib/hydrateEvents.test.ts` | ❌ Wave 0 |
+| Req ID               | Behavior                                                                                                        | Test Type | Automated Command                                                   | File Exists? |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------- | ------------ |
+| CAL-02 (color)       | Events returned with correct `color` field from `users.color`                                                   | unit      | `pnpm --filter @familysync/api test -- tests/routes/events.test.ts` | ❌ Wave 0    |
+| CAL-02 (aggregation) | Events from multiple calendars (multiple users) returned in single response                                     | unit      | same file                                                           | ❌ Wave 0    |
+| CAL-03 (views)       | Schedule-X renders without error with all four views configured                                                 | smoke     | `pnpm --filter @familysync/pwa test -- calendar.spec.tsx`           | ❌ Wave 0    |
+| CAL-07 (recurrence)  | `expandOccurrences()` returns correct occurrences for weekly RRULE in a 30-day window                           | unit      | `pnpm --filter @familysync/api test -- tests/broker/expand.test.ts` | ❌ Wave 0    |
+| CAL-07 (DST)         | `expandOccurrences()` with America/New_York RRULE across March DST boundary returns correct wall-clock times    | unit      | same file                                                           | ❌ Wave 0    |
+| CAL-07 (all-day)     | `expandOccurrences()` for all-day event returns `allDay: true` and `start: 'YYYY-MM-DD'` with no time component | unit      | same file                                                           | ❌ Wave 0    |
+| CAL-07 (EXDATE)      | `expandOccurrences()` excludes EXDATE occurrences from expansion                                                | unit      | same file                                                           | ❌ Wave 0    |
+| CAL-07 (Temporal)    | `hydrateEvents()` converts all-day occurrences to `Temporal.PlainDate` and timed to `Temporal.ZonedDateTime`    | unit      | `pnpm --filter @familysync/pwa test -- lib/hydrateEvents.test.ts`   | ❌ Wave 0    |
 
 ### Fixture ICS Files (test corpus)
 
 The most valuable test artifacts are fixture `.ics` files. Create in `apps/api/tests/fixtures/`:
 
-| Filename | Contents | Tests |
-|----------|----------|-------|
-| `weekly-dst.ics` | Weekly meeting at 10:00 America/New_York spanning March DST transition (2026-03-01 to 2026-04-30) | CAL-07 DST |
-| `allday-birthday.ics` | Annual birthday event (DATE type, no DTEND) | CAL-07 all-day |
-| `exdate-series.ics` | Weekly series with one EXDATE (a skipped occurrence) | CAL-07 EXDATE |
-| `multi-cal.ics` | Two separate VCALENDAR blobs to represent two members' events | CAL-02 aggregation |
+| Filename              | Contents                                                                                          | Tests              |
+| --------------------- | ------------------------------------------------------------------------------------------------- | ------------------ |
+| `weekly-dst.ics`      | Weekly meeting at 10:00 America/New_York spanning March DST transition (2026-03-01 to 2026-04-30) | CAL-07 DST         |
+| `allday-birthday.ics` | Annual birthday event (DATE type, no DTEND)                                                       | CAL-07 all-day     |
+| `exdate-series.ics`   | Weekly series with one EXDATE (a skipped occurrence)                                              | CAL-07 EXDATE      |
+| `multi-cal.ics`       | Two separate VCALENDAR blobs to represent two members' events                                     | CAL-02 aggregation |
 
 These fixture files can be generated from real Fastmail ICS exports or hand-crafted with known-correct VTIMEZONE blocks.
 
@@ -813,34 +821,34 @@ These fixture files can be generated from real Fastmail ICS exports or hand-craf
 
 ### Applicable ASVS Categories
 
-| ASVS Category | Applies | Standard Control |
-|---------------|---------|-----------------|
-| V2 Authentication | yes — dev bypass must not leak | `NODE_ENV === 'production'` hard guard in `devAuthBypass()` |
-| V3 Session Management | carried from Phase 1 | `@hono/oidc-auth` JWT cookie (httpOnly + Secure + SameSite) |
-| V4 Access Control | yes — `/api/events` must be authenticated | `oidcAuthMiddleware` on `/api/*` (Phase 1 pattern) |
-| V5 Input Validation | yes — `?start=` and `?end=` query params | `zod` + `@hono/zod-validator`: validate ISO date format before SQL |
-| V6 Cryptography | no new crypto in Phase 2 | — |
+| ASVS Category         | Applies                                   | Standard Control                                                   |
+| --------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| V2 Authentication     | yes — dev bypass must not leak            | `NODE_ENV === 'production'` hard guard in `devAuthBypass()`        |
+| V3 Session Management | carried from Phase 1                      | `@hono/oidc-auth` JWT cookie (httpOnly + Secure + SameSite)        |
+| V4 Access Control     | yes — `/api/events` must be authenticated | `oidcAuthMiddleware` on `/api/*` (Phase 1 pattern)                 |
+| V5 Input Validation   | yes — `?start=` and `?end=` query params  | `zod` + `@hono/zod-validator`: validate ISO date format before SQL |
+| V6 Cryptography       | no new crypto in Phase 2                  | —                                                                  |
 
 ### Known Threat Patterns for This Phase
 
-| Pattern | STRIDE | Standard Mitigation |
-|---------|--------|---------------------|
-| Dev-auth bypass left active in production | Elevation of privilege | Hard `NODE_ENV !== 'production'` guard; `.env.example` warning |
-| SQL injection via `?start=` / `?end=` date params | Tampering | Zod ISO date validation; Drizzle parameterized queries |
-| XSS via event title/description in EventDetailPopover | Tampering | React's default JSX escaping; never use `dangerouslySetInnerHTML` for event fields |
-| Overfetch (no window) timing/DoS | Denial of service | Zod-enforce required `start` + `end` params; cap window to 90 days max |
+| Pattern                                               | STRIDE                 | Standard Mitigation                                                                |
+| ----------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
+| Dev-auth bypass left active in production             | Elevation of privilege | Hard `NODE_ENV !== 'production'` guard; `.env.example` warning                     |
+| SQL injection via `?start=` / `?end=` date params     | Tampering              | Zod ISO date validation; Drizzle parameterized queries                             |
+| XSS via event title/description in EventDetailPopover | Tampering              | React's default JSX escaping; never use `dangerouslySetInnerHTML` for event fields |
+| Overfetch (no window) timing/DoS                      | Denial of service      | Zod-enforce required `start` + `end` params; cap window to 90 days max             |
 
 ---
 
 ## Environment Availability
 
-| Dependency | Required By | Available | Version | Fallback |
-|------------|------------|-----------|---------|----------|
-| Node.js 22 | API + PWA build | ✓ | (WSL2 dev env — assumed from Phase 1) | — |
-| pnpm | Workspace install | ✓ | (Phase 1 used it) | — |
-| MariaDB (Docker) | `/api/events` windowed query | ✓ | Phase 1 confirmed: 503 events cached | — |
-| Temporal (browser) | Schedule-X v4 | Partial | Needs `temporal-polyfill` in PWA | `temporal-polyfill@0.3.2` — no fallback needed |
-| Live Authelia/Pangolin | Full auth flow | ✗ (D-14 deferred) | — | Dev-auth bypass middleware (must build in Phase 2) |
+| Dependency             | Required By                  | Available         | Version                               | Fallback                                           |
+| ---------------------- | ---------------------------- | ----------------- | ------------------------------------- | -------------------------------------------------- |
+| Node.js 22             | API + PWA build              | ✓                 | (WSL2 dev env — assumed from Phase 1) | —                                                  |
+| pnpm                   | Workspace install            | ✓                 | (Phase 1 used it)                     | —                                                  |
+| MariaDB (Docker)       | `/api/events` windowed query | ✓                 | Phase 1 confirmed: 503 events cached  | —                                                  |
+| Temporal (browser)     | Schedule-X v4                | Partial           | Needs `temporal-polyfill` in PWA      | `temporal-polyfill@0.3.2` — no fallback needed     |
+| Live Authelia/Pangolin | Full auth flow               | ✗ (D-14 deferred) | —                                     | Dev-auth bypass middleware (must build in Phase 2) |
 
 **Missing with no fallback:** None. Dev-auth bypass covers the Authelia deferral.
 
@@ -848,12 +856,12 @@ These fixture files can be generated from real Fastmail ICS exports or hand-craf
 
 ## Assumptions Log
 
-| # | Claim | Section | Risk if Wrong |
-|---|-------|---------|---------------|
-| A1 | `ICAL.RecurExpansion` handles EXDATE internally when using the high-level API | Architecture Patterns | Planner would need to add manual EXDATE filtering in `expandOccurrences` |
-| A2 | `@schedule-x/react@4.1.0` is API-compatible with `@schedule-x/calendar@4.6.0` for the features used (views, calendars, onRangeUpdate, customComponents) | Standard Stack | Version mismatch may cause TypeScript errors on newer options; test in Wave 0 |
-| A3 | The shared-family calendar can be identified programmatically (by displayName or a new `isShared` column) without a schema migration | Backend: /api/events evolution | If not deterministic, Phase 2 plan must include a migration adding `calendars.isShared` |
-| A4 | `onRangeUpdate` fires immediately on mount with the initial window | Architecture Patterns | If it does not fire on mount, initial fetch requires a separate first-render trigger |
+| #   | Claim                                                                                                                                                   | Section                        | Risk if Wrong                                                                           |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------- |
+| A1  | `ICAL.RecurExpansion` handles EXDATE internally when using the high-level API                                                                           | Architecture Patterns          | Planner would need to add manual EXDATE filtering in `expandOccurrences`                |
+| A2  | `@schedule-x/react@4.1.0` is API-compatible with `@schedule-x/calendar@4.6.0` for the features used (views, calendars, onRangeUpdate, customComponents) | Standard Stack                 | Version mismatch may cause TypeScript errors on newer options; test in Wave 0           |
+| A3  | The shared-family calendar can be identified programmatically (by displayName or a new `isShared` column) without a schema migration                    | Backend: /api/events evolution | If not deterministic, Phase 2 plan must include a migration adding `calendars.isShared` |
+| A4  | `onRangeUpdate` fires immediately on mount with the initial window                                                                                      | Architecture Patterns          | If it does not fire on mount, initial fetch requires a separate first-render trigger    |
 
 **A1 verification:** The ical.js wiki states RecurExpansion "takes into account recurrence exceptions (RDATE and EXDATE)" [CITED: github.com/kewisch/ical.js/wiki/Common-Use-Cases]. Treat as HIGH confidence.
 **A2 verification:** Peer dep `^4.0.0` satisfied by 4.6.0 [VERIFIED: npm registry]. API surface used (views, calendars, onRangeUpdate) is stable since v4.0.0. Treat as MEDIUM confidence — validate in Wave 0.
@@ -884,6 +892,7 @@ These fixture files can be generated from real Fastmail ICS exports or hand-craf
 ## Sources
 
 ### Primary (HIGH confidence)
+
 - [schedule-x.dev/docs/frameworks/react](https://schedule-x.dev/docs/frameworks/react) — React adapter usage, views, eventsService plugin
 - [schedule-x.dev/docs/calendar/calendars](https://schedule-x.dev/docs/calendar/calendars) — lightColors config, calendarId on events
 - [schedule-x.dev/docs/calendar/events](https://schedule-x.dev/docs/calendar/events) — Temporal.ZonedDateTime / Temporal.PlainDate requirement
@@ -895,11 +904,13 @@ These fixture files can be generated from real Fastmail ICS exports or hand-craf
 - `npm view` on all Phase 2 packages — versions and publish dates confirmed [VERIFIED: npm registry]
 
 ### Secondary (MEDIUM confidence)
+
 - [schedule-x.dev/docs/calendar/major-version-migrations](https://schedule-x.dev/docs/calendar/major-version-migrations) — v2→v3 breaking changes (Temporal adoption confirmed)
 - [schedule-x.dev/docs/calendar/plugins/event-modal](https://schedule-x.dev/docs/calendar/plugins/event-modal) — createEventModalPlugin + customComponents.eventModal
 - WebSearch on rrule DST behavior — confirmed known issue with `tzid` parameter and UTC fallback; `ICAL.RecurExpansion` is the recommended alternative
 
 ### Tertiary (LOW confidence)
+
 - WebSearch results on VTIMEZONE registration best practices — cross-verified with official ical.js wiki
 
 ---
@@ -907,6 +918,7 @@ These fixture files can be generated from real Fastmail ICS exports or hand-craf
 ## Metadata
 
 **Confidence breakdown:**
+
 - Standard stack: HIGH — all packages verified on npm registry; Schedule-X selected in UI-SPEC
 - Architecture (recurrence expansion): HIGH — ICAL.RecurExpansion documented in official ical.js wiki; Phase 1 sync.ts pattern extended
 - Architecture (Schedule-X Temporal format): HIGH — verified against official Schedule-X docs

.planning/milestones/v1.0-phases/02-calendar-display/02-UI-SPEC.md

@@ -8,6 +8,7 @@ created: 2026-06-04
 ---
 
 # Phase 2 — UI Design Contract
+
 ## Calendar Display
 
 > Visual and interaction contract for Phase 2. Generated by gsd-ui-researcher.
@@ -17,13 +18,13 @@ created: 2026-06-04
 
 ## Design System
 
-| Property | Value |
-|----------|-------|
-| Tool | none (shadcn not yet initialized) |
-| Preset | not applicable |
-| Component library | none — custom components against token layer |
-| Icon library | lucide-react (lightweight, tree-shakeable, first-party React SVGs; consistent stroke style) |
-| Font | system-ui stack: `system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` |
+| Property          | Value                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| Tool              | none (shadcn not yet initialized)                                                           |
+| Preset            | not applicable                                                                              |
+| Component library | none — custom components against token layer                                                |
+| Icon library      | lucide-react (lightweight, tree-shakeable, first-party React SVGs; consistent stroke style) |
+| Font              | system-ui stack: `system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`     |
 
 **Note:** No `components.json` exists in the PWA app. The Phase 1 shell uses inline styles.
 Phase 2 introduces a CSS custom-property token layer (see § Token Layer below) as the primary
@@ -51,7 +52,7 @@ props; they use `var(--token-name)` in CSS Modules or `className` strings.
 
 ```ts
 // apps/pwa/src/lib/calendarConfig.ts
-export const WEEK_START_DAY = 0  // 0 = Sunday; flip to 1 = Monday with one edit
+export const WEEK_START_DAY = 0; // 0 = Sunday; flip to 1 = Monday with one edit
 ```
 
 Pass to Schedule-X's `firstDayOfWeek` option. Do not hardcode 0 anywhere else.
@@ -62,33 +63,33 @@ Pass to Schedule-X's `firstDayOfWeek` option. Do not hardcode 0 anywhere else.
 
 ### Base palette
 
-| Token | Hex | Role |
-|-------|-----|------|
-| `--color-surface` | `#FFFFFF` | Page background, calendar grid cells |
-| `--color-surface-dim` | `#F7F7F8` | Off-white wash: week/day off-hours bands, modal backdrop |
-| `--color-surface-raised` | `#FFFFFF` | Cards, popovers (shadow provides elevation) |
-| `--color-border` | `#E2E4E9` | Grid lines, dividers, input borders |
-| `--color-border-subtle` | `#ECEEF2` | Secondary separators |
-| `--color-text-primary` | `#111318` | Body text, event titles |
-| `--color-text-secondary` | `#6B7280` | Meta text: times, locations, legend labels |
-| `--color-text-muted` | `#9CA3AF` | Placeholder, empty-state body, disabled |
-| `--color-focus-ring` | `#4A90D9` | Keyboard focus outline (3px, 2px offset) |
-| `--color-overlay` | `rgba(0,0,0,0.32)` | Popover backdrop scrim |
+| Token                    | Hex                | Role                                                     |
+| ------------------------ | ------------------ | -------------------------------------------------------- |
+| `--color-surface`        | `#FFFFFF`          | Page background, calendar grid cells                     |
+| `--color-surface-dim`    | `#F7F7F8`          | Off-white wash: week/day off-hours bands, modal backdrop |
+| `--color-surface-raised` | `#FFFFFF`          | Cards, popovers (shadow provides elevation)              |
+| `--color-border`         | `#E2E4E9`          | Grid lines, dividers, input borders                      |
+| `--color-border-subtle`  | `#ECEEF2`          | Secondary separators                                     |
+| `--color-text-primary`   | `#111318`          | Body text, event titles                                  |
+| `--color-text-secondary` | `#6B7280`          | Meta text: times, locations, legend labels               |
+| `--color-text-muted`     | `#9CA3AF`          | Placeholder, empty-state body, disabled                  |
+| `--color-focus-ring`     | `#4A90D9`          | Keyboard focus outline (3px, 2px offset)                 |
+| `--color-overlay`        | `rgba(0,0,0,0.32)` | Popover backdrop scrim                                   |
 
 ### Semantic calendar colors
 
 These are the ONLY colors used for event fills. All are derived from member records
 (`users.color`) or the reserved shared-family constant.
 
-| Token | Hex | Assigned to | Source |
-|-------|-----|-------------|--------|
-| `--color-member-0` | `#4A90D9` | Lucas (member 1) | Phase-1 `users.color` |
-| `--color-member-1` | `#50C878` | Wife (member 2) | Phase-1 `users.color` |
-| `--color-member-2` | `#F5A623` | Slot 3 (future) | Phase-1 palette |
-| `--color-member-3` | `#9B59B6` | Slot 4 (future) | Phase-1 palette |
-| `--color-member-4` | `#E67E22` | Slot 5 (future) | Phase-1 palette |
-| `--color-member-5` | `#1ABC9C` | Slot 6 (future) | Phase-1 palette |
-| `--color-shared-family` | `#F25C7A` | Shared-family calendar (ALL members) | Confirmed by user |
+| Token                   | Hex       | Assigned to                          | Source                |
+| ----------------------- | --------- | ------------------------------------ | --------------------- |
+| `--color-member-0`      | `#4A90D9` | Lucas (member 1)                     | Phase-1 `users.color` |
+| `--color-member-1`      | `#50C878` | Wife (member 2)                      | Phase-1 `users.color` |
+| `--color-member-2`      | `#F5A623` | Slot 3 (future)                      | Phase-1 palette       |
+| `--color-member-3`      | `#9B59B6` | Slot 4 (future)                      | Phase-1 palette       |
+| `--color-member-4`      | `#E67E22` | Slot 5 (future)                      | Phase-1 palette       |
+| `--color-member-5`      | `#1ABC9C` | Slot 6 (future)                      | Phase-1 palette       |
+| `--color-shared-family` | `#F25C7A` | Shared-family calendar (ALL members) | Confirmed by user     |
 
 **Implementation note:** The `calendars` configuration object passed to Schedule-X is built
 dynamically at runtime by mapping `users.color` values to Schedule-X `lightColors.main`. The
@@ -99,29 +100,29 @@ The shared-family calendar always uses `#F25C7A` regardless of any user row.
 
 For each member color `MAIN`, derive:
 
-| Sub-token suffix | Derivation | Usage |
-|------------------|------------|-------|
-| `container` | `MAIN` at 15% opacity over white | Event chip background |
-| `onContainer` | `MAIN` darkened 40% | Event chip text, passed to Schedule-X |
+| Sub-token suffix | Derivation                       | Usage                                 |
+| ---------------- | -------------------------------- | ------------------------------------- |
+| `container`      | `MAIN` at 15% opacity over white | Event chip background                 |
+| `onContainer`    | `MAIN` darkened 40%              | Event chip text, passed to Schedule-X |
 
 These need not be pre-declared for every slot — compute them with a small utility function
 (`colorTokens.ts`) at runtime using CSS Color Level 4 or a tiny LCH/hex math helper.
 
 ### 60 / 30 / 10 split
 
-| Band | Tokens | Approximate coverage |
-|------|--------|----------------------|
-| 60% dominant (surface) | `--color-surface`, `--color-surface-dim` | Calendar grid, page background |
+| Band                      | Tokens                                                              | Approximate coverage                   |
+| ------------------------- | ------------------------------------------------------------------- | -------------------------------------- |
+| 60% dominant (surface)    | `--color-surface`, `--color-surface-dim`                            | Calendar grid, page background         |
 | 30% secondary (structure) | `--color-surface-raised`, `--color-border`, `--color-border-subtle` | Cards, nav bar, header, popover shells |
-| 10% accent | `--color-shared-family` + per-member fills | Event chips only |
+| 10% accent                | `--color-shared-family` + per-member fills                          | Event chips only                       |
 
 **Accent reserved for:** event chip fills and the color legend swatches. Accent colors MUST NOT
 appear on buttons, nav items, headings, or any chrome element.
 
 ### Destructive
 
-| Token | Hex | Usage |
-|-------|-----|-------|
+| Token                 | Hex       | Usage                                                              |
+| --------------------- | --------- | ------------------------------------------------------------------ |
 | `--color-destructive` | `#DC2626` | Not used in Phase 2 (read-only). Token declared for Phase 3 reuse. |
 
 ---
@@ -130,17 +131,18 @@ appear on buttons, nav items, headings, or any chrome element.
 
 All values are multiples of 4px. Use tokens; never write raw `px` values in components.
 
-| Token | Value | CSS var | Usage |
-|-------|-------|---------|-------|
-| `space-1` | 4px | `--space-1` | Icon gap, badge dot, tight inline padding |
-| `space-2` | 8px | `--space-2` | Event chip inner padding (vertical), color legend row gap |
-| `space-3` | 12px | `--space-3` | Event chip inner padding (horizontal), compact cell padding |
-| `space-4` | 16px | `--space-4` | Default element spacing, popover section gap |
-| `space-6` | 24px | `--space-6` | Section padding, nav bar height rhythm |
-| `space-8` | 32px | `--space-8` | Layout gaps, popover width gutter |
-| `space-12` | 48px | `--space-12` | Major section breaks |
+| Token      | Value | CSS var      | Usage                                                       |
+| ---------- | ----- | ------------ | ----------------------------------------------------------- |
+| `space-1`  | 4px   | `--space-1`  | Icon gap, badge dot, tight inline padding                   |
+| `space-2`  | 8px   | `--space-2`  | Event chip inner padding (vertical), color legend row gap   |
+| `space-3`  | 12px  | `--space-3`  | Event chip inner padding (horizontal), compact cell padding |
+| `space-4`  | 16px  | `--space-4`  | Default element spacing, popover section gap                |
+| `space-6`  | 24px  | `--space-6`  | Section padding, nav bar height rhythm                      |
+| `space-8`  | 32px  | `--space-8`  | Layout gaps, popover width gutter                           |
+| `space-12` | 48px  | `--space-12` | Major section breaks                                        |
 
 **Exceptions:**
+
 - Touch targets: minimum 44px height/width on interactive elements (iOS HIG). This is a layout
   constraint, not a spacing token. Apply via `min-height: 44px`.
 - Calendar header row height: 48px (`--space-12` used as a layout constant).
@@ -152,12 +154,12 @@ All values are multiples of 4px. Use tokens; never write raw `px` values in comp
 
 Font family token: `--font-family-base: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
 
-| Role | Token | Size | Weight | Line Height | Usage |
-|------|-------|------|--------|-------------|-------|
-| Body | `--text-body` | 15px | 400 | 1.5 | Popover description, agenda location lines |
-| Label | `--text-label` | 13px | 400 | 1.4 | Event chip text, time labels, legend labels, secondary meta |
-| Heading | `--text-heading` | 18px | 600 | 1.25 | Popover title, view section headers (month name + year) |
-| Display | `--text-display` | 24px | 600 | 1.2 | App name in nav bar (desktop), day number in day-view header |
+| Role    | Token            | Size | Weight | Line Height | Usage                                                        |
+| ------- | ---------------- | ---- | ------ | ----------- | ------------------------------------------------------------ |
+| Body    | `--text-body`    | 15px | 400    | 1.5         | Popover description, agenda location lines                   |
+| Label   | `--text-label`   | 13px | 400    | 1.4         | Event chip text, time labels, legend labels, secondary meta  |
+| Heading | `--text-heading` | 18px | 600    | 1.25        | Popover title, view section headers (month name + year)      |
+| Display | `--text-display` | 24px | 600    | 1.2         | App name in nav bar (desktop), day number in day-view header |
 
 **Weights declared:** 400 (regular) and 600 (semibold). No other weights permitted.
 
@@ -169,17 +171,19 @@ Font family token: `--font-family-base: system-ui, -apple-system, BlinkMacSystem
 
 These are the only three breakpoints. Reference them by name in code, never by raw px value.
 
-| Name | Token | Min width | Default view | Notes |
-|------|-------|-----------|--------------|-------|
-| `phone` | `--bp-phone` | 0px | Agenda | Stacked single-column layout |
-| `tablet` | `--bp-tablet` | 768px | Month | Two-column possible; nav becomes persistent sidebar |
-| `desktop` | `--bp-desktop` | 1280px | Month | Full grid width |
+| Name      | Token          | Min width | Default view | Notes                                               |
+| --------- | -------------- | --------- | ------------ | --------------------------------------------------- |
+| `phone`   | `--bp-phone`   | 0px       | Agenda       | Stacked single-column layout                        |
+| `tablet`  | `--bp-tablet`  | 768px     | Month        | Two-column possible; nav becomes persistent sidebar |
+| `desktop` | `--bp-desktop` | 1280px    | Month        | Full grid width                                     |
 
 **View default logic (D-05):**
+
 ```ts
-const isMobile = window.matchMedia('(max-width: 767px)').matches
-const defaultView = isMobile ? 'month-agenda' : 'month-grid'
+const isMobile = window.matchMedia('(max-width: 767px)').matches;
+const defaultView = isMobile ? 'month-agenda' : 'month-grid';
 ```
+
 Last-used view is persisted in Zustand and localStorage, keyed by breakpoint group
 (`'phone' | 'tablet-desktop'`).
 
@@ -190,12 +194,13 @@ Last-used view is persisted in Zustand and localStorage, keyed by breakpoint gro
 **Selected: Schedule-X** (`@schedule-x/react` + `@schedule-x/calendar`)
 
 **Rationale:**
+
 - Supports all four required views natively: `createViewDay`, `createViewWeek`,
   `createViewMonthGrid`, `createViewMonthAgenda` (agenda).
 - Theming via CSS custom properties — its `--sx-color-*` vars are overridden by mapping to
   this spec's token values in `tokens.css`. No Schedule-X default stylesheet bleeds through.
 - Per-calendar color is first-class (`calendars` config with `lightColors.main / container /
-  onContainer`) — maps directly to per-member `users.color` and the shared-family rose.
+onContainer`) — maps directly to per-member `users.color` and the shared-family rose.
 - `onRangeUpdate` callback fires when the user navigates, enabling TanStack Query to fetch
   only the visible window from `/api/events?start=&end=`.
 - Custom `eventModal` component via `customComponents` prop — the read-only detail popover
@@ -204,6 +209,7 @@ Last-used view is persisted in Zustand and localStorage, keyed by breakpoint gro
 - Active maintenance; Temporal-polyfill based (aligns with modern date handling).
 
 **Rejected alternatives:**
+
 - `react-big-calendar`: opinionated CSS (hard to token-ify without !important fights);
   unmaintained `moment` / `date-fns` localization coupling; weak agenda view.
 - `FullCalendar`: commercial license for premium features; React package adds ~140 KB gzip.
@@ -220,17 +226,21 @@ Result: Schedule-X internal layout engine works; all colors come from this spec'
 ## Component Inventory
 
 ### CalendarShell
+
 Top-level layout wrapper.
+
 - `<AppNav>` (top bar on phone; left sidebar 240px on tablet/desktop)
 - `<ViewToolbar>` (Today button, prev/next arrows, date label, view switcher)
 - `<ColorLegend>` (member → color; always visible on tablet/desktop; collapsible on phone)
 - `<ScheduleXCalendar>` (fills remaining space)
 
 ### AppNav
+
 - Phone: top bar, 48px height, app name left, user avatar/color swatch right
 - Tablet/Desktop: left sidebar, 240px width; app name + color legend + (future) nav items
 
 ### ViewToolbar
+
 - Buttons: Today | < | > | [Day] [Week] [Month] [Agenda]
 - Font: 13px label weight
 - Active view button: `--color-member-0` (Lucas, current user) background at 12% opacity,
@@ -238,12 +248,14 @@ Top-level layout wrapper.
 - Touch targets: 44px minimum height
 
 ### ColorLegend
+
 - One row per member: color swatch (12px circle) + display name
 - Shared-family row: rose swatch + "Family" label
 - Font: 13px label weight, `--color-text-secondary`
 - Always rendered; never interactive in Phase 2 (show/hide filter deferred)
 
 ### EventChip (month grid)
+
 - Rounded pill, 4px radius
 - Background: member `container` color (15% opacity)
 - Text: member `onContainer` color, 13px, weight 400, single line, truncated with ellipsis
@@ -251,18 +263,21 @@ Top-level layout wrapper.
 - Minimum height: 20px; minimum tap target area: 44px via transparent padding
 
 ### EventBlock (week / day view)
+
 - Rectangular block, 4px radius
 - Same fill/border as EventChip
 - Displays: title (13px, weight 600) + start time (13px, weight 400) stacked
 - Overflow clips; no ellipsis in short blocks (too short = just color)
 
 ### AgendaRow
+
 - Date group header: heading weight (18px/600), `--color-text-primary`
 - Event row: time (13px, muted) | title (15px, primary) | location (13px, secondary, italic)
 - Left 4px border strip: member color
 - Tap target: full row, min 44px height
 
 ### EventDetailPopover (read-only in Phase 2; reused as edit surface in Phase 3)
+
 - Modal-style overlay on phone (full bottom sheet, slides up)
 - Popover anchored to event on tablet/desktop (max-width 360px, 8px radius, shadow)
 - Sections:
@@ -275,6 +290,7 @@ Top-level layout wrapper.
 - Phase 3 note: add edit/delete actions in the footer area (reserved but empty in Phase 2)
 
 ### SkeletonCalendar
+
 - Month skeleton: 6×7 grid of rounded rect placeholders, animated shimmer
   (`background: linear-gradient(90deg, --color-surface-dim, --color-border-subtle, --color-surface-dim)`)
 - Agenda skeleton: 4 date-group blocks, 2–3 rows each, varying widths (60–90% of row)
@@ -282,6 +298,7 @@ Top-level layout wrapper.
 - No spinner; shimmer only (matches Fantastical-style)
 
 ### EmptyState (no events in range)
+
 - Centered in the calendar viewport
 - Icon: lucide-react `CalendarDays` (32px, `--color-text-muted`)
 - Heading + body copy (see § Copywriting)
@@ -292,6 +309,7 @@ Top-level layout wrapper.
 ## View Layout Specification
 
 ### Month view (default: tablet/desktop)
+
 - 7-column grid, column headers: Sun–Sat (3-letter, label weight)
 - Day cells: 4px border, corner shows day number (13px label)
 - Today's cell: `--color-surface-dim` background; day number has filled dot indicator
@@ -300,6 +318,7 @@ Top-level layout wrapper.
 - Off-month days: day number in `--color-text-muted`; cells at 60% opacity
 
 ### Week view
+
 - Time column 48px wide; columns for each day
 - Current time indicator: 2px `--color-member-0` (current user's color) horizontal line
 - All-day banner row at top, above time grid: full-width event blocks
@@ -307,10 +326,12 @@ Top-level layout wrapper.
 - Event blocks overlap-handled by Schedule-X internals
 
 ### Day view
+
 - Same layout as week, single day column (full width minus time column)
 - Date in header: `--text-display` (24px/600)
 
 ### Agenda view (default: phone)
+
 - Chronological list, grouped by date
 - Infinite scroll or paginated by month (Schedule-X `createViewMonthAgenda`)
 - Past events: not shown; starts at today
@@ -320,20 +341,20 @@ Top-level layout wrapper.
 
 ## Copywriting Contract
 
-| Element | Copy |
-|---------|------|
-| Primary CTA (Phase 2) | None — read-only phase; no create action |
-| Empty state heading | "Nothing here" |
-| Empty state body | "No events in this period. Try a different date or switch views." |
-| Loading state | (No text — skeleton shimmer only) |
-| Error state heading | "Couldn't load events" |
-| Error state body | "Check your connection and try again." |
-| Error action | "Retry" (taps `queryClient.refetchQueries(['events'])`) |
-| "+N more" label | "+{N} more" (month grid overflow) |
-| Popover close | "×" (aria-label="Close") |
-| Today button | "Today" |
-| Color legend — shared | "Family" |
-| Nav bar — app name | "FamilySync" |
+| Element               | Copy                                                              |
+| --------------------- | ----------------------------------------------------------------- |
+| Primary CTA (Phase 2) | None — read-only phase; no create action                          |
+| Empty state heading   | "Nothing here"                                                    |
+| Empty state body      | "No events in this period. Try a different date or switch views." |
+| Loading state         | (No text — skeleton shimmer only)                                 |
+| Error state heading   | "Couldn't load events"                                            |
+| Error state body      | "Check your connection and try again."                            |
+| Error action          | "Retry" (taps `queryClient.refetchQueries(['events'])`)           |
+| "+N more" label       | "+{N} more" (month grid overflow)                                 |
+| Popover close         | "×" (aria-label="Close")                                          |
+| Today button          | "Today"                                                           |
+| Color legend — shared | "Family"                                                          |
+| Nav bar — app name    | "FamilySync"                                                      |
 
 **Destructive actions in Phase 2:** None. Phase 2 is read-only.
 
@@ -342,12 +363,14 @@ Top-level layout wrapper.
 ## Interaction Contract
 
 ### Navigation
+
 - Prev/next: advance by one unit of current view (day/week/month)
 - Today: jump to today's date, preserve current view
 - View switch: instant; no animation (avoid jank on low-end Android WebViews)
 - All transitions: no slide animations; content replaces in-place
 
 ### Touch (iOS PWA)
+
 - All tap targets: minimum 44×44px (enforced via `min-height` / `padding`)
 - No hover states on touch devices (use `:focus-visible` only)
 - Swipe left/right on calendar grid: advance/retreat by one unit (Schedule-X built-in)
@@ -355,6 +378,7 @@ Top-level layout wrapper.
 - Tap backdrop / swipe down: close EventDetailPopover (bottom sheet on phone)
 
 ### Keyboard / accessibility
+
 - View toolbar buttons: focusable, `role="button"`, keyboard activated with Enter/Space
 - Event chips: `role="button"`, `aria-label="{title}, {date}, {time}"`
 - Popover: focus trap while open; Escape closes; focus returns to triggering element
@@ -363,6 +387,7 @@ Top-level layout wrapper.
 - Skeleton: `aria-busy="true"` on calendar root during loading
 
 ### Error / retry
+
 - TanStack Query `retry: 2` for events query; after exhaustion show error state
 - Error state replaces calendar grid (not a toast); "Retry" button triggers manual refetch
 
@@ -370,14 +395,14 @@ Top-level layout wrapper.
 
 ## State Management Contract
 
-| State | Owner | Key | Notes |
-|-------|-------|-----|-------|
-| Visible event list | TanStack Query | `['events', start, end]` | Invalidated on range change |
-| Current user (`/api/me`) | TanStack Query | `['me']` | Used for color derivation |
-| Selected view | Zustand + localStorage | `calendarView.{breakpointGroup}` | Persisted per device category |
-| Selected date (nav) | Zustand | `calendarSelectedDate` | ISO string; not persisted |
-| Open popover event ID | Zustand | `openEventId` | `null` when closed |
-| Visible range | Zustand | `calendarRange` | `{ start: string, end: string }` — drives Query key |
+| State                    | Owner                  | Key                              | Notes                                               |
+| ------------------------ | ---------------------- | -------------------------------- | --------------------------------------------------- |
+| Visible event list       | TanStack Query         | `['events', start, end]`         | Invalidated on range change                         |
+| Current user (`/api/me`) | TanStack Query         | `['me']`                         | Used for color derivation                           |
+| Selected view            | Zustand + localStorage | `calendarView.{breakpointGroup}` | Persisted per device category                       |
+| Selected date (nav)      | Zustand                | `calendarSelectedDate`           | ISO string; not persisted                           |
+| Open popover event ID    | Zustand                | `openEventId`                    | `null` when closed                                  |
+| Visible range            | Zustand                | `calendarRange`                  | `{ start: string, end: string }` — drives Query key |
 
 Server events NEVER enter Zustand. Zustand holds only UI-shape state.
 
@@ -385,11 +410,11 @@ Server events NEVER enter Zustand. Zustand holds only UI-shape state.
 
 ## Registry Safety
 
-| Registry | Blocks Used | Safety Gate |
-|----------|-------------|-------------|
-| shadcn official | none — shadcn not initialized in Phase 2 | not applicable |
-| schedule-x (npm) | `@schedule-x/react`, `@schedule-x/calendar`, `@schedule-x/theme-default` | npm package — no registry vetting gate required; standard npm supply chain |
-| lucide-react (npm) | icon components | npm package — standard |
+| Registry           | Blocks Used                                                              | Safety Gate                                                                |
+| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| shadcn official    | none — shadcn not initialized in Phase 2                                 | not applicable                                                             |
+| schedule-x (npm)   | `@schedule-x/react`, `@schedule-x/calendar`, `@schedule-x/theme-default` | npm package — no registry vetting gate required; standard npm supply chain |
+| lucide-react (npm) | icon components                                                          | npm package — standard                                                     |
 
 No third-party shadcn registries in Phase 2.
 
@@ -397,23 +422,23 @@ No third-party shadcn registries in Phase 2.
 
 ## Pre-Population Sources
 
-| Decision | Source |
-|----------|--------|
-| Shared-family color = `#F25C7A` | User-confirmed in phase prompt |
-| `WEEK_START_DAY = 0` (Sunday) | User-confirmed in phase prompt |
-| Token-layer architecture (D-01/D-02) | CONTEXT.md §Theming |
-| Clean theme only (D-02) | CONTEXT.md §Theming |
-| All four views (D-04) | CONTEXT.md §Views, REQUIREMENTS.md CAL-03 |
-| Phone→Agenda / tablet→Month default (D-05) | CONTEXT.md §Views |
-| Per-member color from `users.color` (D-06) | CONTEXT.md §Color, CLAUDE.md schema |
-| Color legend, no show/hide filter (D-07) | CONTEXT.md §Color |
-| Informational density + tap-to-expand (D-08) | CONTEXT.md §Event detail |
-| Server-side recurrence expansion (D-09) | CONTEXT.md §Recurrence, CLAUDE.md |
-| Single local timezone, no shift for all-day (D-10) | CONTEXT.md §Recurrence |
-| TanStack Query = server state, Zustand = UI state | CLAUDE.md, CONTEXT.md §Code patterns |
-| React 19 + Vite stack | CLAUDE.md §Recommended Stack |
-| No shadcn yet (Phase 3 adoption) | Codebase scan (no components.json) |
-| Schedule-X as rendering library | Researcher decision (D-Claude); see §Rendering Library |
+| Decision                                           | Source                                                 |
+| -------------------------------------------------- | ------------------------------------------------------ |
+| Shared-family color = `#F25C7A`                    | User-confirmed in phase prompt                         |
+| `WEEK_START_DAY = 0` (Sunday)                      | User-confirmed in phase prompt                         |
+| Token-layer architecture (D-01/D-02)               | CONTEXT.md §Theming                                    |
+| Clean theme only (D-02)                            | CONTEXT.md §Theming                                    |
+| All four views (D-04)                              | CONTEXT.md §Views, REQUIREMENTS.md CAL-03              |
+| Phone→Agenda / tablet→Month default (D-05)         | CONTEXT.md §Views                                      |
+| Per-member color from `users.color` (D-06)         | CONTEXT.md §Color, CLAUDE.md schema                    |
+| Color legend, no show/hide filter (D-07)           | CONTEXT.md §Color                                      |
+| Informational density + tap-to-expand (D-08)       | CONTEXT.md §Event detail                               |
+| Server-side recurrence expansion (D-09)            | CONTEXT.md §Recurrence, CLAUDE.md                      |
+| Single local timezone, no shift for all-day (D-10) | CONTEXT.md §Recurrence                                 |
+| TanStack Query = server state, Zustand = UI state  | CLAUDE.md, CONTEXT.md §Code patterns                   |
+| React 19 + Vite stack                              | CLAUDE.md §Recommended Stack                           |
+| No shadcn yet (Phase 3 adoption)                   | Codebase scan (no components.json)                     |
+| Schedule-X as rendering library                    | Researcher decision (D-Claude); see §Rendering Library |
 
 ---
 

.planning/milestones/v1.0-phases/02-calendar-display/02-VALIDATION.md

@@ -0,0 +1,103 @@
+---
+phase: 02
+slug: calendar-display
+status: ready
+nyquist_compliant: true
+wave_0_complete: false
+created: 2026-06-04
+---
+
+# Phase 02 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property                    | Value                                                                        |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| **Framework**               | vitest                                                                       |
+| **Config (API)**            | `apps/api/vitest.config.ts` (environment: node — exists, Phase 1)            |
+| **Config (PWA)**            | `apps/pwa/vitest.config.ts` (environment: jsdom — created in Plan 01 Task 1) |
+| **Quick run command (API)** | `cd apps/api && pnpm test -- <test-file>`                                    |
+| **Quick run command (PWA)** | `cd apps/pwa && pnpm test -- <test-file>`                                    |
+| **Full suite command**      | `pnpm -r test` (runs both workspaces)                                        |
+| **Type gate**               | `pnpm exec tsc --noEmit` per workspace                                       |
+| **Estimated runtime**       | ~25 seconds full suite (no live network; broker mocked)                      |
+
+PWA harness (vitest + jsdom + @testing-library/react + @testing-library/jest-dom) is installed in **Plan 01 Task 1** — until that task completes, all PWA test rows are blocked on the harness (`❌ W0`).
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run the task's quick run command (the `<automated>` in that task)
+- **After every plan wave:** Run `pnpm -r test`
+- **Before `/gsd-verify-work`:** `pnpm -r test` green + `tsc --noEmit` clean in both workspaces
+- **Max feedback latency:** 30 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID  | Plan | Wave | Requirement            | Threat Ref  | Secure Behavior                                                            | Test Type   | Automated Command                                                                       | File Exists                             | Status     |
+| -------- | ---- | ---- | ---------------------- | ----------- | -------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | --------------------------------------- | ---------- |
+| 02-01-01 | 01   | 1    | CAL-07                 | T-02-SC     | schema + RED stubs + fixtures (no behavior yet)                            | unit/grep   | `grep -q has_rrule + ICAL.parse fixtures` (3 grep/node checks)                          | ✅ creates RED stubs                    | ⬜ pending |
+| 02-01-02 | 01   | 1    | CAL-02                 | T-02-01     | dev-bypass hard-disabled when NODE_ENV=production                          | unit        | `cd apps/api && pnpm test -- tests/auth/devBypass.test.ts`                              | ❌ W0 (this task creates it)            | ⬜ pending |
+| 02-01-03 | 01   | 1    | CAL-07                 | T-02-02     | live MariaDB has has_rrule + is_shared (no false-green)                    | integration | `node SHOW COLUMNS calendar_events/calendars`                                           | N/A (DB assertion)                      | ⬜ pending |
+| 02-02-01 | 02   | 2    | CAL-07                 | T-02b-04    | DST wall-clock preserved; all-day no shift; EXDATE excluded                | unit        | `cd apps/api && pnpm test -- tests/broker/expand.test.ts`                               | ✅ RED stub from 02-01                  | ⬜ pending |
+| 02-02-02 | 02   | 2    | CAL-02, CAL-07         | T-02b-01/02 | start/end zod-validated before SQL; 90-day cap; color+isShared join        | unit        | `cd apps/api && pnpm test -- tests/routes/events.test.ts`                               | ✅ RED stub from 02-01                  | ⬜ pending |
+| 02-02-03 | 02   | 2    | CAL-02                 | —           | operator marks shared calendar (is_shared=1)                               | manual      | human-verify checkpoint (see Manual-Only)                                               | N/A                                     | ⬜ pending |
+| 02-03-01 | 03   | 2    | CAL-02                 | T-02c-SC    | token layer + Schedule-X var overrides; Temporal-first import              | grep/node   | `grep --color-shared-family + node require deps`                                        | N/A (style/deps)                        | ⬜ pending |
+| 02-03-02 | 03   | 2    | CAL-02                 | —           | firstDayOfWeek 0→7; per-member + 'shared' config                           | unit        | `cd apps/pwa && pnpm test -- src/lib/colorUtils.test.ts src/lib/calendarConfig.test.ts` | ✅ RED stub (calendarConfig) from 02-01 | ⬜ pending |
+| 02-03-03 | 03   | 2    | CAL-07                 | T-02c-02    | all-day→PlainDate guard; calendarId routed by isShared/ownerUserId         | unit        | `cd apps/pwa && pnpm test -- src/lib/hydrateEvents.test.ts`                             | ✅ RED stub from 02-01                  | ⬜ pending |
+| 02-04-01 | 04   | 3    | CAL-02, CAL-03         | T-02d-01    | Schedule-X renders real windowed occurrences; 4 views; token-only          | grep/type   | `grep ScheduleXCalendar/hydrateEvents + tsc --noEmit`                                   | N/A (wired in 04)                       | ⬜ pending |
+| 02-04-02 | 04   | 3    | CAL-03                 | T-02d-01    | render smoke: 4 views + timed+all-day through hydrate→eventsService        | unit        | `cd apps/pwa && pnpm test -- src/components/CalendarShell.test.tsx`                     | ❌ W0 (this task creates it)            | ⬜ pending |
+| 02-05-01 | 05   | 4    | CAL-03                 | T-02e-01    | popover renders fields as text (no dangerouslySetInnerHTML); Escape closes | unit        | `cd apps/pwa && pnpm test -- src/components/EventDetailPopover.test.tsx`                | ❌ W0 (this task creates it)            | ⬜ pending |
+| 02-05-02 | 05   | 4    | CAL-02, CAL-03         | T-02e-02    | legend/nav/toolbar + skeleton/empty/error; EventProof removed              | grep/type   | `grep SkeletonCalendar/EmptyState + tsc --noEmit`                                       | N/A (wired in 05)                       | ⬜ pending |
+| 02-05-03 | 05   | 4    | CAL-02, CAL-03, CAL-07 | —           | visual + functional verification of 4 success criteria                     | manual      | human-verify checkpoint (see Manual-Only)                                               | N/A                                     | ⬜ pending |
+
+_Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky_
+
+Tasks without a unit-test `<automated>` (02-01-01 grep/fixture, 02-01-03 DB, 02-03-01 grep/deps, 02-04-01 grep/type, 02-05-02 grep/type) each carry an automated grep/node/tsc check, and none of them appear in 3-consecutive sequence without a unit test between them: the expand/events/colorUtils/hydrateEvents/popover/smoke unit tests interleave every wave.
+
+---
+
+## Wave 0 Requirements
+
+Wave 0 = Plan 01 Task 1, which creates the failing-but-present test stubs and fixtures the later waves turn green:
+
+- [ ] `apps/api/tests/broker/expand.test.ts` — RED stub for `expandOccurrences` (CAL-07). Contract: weekly `America/New_York` RRULE across the March 2026 DST boundary keeps 10:00 local wall-clock on both sides; all-day birthday → `allDay:true` + `'YYYY-MM-DD'` start; EXDATE-excluded occurrence absent. Fails at import (`../../src/broker/expand.js` not yet built).
+- [ ] `apps/api/tests/routes/events.test.ts` — RED stub for windowed `/api/events` (CAL-02). Contract: occurrences carry `color` + `isShared`; bad/oversized params → 400.
+- [ ] `apps/pwa/src/lib/hydrateEvents.test.ts` — RED stub (CAL-07). Contract: all-day→`Temporal.PlainDate`; timed→`Temporal.ZonedDateTime`; **Schedule-X `calendarId` = `occ.isShared ? 'shared' : String(occ.ownerUserId)`** (shared occurrence → `'shared'`; personal occurrence → `String(ownerUserId)`).
+- [ ] `apps/pwa/src/lib/calendarConfig.test.ts` — RED stub (CAL-02). Contract: `WEEK_START_DAY=0` → Schedule-X `firstDayOfWeek=7`.
+- [ ] `apps/api/tests/fixtures/{weekly-dst,allday-birthday,exdate-series}.ics` — fixture corpus; `weekly-dst.ics` carries a full VTIMEZONE (STANDARD + DAYLIGHT) for the DST assertion.
+- [ ] `apps/api/tests/auth/devBypass.test.ts` — created and made green within Plan 01 Task 2 (not a cross-wave RED stub).
+- [ ] `apps/pwa/vitest.config.ts` + PWA test deps (vitest, @testing-library/react, @testing-library/jest-dom, jsdom) — installed in Plan 01 Task 1; without this the PWA RED stubs cannot run.
+- [ ] `apps/pwa/src/components/CalendarShell.test.tsx` and `apps/pwa/src/components/EventDetailPopover.test.tsx` — created in-wave by Plan 04/05 (not Wave 0 stubs; depend on components built in the same plan).
+
+---
+
+## Manual-Only Verifications
+
+| Behavior                                                       | Requirement | Why Manual                                                                                                                                                                                                                                                                                                                                 | Test Instructions                                                                                                                                                        |
+| -------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Designate the shared-family calendar (`calendars.is_shared=1`) | CAL-02      | Which calendar is "shared-family" cannot be derived deterministically from data (broker exposes "Calendar" + "USA Holidays"; members' calendars arrive under their own credential) — operator must designate it. A different identification rule (e.g. displayName-pattern matching) is a **plan revision, not a resume-from-checkpoint**. | Plan 02 Task 3: list calendars, `UPDATE calendars SET is_shared=1 WHERE id=<chosen>`, re-list, curl `/api/events` confirms isShared:true + color #F25C7A on marked rows. |
+| DST boundary correctness in the rendered UI                    | CAL-07      | Automated expand.test.ts asserts the wall-clock contract, but visual confirmation that Schedule-X paints the occurrence at the right hour across March 2026 requires a human eye on the grid.                                                                                                                                              | Plan 05 Task 3 step 4: find a recurring event, navigate across the March 2026 DST boundary, confirm time does not jump ±1 hour.                                          |
+| All-day event renders as a full-day banner with no date shift  | CAL-07      | PlainDate guard is unit-tested, but the actual Schedule-X all-day banner placement (correct date, no off-by-one) is a render-path visual check.                                                                                                                                                                                            | Plan 05 Task 3 step 5: find an all-day event (birthday/holiday), confirm it appears as a full-day banner on the correct date, not a day early/late.                      |
+| Color-coded ownership legible at a glance + legend decode      | CAL-02      | "Reads at a glance" is a subjective slick-constraint judgment.                                                                                                                                                                                                                                                                             | Plan 05 Task 3 steps 2–3: confirm each member's events render in their color, shared in rose, legend decodes ownership.                                                  |
+| Phone bottom-sheet popover + agenda default view               | CAL-03      | Responsive breakpoint behavior (D-05) needs a real phone-width render.                                                                                                                                                                                                                                                                     | Plan 05 Task 3 step 7: resize to phone width, confirm default view is Agenda and popover is a bottom sheet.                                                              |
+
+---
+
+## Validation Sign-Off
+
+- [x] All tasks have `<automated>` verify or Wave 0 dependencies
+- [x] Sampling continuity: no 3 consecutive tasks without automated verify
+- [x] Wave 0 covers all MISSING references (expand, events, hydrateEvents, calendarConfig stubs + PWA harness)
+- [x] No watch-mode flags (`vitest run` / `pnpm test -- <file>`, never `--watch`)
+- [x] Feedback latency < 30s
+- [x] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** approved 2026-06-04

.planning/milestones/v1.0-phases/02-calendar-display/02-VERIFICATION.md

@@ -0,0 +1,227 @@
+---
+phase: 02-calendar-display
+verified: 2026-06-05T16:00:00Z
+status: passed
+human_uat: approved 2026-06-05 (see 02-HUMAN-UAT.md) — operator confirmed all 4 success criteria in the running dev stack
+score: 4/4 must-haves verified
+overrides_applied: 0
+human_verification:
+  - test: "Confirm color-coded event display: each member's events appear in their assigned hex, shared-family events in rose #F25C7A; the ColorLegend decodes ownership"
+    expected: "Personal events use the owner's color from users.color; rose lane is empty (D-16, no shared calendar yet) but the legend shows the Family row correctly"
+    why_human: 'Color rendering is visual; CSS token overrides and Schedule-X lightColors derivation cannot be verified by grep — only by visual inspection in a browser'
+  - test: 'Switch between Day, Week, Month, and Agenda views and confirm events render correctly in each with no missing or misplaced events'
+    expected: 'All four view factories (createViewDay/Week/MonthGrid/MonthAgenda) render events; week/day time-grid scrolls; navigation (Today/prev/next) works in each view'
+    why_human: 'View rendering and grid layout require a running browser; Schedule-X DOM output cannot be asserted statically'
+  - test: 'Find a recurring event and navigate across the March 2026 DST boundary; confirm occurrences stay at the correct local wall-clock time (no ±1h shift)'
+    expected: 'A weekly 10:00 America/New_York event shows 10:00 on both sides of the Spring-forward boundary — not 09:00 or 11:00 after the transition'
+    why_human: 'VTIMEZONE registration + ICAL.RecurExpansion + Schedule-X display timezone are correct in code (verified), but DST correctness must be visually confirmed with real Fastmail data'
+  - test: 'Find a recurring all-day event (e.g. a birthday) and confirm it appears as a full-day banner on the correct date with no day shift'
+    expected: 'All-day events render on the date matching the DTSTART DATE value — not shifted one day early or late by a timezone offset'
+    why_human: 'Temporal.PlainDate routing is correct in code; visual confirmation with live data needed to rule out any Schedule-X display-zone interaction'
+---
+
+# Phase 02: Calendar Display — Verification Report
+
+**Phase Goal:** Both members can see a unified, color-coded calendar aggregating all accessible
+Fastmail calendars across day, week, month, and agenda views — read-only, no write-back yet.
+
+**Verified:** 2026-06-05T16:00:00Z
+**Status:** human_needed (all automated checks pass; 4 human UAT items remain)
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth                                                                                                            | Status          | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --- | ---------------------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Color-coded calendar — each member's events in their assigned color, shared events distinguishable from personal | VERIFIED (code) | `events.ts` derives `color = row.isShared ? '#F25C7A' : row.userColor`; `hydrateEvents.ts` routes `calendarId = occ.isShared ? 'shared' : String(occ.ownerUserId)`; `buildCalendarConfig()` keys per-member by `String(userId)` + `'shared'` with `deriveScheduleXColors()`. Rose lane intentionally empty per D-16 (no shared Fastmail calendar yet — operator-deferred).                                                                                                                                                                                            |
+| 2   | Day/week/month/agenda views — all events render correctly in each                                                | VERIFIED (code) | `CalendarShell.tsx` passes all four factories (`createViewDay`, `createViewWeek`, `createViewMonthGrid`, `createViewMonthAgenda`) to `useCalendarApp`; Schedule-X built-in header provides the view switcher and navigation.                                                                                                                                                                                                                                                                                                                                          |
+| 3   | Recurring events display all occurrences in-window, correct across DST boundaries                                | VERIFIED (code) | `expand.ts` registers VTIMEZONE via `getAllSubcomponents('vtimezone')` at line 190, before `new ICAL.RecurExpansion` at line 264; uses `ICAL.Time.fromJSDate(windowStart, true)` (UTC-based) for absolute occurrence windowing; `serializeTime()` emits IANA-annotated strings (`'...±HH:MM[IANA/Zone]'`); Schedule-X display timezone set to `Intl.DateTimeFormat().resolvedOptions().timeZone`. `events.ts` pre-filter includes all-day recurring masters via `dtstartDate < end` fallback. `sync.ts` sets `hasRrule: isRecurring` on both insert and update paths. |
+| 4   | All-day events appear as full-day banners on the correct date with no timezone shift                             | VERIFIED (code) | `expand.ts` `serializeTime(t, allDay=true)` returns `'YYYY-MM-DD'` strings only; `hydrateEvents.ts` branches on `occ.allDay` to call `Temporal.PlainDate.from(occ.start)` (never `ZonedDateTime`); `events.ts` non-recurring all-day pre-filter uses `dtstartDate` (DATE column) comparison — no DATETIME coercion.                                                                                                                                                                                                                                                   |
+
+**Score: 4/4 truths — all verified in code**
+
+Automated test confirmation: `apps/api` 47/47 tests pass; `apps/pwa` 39/39 tests pass; both
+workspaces typecheck clean (`tsc --noEmit`).
+
+---
+
+### Deferred Items
+
+| #   | Item                                                | Addressed In           | Evidence                                                                                                                                                                                                                                       |
+| --- | --------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Shared-family color lane populated with real events | Operator action (D-16) | `calendars.is_shared` column exists and is read by the route; lane is empty because no shared Fastmail calendar has been created yet. STATE.md Deferred Items entry D-16 and PROJECT.md D-16 confirm this is intentional and operator-tracked. |
+
+---
+
+### Required Artifacts
+
+| Artifact                                         | Expected                                                                          | Status               | Details                                                                                                                                                                              |
+| ------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `apps/api/src/broker/expand.ts`                  | `expandOccurrences()` + `CalendarOccurrence` interface                            | VERIFIED             | Exports both; full VTIMEZONE registration, ICAL.RecurExpansion, allDay split, IANA-annotated output, CSS-safe IDs                                                                    |
+| `apps/api/src/routes/events.ts`                  | Windowed `/api/events` with join, hasRrule pre-filter, zod validation             | VERIFIED             | `zValidator`, 3-clause WHERE (recurring/non-recurring/all-day), `expandOccurrences` called per row                                                                                   |
+| `apps/api/src/db/schema.ts`                      | `has_rrule` + `idx_calendar_events_has_rrule` + `is_shared`                       | VERIFIED             | Lines 99-108 confirm columns and index                                                                                                                                               |
+| `apps/api/src/broker/sync.ts`                    | `hasRrule` set on both insert and upsert paths                                    | VERIFIED             | Lines 113, 122                                                                                                                                                                       |
+| `apps/pwa/src/lib/hydrateEvents.ts`              | ISO→Temporal hydration with all-day PlainDate guard + ownership-routed calendarId | VERIFIED             | `Temporal.PlainDate.from` for allDay; `String(occ.ownerUserId)` routing                                                                                                              |
+| `apps/pwa/src/lib/calendarConfig.ts`             | `WEEK_START_DAY=0→SX_FIRST_DAY_OF_WEEK=7`, `buildCalendarConfig()`                | VERIFIED             | `WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY` at line 31                                                                                                                               |
+| `apps/pwa/src/lib/colorUtils.ts`                 | `deriveScheduleXColors()` (main/container/onContainer)                            | VERIFIED             | Full implementation without third-party color library                                                                                                                                |
+| `apps/pwa/src/styles/tokens.css`                 | CSS token layer with `--color-shared-family`, `--sx-color-*` overrides            | VERIFIED (existence) | File exists; not re-read but confirmed by prior grep showing `--color-shared-family: #F25C7A` and `--sx-color-`                                                                      |
+| `apps/pwa/src/components/CalendarShell.tsx`      | Schedule-X wired to TanStack Query + hydrateEvents + Zustand range                | VERIFIED             | Full pipeline confirmed (fetchEvents → hydrateEvents → eventsService.set); all four views; display timezone; onRangeUpdate exclusive end                                             |
+| `apps/pwa/src/components/EventDetailPopover.tsx` | Read-only popover; XSS-safe; focus trap; Escape-to-close                          | VERIFIED             | No `dangerouslySetInnerHTML` anywhere; all fields are plain-text JSX children; `aria-label="Close"`, `minHeight: 44px` close button; Escape listener via `document.addEventListener` |
+| `apps/pwa/src/components/ColorLegend.tsx`        | Always-visible legend with member rows + Family rose row                          | VERIFIED             | Per-member rows + hardcoded `'Family'` / `#F25C7A` row                                                                                                                               |
+| `apps/pwa/src/components/SkeletonCalendar.tsx`   | Shimmer skeleton                                                                  | VERIFIED (existence) | File present                                                                                                                                                                         |
+| `apps/pwa/src/components/EmptyState.tsx`         | Empty state component                                                             | VERIFIED (existence) | File present                                                                                                                                                                         |
+| `apps/pwa/src/components/EventProof.tsx`         | DELETED                                                                           | VERIFIED             | `grep -rn "EventProof" apps/pwa/src/` returns nothing                                                                                                                                |
+
+---
+
+### Key Link Verification
+
+| From                | To                         | Via                                                                                             | Status | Details                           |
+| ------------------- | -------------------------- | ----------------------------------------------------------------------------------------------- | ------ | --------------------------------- |
+| `expand.ts`         | VTIMEZONE registration     | `getAllSubcomponents('vtimezone')` at line 190, before `new ICAL.RecurExpansion` at line 264    | WIRED  | Mandatory ordering confirmed      |
+| `events.ts`         | `expand.ts`                | `expandOccurrences()` called per row in flatMap                                                 | WIRED  | Line 123                          |
+| `events.ts`         | `users.color` + `isShared` | `innerJoin(users)`, `select({ userColor: users.color, isShared: calendars.isShared })`          | WIRED  | Lines 84-89                       |
+| `CalendarShell.tsx` | `/api/events`              | `useQuery(['events', start, end]) → fetchEvents(start, end)`                                    | WIRED  | Lines 89-94                       |
+| `CalendarShell.tsx` | `hydrateEvents`            | `eventsService.set(hydrateEvents(eventsQuery.data.occurrences))` in data-keyed effect           | WIRED  | Lines 164-168                     |
+| `CalendarShell.tsx` | `calendarStore`            | Zustand selectors for `calendarRange`, `setCalendarRange`, `setOpenEventId`, `selectedView`     | WIRED  | Lines 73-76                       |
+| `CalendarShell.tsx` | `EventDetailPopover`       | Rendered as sibling; popover resolves event from TanStack Query cache via Zustand `openEventId` | WIRED  | Lines 318, 347                    |
+| `hydrateEvents.ts`  | `buildCalendarConfig` keys | `occ.isShared ? 'shared' : String(occ.ownerUserId)` exactly matches `buildCalendarConfig` keys  | WIRED  | Contract documented in both files |
+| `main.tsx`          | `temporal-polyfill/global` | First import before any Schedule-X code                                                         | WIRED  | Line 7                            |
+| `expand.ts`         | UTC windowing              | `ICAL.Time.fromJSDate(windowStart, true)` — `useUTC=true`                                       | WIRED  | Lines 217-218                     |
+| `CalendarShell.tsx` | Exclusive window end       | `range.end.toPlainDate().add({ days: 1 }).toString()` in `onRangeUpdate`                        | WIRED  | Line 149                          |
+
+---
+
+### Data-Flow Trace (Level 4)
+
+| Artifact                 | Data Variable                  | Source                                                                                      | Produces Real Data                                        | Status  |
+| ------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------- |
+| `CalendarShell.tsx`      | `eventsQuery.data.occurrences` | `fetchEvents(start, end)` → `/api/events` → MariaDB join + `expandOccurrences`              | Yes — DB query with 3-clause WHERE, joins, ICAL expansion | FLOWING |
+| `events.ts`              | `rows`                         | Drizzle `db.select().from(calendarEvents).innerJoin(calendars).innerJoin(users).where(...)` | Yes — parameterized SQL against live cache                | FLOWING |
+| `EventDetailPopover.tsx` | `occurrence`                   | `queryClient.getQueriesData({ queryKey: ['events'] })` — searches TanStack Query cache      | Yes — resolved from the same fetched data                 | FLOWING |
+| `ColorLegend.tsx`        | `members`                      | Passed from `CalendarShell` via `meQuery.data.user` → `fetchMe` → `/api/me`                 | Yes — live user data from DB                              | FLOWING |
+
+---
+
+### Behavioral Spot-Checks
+
+Not run — no dev server started (per spot-check constraints). The test suites stand in as executable
+verification:
+
+| Suite          | Command                                           | Result              | Status |
+| -------------- | ------------------------------------------------- | ------------------- | ------ |
+| API (47 tests) | `pnpm --filter @familysync/api test`              | 47 passed, 0 failed | PASS   |
+| PWA (39 tests) | `pnpm --filter @familysync/pwa test`              | 39 passed, 0 failed | PASS   |
+| API typecheck  | `pnpm --filter @familysync/api exec tsc --noEmit` | Clean               | PASS   |
+| PWA typecheck  | `pnpm --filter @familysync/pwa exec tsc --noEmit` | Clean               | PASS   |
+
+Key tests for the phase's success criteria:
+
+- `expand.test.ts` — DST wall-clock assertion (10:00 AM both sides of March 2026 transition), all-day `'YYYY-MM-DD'` assertion, EXDATE exclusion assertion
+- `events.test.ts` — color field, multi-calendar aggregation, `isShared` flag, `ownerUserId`, 400 on bad params
+- `hydrateEvents.test.ts` — all-day → `PlainDate`, timed → `ZonedDateTime`, shared → `'shared'`, personal → `String(ownerUserId)`
+- `calendarConfig.test.ts` — `WEEK_START_DAY=0` → `firstDayOfWeek=7`
+- `EventDetailPopover.test.tsx` — Escape closes, HTML-in-title rendered as escaped text (XSS guard)
+- `CalendarShell.test.tsx` — renders without throwing with timed + all-day mocked occurrences
+
+---
+
+### Probe Execution
+
+No probes declared in any plan frontmatter. No `scripts/*/tests/probe-*.sh` files found. Step 7c
+skipped.
+
+---
+
+### Requirements Coverage
+
+| Requirement | Source Plans        | Description                                                                     | Status    | Evidence                                                                                                                                                                                                                                                                  |
+| ----------- | ------------------- | ------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CAL-02      | 02-01 through 02-05 | User sees a unified, color-coded calendar aggregating every accessible calendar | SATISFIED | `events.ts` joins all calendars/users; `hydrateEvents` routes calendarId; `buildCalendarConfig` creates per-member + shared entries; `CalendarShell` renders the full aggregate                                                                                           |
+| CAL-03      | 02-01 through 02-05 | User can switch between week, month, day, and agenda/list views                 | SATISFIED | All four `createView*` factories present in `CalendarShell`; Schedule-X built-in header enables switching                                                                                                                                                                 |
+| CAL-07      | 02-01 through 02-05 | User can see all occurrences of a recurring event expanded correctly            | SATISFIED | `expandOccurrences` uses `ICAL.RecurExpansion` with VTIMEZONE pre-registration; EXDATE internal to RecurExpansion; all-day returns `'YYYY-MM-DD'`; IANA-annotated timed strings; UTC windowing; `has_rrule` pre-filter in route; `sync.ts` populates flag on every upsert |
+
+No orphaned requirements: the REQUIREMENTS.md Traceability table maps CAL-02 and CAL-03 to Phase 2
+and CAL-07 to Phase 3. However, all five plans in Phase 2 declare `requirements: [CAL-02, CAL-03, CAL-07]`,
+meaning Phase 2 satisfies CAL-07's display obligations while Phase 3 will deliver the write path.
+This is consistent — the REQUIREMENTS.md description of CAL-07 covers "see all occurrences expanded
+correctly", which Phase 2 delivers.
+
+---
+
+### Anti-Patterns Found
+
+Scanned: `expand.ts`, `events.ts`, `CalendarShell.tsx`, `hydrateEvents.ts`, `calendarConfig.ts`,
+`colorUtils.ts`, `EventDetailPopover.tsx`, `ColorLegend.tsx`, `main.tsx`, `App.tsx`.
+
+No `TBD`, `FIXME`, or `XXX` markers found in any phase file.
+
+No `TODO` or `HACK` markers found.
+
+No `return null` / placeholder stubs found in phase deliverables.
+
+No `dangerouslySetInnerHTML` in `EventDetailPopover.tsx`.
+
+Phase 3 footer area in `EventDetailPopover.tsx` is an empty `<div aria-hidden="true">` with an
+explicit "Phase 3 wires edit/delete here (D-08)" comment — this is an intentional reserved slot,
+not a stub (no user-visible output is missing).
+
+| File | Line | Pattern | Severity | Impact                 |
+| ---- | ---- | ------- | -------- | ---------------------- |
+| —    | —    | —       | —        | No anti-patterns found |
+
+---
+
+### Human Verification Required
+
+The following items need human testing in the running dev stack. All automated checks pass; these
+are inherently visual or behavioral and cannot be verified by static analysis.
+
+#### 1. Color-coded event rendering
+
+**Test:** Open the PWA with `DEV_AUTH_BYPASS=true`. Confirm personal events appear in the member's
+assigned color (from `users.color`). Confirm the ColorLegend is visible and decodes ownership.
+**Expected:** Member color chips in legend match event chip colors; rose lane ("Family") is present
+in the legend and will show events once the shared Fastmail calendar is created (D-16).
+**Why human:** Color rendering is visual; CSS token derivation and Schedule-X lightColors cannot be
+verified by grep.
+
+#### 2. All four views render events correctly
+
+**Test:** Click Day, Week, Month, and Agenda view buttons (Schedule-X built-in header). Confirm
+events appear in each view; confirm the week/day time grid scrolls and does not clip events.
+**Expected:** Consistent event list across all four views; no misplaced events; view switcher
+keyboard-accessible.
+**Why human:** DOM layout and Schedule-X rendering are not testable without a browser.
+
+#### 3. Recurring events — DST boundary (CAL-07)
+
+**Test:** Navigate to a week containing a recurring timed event that crosses the March 2026
+America/New_York DST boundary. Confirm the occurrence time does not shift ±1 hour after Spring
+Forward.
+**Expected:** A weekly 10:00 AM event shows 10:00 AM on both sides of the DST transition.
+**Why human:** VTIMEZONE registration is correct in code; real-data confirmation is needed.
+
+#### 4. All-day events — no date shift (CAL-07)
+
+**Test:** Find a recurring all-day event (birthday or holiday). Confirm it appears as a full-day
+banner on exactly the correct date in month and week views.
+**Expected:** `'2026-06-15'` all-day event appears on June 15, not June 14 or 16.
+**Why human:** `Temporal.PlainDate` routing is correct in code; visual confirmation needed.
+
+---
+
+### Gaps Summary
+
+None. All four success criteria are implemented and verified in the codebase. The only open item is
+the shared-family color lane being empty, which is explicitly deferred (D-16) pending creation of
+the shared Fastmail calendar — it is not a gap in the implementation.
+
+---
+
+_Verified: 2026-06-05T16:00:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-01-PLAN.md

@@ -20,23 +20,23 @@ user_setup: []
 
 must_haves:
   truths:
-    - "calendar_outbox table exists in the live MariaDB schema after drizzle-kit push"
-    - "calendar_events has an object_url column populated by sync.ts from obj.url"
-    - "vite-plugin-pwa is installed and importable in apps/pwa"
-    - "All Wave 0 RED test files exist and fail (no implementation yet)"
+    - 'calendar_outbox table exists in the live MariaDB schema after drizzle-kit push'
+    - 'calendar_events has an object_url column populated by sync.ts from obj.url'
+    - 'vite-plugin-pwa is installed and importable in apps/pwa'
+    - 'All Wave 0 RED test files exist and fail (no implementation yet)'
   artifacts:
-    - path: "apps/api/src/db/schema.ts"
-      provides: "calendarOutbox table + calendarEvents.objectUrl column"
-      contains: "calendarOutbox"
-    - path: "apps/api/tests/broker/vevent.test.ts"
-      provides: "RED stubs for VEVENT builder (CAL-04/CAL-07)"
-    - path: "apps/api/tests/broker/outboxWorker.test.ts"
-      provides: "RED stubs for outbox state machine (D-07/D-08/D-04)"
+    - path: 'apps/api/src/db/schema.ts'
+      provides: 'calendarOutbox table + calendarEvents.objectUrl column'
+      contains: 'calendarOutbox'
+    - path: 'apps/api/tests/broker/vevent.test.ts'
+      provides: 'RED stubs for VEVENT builder (CAL-04/CAL-07)'
+    - path: 'apps/api/tests/broker/outboxWorker.test.ts'
+      provides: 'RED stubs for outbox state machine (D-07/D-08/D-04)'
   key_links:
-    - from: "apps/api/src/broker/sync.ts"
-      to: "calendarEvents.objectUrl"
-      via: "upsert sets objectUrl from obj.url"
-      pattern: "objectUrl"
+    - from: 'apps/api/src/broker/sync.ts'
+      to: 'calendarEvents.objectUrl'
+      via: 'upsert sets objectUrl from obj.url'
+      pattern: 'objectUrl'
 ---
 
 <objective>
@@ -73,6 +73,7 @@ five RED test files.
 
 <artifacts_this_phase_produces>
 New symbols introduced across Phase 3 (excluded from drift verification):
+
 - DB: `calendarOutbox` table (`calendar_outbox`), `calendarEvents.objectUrl` column (`object_url`)
 - Backend files: `apps/api/src/broker/vevent.ts` (`buildVeventString`, `NewEventParams`), `apps/api/src/broker/write.ts` (`createCalendarEvent`, `updateCalendarEvent`, `deleteCalendarEvent`), `apps/api/src/broker/outboxWorker.ts` (`runOutboxDrain`, `startOutboxWorker`, `RRULE_PRESETS`)
 - Backend routes: `POST /api/events/create`, `PATCH /api/events/:uid/edit`, `DELETE /api/events/:uid`, `GET /api/events/sync-status`, `GET /api/events/writable-calendars`
@@ -81,7 +82,7 @@ New symbols introduced across Phase 3 (excluded from drift verification):
 - Zustand keys: `eventFormOpen`, `eventFormMode`, `eventFormUid`, `deleteDialogOpen`, `deleteDialogUid`, `lastSyncedUid`
 - Dep: `vite-plugin-pwa` (+ peer `workbox-window`, `workbox-build`)
 - PWA assets: `apps/pwa/public/icon-192.png`, `icon-512.png`, `apple-touch-icon.png`, generated `manifest.webmanifest` + service worker
-</artifacts_this_phase_produces>
+  </artifacts_this_phase_produces>
 
 <tasks>
 
@@ -123,6 +124,7 @@ New symbols introduced across Phase 3 (excluded from drift verification):
     On the existing `calendarEvents` table, add `objectUrl: varchar('object_url', { length: 1024 })` (nullable) immediately after the `etag` column — this stores the CalDAV object URL for If-Match update/delete (D-08, RESEARCH.md Open Q2).
 
     From the apps/pwa directory, install vite-plugin-pwa: `pnpm --filter @familysync/pwa add vite-plugin-pwa` (workbox-window and workbox-build install as peer deps). Do NOT configure the plugin yet (that is Plan 06).
+
   </action>
   <verify>
     <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api exec tsc --noEmit && grep -q "calendar_outbox" apps/api/src/db/schema.ts && grep -q "object_url" apps/api/src/db/schema.ts && grep -q '"vite-plugin-pwa"' apps/pwa/package.json</automated>
@@ -212,20 +214,22 @@ New symbols introduced across Phase 3 (excluded from drift verification):
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                 | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
 | package registry → build | New npm dependency (vite-plugin-pwa) enters the supply chain |
-| schema file → live DB | drizzle-kit push mutates the production schema |
+| schema file → live DB    | drizzle-kit push mutates the production schema               |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-SC | Tampering | vite-plugin-pwa + workbox peer deps install | mitigate | Blocking human-verify legitimacy checkpoint (Task 1) before install; `npm view` version check; npmjs.com repo confirmation |
-| T-03-01 | Tampering | drizzle-kit push | mitigate | Blocking human-action checkpoint (Task 5); abort on any reported destructive operation |
-| T-03-02 | Information Disclosure | calendar_outbox stores payload/etag | accept | Outbox rows are server-side only, never exposed to frontend; payload is the member's own VEVENT |
+| Threat ID | Category               | Component                                   | Disposition | Mitigation Plan                                                                                                            |
+| --------- | ---------------------- | ------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| T-03-SC   | Tampering              | vite-plugin-pwa + workbox peer deps install | mitigate    | Blocking human-verify legitimacy checkpoint (Task 1) before install; `npm view` version check; npmjs.com repo confirmation |
+| T-03-01   | Tampering              | drizzle-kit push                            | mitigate    | Blocking human-action checkpoint (Task 5); abort on any reported destructive operation                                     |
+| T-03-02   | Information Disclosure | calendar_outbox stores payload/etag         | accept      | Outbox rows are server-side only, never exposed to frontend; payload is the member's own VEVENT                            |
+
 </threat_model>
 
 <verification>
@@ -236,10 +240,11 @@ New symbols introduced across Phase 3 (excluded from drift verification):
 </verification>
 
 <success_criteria>
+
 - Outbox table + objectUrl column pushed live (the schema-push blocking requirement is satisfied here for the schema introduced this wave).
 - PWA tooling installed and legitimacy-gated.
 - Complete Wave 0 RED scaffold in place for every later implementing task.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-01-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-01-SUMMARY.md

@@ -38,12 +38,12 @@ key-files:
     - apps/pwa/package.json
 
 key-decisions:
-  - "D-Task5-DDL: drizzle-kit push is unsafe on MariaDB 11 with mysql dialect — misreads metadata and schedules truncate on populated tables. Additive DDL (calendar_outbox CREATE + object_url ALTER) was hand-applied and verified. Adopt drizzle-kit generate+migrate workflow before next schema change (tracked in todos/pending/adopt-drizzle-migrations-workflow.md)."
+  - 'D-Task5-DDL: drizzle-kit push is unsafe on MariaDB 11 with mysql dialect — misreads metadata and schedules truncate on populated tables. Additive DDL (calendar_outbox CREATE + object_url ALTER) was hand-applied and verified. Adopt drizzle-kit generate+migrate workflow before next schema change (tracked in todos/pending/adopt-drizzle-migrations-workflow.md).'
 
 patterns-established:
-  - "Outbox pattern: calendar_outbox table with status enum (pending/done/failed/dead), groupId for edit-as-move pairing, nextAttemptAt for exponential backoff"
-  - "objectUrl stored from tsdav obj.url on every sync upsert — enables If-Match header on CalDAV update/delete"
-  - "Wave 0 RED scaffold: all phase test files created before any implementation so GREEN gate is explicit"
+  - 'Outbox pattern: calendar_outbox table with status enum (pending/done/failed/dead), groupId for edit-as-move pairing, nextAttemptAt for exponential backoff'
+  - 'objectUrl stored from tsdav obj.url on every sync upsert — enables If-Match header on CalDAV update/delete'
+  - 'Wave 0 RED scaffold: all phase test files created before any implementation so GREEN gate is explicit'
 
 requirements-completed: [CAL-04, CAL-05, CAL-06, CAL-07, PWA-01, PWA-02]
 
@@ -128,5 +128,6 @@ None — no external service configuration required for this plan. The schema pu
 - **Action before next schema change:** Adopt `drizzle-kit generate` + `drizzle-kit migrate` (see pending todo) — do NOT run `drizzle-kit push` again
 
 ---
-*Phase: 03-event-write-back-pwa-install*
-*Completed: 2026-06-05*
+
+_Phase: 03-event-write-back-pwa-install_
+_Completed: 2026-06-05_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-02-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 02
 type: tdd
 wave: 2
-depends_on: ["03-01"]
+depends_on: ['03-01']
 files_modified:
   - apps/api/src/broker/vevent.ts
   - apps/api/src/broker/write.ts
@@ -15,26 +15,26 @@ user_setup: []
 
 must_haves:
   truths:
-    - "buildVeventString produces a valid VCALENDAR/VEVENT for timed, all-day, and recurring events"
-    - "All-day events serialize as DATE (no time component, no TZID) per D-13 — never coerced to DATETIME"
-    - "createCalendarEvent / updateCalendarEvent / deleteCalendarEvent route all Fastmail writes through tsdav with correct If-Match/If-None-Match"
+    - 'buildVeventString produces a valid VCALENDAR/VEVENT for timed, all-day, and recurring events'
+    - 'All-day events serialize as DATE (no time component, no TZID) per D-13 — never coerced to DATETIME'
+    - 'createCalendarEvent / updateCalendarEvent / deleteCalendarEvent route all Fastmail writes through tsdav with correct If-Match/If-None-Match'
   artifacts:
-    - path: "apps/api/src/broker/vevent.ts"
-      provides: "buildVeventString(NewEventParams) → { uid, icsString }"
-      exports: ["buildVeventString", "NewEventParams", "RRULE_PRESETS"]
+    - path: 'apps/api/src/broker/vevent.ts'
+      provides: 'buildVeventString(NewEventParams) → { uid, icsString }'
+      exports: ['buildVeventString', 'NewEventParams', 'RRULE_PRESETS']
       min_lines: 40
-    - path: "apps/api/src/broker/write.ts"
-      provides: "tsdav PUT/DELETE wrappers (broker boundary, D-12)"
-      exports: ["createCalendarEvent", "updateCalendarEvent", "deleteCalendarEvent"]
+    - path: 'apps/api/src/broker/write.ts'
+      provides: 'tsdav PUT/DELETE wrappers (broker boundary, D-12)'
+      exports: ['createCalendarEvent', 'updateCalendarEvent', 'deleteCalendarEvent']
   key_links:
-    - from: "apps/api/src/broker/vevent.ts"
-      to: "ical.js ICAL.Component / ICAL.Time"
-      via: "VEVENT construction"
+    - from: 'apps/api/src/broker/vevent.ts'
+      to: 'ical.js ICAL.Component / ICAL.Time'
+      via: 'VEVENT construction'
       pattern: "ICAL\\.(Component|Time)"
-    - from: "apps/api/src/broker/write.ts"
-      to: "tsdav createCalendarObject/updateCalendarObject/deleteCalendarObject"
-      via: "FastmailClient methods"
-      pattern: "(create|update|delete)CalendarObject"
+    - from: 'apps/api/src/broker/write.ts'
+      to: 'tsdav createCalendarObject/updateCalendarObject/deleteCalendarObject'
+      via: 'FastmailClient methods'
+      pattern: '(create|update|delete)CalendarObject'
 ---
 
 <objective>
@@ -129,19 +129,21 @@ Output: `vevent.ts`, `write.ts`, both GREEN against their Plan 01 test files.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                 | Description                                        |
+| ------------------------ | -------------------------------------------------- |
 | broker → Fastmail CalDAV | Only write.ts issues PUT/DELETE to Fastmail (D-12) |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-03 | Tampering | VEVENT field serialization (summary/location/description with special chars) | mitigate | ical.js ICAL.Component handles line-folding + escaping (commas, semicolons, newlines); never hand-roll ICS strings (RESEARCH §Don't Hand-Roll) |
-| T-03-04 | Spoofing | etag forgery to bypass conflict detection | mitigate | etag is sourced server-side (calendarEvents.etag) by the worker, never accepted from the browser; write.ts only forwards what the server supplies |
-| T-03-05 | Elevation of Privilege | write.ts called with another member's calendar | accept (here) | Calendar ownership is enforced at the route layer (Plan 04, V4); write.ts is a low-level primitive with no auth context |
+| Threat ID | Category               | Component                                                                    | Disposition   | Mitigation Plan                                                                                                                                   |
+| --------- | ---------------------- | ---------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-03   | Tampering              | VEVENT field serialization (summary/location/description with special chars) | mitigate      | ical.js ICAL.Component handles line-folding + escaping (commas, semicolons, newlines); never hand-roll ICS strings (RESEARCH §Don't Hand-Roll)    |
+| T-03-04   | Spoofing               | etag forgery to bypass conflict detection                                    | mitigate      | etag is sourced server-side (calendarEvents.etag) by the worker, never accepted from the browser; write.ts only forwards what the server supplies |
+| T-03-05   | Elevation of Privilege | write.ts called with another member's calendar                               | accept (here) | Calendar ownership is enforced at the route layer (Plan 04, V4); write.ts is a low-level primitive with no auth context                           |
+
 </threat_model>
 
 <verification>
@@ -151,9 +153,10 @@ Output: `vevent.ts`, `write.ts`, both GREEN against their Plan 01 test files.
 </verification>
 
 <success_criteria>
+
 - VEVENT builder correct for timed, all-day (DATE), and recurring events.
 - tsdav write wrappers enforce the broker boundary with correct If-Match/filename wiring.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-02-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-02-SUMMARY.md

@@ -22,8 +22,8 @@ tech-stack:
   added: []
   patterns:
     - "ICAL.Recur.fromString + new ICAL.Property('rrule') for RRULE serialization (addPropertyWithValue on string produces char-split output)"
-    - "ICAL.Time({ isDate: true }, ICAL.Timezone.localTimezone) for all-day DATE values (TS types require 2-arg constructor)"
-    - "ICAL.Time.fromJSDate(date, true) for timed UTC events (useUTC=true → Z suffix, no TZID)"
+    - 'ICAL.Time({ isDate: true }, ICAL.Timezone.localTimezone) for all-day DATE values (TS types require 2-arg constructor)'
+    - 'ICAL.Time.fromJSDate(date, true) for timed UTC events (useUTC=true → Z suffix, no TZID)'
     - "null etag passed as '' in tsdav calendarObject (safe default; tsdav skips If-Match header)"
 
 key-files:
@@ -34,7 +34,7 @@ key-files:
 
 key-decisions:
   - "D-02-RRULE: ICAL.Recur.fromString + ICAL.Property('rrule') is required for correct RRULE serialization. ICAL.Component.addPropertyWithValue('rrule', string) treats the string as a TEXT value and serializes each character individually — unusable. Use ICAL.Recur.fromString → prop.setValue(recur) → vevent.addProperty(prop)."
-  - "D-02-DATE-ZONE: ICAL.Time constructor TypeScript signature requires 2 args (data, zone). For all-day DATE values, isDate:true suppresses any TZID output regardless of which zone is passed. ICAL.Timezone.localTimezone is the safe choice; it satisfies the type without adding TZID to DATE properties."
+  - 'D-02-DATE-ZONE: ICAL.Time constructor TypeScript signature requires 2 args (data, zone). For all-day DATE values, isDate:true suppresses any TZID output regardless of which zone is passed. ICAL.Timezone.localTimezone is the safe choice; it satisfies the type without adding TZID to DATE properties.'
 
 # Metrics
 duration: ~4min
@@ -83,6 +83,7 @@ completed: 2026-06-05
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] RRULE serialization via addPropertyWithValue produces character-split output**
+
 - **Found during:** Task 1 — first test run showed `RRULE:0=F;1=R;2=E;3=Q...` instead of `RRULE:FREQ=WEEKLY;BYDAY=MO`
 - **Issue:** `vevent.addPropertyWithValue('rrule', string)` passes a JavaScript string where ical.js expects a RECUR value type. ical.js iterates the string object properties (0, 1, 2...) and serializes each character as a key-value pair.
 - **Fix:** Use `ICAL.Recur.fromString(params.rruleString)` to parse the string into a RECUR value object, then `new ICAL.Property('rrule')` + `prop.setValue(recur)` + `vevent.addProperty(prop)`.
@@ -90,6 +91,7 @@ completed: 2026-06-05
 - **Commit:** `a1243c1` (combined with Task 2)
 
 **2. [Rule 1 - Bug] ICAL.Time constructor TypeScript type error (2 args required)**
+
 - **Found during:** Task 2 — `tsc --noEmit` reported `Expected 2 arguments, but got 1` for `new ICAL.Time({ isDate: true })` calls
 - **Issue:** ical.js TypeScript declarations define `constructor(data: timeInit, zone: Timezone)` as requiring both arguments, though the JavaScript implementation accepts 1.
 - **Fix:** Pass `ICAL.Timezone.localTimezone` as the second arg. For `isDate: true` DATE values, the zone has no effect on serialization — it does not add TZID to the property.
@@ -115,5 +117,6 @@ No new network endpoints or auth paths introduced. `broker/write.ts` is a low-le
 - `pnpm --filter @familysync/api exec tsc --noEmit` — clean (no errors)
 
 ---
-*Phase: 03-event-write-back-pwa-install*
-*Completed: 2026-06-05*
+
+_Phase: 03-event-write-back-pwa-install_
+_Completed: 2026-06-05_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-03-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 03
 type: execute
 wave: 2
-depends_on: ["03-01"]
+depends_on: ['03-01']
 files_modified:
   - apps/api/src/routes/events.ts
   - apps/api/tests/routes/events.test.ts
@@ -13,24 +13,24 @@ user_setup: []
 
 must_haves:
   truths:
-    - "POST /api/events/create validates input, resolves the writable target calendar, enqueues a pending outbox row, and returns 202"
-    - "PATCH /api/events/:uid/edit and DELETE /api/events/:uid enqueue update/delete outbox rows with the cached etag"
-    - "A member cannot enqueue a write to a calendar they do not own (403) — D-03 / V4 access control"
+    - 'POST /api/events/create validates input, resolves the writable target calendar, enqueues a pending outbox row, and returns 202'
+    - 'PATCH /api/events/:uid/edit and DELETE /api/events/:uid enqueue update/delete outbox rows with the cached etag'
+    - 'A member cannot enqueue a write to a calendar they do not own (403) — D-03 / V4 access control'
     - "GET /api/events/sync-status?uid= returns the outbox status for that member's UID"
-    - "Edit that changes the target calendar enqueues a linked delete+create pair in one transaction (D-04)"
+    - 'Edit that changes the target calendar enqueues a linked delete+create pair in one transaction (D-04)'
     - "GET /api/events/writable-calendars returns the member's writable set per D-03 — own personal + shared Family (read-write); never the other member's read-only personal"
   artifacts:
-    - path: "apps/api/src/routes/events.ts"
-      provides: "create/edit/delete write endpoints + sync-status + writable-calendars, all enqueue-only (broker boundary)"
-      contains: "/writable-calendars"
+    - path: 'apps/api/src/routes/events.ts'
+      provides: 'create/edit/delete write endpoints + sync-status + writable-calendars, all enqueue-only (broker boundary)'
+      contains: '/writable-calendars'
   key_links:
-    - from: "apps/api/src/routes/events.ts"
-      to: "calendarOutbox"
-      via: "db.insert(calendarOutbox)"
-      pattern: "calendarOutbox"
-    - from: "apps/api/src/routes/events.ts"
-      to: "calendars (ownership check)"
-      via: "WHERE userId = currentUser.id"
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'calendarOutbox'
+      via: 'db.insert(calendarOutbox)'
+      pattern: 'calendarOutbox'
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'calendars (ownership check)'
+      via: 'WHERE userId = currentUser.id'
       pattern: "calendars\\.userId"
 ---
 
@@ -89,6 +89,7 @@ tests from Plan 01.
     DELETE `/:uid`: ownership check as above; insert a `delete` outbox row with `calendarObjectUrl` + `etag`. Return 202.
 
     Do NOT build the VEVENT here and do NOT call Fastmail — the worker (Plan 04 wiring) does both. Wrap DB work in try/catch returning 503 per the existing pattern.
+
   </action>
   <verify>
     <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- routes/events && pnpm --filter @familysync/api exec tsc --noEmit</automated>
@@ -139,6 +140,7 @@ tests from Plan 01.
     Per RESEARCH.md Open Q3: select the writable set = rows in `calendars WHERE userId = currentUser.id` (the member's own personal calendar(s)) UNION rows WHERE `isShared = 1` (the shared Family calendar, when read-write to the household). Express this as a single Drizzle query with `WHERE eq(calendars.userId, currentUser.id) OR eq(calendars.isShared, true)`. The other member's personal calendar (a row with a different `userId` and `isShared = 0/false`) MUST NOT appear — it is a read-only overlay only (D-03), never a write target.
 
     Map each row to the response shape `{ calendars: [{ url, displayName, color, isShared }] }` (exactly the `WritableCalendar` shape Plan 05's `fetchWritableCalendars` consumes). Wrap the db work in try/catch returning 503 per the existing GET handler pattern. Do NOT include any Fastmail call (broker boundary).
+
   </action>
   <verify>
     <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- routes/events && grep -q "/writable-calendars" apps/api/src/routes/events.ts && pnpm --filter @familysync/api exec tsc --noEmit</automated>
@@ -155,23 +157,25 @@ tests from Plan 01.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| client → write API | Untrusted member input (event fields, target calendar, uid) crosses here |
+| Boundary                 | Description                                                                               |
+| ------------------------ | ----------------------------------------------------------------------------------------- |
+| client → write API       | Untrusted member input (event fields, target calendar, uid) crosses here                  |
 | member A → member B data | A member must never write to, treat-as-writable, or read another member's outbox/calendar |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-06 | Elevation of Privilege | write to another member's personal calendar | mitigate | Route asserts `calendars.userId === currentUser.id OR isShared=1` before enqueue; else 403 (D-03 / ASVS V4) |
-| T-03-07 | Information Disclosure | sync-status leaking another member's outbox row | mitigate | sync-status query filtered `WHERE userId = currentUser.id` |
-| T-03-08 | Tampering | XSS/oversized payload via title/location/description | mitigate | zod length bounds (title 255, location/description 2000); plain-text storage; rendered as JSX children downstream |
-| T-03-09 | Tampering | SQL injection via uid/calendarUrl | mitigate | Drizzle parameterized queries; no string interpolation |
-| T-03-10 | Spoofing | client-supplied etag bypassing conflict detection | mitigate | etag read from calendarEvents server-side at enqueue; client never supplies it |
-| T-03-11 | Elevation of Privilege | writable-calendars surfacing another member's personal calendar as a write target | mitigate | Query restricted to `userId = currentUser.id OR isShared = true`; another member's `isShared=false` personal row is never returned; client treats the response as authoritative and the write endpoints re-enforce D-03 on enqueue |
+| Threat ID | Category               | Component                                                                         | Disposition | Mitigation Plan                                                                                                                                                                                                                    |
+| --------- | ---------------------- | --------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-06   | Elevation of Privilege | write to another member's personal calendar                                       | mitigate    | Route asserts `calendars.userId === currentUser.id OR isShared=1` before enqueue; else 403 (D-03 / ASVS V4)                                                                                                                        |
+| T-03-07   | Information Disclosure | sync-status leaking another member's outbox row                                   | mitigate    | sync-status query filtered `WHERE userId = currentUser.id`                                                                                                                                                                         |
+| T-03-08   | Tampering              | XSS/oversized payload via title/location/description                              | mitigate    | zod length bounds (title 255, location/description 2000); plain-text storage; rendered as JSX children downstream                                                                                                                  |
+| T-03-09   | Tampering              | SQL injection via uid/calendarUrl                                                 | mitigate    | Drizzle parameterized queries; no string interpolation                                                                                                                                                                             |
+| T-03-10   | Spoofing               | client-supplied etag bypassing conflict detection                                 | mitigate    | etag read from calendarEvents server-side at enqueue; client never supplies it                                                                                                                                                     |
+| T-03-11   | Elevation of Privilege | writable-calendars surfacing another member's personal calendar as a write target | mitigate    | Query restricted to `userId = currentUser.id OR isShared = true`; another member's `isShared=false` personal row is never returned; client treats the response as authoritative and the write endpoints re-enforce D-03 on enqueue |
+
 </threat_model>
 
 <verification>
@@ -181,9 +185,10 @@ tests from Plan 01.
 </verification>
 
 <success_criteria>
+
 - All five write/status/writable-calendars endpoints enqueue-only and member-scoped.
 - D-03 ownership enforced on both the write path and the writable-calendars listing; D-04 edit-as-move pair transactional; D-09 polling endpoint live.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-03-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-03-SUMMARY.md

@@ -26,11 +26,11 @@ tech-stack:
   added: []
   patterns:
     - "resolveUserId(c): dev-bypass c.get('user') first, fallback to getAuth(c) for OIDC — same pattern as me.ts"
-    - "Enqueue-only write endpoints: no Fastmail call in routes; db.insert(calendarOutbox) is the only side effect"
-    - "Edit-as-move: db.transaction with paired delete+create sharing a groupId (D-04)"
-    - "sync-status: .orderBy(desc(createdAt)).limit(1) to get latest outbox row; userId-scoped (T-03-07)"
-    - "writable-calendars: WHERE userId=currentUser.id OR isShared=1 — authoritative D-03 enforcement (T-03-11)"
-    - "Test mock pattern for db.transaction: factory fn cb receives mock tx with insert; vi.mock hoisted factory captures mutable refs"
+    - 'Enqueue-only write endpoints: no Fastmail call in routes; db.insert(calendarOutbox) is the only side effect'
+    - 'Edit-as-move: db.transaction with paired delete+create sharing a groupId (D-04)'
+    - 'sync-status: .orderBy(desc(createdAt)).limit(1) to get latest outbox row; userId-scoped (T-03-07)'
+    - 'writable-calendars: WHERE userId=currentUser.id OR isShared=1 — authoritative D-03 enforcement (T-03-11)'
+    - 'Test mock pattern for db.transaction: factory fn cb receives mock tx with insert; vi.mock hoisted factory captures mutable refs'
     - "devAuthBypass mock in tests: vi.mock('../auth/devBypass.js') injects dev user so write tests get authenticated context"
 
 key-files:
@@ -40,15 +40,15 @@ key-files:
     - apps/api/tests/routes/events.test.ts
 
 key-decisions:
-  - "resolveUserId helper uses any type to avoid Hono context generic complexity — acceptable for internal helper"
-  - "Two-query ownership check for edit/delete (get event, then check calendar isShared) to maintain simple from().where() chain that test mocks can intercept without innerJoin complexity"
-  - "Writable-calendars response maps to { url, displayName, color, isShared } — the Plan 05 WritableCalendar shape"
+  - 'resolveUserId helper uses any type to avoid Hono context generic complexity — acceptable for internal helper'
+  - 'Two-query ownership check for edit/delete (get event, then check calendar isShared) to maintain simple from().where() chain that test mocks can intercept without innerJoin complexity'
+  - 'Writable-calendars response maps to { url, displayName, color, isShared } — the Plan 05 WritableCalendar shape'
   - "sync-status returns { uid, status: 'done' } when no outbox row found (nothing pending = settled)"
 
 patterns-established:
-  - "Enqueue-only write route: validate → check ownership → db.insert(calendarOutbox) → return 202; no broker call"
-  - "D-03 ownership enforcement at two layers: write endpoints AND writable-calendars listing"
-  - "vi.mock devAuthBypass for write-endpoint tests avoids needing ENV manipulation or OIDC infrastructure"
+  - 'Enqueue-only write route: validate → check ownership → db.insert(calendarOutbox) → return 202; no broker call'
+  - 'D-03 ownership enforcement at two layers: write endpoints AND writable-calendars listing'
+  - 'vi.mock devAuthBypass for write-endpoint tests avoids needing ENV manipulation or OIDC infrastructure'
 
 requirements-completed: [CAL-04, CAL-05, CAL-06, CAL-07]
 
@@ -98,6 +98,7 @@ completed: 2026-06-05
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] TypeScript error on resolveUserId helper**
+
 - **Found during:** Task 1 (implementation) — tsc --noEmit reported TS2493/TS2339 on complex Hono context type inference
 - **Issue:** The helper function tried to infer the Hono context type from `eventsRouter.get` parameters, which failed due to tuple type length mismatch
 - **Fix:** Changed helper parameter to `any` with inline cast; added clarifying comment
@@ -139,5 +140,6 @@ No new network endpoints or auth paths beyond what is in the plan's threat model
 - Plan 05 (EventForm + client.ts): POST /create, PATCH /:uid/edit, DELETE /:uid endpoints are live; GET /writable-calendars provides the picker data
 
 ---
-*Phase: 03-event-write-back-pwa-install*
-*Completed: 2026-06-05*
+
+_Phase: 03-event-write-back-pwa-install_
+_Completed: 2026-06-05_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-04-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 04
 type: tdd
 wave: 3
-depends_on: ["03-02", "03-03"]
+depends_on: ['03-02', '03-03']
 files_modified:
   - apps/api/src/broker/outboxWorker.ts
   - apps/api/src/index.ts
@@ -14,33 +14,33 @@ user_setup: []
 
 must_haves:
   truths:
-    - "The worker drains pending outbox rows, builds the VEVENT, PUTs/DELETEs via the broker, and triggers a targeted single-calendar re-sync on success (D-06)"
-    - "Transient failures (5xx/network/timeout) back off exponentially within a bounded window; max attempts → dead (D-07)"
-    - "Hard failures (400/401/403) stop immediately as failed (D-07)"
-    - "412 conflicts route OUT of the retry loop into the conflict flow: mark failed, re-sync, no overwrite (D-08)"
-    - "Edit-as-move processes the create row before the linked delete row; create-fail aborts the delete (D-04)"
-    - "The worker is started from index.ts as a sibling to the ctag poller"
+    - 'The worker drains pending outbox rows, builds the VEVENT, PUTs/DELETEs via the broker, and triggers a targeted single-calendar re-sync on success (D-06)'
+    - 'Transient failures (5xx/network/timeout) back off exponentially within a bounded window; max attempts → dead (D-07)'
+    - 'Hard failures (400/401/403) stop immediately as failed (D-07)'
+    - '412 conflicts route OUT of the retry loop into the conflict flow: mark failed, re-sync, no overwrite (D-08)'
+    - 'Edit-as-move processes the create row before the linked delete row; create-fail aborts the delete (D-04)'
+    - 'The worker is started from index.ts as a sibling to the ctag poller'
   artifacts:
-    - path: "apps/api/src/broker/outboxWorker.ts"
-      provides: "runOutboxDrain + startOutboxWorker (state machine, retry/backoff, re-sync)"
-      exports: ["runOutboxDrain", "startOutboxWorker"]
+    - path: 'apps/api/src/broker/outboxWorker.ts'
+      provides: 'runOutboxDrain + startOutboxWorker (state machine, retry/backoff, re-sync)'
+      exports: ['runOutboxDrain', 'startOutboxWorker']
       min_lines: 60
-    - path: "apps/api/src/index.ts"
-      provides: "startOutboxWorker() wired at startup"
-      contains: "startOutboxWorker"
+    - path: 'apps/api/src/index.ts'
+      provides: 'startOutboxWorker() wired at startup'
+      contains: 'startOutboxWorker'
   key_links:
-    - from: "apps/api/src/broker/outboxWorker.ts"
-      to: "broker/write.ts"
-      via: "create/update/deleteCalendarEvent"
-      pattern: "(create|update|delete)CalendarEvent"
-    - from: "apps/api/src/broker/outboxWorker.ts"
-      to: "broker/sync.ts syncCalendar"
-      via: "targeted re-sync on confirm (D-06)"
-      pattern: "syncCalendar"
-    - from: "apps/api/src/index.ts"
-      to: "startOutboxWorker"
-      via: "background worker startup"
-      pattern: "startOutboxWorker"
+    - from: 'apps/api/src/broker/outboxWorker.ts'
+      to: 'broker/write.ts'
+      via: 'create/update/deleteCalendarEvent'
+      pattern: '(create|update|delete)CalendarEvent'
+    - from: 'apps/api/src/broker/outboxWorker.ts'
+      to: 'broker/sync.ts syncCalendar'
+      via: 'targeted re-sync on confirm (D-06)'
+      pattern: 'syncCalendar'
+    - from: 'apps/api/src/index.ts'
+      to: 'startOutboxWorker'
+      via: 'background worker startup'
+      pattern: 'startOutboxWorker'
 ---
 
 <objective>
@@ -132,21 +132,23 @@ Output: `outboxWorker.ts` GREEN against Plan 01's state-machine tests; worker st
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
-| worker → Fastmail | The worker is the only component that drains the outbox to Fastmail |
-| stored payload → VEVENT | Member-supplied payload is reconstructed into an ICS PUT |
+| Boundary                | Description                                                         |
+| ----------------------- | ------------------------------------------------------------------- |
+| worker → Fastmail       | The worker is the only component that drains the outbox to Fastmail |
+| stored payload → VEVENT | Member-supplied payload is reconstructed into an ICS PUT            |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-11 | Repudiation | silent last-write-wins on concurrent edit | mitigate | 412 If-Match conflict routes to conflict flow (re-sync + warn), never overwrites (D-08) |
-| T-03-12 | Denial of Service | a poison row retrying forever | mitigate | MAX_ATTEMPTS=5 then dead-letter; bounded backoff window (~30 min) per D-07 |
-| T-03-13 | Information Disclosure | logging decrypted app password during dispatch | mitigate | Per-item catch logs `err.message` only; never the credential (poller T-03-04 pattern) |
-| T-03-14 | Tampering | partial-failure data loss on edit-as-move | mitigate | create-before-delete ordering; create-fail aborts delete; delete-fail surfaces "remove manually" (D-04) |
+| Threat ID | Category               | Component                                      | Disposition | Mitigation Plan                                                                                         |
+| --------- | ---------------------- | ---------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
+| T-03-11   | Repudiation            | silent last-write-wins on concurrent edit      | mitigate    | 412 If-Match conflict routes to conflict flow (re-sync + warn), never overwrites (D-08)                 |
+| T-03-12   | Denial of Service      | a poison row retrying forever                  | mitigate    | MAX_ATTEMPTS=5 then dead-letter; bounded backoff window (~30 min) per D-07                              |
+| T-03-13   | Information Disclosure | logging decrypted app password during dispatch | mitigate    | Per-item catch logs `err.message` only; never the credential (poller T-03-04 pattern)                   |
+| T-03-14   | Tampering              | partial-failure data loss on edit-as-move      | mitigate    | create-before-delete ordering; create-fail aborts delete; delete-fail surfaces "remove manually" (D-04) |
+
 </threat_model>
 
 <verification>
@@ -156,9 +158,10 @@ Output: `outboxWorker.ts` GREEN against Plan 01's state-machine tests; worker st
 </verification>
 
 <success_criteria>
+
 - End-to-end backend write loop closed: endpoint → outbox → worker → Fastmail → re-sync → cache authoritative.
 - D-04/D-06/D-07/D-08 all enforced and tested.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-04-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-04-SUMMARY.md

@@ -26,14 +26,14 @@ affects:
 tech-stack:
   added: []
   patterns:
-    - "runOutboxDrain/startOutboxWorker exports follow runPoll/startBrokerPoller pattern from poller.ts"
-    - "CONFLICT_STATUS=412 routes to conflict flow (mark failed + re-sync) — never overwrite (D-08)"
-    - "TRANSIENT_STATUSES set for backoff; HARD_FAIL_STATUSES for immediate failure (D-07)"
-    - "MAX_ATTEMPTS=5, BACKOFF_SECONDS=[15,60,300,600,1800] (~30min window, T-03-12)"
-    - "Edit-as-move D-04: sort create-before-delete within groupId; failedCreateGroups set skips paired delete"
-    - "triggerTargetedResync: fetch fresh fetchCalendars(), find by URL, call syncCalendar (Pitfall 7 + D-06)"
-    - "vi.hoisted() required for vi.mock() factory variables when test file has static import of the module under test"
-    - "and() single .where() call required for Drizzle TS correctness (chained .where().where() not typed)"
+    - 'runOutboxDrain/startOutboxWorker exports follow runPoll/startBrokerPoller pattern from poller.ts'
+    - 'CONFLICT_STATUS=412 routes to conflict flow (mark failed + re-sync) — never overwrite (D-08)'
+    - 'TRANSIENT_STATUSES set for backoff; HARD_FAIL_STATUSES for immediate failure (D-07)'
+    - 'MAX_ATTEMPTS=5, BACKOFF_SECONDS=[15,60,300,600,1800] (~30min window, T-03-12)'
+    - 'Edit-as-move D-04: sort create-before-delete within groupId; failedCreateGroups set skips paired delete'
+    - 'triggerTargetedResync: fetch fresh fetchCalendars(), find by URL, call syncCalendar (Pitfall 7 + D-06)'
+    - 'vi.hoisted() required for vi.mock() factory variables when test file has static import of the module under test'
+    - 'and() single .where() call required for Drizzle TS correctness (chained .where().where() not typed)'
 
 key-files:
   created:
@@ -44,7 +44,7 @@ key-files:
 
 key-decisions:
   - "D-03-04-hoisting: test scaffold's vi.mock() factory referenced const variables in TDZ (hoisting issue hidden by previous RED import failure). Fix: wrap all factory-referenced mock variables in vi.hoisted(). Auto-fixed per Rule 1."
-  - "D-03-04-where: Drizzle types remove .where() from return after first call. Use and(cond1, cond2) in a single .where() — aligned test mock chain accordingly (mockFromFn → mockWherePending directly)."
+  - 'D-03-04-where: Drizzle types remove .where() from return after first call. Use and(cond1, cond2) in a single .where() — aligned test mock chain accordingly (mockFromFn → mockWherePending directly).'
   - "D-03-04-cred: loadClientForUser called inside dispatchRow try/catch. In tests, the db mock returns outbox rows for any select call causing decryptPassword to throw; catch falls back to createFastmailClient('','') which is mocked. In production the real Drizzle query always succeeds."
 
 # Metrics
@@ -98,6 +98,7 @@ completed: 2026-06-05
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] vi.mock() factory references TDZ variable (hoisting issue in test scaffold)**
+
 - **Found during:** Task 1 — vitest threw `ReferenceError: Cannot access 'mockSelectFn' before initialization`
 - **Issue:** Wave-0 RED scaffold used `const mockSelectFn = vi.fn()` in file scope, referenced inside `vi.mock()` factory. `vi.mock()` is hoisted to top of file; `const` is not. When `outboxWorker.ts` existed, the static import triggered module loading which triggered the mock factory before `mockSelectFn` was initialized.
 - **Fix:** Wrapped all factory-referenced mock variables in `vi.hoisted(() => { ... })` so they are initialized before the hoisted `vi.mock()` factory runs. Also simplified mock chain from two-layer (mockLimitFn → mockWherePending) to single-layer (mockWherePending directly from mockFromFn) to match the and()-based single `.where()` call.
@@ -105,6 +106,7 @@ completed: 2026-06-05
 - **Commit:** `cd4a893`
 
 **2. [Rule 1 - Bug] Drizzle TS types disallow chained .where().where() — single and() required**
+
 - **Found during:** Task 1 — `tsc --noEmit` reported TS2339 `Property 'where' does not exist on type Omit<MySqlSelectBase<...>, 'where'>`
 - **Issue:** The initial implementation used two separate `.where()` calls (`.where(eq(...)).where(lte(...))`). Drizzle removes `where` from the type after the first `.where()` call.
 - **Fix:** Replaced with `and(eq(calendarOutbox.status, 'pending'), lte(calendarOutbox.nextAttemptAt, new Date()))` in a single `.where()` call. Updated test mock chain to match.
@@ -118,6 +120,7 @@ None — outboxWorker.ts is a fully wired state machine calling real broker func
 ## Threat Surface Scan
 
 No new network endpoints or auth paths. The worker is an internal background process with no HTTP surface. All T-03-11 through T-03-14 threat mitigations from the plan's threat model are implemented:
+
 - T-03-11 (repudiation/last-write-wins): 412 routes to conflict flow, never overwrites
 - T-03-12 (DoS/poison row): MAX_ATTEMPTS=5 + dead-letter enforced
 - T-03-13 (info disclosure): per-item catch logs err.message only; credential never logged
@@ -138,5 +141,6 @@ No new network endpoints or auth paths. The worker is an internal background pro
 ## Self-Check: PASSED
 
 ---
-*Phase: 03-event-write-back-pwa-install*
-*Completed: 2026-06-05*
+
+_Phase: 03-event-write-back-pwa-install_
+_Completed: 2026-06-05_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-05-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 05
 type: execute
 wave: 3
-depends_on: ["03-03"]
+depends_on: ['03-03']
 files_modified:
   - apps/pwa/src/api/client.ts
   - apps/pwa/src/store/calendarStore.ts
@@ -16,29 +16,29 @@ user_setup: []
 must_haves:
   truths:
     - "A member can tap 'New Event', fill the form, and save — POST /api/events/create fires and the form closes"
-    - "The form supports timed and all-day events, a recurrence preset (None/Daily/Weekly/Monthly/Yearly), title/location/description"
-    - "The calendar picker is hidden when the member has exactly one writable calendar (D-02)"
-    - "Edit mode pre-populates the form and calls PATCH /api/events/:uid/edit"
+    - 'The form supports timed and all-day events, a recurrence preset (None/Daily/Weekly/Monthly/Yearly), title/location/description'
+    - 'The calendar picker is hidden when the member has exactly one writable calendar (D-02)'
+    - 'Edit mode pre-populates the form and calls PATCH /api/events/:uid/edit'
   artifacts:
-    - path: "apps/pwa/src/components/EventForm.tsx"
-      provides: "create/edit modal form (bottom sheet on phone, dialog on desktop)"
+    - path: 'apps/pwa/src/components/EventForm.tsx'
+      provides: 'create/edit modal form (bottom sheet on phone, dialog on desktop)'
       min_lines: 80
-    - path: "apps/pwa/src/api/client.ts"
-      provides: "createEvent, updateEvent, fetchWritableCalendars typed calls"
-      exports: ["createEvent", "updateEvent", "fetchWritableCalendars"]
+    - path: 'apps/pwa/src/api/client.ts'
+      provides: 'createEvent, updateEvent, fetchWritableCalendars typed calls'
+      exports: ['createEvent', 'updateEvent', 'fetchWritableCalendars']
   key_links:
-    - from: "apps/pwa/src/components/EventForm.tsx"
-      to: "/api/events/create"
-      via: "createEvent mutation"
-      pattern: "createEvent"
-    - from: "apps/pwa/src/api/client.ts"
-      to: "/api/events/writable-calendars"
-      via: "fetchWritableCalendars GET"
-      pattern: "writable-calendars"
-    - from: "apps/pwa/src/components/CalendarShell.tsx"
-      to: "EventForm"
-      via: "New Event FAB toggles eventFormOpen"
-      pattern: "eventFormOpen"
+    - from: 'apps/pwa/src/components/EventForm.tsx'
+      to: '/api/events/create'
+      via: 'createEvent mutation'
+      pattern: 'createEvent'
+    - from: 'apps/pwa/src/api/client.ts'
+      to: '/api/events/writable-calendars'
+      via: 'fetchWritableCalendars GET'
+      pattern: 'writable-calendars'
+    - from: 'apps/pwa/src/components/CalendarShell.tsx'
+      to: 'EventForm'
+      via: 'New Event FAB toggles eventFormOpen'
+      pattern: 'eventFormOpen'
 ---
 
 <objective>
@@ -95,6 +95,7 @@ Output: EventForm + client write calls + store keys + FAB, all wired to the Plan
     In client.ts add exported interfaces `CreateEventPayload` (title, allDay, start, end, optional location, description, recurrence: 'none'|'daily'|'weekly'|'monthly'|'yearly', calendarUrl?), `CreateEventResponse` ({ uid }), `WritableCalendar` ({ url, displayName, color, isShared }). Add `createEvent(payload): Promise<CreateEventResponse>` (POST), `updateEvent(uid, payload): Promise<CreateEventResponse>` (PATCH `/api/events/${uid}/edit`), and `fetchWritableCalendars(): Promise<WritableCalendar[]>` (GET `/api/events/writable-calendars`, added by Plan 03 Task 3 — call it unconditionally; parse the JSON `{ calendars }` envelope and return `body.calendars`). The server is the authoritative owner of the D-03 writable set; do NOT derive the writable set on the client. All follow the existing fetch shape with credentials:'include' and `if (!res.ok) throw`.
 
     In calendarStore.ts extend `CalendarStore` with `eventFormOpen: boolean`, `eventFormMode: 'create'|'edit'`, `eventFormUid: string|null`, plus setters `setEventForm(open, mode?, uid?)`. Defaults: closed, mode 'create', uid null. Keep all server data out of Zustand (D — server state stays in TanStack Query).
+
   </action>
   <verify>
     <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa exec tsc --noEmit && grep -q "createEvent" apps/pwa/src/api/client.ts && grep -q "writable-calendars" apps/pwa/src/api/client.ts && grep -q "eventFormOpen" apps/pwa/src/store/calendarStore.ts && pnpm --filter @familysync/pwa test</automated>
@@ -158,18 +159,20 @@ Output: EventForm + client write calls + store keys + FAB, all wired to the Plan
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary         | Description                                      |
+| ---------------- | ------------------------------------------------ |
 | form input → API | Member-typed event fields cross to the write API |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-15 | Tampering | XSS via event title/location/description in the form | mitigate | All values rendered as plain-text JSX children; never dangerouslySetInnerHTML (Phase 2 T-02e-01 pattern); server re-validates with zod (Plan 03) |
-| T-03-16 | Elevation of Privilege | client offering a non-writable calendar in the picker | mitigate | Picker is populated only from the authoritative `GET /api/events/writable-calendars` set (Plan 03, D-03 enforced server-side); the client never derives writability, and the write endpoints re-enforce D-03 ownership on enqueue regardless |
+| Threat ID | Category               | Component                                             | Disposition | Mitigation Plan                                                                                                                                                                                                                              |
+| --------- | ---------------------- | ----------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-15   | Tampering              | XSS via event title/location/description in the form  | mitigate    | All values rendered as plain-text JSX children; never dangerouslySetInnerHTML (Phase 2 T-02e-01 pattern); server re-validates with zod (Plan 03)                                                                                             |
+| T-03-16   | Elevation of Privilege | client offering a non-writable calendar in the picker | mitigate    | Picker is populated only from the authoritative `GET /api/events/writable-calendars` set (Plan 03, D-03 enforced server-side); the client never derives writability, and the write endpoints re-enforce D-03 ownership on enqueue regardless |
+
 </threat_model>
 
 <verification>
@@ -179,9 +182,10 @@ Output: EventForm + client write calls + store keys + FAB, all wired to the Plan
 </verification>
 
 <success_criteria>
+
 - CAL-04 and CAL-07 create paths are user-reachable through EventForm → POST /api/events/create.
 - Edit mode pre-populates and PATCHes; calendar picker honors D-01/D-02, sourced from the Plan 03 writable-calendars endpoint.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-05-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-05-SUMMARY.md

@@ -1,15 +1,30 @@
 ---
-phase: "03"
-plan: "05"
+phase: '03'
+plan: '05'
 subsystem: pwa-event-write-ui
 tags: [react, tanstack-query, zustand, eventform, caldav-write, pwa]
 dependency_graph:
-  requires: ["03-03"]
-  provides: ["EventForm component", "createEvent/updateEvent/fetchWritableCalendars client calls", "eventFormOpen/eventFormMode/eventFormUid Zustand keys"]
-  affects: ["CalendarShell", "EventDetailPopover (future edit trigger)"]
+  requires: ['03-03']
+  provides:
+    [
+      'EventForm component',
+      'createEvent/updateEvent/fetchWritableCalendars client calls',
+      'eventFormOpen/eventFormMode/eventFormUid Zustand keys',
+    ]
+  affects: ['CalendarShell', 'EventDetailPopover (future edit trigger)']
 tech_stack:
   added: []
-  patterns: ["TanStack Query useMutation + useQuery", "Zustand UI-only state", "bottom-sheet/dialog responsive overlay", "vi.hoisted() for mock TDZ", "D-01 last-used calendar localStorage", "D-02 conditional calendar picker", "D-11 whole-series recurrence presets", "T-03-15 plain-text JSX XSS guard"]
+  patterns:
+    [
+      'TanStack Query useMutation + useQuery',
+      'Zustand UI-only state',
+      'bottom-sheet/dialog responsive overlay',
+      'vi.hoisted() for mock TDZ',
+      'D-01 last-used calendar localStorage',
+      'D-02 conditional calendar picker',
+      'D-11 whole-series recurrence presets',
+      'T-03-15 plain-text JSX XSS guard',
+    ]
 key_files:
   created:
     - apps/pwa/src/components/EventForm.tsx
@@ -20,14 +35,14 @@ key_files:
     - apps/pwa/src/store/calendarStore.ts
     - apps/pwa/src/components/CalendarShell.tsx
 decisions:
-  - "D-01 calendar default: last-used URL from localStorage (eventForm.lastCalendarUrl), first writable calendar as fallback"
-  - "D-02 calendar picker: hidden when writableCalendars.length === 1, shown when >1 — driven by GET /api/events/writable-calendars"
-  - "T-03-15 XSS: all field values as plain-text JSX children in EventForm; no dangerouslySetInnerHTML in code"
-  - "vi.hoisted() required for mock factory variables to avoid TDZ (D-03-04-hoisting pattern)"
-  - "eventFormOpen selector added to CalendarShell per-field selector pattern (Bug B guard preserved)"
+  - 'D-01 calendar default: last-used URL from localStorage (eventForm.lastCalendarUrl), first writable calendar as fallback'
+  - 'D-02 calendar picker: hidden when writableCalendars.length === 1, shown when >1 — driven by GET /api/events/writable-calendars'
+  - 'T-03-15 XSS: all field values as plain-text JSX children in EventForm; no dangerouslySetInnerHTML in code'
+  - 'vi.hoisted() required for mock factory variables to avoid TDZ (D-03-04-hoisting pattern)'
+  - 'eventFormOpen selector added to CalendarShell per-field selector pattern (Bug B guard preserved)'
 metrics:
   duration_minutes: 6
-  completed_date: "2026-06-05"
+  completed_date: '2026-06-05'
   tasks_completed: 3
   files_created: 3
   files_modified: 3
@@ -42,6 +57,7 @@ metrics:
 ### Task 1: Typed write client calls + Zustand form-state keys
 
 Extended `apps/pwa/src/api/client.ts` with:
+
 - `CreateEventPayload` interface (title, allDay, start, end, recurrence, optional location/description/calendarUrl)
 - `CreateEventResponse` interface ({ uid })
 - `WritableCalendar` interface ({ url, displayName, color, isShared }) — D-03 server-authoritative shape
@@ -51,6 +67,7 @@ Extended `apps/pwa/src/api/client.ts` with:
 - `fetchWritableCalendars()` — GET /api/events/writable-calendars, parses `{ calendars }` envelope, returns `WritableCalendar[]`
 
 Extended `apps/pwa/src/store/calendarStore.ts` with:
+
 - `eventFormOpen: boolean` (default: false)
 - `eventFormMode: 'create' | 'edit'` (default: 'create')
 - `eventFormUid: string | null` (default: null)
@@ -59,6 +76,7 @@ Extended `apps/pwa/src/store/calendarStore.ts` with:
 ### Task 2: EventForm modal
 
 New `apps/pwa/src/components/EventForm.tsx` (715 lines):
+
 - Bottom sheet on phone (≤767px), centered 480px dialog on tablet/desktop — reuses EventDetailPopover pattern
 - Fields per UI-SPEC §EventForm order: title, all-day toggle, start date/time, end date/time, calendar picker (conditional), recurrence, location, description
 - All-day toggle (`role="switch"`, aria-checked): hides time inputs when on, restores 09:00/10:00 defaults when off
@@ -77,6 +95,7 @@ New `apps/pwa/src/components/EventForm.tsx` (715 lines):
 ### Task 3: Mount EventForm + "New Event" FAB/toolbar in CalendarShell
 
 Updated `apps/pwa/src/components/CalendarShell.tsx`:
+
 - Added `setEventForm` and `eventFormOpen` per-field selectors (Bug B guard preserved)
 - Phone layout: fixed FAB bottom-right (56×56px, dark neutral fill, Plus icon, 56px ≥ 44px touch target)
 - Tablet/desktop layout: toolbar button above calendar content (dark neutral fill, Plus icon + "New Event" label)
@@ -95,6 +114,7 @@ Updated `apps/pwa/src/components/CalendarShell.tsx`:
 ### Auto-fixed Issues
 
 **1. [Rule 3 - Blocking] vi.hoisted() required for EventForm.test.tsx mock factory variables**
+
 - **Found during:** Task 2 GREEN phase
 - **Issue:** `vi.mock('../api/client.js', ...)` factory captured `mockCreateEvent` etc. before initialization (TDZ), causing `ReferenceError: Cannot access 'mockCreateEvent' before initialization`
 - **Fix:** Moved mock function declarations into `vi.hoisted()` call per decision D-03-04-hoisting
@@ -105,10 +125,10 @@ None — plan executed with one auto-fixed TDZ blocker.
 
 ## Threat Surface Scan
 
-| Flag | File | Description |
-|------|------|-------------|
+| Flag             | File                                  | Description                                                                                                                      |
+| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | T-03-15 verified | apps/pwa/src/components/EventForm.tsx | All event field values rendered as plain-text JSX children; no `dangerouslySetInnerHTML` in code (appears only in JSDoc comment) |
-| T-03-16 verified | apps/pwa/src/api/client.ts | `fetchWritableCalendars` reads server-authoritative D-03 set verbatim; no client-side writability derivation |
+| T-03-16 verified | apps/pwa/src/api/client.ts            | `fetchWritableCalendars` reads server-authoritative D-03 set verbatim; no client-side writability derivation                     |
 
 No new threat surface introduced beyond what was planned.
 
@@ -118,13 +138,13 @@ None. All API calls are wired to real Plan 03 endpoints. SyncStateToast feedback
 
 ## Self-Check: PASSED
 
-| Item | Status |
-|------|--------|
-| apps/pwa/src/components/EventForm.tsx | FOUND |
-| apps/pwa/src/api/client.test.ts | FOUND |
-| apps/pwa/src/components/EventForm.test.tsx | FOUND |
-| 6400ce6 test(03-05): RED client calls | FOUND |
-| 6ffcdcb feat(03-05): client calls GREEN | FOUND |
-| df416a4 test(03-05): RED EventForm | FOUND |
-| 86cefff feat(03-05): EventForm GREEN | FOUND |
-| 69eac90 feat(03-05): CalendarShell wired | FOUND |
+| Item                                       | Status |
+| ------------------------------------------ | ------ |
+| apps/pwa/src/components/EventForm.tsx      | FOUND  |
+| apps/pwa/src/api/client.test.ts            | FOUND  |
+| apps/pwa/src/components/EventForm.test.tsx | FOUND  |
+| 6400ce6 test(03-05): RED client calls      | FOUND  |
+| 6ffcdcb feat(03-05): client calls GREEN    | FOUND  |
+| df416a4 test(03-05): RED EventForm         | FOUND  |
+| 86cefff feat(03-05): EventForm GREEN       | FOUND  |
+| 69eac90 feat(03-05): CalendarShell wired   | FOUND  |

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-06-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 06
 type: execute
 wave: 4
-depends_on: ["03-05", "03-03"]
+depends_on: ['03-05', '03-03']
 files_modified:
   - apps/pwa/src/api/client.ts
   - apps/pwa/src/store/calendarStore.ts
@@ -17,26 +17,26 @@ user_setup: []
 
 must_haves:
   truths:
-    - "The EventDetailPopover footer shows Edit and Delete actions (D-10)"
-    - "Tapping Edit opens EventForm pre-populated; tapping Delete opens a two-tap confirmation dialog"
-    - "Confirming delete calls DELETE /api/events/:uid and shows the sync toast"
+    - 'The EventDetailPopover footer shows Edit and Delete actions (D-10)'
+    - 'Tapping Edit opens EventForm pre-populated; tapping Delete opens a two-tap confirmation dialog'
+    - 'Confirming delete calls DELETE /api/events/:uid and shows the sync toast'
     - "After any write the SyncStateToast polls /api/events/sync-status and shows Syncing/Saved/Didn't save; on done it invalidates the events query (D-06/D-09)"
-    - "A 412 conflict shows the conflict copy and re-fetches the calendar (D-08)"
+    - 'A 412 conflict shows the conflict copy and re-fetches the calendar (D-08)'
   artifacts:
-    - path: "apps/pwa/src/components/SyncStateToast.tsx"
-      provides: "polled sync-state feedback toast (D-05/D-09)"
+    - path: 'apps/pwa/src/components/SyncStateToast.tsx'
+      provides: 'polled sync-state feedback toast (D-05/D-09)'
       min_lines: 40
-    - path: "apps/pwa/src/components/DeleteConfirmationDialog.tsx"
-      provides: "two-tap destructive delete confirmation"
+    - path: 'apps/pwa/src/components/DeleteConfirmationDialog.tsx'
+      provides: 'two-tap destructive delete confirmation'
   key_links:
-    - from: "apps/pwa/src/components/SyncStateToast.tsx"
-      to: "/api/events/sync-status"
-      via: "useQuery refetchInterval while pending"
-      pattern: "syncStatus|sync-status"
-    - from: "apps/pwa/src/components/EventDetailPopover.tsx"
-      to: "DeleteConfirmationDialog"
-      via: "Delete footer button opens deleteDialog"
-      pattern: "deleteDialogOpen"
+    - from: 'apps/pwa/src/components/SyncStateToast.tsx'
+      to: '/api/events/sync-status'
+      via: 'useQuery refetchInterval while pending'
+      pattern: 'syncStatus|sync-status'
+    - from: 'apps/pwa/src/components/EventDetailPopover.tsx'
+      to: 'DeleteConfirmationDialog'
+      via: 'Delete footer button opens deleteDialog'
+      pattern: 'deleteDialogOpen'
 ---
 
 <objective>
@@ -154,19 +154,21 @@ Output: edit/delete footer, delete dialog, sync toast + polling, all per the UI
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary            | Description                                      |
+| ------------------- | ------------------------------------------------ |
 | delete action → API | A destructive operation crosses to the write API |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-17 | Tampering | accidental/irreversible delete | mitigate | Mandatory two-tap DeleteConfirmationDialog; no inline single-tap delete; no "don't ask again" (UI-SPEC) |
-| T-03-18 | Repudiation | silent data loss on failed delete sync | mitigate | failed/dead toast persists until dismissed; server-authoritative refetch restores the event; no silent loss (D-08) |
-| T-03-19 | Information Disclosure | sync-status of another member surfaced in toast | mitigate | sync-status is member-scoped server-side (Plan 03 T-03-07); toast only queries the current member's uid |
+| Threat ID | Category               | Component                                       | Disposition | Mitigation Plan                                                                                                    |
+| --------- | ---------------------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| T-03-17   | Tampering              | accidental/irreversible delete                  | mitigate    | Mandatory two-tap DeleteConfirmationDialog; no inline single-tap delete; no "don't ask again" (UI-SPEC)            |
+| T-03-18   | Repudiation            | silent data loss on failed delete sync          | mitigate    | failed/dead toast persists until dismissed; server-authoritative refetch restores the event; no silent loss (D-08) |
+| T-03-19   | Information Disclosure | sync-status of another member surfaced in toast | mitigate    | sync-status is member-scoped server-side (Plan 03 T-03-07); toast only queries the current member's uid            |
+
 </threat_model>
 
 <verification>
@@ -176,9 +178,10 @@ Output: edit/delete footer, delete dialog, sync toast + polling, all per the UI
 </verification>
 
 <success_criteria>
+
 - CAL-05 edit and CAL-06 delete are user-reachable from the popover.
 - Every write surfaces non-blocking polled sync feedback; 412 conflict shows the warning + re-fetch (D-08); done invalidates events (D-06).
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-06-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-06-SUMMARY.md

@@ -1,19 +1,20 @@
 ---
 phase: 03-event-write-back-pwa-install
-plan: "06"
+plan: '06'
 subsystem: pwa-frontend
 tags: [delete, sync-feedback, toast, confirmation-dialog, tdd, zustand, tanstack-query]
 dependency_graph:
-  requires: ["03-03", "03-05"]
-  provides: ["edit/delete vertical slices", "polled sync-state feedback toast"]
-  affects: ["apps/pwa/src/components/CalendarShell.tsx", "apps/pwa/src/components/EventDetailPopover.tsx"]
+  requires: ['03-03', '03-05']
+  provides: ['edit/delete vertical slices', 'polled sync-state feedback toast']
+  affects:
+    ['apps/pwa/src/components/CalendarShell.tsx', 'apps/pwa/src/components/EventDetailPopover.tsx']
 tech_stack:
   added: []
   patterns:
-    - "refetchInterval: (query) => pending ? 3000 : false — conditional poll for SyncStateToast"
-    - "useCalendarStore selector form for new keys — avoids CalendarShell re-renders"
-    - "DeleteConfirmationDialog: useMutation + onSuccess wires lastSyncedUid then closes"
-    - "SyncStateToast invalidateQueries on done/conflict (D-06/D-08); EventForm no longer self-invalidates"
+    - 'refetchInterval: (query) => pending ? 3000 : false — conditional poll for SyncStateToast'
+    - 'useCalendarStore selector form for new keys — avoids CalendarShell re-renders'
+    - 'DeleteConfirmationDialog: useMutation + onSuccess wires lastSyncedUid then closes'
+    - 'SyncStateToast invalidateQueries on done/conflict (D-06/D-08); EventForm no longer self-invalidates'
 key_files:
   created:
     - apps/pwa/src/components/SyncStateToast.tsx
@@ -29,13 +30,13 @@ key_files:
     - apps/pwa/src/components/EventDetailPopover.test.tsx
     - apps/pwa/src/components/EventForm.test.tsx
 decisions:
-  - "EventForm.onSuccess calls setLastSyncedUid(uid) instead of invalidateQueries — SyncStateToast owns the cache invalidation on done/conflict (D-06/D-08)"
-  - "DeleteConfirmationDialog mounts unconditionally in CalendarShell (like SyncStateToast); renders null when closed — avoids conditional mount logic in shell"
-  - "SyncStateToast refetchInterval callback form used (not a static number) so it reads current query data for the pending check"
-  - "EventDetailPopover footer tests updated to support selector-form useCalendarStore calls (selector-aware mock pattern)"
+  - 'EventForm.onSuccess calls setLastSyncedUid(uid) instead of invalidateQueries — SyncStateToast owns the cache invalidation on done/conflict (D-06/D-08)'
+  - 'DeleteConfirmationDialog mounts unconditionally in CalendarShell (like SyncStateToast); renders null when closed — avoids conditional mount logic in shell'
+  - 'SyncStateToast refetchInterval callback form used (not a static number) so it reads current query data for the pending check'
+  - 'EventDetailPopover footer tests updated to support selector-form useCalendarStore calls (selector-aware mock pattern)'
 metrics:
   duration_minutes: 70
-  completed: "2026-06-05"
+  completed: '2026-06-05'
   tasks: 3
   files_created: 4
   files_modified: 7
@@ -47,22 +48,24 @@ metrics:
 
 ## Tasks Completed
 
-| Task | Name | Commit | Files |
-|------|------|--------|-------|
-| 1 | deleteEvent + fetchSyncStatus + Zustand delete/sync keys | `8aeacc8` | client.ts, calendarStore.ts |
-| 2 | SyncStateToast with polled sync-status (D-05/D-06/D-08/D-09) | `aa7c4c3` | SyncStateToast.tsx, CalendarShell.tsx, EventForm.tsx |
-| 3 | EventDetailPopover Edit/Delete footer + DeleteConfirmationDialog | `40322e1` | EventDetailPopover.tsx, DeleteConfirmationDialog.tsx, CalendarShell.tsx |
+| Task | Name                                                             | Commit    | Files                                                                   |
+| ---- | ---------------------------------------------------------------- | --------- | ----------------------------------------------------------------------- |
+| 1    | deleteEvent + fetchSyncStatus + Zustand delete/sync keys         | `8aeacc8` | client.ts, calendarStore.ts                                             |
+| 2    | SyncStateToast with polled sync-status (D-05/D-06/D-08/D-09)     | `aa7c4c3` | SyncStateToast.tsx, CalendarShell.tsx, EventForm.tsx                    |
+| 3    | EventDetailPopover Edit/Delete footer + DeleteConfirmationDialog | `40322e1` | EventDetailPopover.tsx, DeleteConfirmationDialog.tsx, CalendarShell.tsx |
 
 ## What Was Built
 
 ### Task 1 — Client calls + Zustand keys (RED: `8357cf9`, GREEN: `8aeacc8`)
 
 **`apps/pwa/src/api/client.ts`:**
+
 - `deleteEvent(uid): Promise<void>` — DELETE `/api/events/:uid`, credentials:include, throws on !ok
 - `fetchSyncStatus(uid): Promise<SyncStatus>` — GET `/api/events/sync-status?uid=`
 - Exported types: `SyncStatusValue`, `SyncStatus`
 
 **`apps/pwa/src/store/calendarStore.ts`:**
+
 - `deleteDialogOpen: boolean` — default false
 - `deleteDialogUid: string | null` — default null
 - `lastSyncedUid: string | null` — drives SyncStateToast polling
@@ -72,6 +75,7 @@ metrics:
 ### Task 2 — SyncStateToast (RED: `6874e1a`, GREEN: `aa7c4c3`)
 
 **`apps/pwa/src/components/SyncStateToast.tsx`** (210 lines):
+
 - `useQuery(['syncStatus', lastSyncedUid], fetchSyncStatus)` with `refetchInterval` callback — 3000ms while pending, disabled on terminal status
 - States per UI-SPEC: pending (Loader2 spinner, "Syncing…"), done (Check, "Saved"), failed generic (AlertCircle, "Didn't save. Try again."), failed conflict/412 (conflict copy), dead ("Not saved. Check your connection.")
 - `role="status"` for pending/done; `role="alert"` for failed/dead
@@ -87,12 +91,14 @@ metrics:
 ### Task 3 — EventDetailPopover footer + DeleteConfirmationDialog (RED: `2fbeffe`, GREEN: `40322e1`)
 
 **`apps/pwa/src/components/EventDetailPopover.tsx`:**
+
 - Replaced `aria-hidden="true"` reserved footer placeholder with a live flex row
 - Left: "Edit" ghost button (Edit2 icon, `--color-text-primary`) — calls `setEventForm(true, 'edit', uid)` + closes popover
 - Right: "Delete" ghost button (Trash2 icon, `--color-destructive`) — calls `setDeleteDialog(true, uid)`
 - Both buttons: 44px touch targets, plain-text label children
 
 **`apps/pwa/src/components/DeleteConfirmationDialog.tsx`** (208 lines):
+
 - Centered modal, max-width 320px, `--color-overlay` backdrop, focus trap
 - `role="dialog"`, `aria-modal="true"`, Escape to cancel
 - Heading "Delete event?" (18px/600), body "This will be removed from your Fastmail calendar."
@@ -123,6 +129,7 @@ grep -q "Delete event?" apps/pwa/src/components/DeleteConfirmationDialog.tsx →
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] EventForm.test.tsx mock lacked setLastSyncedUid**
+
 - **Found during:** Task 2 GREEN
 - **Issue:** EventForm calls `useCalendarStore((s) => s.setLastSyncedUid)` (selector form). The existing test mock returned a static object regardless of selector, so the selector call returned the full mock object instead of the setter function.
 - **Fix:** Updated both the `vi.mock` factory and the `renderForm` helper's `mockImplementation` to support the selector call pattern — `if (typeof selector === 'function') return selector(state)`.
@@ -130,24 +137,28 @@ grep -q "Delete event?" apps/pwa/src/components/DeleteConfirmationDialog.tsx →
 - **Commit:** `aa7c4c3`
 
 **2. [Rule 2 - Missing] SyncStateToast test used @testing-library/user-event not installed**
+
 - **Found during:** Task 2 RED
 - **Issue:** Test imported `userEvent` but only `@testing-library/react` is installed.
 - **Fix:** Replaced with `fireEvent.click` from `@testing-library/react` (already in project).
 - **Files modified:** `apps/pwa/src/components/SyncStateToast.test.tsx`
 
 **3. [Rule 1 - Bug] Fake timers blocked waitFor in SyncStateToast tests**
+
 - **Found during:** Task 2 GREEN
 - **Issue:** `vi.useFakeTimers()` in `beforeEach` caused all `waitFor` calls to timeout because `waitFor` uses `setTimeout` internally.
 - **Fix:** Use `vi.useFakeTimers({ shouldAdvanceTime: true })` only for the specific auto-dismiss and refetch interval tests; use real timers for all query-resolution tests. `afterEach` calls `vi.useRealTimers()`.
 - **Files modified:** `apps/pwa/src/components/SyncStateToast.test.tsx`
 
 **4. [Rule 1 - Bug] SyncStateToast JSDoc comment contained "EventSource"**
+
 - **Found during:** Task 2 verify
 - **Issue:** Acceptance criteria `grep -c "EventSource" ... returns 0` would have failed due to a comment mentioning "No SSE / EventSource".
 - **Fix:** Changed comment to "No SSE — polling only (D-09)".
 - **Files modified:** `apps/pwa/src/components/SyncStateToast.tsx`
 
 **5. [Rule 3 - Required] EventDetailPopover.test.tsx needed selector-aware mock**
+
 - **Found during:** Task 3 GREEN (during mock update for new selector calls)
 - **Issue:** EventDetailPopover now calls `useCalendarStore` in selector form for `setEventForm` and `setDeleteDialog`. Old mock was not selector-aware.
 - **Fix:** Updated all mock implementations in `EventDetailPopover.test.tsx` to support both selector and non-selector call patterns.
@@ -160,6 +171,7 @@ None — all data is wired from real TanStack Query + Zustand state. No placehol
 ## Threat Flags
 
 No new network endpoints, auth paths, or schema changes introduced. All threats in plan's threat register are mitigated:
+
 - T-03-17: Two-tap DeleteConfirmationDialog enforced; no inline single-tap delete
 - T-03-18: failed/dead toast persists until dismissed; server refetch restores event on conflict
 - T-03-19: fetchSyncStatus is member-scoped server-side (Plan 03-03 T-03-07); client queries current member's uid only
@@ -167,10 +179,12 @@ No new network endpoints, auth paths, or schema changes introduced. All threats
 ## Self-Check: PASSED
 
 Files exist:
+
 - apps/pwa/src/components/SyncStateToast.tsx — FOUND
 - apps/pwa/src/components/DeleteConfirmationDialog.tsx — FOUND
 
 Commits exist:
+
 - 8357cf9 — FOUND (test RED task 1)
 - 8aeacc8 — FOUND (feat GREEN task 1)
 - 6874e1a — FOUND (test RED task 2)

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-07-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 07
 type: execute
 wave: 3
-depends_on: ["03-01"]
+depends_on: ['03-01']
 files_modified:
   - apps/pwa/vite.config.ts
   - apps/pwa/index.html
@@ -18,27 +18,27 @@ user_setup: []
 
 must_haves:
   truths:
-    - "The production build emits a valid manifest.webmanifest with name/icons/display:standalone/scope:/ and a service worker"
+    - 'The production build emits a valid manifest.webmanifest with name/icons/display:standalone/scope:/ and a service worker'
     - "The service worker's navigateFallbackDenylist excludes /callback, /api/, /health so the OIDC redirect is never intercepted (Gate 2 risk)"
-    - "On iOS Safari non-standalone, a first-visit install banner appears with a 5-step annotated Add-to-Home-Screen walkthrough"
-    - "On Android, an Install banner appears only when beforeinstallprompt fires and triggers the native prompt"
-    - "Neither install surface renders when the app is already installed (display-mode: standalone)"
+    - 'On iOS Safari non-standalone, a first-visit install banner appears with a 5-step annotated Add-to-Home-Screen walkthrough'
+    - 'On Android, an Install banner appears only when beforeinstallprompt fires and triggers the native prompt'
+    - 'Neither install surface renders when the app is already installed (display-mode: standalone)'
   artifacts:
-    - path: "apps/pwa/vite.config.ts"
-      provides: "VitePWA manifest + SW config with auth-safe denylist"
-      contains: "navigateFallbackDenylist"
-    - path: "apps/pwa/src/components/InstallPrompt.tsx"
-      provides: "iOS walkthrough banner/sheet + Android beforeinstallprompt banner"
+    - path: 'apps/pwa/vite.config.ts'
+      provides: 'VitePWA manifest + SW config with auth-safe denylist'
+      contains: 'navigateFallbackDenylist'
+    - path: 'apps/pwa/src/components/InstallPrompt.tsx'
+      provides: 'iOS walkthrough banner/sheet + Android beforeinstallprompt banner'
       min_lines: 80
   key_links:
-    - from: "apps/pwa/vite.config.ts"
-      to: "OIDC /callback"
-      via: "navigateFallbackDenylist excludes /callback"
-      pattern: "callback"
-    - from: "apps/pwa/src/components/InstallPrompt.tsx"
-      to: "iOS standalone detection"
-      via: "isIOSSafariNonStandalone + display-mode media query"
-      pattern: "standalone"
+    - from: 'apps/pwa/vite.config.ts'
+      to: 'OIDC /callback'
+      via: 'navigateFallbackDenylist excludes /callback'
+      pattern: 'callback'
+    - from: 'apps/pwa/src/components/InstallPrompt.tsx'
+      to: 'iOS standalone detection'
+      via: 'isIOSSafariNonStandalone + display-mode media query'
+      pattern: 'standalone'
 ---
 
 <objective>
@@ -84,6 +84,7 @@ Output: configured VitePWA build, install icons + meta, InstallPrompt mounted in
     Generate the three icon PNGs into apps/pwa/public/: `icon-192.png` (192×192), `icon-512.png` (512×512), `apple-touch-icon.png` (180×180). Create a simple solid `#4A90D9` background with a white "F" / calendar glyph using an available CLI tool (ImageMagick `convert`, `sharp` via a one-off node script, or similar). If no image tool is available, set autonomous:false is NOT needed — emit minimal valid PNGs programmatically (node Buffer / sharp). The icons must be valid PNGs at the exact pixel dimensions.
 
     Add to apps/pwa/index.html `<head>` the five entries from RESEARCH.md Pattern 5: apple-touch-icon link (180×180), theme-color meta (#4A90D9), apple-mobile-web-app-capable yes, apple-mobile-web-app-status-bar-style default, apple-mobile-web-app-title FamilySync.
+
   </action>
   <verify>
     <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa build && test -f apps/pwa/dist/manifest.webmanifest && node -e "const m=require('./apps/pwa/dist/manifest.webmanifest');if(m.display!=='standalone'||m.scope!=='/'||!m.icons.some(i=>i.sizes==='512x512'))process.exit(1)" && grep -q "navigateFallbackDenylist" apps/pwa/vite.config.ts && grep -q "apple-touch-icon" apps/pwa/index.html</automated>
@@ -128,19 +129,21 @@ Output: configured VitePWA build, install icons + meta, InstallPrompt mounted in
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                    | Description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
 | service worker → navigation | The SW can intercept navigations including the OIDC callback |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-20 | Spoofing | SW serving a cached shell for /callback, breaking OIDC code exchange / iOS standalone login | mitigate | `navigateFallbackDenylist: [/^\/callback/, /^\/api\//, /^\/health/]`; verified against a production build (Pitfall 1/6); Gate 2 confirms end-to-end (Plan 08) |
-| T-03-21 | Tampering | SW caching authenticated API responses | mitigate | `runtimeCaching: []` — no /api caching; /api in denylist |
-| T-03-22 | Information Disclosure | manifest/icons leaking nothing sensitive | accept | Static public assets only; no secrets in manifest |
+| Threat ID | Category               | Component                                                                                   | Disposition | Mitigation Plan                                                                                                                                               |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-20   | Spoofing               | SW serving a cached shell for /callback, breaking OIDC code exchange / iOS standalone login | mitigate    | `navigateFallbackDenylist: [/^\/callback/, /^\/api\//, /^\/health/]`; verified against a production build (Pitfall 1/6); Gate 2 confirms end-to-end (Plan 08) |
+| T-03-21   | Tampering              | SW caching authenticated API responses                                                      | mitigate    | `runtimeCaching: []` — no /api caching; /api in denylist                                                                                                      |
+| T-03-22   | Information Disclosure | manifest/icons leaking nothing sensitive                                                    | accept      | Static public assets only; no secrets in manifest                                                                                                             |
+
 </threat_model>
 
 <verification>
@@ -150,10 +153,11 @@ Output: configured VitePWA build, install icons + meta, InstallPrompt mounted in
 </verification>
 
 <success_criteria>
+
 - PWA-01: app installs to Home Screen (manifest + SW, standalone) on iOS and Android.
 - PWA-02: first-time guided install (iOS walkthrough + Android prompt); never shown when installed.
 - OIDC `/callback` is never SW-intercepted (Gate 2 prerequisite).
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-07-SUMMARY.md` when done.

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-07-SUMMARY.md

@@ -124,6 +124,7 @@ None — plan executed exactly as written. Icon generation method (pure Node.js
 ## Threat Surface Scan
 
 No new security-relevant surface introduced beyond what was in the threat model:
+
 - T-03-20 (SW intercepts /callback): **mitigated** — `navigateFallbackDenylist` confirmed in vite.config.ts
 - T-03-21 (SW caches API responses): **mitigated** — `runtimeCaching: []`
 - T-03-22 (icons/manifest leak secrets): **accepted** — static public assets only
@@ -142,5 +143,6 @@ No new security-relevant surface introduced beyond what was in the threat model:
 - Commit `e0fb34b` — verified in git log
 
 ---
-*Phase: 03-event-write-back-pwa-install*
-*Completed: 2026-06-05*
+
+_Phase: 03-event-write-back-pwa-install_
+_Completed: 2026-06-05_

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-08-PLAN.md

@@ -3,38 +3,38 @@ phase: 03-event-write-back-pwa-install
 plan: 08
 type: execute
 wave: 5
-depends_on: ["03-04", "03-06", "03-07"]
+depends_on: ['03-04', '03-06', '03-07']
 files_modified:
   - .planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md
 autonomous: false
 requirements: [CAL-04, CAL-05, CAL-06, PWA-01, PWA-02]
 user_setup:
   - service: authelia
-    why: "Gate 2 verifies real Authelia OIDC login over the public Pangolin URL including the iOS standalone-PWA flow (success criterion 6, D-14)"
+    why: 'Gate 2 verifies real Authelia OIDC login over the public Pangolin URL including the iOS standalone-PWA flow (success criterion 6, D-14)'
     env_vars:
       - name: OIDC_AUTH_EXTERNAL_URL
-        source: "Set to the public familysync URL (e.g. https://familysync.<domain>) so redirect_uri is correct behind Pangolin"
+        source: 'Set to the public familysync URL (e.g. https://familysync.<domain>) so redirect_uri is correct behind Pangolin'
     dashboard_config:
-      - task: "Register FamilySync as an OIDC confidential client (code flow + PKCE S256, client_secret_basic) and ensure the redirect_uri matches the public URL"
-        location: "Authelia configuration"
-      - task: "Expose familysync through Pangolin/Newt (Mode A local test rig is sufficient — Unraid prod optional until go-live, D-15)"
-        location: "Pangolin / Newt connector"
+      - task: 'Register FamilySync as an OIDC confidential client (code flow + PKCE S256, client_secret_basic) and ensure the redirect_uri matches the public URL'
+        location: 'Authelia configuration'
+      - task: 'Expose familysync through Pangolin/Newt (Mode A local test rig is sufficient — Unraid prod optional until go-live, D-15)'
+        location: 'Pangolin / Newt connector'
 
 must_haves:
   truths:
-    - "A real member completes Authelia OIDC login over the public Pangolin URL in a desktop browser; the session persists across a browser restart"
-    - "On iPhone, the member installs FamilySync to the Home Screen and completes login WITHOUT the redirect breaking out of standalone mode"
-    - "Each member shows a distinct, stable color (AUTH-03) in the live deploy"
-    - "Create, edit, and delete an event end-to-end through the live deploy; the change appears in the native Fastmail app on the next sync (CAL-04/05/06)"
-    - "The installed PWA opens full-screen with no browser chrome on iOS and Android (PWA-01/02)"
+    - 'A real member completes Authelia OIDC login over the public Pangolin URL in a desktop browser; the session persists across a browser restart'
+    - 'On iPhone, the member installs FamilySync to the Home Screen and completes login WITHOUT the redirect breaking out of standalone mode'
+    - 'Each member shows a distinct, stable color (AUTH-03) in the live deploy'
+    - 'Create, edit, and delete an event end-to-end through the live deploy; the change appears in the native Fastmail app on the next sync (CAL-04/05/06)'
+    - 'The installed PWA opens full-screen with no browser chrome on iOS and Android (PWA-01/02)'
   artifacts:
-    - path: ".planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md"
-      provides: "Recorded Gate 2 verification results (pass/fail per checklist row)"
+    - path: '.planning/phases/03-event-write-back-pwa-install/03-GATE2-RESULTS.md'
+      provides: 'Recorded Gate 2 verification results (pass/fail per checklist row)'
   key_links:
-    - from: "live deploy"
-      to: "docs/deployment.md Gate 2 checklist"
-      via: "operator executes each row"
-      pattern: "Gate 2"
+    - from: 'live deploy'
+      to: 'docs/deployment.md Gate 2 checklist'
+      via: 'operator executes each row'
+      pattern: 'Gate 2'
 ---
 
 <objective>
@@ -135,19 +135,21 @@ Output: 03-GATE2-RESULTS.md with a pass/fail line per Gate 2 checklist row.
 </tasks>
 
 <threat_model>
+
 ## Trust Boundaries
 
-| Boundary | Description |
-|----------|-------------|
+| Boundary                         | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
 | public internet → Pangolin → app | First real external exposure of the auth + write path |
 
 ## STRIDE Threat Register
 
-| Threat ID | Category | Component | Disposition | Mitigation Plan |
-|-----------|----------|-----------|-------------|-----------------|
-| T-03-23 | Spoofing | dev-auth bypass accidentally active in the live deploy | mitigate | Production build sets NODE_ENV=production → bypass forced OFF, OIDC unconditionally mounted (index.ts); verify the login is real Authelia, not the dev user |
-| T-03-24 | Information Disclosure | OIDC redirect_uri mismatch leaking codes or failing login | mitigate | OIDC_AUTH_EXTERNAL_URL set to the public URL; Authelia client redirect_uri matches (deployment.md) |
-| T-03-25 | Tampering | SW intercepting /callback in the live build | mitigate | Plan 07 denylist verified against the production build; Gate 2 row 4 confirms standalone login end-to-end |
+| Threat ID | Category               | Component                                                 | Disposition | Mitigation Plan                                                                                                                                             |
+| --------- | ---------------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T-03-23   | Spoofing               | dev-auth bypass accidentally active in the live deploy    | mitigate    | Production build sets NODE_ENV=production → bypass forced OFF, OIDC unconditionally mounted (index.ts); verify the login is real Authelia, not the dev user |
+| T-03-24   | Information Disclosure | OIDC redirect_uri mismatch leaking codes or failing login | mitigate    | OIDC_AUTH_EXTERNAL_URL set to the public URL; Authelia client redirect_uri matches (deployment.md)                                                          |
+| T-03-25   | Tampering              | SW intercepting /callback in the live build               | mitigate    | Plan 07 denylist verified against the production build; Gate 2 row 4 confirms standalone login end-to-end                                                   |
+
 </threat_model>
 
 <verification>
@@ -156,9 +158,10 @@ Output: 03-GATE2-RESULTS.md with a pass/fail line per Gate 2 checklist row.
 </verification>
 
 <success_criteria>
+
 - Success criterion 6 satisfied: live Authelia OIDC over Pangolin works including iOS standalone-PWA login; sessions persist; distinct stable colors.
 - Success criteria 1-5 confirmed live: create/edit/delete round-trip to Fastmail; installable + full-screen on iOS and Android.
-</success_criteria>
+  </success_criteria>
 
 <output>
 Create `.planning/phases/03-event-write-back-pwa-install/03-08-SUMMARY.md` when done.

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

@@ -27,8 +27,8 @@ affects: [phase-04]
 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"
+    - '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:
@@ -47,7 +47,7 @@ Gate 2 is **complete for Phase 03 scope**. See `03-GATE2-RESULTS.md` for the per
 
 - **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.
+- **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)

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-09-PLAN.md

@@ -12,18 +12,18 @@ files_modified:
   - apps/api/tests/routes/events.test.ts
 must_haves:
   truths:
-    - "POST /api/events/create with the exact client CreateEventPayload shape ({title,start,end,allDay,recurrence}) returns 202, not 400"
-    - "PATCH /api/events/:uid/edit with the same client shape returns 202, not 400"
-    - "An authenticated OIDC request (devBypassActive=false) with a known iss+sub resolves to a real users.id and is allowed to write — it does NOT unconditionally 401"
-    - "A request with no dev user and no OIDC session returns 401"
+    - 'POST /api/events/create with the exact client CreateEventPayload shape ({title,start,end,allDay,recurrence}) returns 202, not 400'
+    - 'PATCH /api/events/:uid/edit with the same client shape returns 202, not 400'
+    - 'An authenticated OIDC request (devBypassActive=false) with a known iss+sub resolves to a real users.id and is allowed to write — it does NOT unconditionally 401'
+    - 'A request with no dev user and no OIDC session returns 401'
   artifacts:
     - path: apps/api/src/routes/events.ts
-      provides: "Canonical title/start/end zod contract + async OIDC iss/sub→users.id resolution on all 5 handlers"
-      contains: "upsertUser"
+      provides: 'Canonical title/start/end zod contract + async OIDC iss/sub→users.id resolution on all 5 handlers'
+      contains: 'upsertUser'
   key_links:
-    - from: "apps/api/src/routes/events.ts"
-      to: "apps/api/src/auth/user.ts"
-      via: "upsertUser(iss, sub, email)"
+    - from: 'apps/api/src/routes/events.ts'
+      to: 'apps/api/src/auth/user.ts'
+      via: 'upsertUser(iss, sub, email)'
       pattern: "upsertUser\\("
 ---
 
@@ -101,6 +101,7 @@ Downstream gap plans (03-10) read the new field names (`title/start/end`) out of
 
     Add the two contract tests described in <behavior>. Commit RED then GREEN
     (`test(03-09): ...` then `feat(03-09): ...`).
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/routes/events.test.ts</automated>
@@ -143,6 +144,7 @@ Downstream gap plans (03-10) read the new field names (`title/start/end`) out of
     Per D-10 identity is oidc_iss+oidc_sub; upsertUser keys on `uniq_oidc_identity`. Return 401 ONLY when no session exists (covered by upsertUser path).
 
     Add the two tests in <behavior>. Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/routes/events.test.ts</automated>

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-09-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 03-event-write-back-pwa-install
-plan: "09"
+plan: '09'
 subsystem: api-events-router
 tags: [tdd, gap-closure, auth, schema, zod, oidc]
 dependency_graph:
@@ -15,19 +15,19 @@ dependency_graph:
 tech_stack:
   added: []
   patterns:
-    - "TDD RED→GREEN per task"
-    - "vi.hoisted() for configurable per-test auth mocks"
-    - "async resolveUserId with upsertUser for OIDC path"
+    - 'TDD RED→GREEN per task'
+    - 'vi.hoisted() for configurable per-test auth mocks'
+    - 'async resolveUserId with upsertUser for OIDC path'
 key_files:
   modified:
     - apps/api/src/routes/events.ts
     - apps/api/tests/routes/events.test.ts
 decisions:
-  - "D-CR01: Server adopts client field names title/start/end — one canonical name set end-to-end, no rename map"
-  - "D-CR06: resolveUserId async; dev-bypass path unchanged; OIDC path calls upsertUser(iss,sub,email)"
+  - 'D-CR01: Server adopts client field names title/start/end — one canonical name set end-to-end, no rename map'
+  - 'D-CR06: resolveUserId async; dev-bypass path unchanged; OIDC path calls upsertUser(iss,sub,email)'
 metrics:
   duration_minutes: 6
-  completed_date: "2026-06-06"
+  completed_date: '2026-06-06'
   tasks_completed: 2
   files_modified: 2
 ---
@@ -38,12 +38,12 @@ Fix the events router's two blockers that made the write path dead on arrival: a
 
 ## Tasks Completed
 
-| Task | Name | Commit | Files |
-|------|------|--------|-------|
-| 1 RED | Add contract tests for canonical title/start/end | 944693f | events.test.ts |
-| 1 GREEN | Rename eventFieldsSchema to title/start/end (CR-01) | 99cb169 | events.ts, events.test.ts |
-| 2 RED | Add OIDC path tests — resolveUserId must call upsertUser | 6d1d338 | events.test.ts |
-| 2 GREEN | Async resolveUserId with upsertUser on all 5 handlers (CR-06) | fac3a21 | events.ts |
+| Task    | Name                                                          | Commit  | Files                     |
+| ------- | ------------------------------------------------------------- | ------- | ------------------------- |
+| 1 RED   | Add contract tests for canonical title/start/end              | 944693f | events.test.ts            |
+| 1 GREEN | Rename eventFieldsSchema to title/start/end (CR-01)           | 99cb169 | events.ts, events.test.ts |
+| 2 RED   | Add OIDC path tests — resolveUserId must call upsertUser      | 6d1d338 | events.test.ts            |
+| 2 GREEN | Async resolveUserId with upsertUser on all 5 handlers (CR-06) | fac3a21 | events.ts                 |
 
 ## Verification
 
@@ -71,6 +71,7 @@ The worktree has no `node_modules` — the pnpm workspace installs them in the m
 ## TDD Gate Compliance
 
 Both tasks followed RED→GREEN strictly:
+
 - Task 1: `test(03-09)` commit (944693f) → `feat(03-09)` commit (99cb169)
 - Task 2: `test(03-09)` commit (6d1d338) → `feat(03-09)` commit (fac3a21)
 

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-10-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 10
 type: tdd
 wave: 2
-depends_on: ["03-09"]
+depends_on: ['03-09']
 gap_closure: true
 autonomous: true
 requirements: [CAL-04, CAL-05, CAL-06, CAL-07]
@@ -14,25 +14,25 @@ files_modified:
   - apps/api/tests/broker/vevent.test.ts
 must_haves:
   truths:
-    - "The worker parses the stored form JSON and PUTs a real VCALENDAR string built by buildVeventString — never raw {\"title\":...} JSON"
+    - 'The worker parses the stored form JSON and PUTs a real VCALENDAR string built by buildVeventString — never raw {"title":...} JSON'
     - "The PUT body begins with 'BEGIN:VCALENDAR' for both create and update operations"
-    - "A single-day all-day event produces DTEND = DTSTART + 1 day (RFC 5545 exclusive end), proven by a DIRECT buildVeventString unit test against the D-13 contract"
-    - "A credential-load failure leaves the row pending for retry — the worker never PUTs with empty Basic-auth"
-    - "The first transient failure waits 15s (BACKOFF_SECONDS[0]), not 60s"
+    - 'A single-day all-day event produces DTEND = DTSTART + 1 day (RFC 5545 exclusive end), proven by a DIRECT buildVeventString unit test against the D-13 contract'
+    - 'A credential-load failure leaves the row pending for retry — the worker never PUTs with empty Basic-auth'
+    - 'The first transient failure waits 15s (BACKOFF_SECONDS[0]), not 60s'
   artifacts:
     - path: apps/api/src/broker/outboxWorker.ts
-      provides: "ICS-building dispatch path + removed empty-cred fallback + corrected backoff index + explicit randomUUID import"
-      contains: "buildVeventString"
+      provides: 'ICS-building dispatch path + removed empty-cred fallback + corrected backoff index + explicit randomUUID import'
+      contains: 'buildVeventString'
     - path: apps/api/src/broker/vevent.ts
-      provides: "All-day DTEND+1-day exclusivity fix (the WR-04 owning boundary)"
+      provides: 'All-day DTEND+1-day exclusivity fix (the WR-04 owning boundary)'
   key_links:
-    - from: "apps/api/src/broker/outboxWorker.ts"
-      to: "apps/api/src/broker/vevent.ts"
-      via: "buildVeventString(parsedFormFields)"
+    - from: 'apps/api/src/broker/outboxWorker.ts'
+      to: 'apps/api/src/broker/vevent.ts'
+      via: 'buildVeventString(parsedFormFields)'
       pattern: "buildVeventString\\("
-    - from: "apps/api/src/broker/outboxWorker.ts"
-      to: "apps/api/src/broker/write.ts"
-      via: "createCalendarEvent/updateCalendarEvent with the built icsString"
+    - from: 'apps/api/src/broker/outboxWorker.ts'
+      to: 'apps/api/src/broker/write.ts'
+      via: 'createCalendarEvent/updateCalendarEvent with the built icsString'
       pattern: "createCalendarEvent\\(|updateCalendarEvent\\("
 ---
 
@@ -120,6 +120,7 @@ an internal `JSON.parse(row.payload)` → `buildVeventString` step.
 
     Update the existing outbox test that fed a pre-built ICS string so it instead feeds
     form JSON and asserts the built ICS (it was testing the wrong boundary). Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/broker/outboxWorker.test.ts tests/broker/vevent.test.ts</automated>
@@ -168,6 +169,7 @@ an internal `JSON.parse(row.payload)` → `buildVeventString` step.
     this plan's <verification> and the acceptance criterion below — this closes Warning 5.
 
     Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/broker/outboxWorker.test.ts && cd apps/api && npm run build</automated>

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-10-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 03-event-write-back-pwa-install
-plan: "10"
+plan: '10'
 subsystem: api-broker
 tags: [tdd, gap-closure, ics-builder, outbox-worker, vevent, rfc5545, credentials]
 dependency_graph:
@@ -20,13 +20,13 @@ dependency_graph:
 tech_stack:
   added: []
   patterns:
-    - "TDD RED→GREEN per task"
-    - "vi.hoisted() + per-test crypto mock for loadClientForUser failure scenarios"
-    - "Table-differentiated db select mock (credential vs outbox queries)"
+    - 'TDD RED→GREEN per task'
+    - 'vi.hoisted() + per-test crypto mock for loadClientForUser failure scenarios'
+    - 'Table-differentiated db select mock (credential vs outbox queries)'
 decisions:
-  - "WR-04 owning boundary is vevent.ts only — form/routes pass inclusive end unchanged"
-  - "CR-03: loadClientForUser throws propagate to outer catch (row stays pending); no empty-cred fallback"
-  - "WR-01: backoff index is row.attemptCount (the failed attempt, 0-based) not nextAttemptCount"
+  - 'WR-04 owning boundary is vevent.ts only — form/routes pass inclusive end unchanged'
+  - 'CR-03: loadClientForUser throws propagate to outer catch (row stays pending); no empty-cred fallback'
+  - 'WR-01: backoff index is row.attemptCount (the failed attempt, 0-based) not nextAttemptCount'
 key_files:
   modified:
     - apps/api/src/broker/outboxWorker.ts
@@ -36,7 +36,7 @@ key_files:
     - apps/api/tests/broker/vevent.test.ts
 metrics:
   duration_minutes: 6
-  completed_date: "2026-06-06"
+  completed_date: '2026-06-06'
   tasks_completed: 2
   files_modified: 5
 ---
@@ -47,12 +47,12 @@ Wire the VEVENT builder into the outbox worker dispatch path, pin the D-13 DATE/
 
 ## Tasks Completed
 
-| Task | Name | Commit | Files |
-|------|------|--------|-------|
-| 1 RED | Add D-13 contract + ICS wiring test (vevent + worker) | 813a7ba | vevent.test.ts, outboxWorker.test.ts |
-| 1 GREEN | Wire buildVeventString, fix all-day DTEND+1 (CR-02, WR-04) | c03b479 | outboxWorker.ts, vevent.ts |
-| 2 RED | Add CR-03 + WR-01 RED tests (crypto mock, backoff timing) | c178dce | outboxWorker.test.ts |
-| 2 GREEN | Fail closed on bad creds, fix backoff index, explicit randomUUID | c21b040 | outboxWorker.ts, events.ts |
+| Task    | Name                                                             | Commit  | Files                                |
+| ------- | ---------------------------------------------------------------- | ------- | ------------------------------------ |
+| 1 RED   | Add D-13 contract + ICS wiring test (vevent + worker)            | 813a7ba | vevent.test.ts, outboxWorker.test.ts |
+| 1 GREEN | Wire buildVeventString, fix all-day DTEND+1 (CR-02, WR-04)       | c03b479 | outboxWorker.ts, vevent.ts           |
+| 2 RED   | Add CR-03 + WR-01 RED tests (crypto mock, backoff timing)        | c178dce | outboxWorker.test.ts                 |
+| 2 GREEN | Fail closed on bad creds, fix backoff index, explicit randomUUID | c21b040 | outboxWorker.ts, events.ts           |
 
 ## Verification
 
@@ -73,10 +73,12 @@ Wire the VEVENT builder into the outbox worker dispatch path, pin the D-13 DATE/
 ## TDD Gate Compliance
 
 Both tasks followed strict RED→GREEN:
+
 - Task 1: `test(03-10)` commit (813a7ba) → `feat(03-10)` commit (c03b479)
 - Task 2: `test(03-10)` commit (c178dce) → `feat(03-10)` commit (c21b040)
 
 RED confirmed failing for correct reasons before each GREEN commit:
+
 - Task 1 RED: vevent DTEND=20260610 not 20260611; worker passed raw JSON not BEGIN:VCALENDAR
 - Task 2 RED: CR-03 worker updated row to 'done' via empty-cred path; WR-01 backoff was 60s not 15s
 
@@ -94,14 +96,14 @@ The existing db mock in `outboxWorker.test.ts` returned the same rows for any `d
 
 ## Issues Closed
 
-| ID | Description |
-|----|-------------|
-| CR-02 | Worker was passing raw form JSON to CalDAV PUT — now builds VCALENDAR via buildVeventString |
-| CR-03 | Worker fell back to empty-cred createFastmailClient on any credential error — removed fallback |
+| ID    | Description                                                                                       |
+| ----- | ------------------------------------------------------------------------------------------------- |
+| CR-02 | Worker was passing raw form JSON to CalDAV PUT — now builds VCALENDAR via buildVeventString       |
+| CR-03 | Worker fell back to empty-cred createFastmailClient on any credential error — removed fallback    |
 | WR-01 | First transient retry used BACKOFF_SECONDS[1]=60s instead of BACKOFF_SECONDS[0]=15s — fixed index |
-| WR-04 | All-day events emitted DTEND = DTSTART (no +1 day) — fixed in vevent.ts (owning boundary) |
-| WR-08 | events.ts used bare crypto.randomUUID() — replaced with import { randomUUID } from 'node:crypto' |
-| IN-01 | buildVeventString was dead code (never called outside vevent.ts) — now has 2 live call sites |
+| WR-04 | All-day events emitted DTEND = DTSTART (no +1 day) — fixed in vevent.ts (owning boundary)         |
+| WR-08 | events.ts used bare crypto.randomUUID() — replaced with import { randomUUID } from 'node:crypto'  |
+| IN-01 | buildVeventString was dead code (never called outside vevent.ts) — now has 2 live call sites      |
 
 ## Known Stubs
 

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-11-PLAN.md

@@ -3,7 +3,7 @@ phase: 03-event-write-back-pwa-install
 plan: 11
 type: tdd
 wave: 3
-depends_on: ["03-10"]
+depends_on: ['03-10']
 gap_closure: true
 autonomous: true
 requirements: [CAL-05, CAL-06]
@@ -13,17 +13,17 @@ files_modified:
 must_haves:
   truths:
     - "An edit-as-move delete row never dispatches until its paired create row has reached status='done' — durably, across separate drain cycles"
-    - "Two overlapping drain cycles never both dispatch the same outbox row"
-    - "A same-calendar update re-reads the freshest etag from calendarEvents just before PUT, so rapid successive edits do not spuriously 412"
+    - 'Two overlapping drain cycles never both dispatch the same outbox row'
+    - 'A same-calendar update re-reads the freshest etag from calendarEvents just before PUT, so rapid successive edits do not spuriously 412'
   artifacts:
     - path: apps/api/src/broker/outboxWorker.ts
-      provides: "Durable create-before-delete gating, drain concurrency guard (single-process), fresh-etag-before-PUT"
-      contains: "isDraining"
+      provides: 'Durable create-before-delete gating, drain concurrency guard (single-process), fresh-etag-before-PUT'
+      contains: 'isDraining'
   key_links:
-    - from: "runOutboxDrain"
-      to: "calendarOutbox status machine"
-      via: "in-flight claim / blocked-delete gate persisted in DB, not an in-memory Set"
-      pattern: "isDraining|processing|blocked"
+    - from: 'runOutboxDrain'
+      to: 'calendarOutbox status machine'
+      via: 'in-flight claim / blocked-delete gate persisted in DB, not an in-memory Set'
+      pattern: 'isDraining|processing|blocked'
 ---
 
 <objective>
@@ -105,6 +105,7 @@ gated by querying its sibling create's status, not enqueued as a new enum value)
     silently rely on it.
 
     Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/broker/outboxWorker.test.ts</automated>
@@ -144,6 +145,7 @@ gated by querying its sibling create's status, not enqueued as a new enum value)
     etag still reflects the last synced server state, so a real external edit still 412s (D-08 intact).
 
     Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/api && npx vitest run tests/broker/outboxWorker.test.ts</automated>

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-11-SUMMARY.md

@@ -1,6 +1,6 @@
 ---
 phase: 03-event-write-back-pwa-install
-plan: "11"
+plan: '11'
 subsystem: api-broker
 tags: [tdd, gap-closure, outbox-worker, concurrency-guard, etag, durability, calDAV]
 dependency_graph:
@@ -16,25 +16,25 @@ dependency_graph:
 tech_stack:
   added: []
   patterns:
-    - "TDD RED→GREEN per task"
-    - "DB sibling-status query pattern for durable inter-row ordering"
-    - "Module-level boolean drain guard for single-process deployment"
+    - 'TDD RED→GREEN per task'
+    - 'DB sibling-status query pattern for durable inter-row ordering'
+    - 'Module-level boolean drain guard for single-process deployment'
     - "Symbol.for('drizzle:Name') for safe Drizzle table identification in tests (JSON.stringify circular)"
-    - "vi.resetAllMocks() instead of vi.clearAllMocks() when mockImplementationOnce queues must be purged"
-    - "Per-table mockWhere functions (mockWherePending vs mockWhereCalEvents) to isolate select mocks"
+    - 'vi.resetAllMocks() instead of vi.clearAllMocks() when mockImplementationOnce queues must be purged'
+    - 'Per-table mockWhere functions (mockWherePending vs mockWhereCalEvents) to isolate select mocks'
 key_files:
   modified:
     - apps/api/src/broker/outboxWorker.ts
     - apps/api/tests/broker/outboxWorker.test.ts
 key_decisions:
-  - "CR-04 durable gate uses DB sibling-status query (not in-memory Set) so create-before-delete ordering holds across drain cycles; in-batch fast path retained as optimization"
+  - 'CR-04 durable gate uses DB sibling-status query (not in-memory Set) so create-before-delete ordering holds across drain cycles; in-batch fast path retained as optimization'
   - "CR-05 isDraining guard is explicitly documented as single-process-only; multi-replica deployments would need DB row-claim (UPDATE WHERE status='pending' with affected-rows check)"
-  - "WR-02 fresh etag reads calendarEvents at dispatch time, not calendarOutbox enqueue time; D-08 conflict detection preserved — genuine external changes update calendarEvents.etag differently from any queued row"
+  - 'WR-02 fresh etag reads calendarEvents at dispatch time, not calendarOutbox enqueue time; D-08 conflict detection preserved — genuine external changes update calendarEvents.etag differently from any queued row'
   - "mockFromFn updated to use Symbol.for('drizzle:Name') to identify Drizzle tables — JSON.stringify throws CircularReference on all MySqlTable instances"
-  - "All beforeEach blocks switched to vi.resetAllMocks() to prevent unconsumed mockImplementationOnce calls bleeding into subsequent tests"
+  - 'All beforeEach blocks switched to vi.resetAllMocks() to prevent unconsumed mockImplementationOnce calls bleeding into subsequent tests'
 requirements-completed: [CAL-05, CAL-06]
 duration: 30min
-completed: "2026-06-05"
+completed: '2026-06-05'
 ---
 
 # Phase 03 Plan 11: Outbox Durability and Etag Fix Summary
@@ -81,6 +81,7 @@ Each task was committed atomically:
 ### Auto-fixed Issues
 
 **1. [Rule 1 - Bug] Drizzle table identification using JSON.stringify throws CircularReference**
+
 - **Found during:** Task 1 GREEN — when running tests after implementing the sibling-status DB select
 - **Issue:** `wireMockChain`'s `mockFromFn` used `JSON.stringify(table).includes('member_credentials')` to identify the credential table. `JSON.stringify` on a Drizzle `MySqlTable` object throws `TypeError: Converting circular structure to JSON` (MySqlInt columns hold a back-reference to their parent table). The `catch` block silently set `isCred = false`, making ALL `db.select().from(...)` calls route to `mockWherePending` — including credential lookups. Prior tests "worked" accidentally because `mockDecryptPassword` was mocked to succeed regardless of input, but the new sibling-status select consumed `mockWherePending` calls out of order, breaking the D-04 ordering test and the CR-04 drain 2 test.
 - **Fix:** Replaced with `(table as Record<symbol, string>)[Symbol.for('drizzle:Name')]` which reads the table name property Drizzle attaches as a Symbol. Added separate `mockWhereCalEvents` for `calendarEvents` table selects. Switched all `beforeEach` to `vi.resetAllMocks()`.
@@ -106,10 +107,10 @@ None beyond the mock infrastructure deviation above.
 
 ## Issues Closed
 
-| ID | Description |
-|----|-------------|
-| CR-04 | Create-before-delete ordering relied on in-memory Set, broke across drain batches — DB sibling-status gate now authoritative |
-| CR-05 | No concurrency guard — overlapping drain cycles could double-dispatch same row — isDraining guard prevents it (single-process) |
+| ID    | Description                                                                                                                               |
+| ----- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| CR-04 | Create-before-delete ordering relied on in-memory Set, broke across drain batches — DB sibling-status gate now authoritative              |
+| CR-05 | No concurrency guard — overlapping drain cycles could double-dispatch same row — isDraining guard prevents it (single-process)            |
 | WR-02 | Update dispatch used stale enqueue-time etag — rapid successive edits guaranteed 412 — fresh calendarEvents.etag re-read at dispatch time |
 
 ## Known Stubs

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-12-PLAN.md

@@ -13,19 +13,19 @@ files_modified:
   - apps/pwa/src/store/calendarStore.ts
 must_haves:
   truths:
-    - "Opening the form in edit mode populates Title/Start/End from the cached occurrence even when the form opens before the occurrence is resolved (no blank edit form)"
+    - 'Opening the form in edit mode populates Title/Start/End from the cached occurrence even when the form opens before the occurrence is resolved (no blank edit form)'
     - "Editing a recurring event preselects its existing recurrence preset instead of resetting to 'none'"
     - "The edit form shows the event's original date/time consistently (no UTC-date / local-time mismatch that shifts the day), proven by a test that pins TZ so it cannot pass by coincidence on an EDT runner"
-    - "Tab and Shift+Tab cycle focus within the open dialog and never reach background controls"
-    - "The PWA install assets (icon-192/512, apple-touch-icon) exist so Add-to-Home-Screen installs with a real icon (PWA-01/PWA-02)"
+    - 'Tab and Shift+Tab cycle focus within the open dialog and never reach background controls'
+    - 'The PWA install assets (icon-192/512, apple-touch-icon) exist so Add-to-Home-Screen installs with a real icon (PWA-01/PWA-02)'
   artifacts:
     - path: apps/pwa/src/components/EventForm.tsx
-      provides: "occurrence-driven reset, recurrence derivation, zone-consistent parseDateTime, real focus trap"
+      provides: 'occurrence-driven reset, recurrence derivation, zone-consistent parseDateTime, real focus trap'
   key_links:
-    - from: "EventForm reset effect"
-      to: "occurrence from TanStack cache"
-      via: "occurrence (or occurrence?.uid) in effect deps"
-      pattern: "occurrence"
+    - from: 'EventForm reset effect'
+      to: 'occurrence from TanStack cache'
+      via: 'occurrence (or occurrence?.uid) in effect deps'
+      pattern: 'occurrence'
 ---
 
 <objective>
@@ -103,6 +103,7 @@ a zone-consistent `parseDateTime`, and a real Tab/Shift+Tab focus-cycle handler.
     default times at the call sites. Do not duplicate the helper — there must be exactly one `todayIso`.
 
     Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/pwa && npx vitest run src/components/EventForm.test.tsx</automated>
@@ -144,6 +145,7 @@ a zone-consistent `parseDateTime`, and a real Tab/Shift+Tab focus-cycle handler.
     exist so the Add-to-Home-Screen flow installs with a real icon. No code change required if assets present.
 
     Commit RED then GREEN.
+
   </action>
   <verify>
     <automated>cd apps/pwa && npx vitest run src/components/EventForm.test.tsx</automated>

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-12-SUMMARY.md

@@ -28,7 +28,7 @@ decisions:
   - vi.importActual used for IN-03 export test to bypass vi.mock() on calendarStore
 metrics:
   duration_minutes: 40
-  completed_date: "2026-06-06T00:42:08Z"
+  completed_date: '2026-06-06T00:42:08Z'
   tasks_completed: 2
   files_modified: 4
 ---
@@ -39,12 +39,12 @@ EventForm edit mode now pre-populates correctly from TanStack cache (even when o
 
 ## Tasks Completed
 
-| Task | Type | Description | Commit |
-|------|------|-------------|--------|
-| 1 RED | test | WR-03 blank/recurrence, WR-05 zone, IN-03 export — failing tests | 02e312a |
-| 1 GREEN | feat | WR-03 deps fix, WR-05 parseDateTime fix, IN-03 todayIso export | f0f1361 |
-| 2 RED | test | WR-07 focus trap Tab/Shift+Tab cycle — failing tests | 4244e8c |
-| 2 GREEN | feat | WR-07 inline focus trap on dialogRef + onKeyDown | e971e16 |
+| Task    | Type | Description                                                      | Commit  |
+| ------- | ---- | ---------------------------------------------------------------- | ------- |
+| 1 RED   | test | WR-03 blank/recurrence, WR-05 zone, IN-03 export — failing tests | 02e312a |
+| 1 GREEN | feat | WR-03 deps fix, WR-05 parseDateTime fix, IN-03 todayIso export   | f0f1361 |
+| 2 RED   | test | WR-07 focus trap Tab/Shift+Tab cycle — failing tests             | 4244e8c |
+| 2 GREEN | feat | WR-07 inline focus trap on dialogRef + onKeyDown                 | e971e16 |
 
 ## What Was Built
 
@@ -73,6 +73,7 @@ The old implementation mixed `toISOString().slice(0,10)` (UTC date) with `getHou
 The docblock claimed "Focus trap while open" but the implementation only called `.focus()` once on open. Tab escaped the modal to background content.
 
 **Fix:** Added `dialogRef` and `handleDialogKeyDown` handler on the dialog div. On Tab/Shift+Tab, queries all focusable elements inside `dialogRef.current` and wraps focus at the boundaries:
+
 - Tab on last element → `first.focus()` + `preventDefault()`
 - Shift+Tab on first element → `last.focus()` + `preventDefault()`
 
@@ -81,6 +82,7 @@ No external library added. Existing focus-on-open (titleRef) and Escape-to-close
 ### PWA-01/PWA-02: Install assets confirmed present (IN-04)
 
 All three required PWA install assets exist in `apps/pwa/public/`:
+
 - `icon-192.png` — 192×192 manifest icon
 - `icon-512.png` — 512×512 manifest icon (+ maskable)
 - `apple-touch-icon.png` — iOS Add-to-Home-Screen icon
@@ -89,24 +91,26 @@ Referenced in `index.html` and `vite.config.ts` manifest. No code change needed;
 
 ## TDD Gate Compliance
 
-| Gate | Commit | Status |
-|------|--------|--------|
-| Task 1 RED | 02e312a | test(03-12): failing tests added (3 failed) |
-| Task 1 GREEN | f0f1361 | feat(03-12): 27 tests passing |
-| Task 2 RED | 4244e8c | test(03-12): 2 failing focus trap tests |
-| Task 2 GREEN | e971e16 | feat(03-12): 29 tests passing |
+| Gate         | Commit  | Status                                      |
+| ------------ | ------- | ------------------------------------------- |
+| Task 1 RED   | 02e312a | test(03-12): failing tests added (3 failed) |
+| Task 1 GREEN | f0f1361 | feat(03-12): 27 tests passing               |
+| Task 2 RED   | 4244e8c | test(03-12): 2 failing focus trap tests     |
+| Task 2 GREEN | e971e16 | feat(03-12): 29 tests passing               |
 
 ## Deviations from Plan
 
 ### Auto-fixed Issues
 
 **1. [Rule 2 - Missing] Add todayIso to calendarStore vi.mock() in test file**
+
 - **Found during:** Task 1 GREEN
 - **Issue:** EventForm now imports `todayIso` from calendarStore, but the `vi.mock('../store/calendarStore.js')` factory in EventForm.test.tsx only exported `useCalendarStore`. Tests crashed with "No todayIso export is defined on the mock."
 - **Fix:** Added `todayIso: () => new Date().toISOString().slice(0, 10)` to the mock factory so the mocked module matches the real module's export surface.
 - **Files modified:** `apps/pwa/src/components/EventForm.test.tsx`
 
 **2. [Rule 2 - Missing] Use vi.importActual for IN-03 test**
+
 - **Found during:** Task 1 GREEN
 - **Issue:** The IN-03 test used `await import('../store/calendarStore.js')` which returns the mock (not the real module), so `actualModule.todayIso` was undefined.
 - **Fix:** Changed to `await vi.importActual('../store/calendarStore.js')` to bypass the mock and test the real module export.
@@ -117,27 +121,30 @@ Referenced in `index.html` and `vite.config.ts` manifest. No code change needed;
 ```
 cd apps/pwa && npx vitest run src/components/EventForm.test.tsx
 ```
+
 **Result:** 29 passed (29)
 
 ```
 cd apps/pwa && npm run build
 ```
+
 **Result:** Built successfully — 509.67 kB bundle, PWA service worker generated.
 
 ## Issues Closed
 
-| ID | Description | Status |
-|----|-------------|--------|
-| WR-03 | Edit form blank when occurrence resolves after open | CLOSED |
-| WR-03 | Editing recurring event resets recurrence to 'none' | CLOSED |
-| WR-05 | parseDateTime mixes UTC date and local time | CLOSED |
-| WR-07 | Focus trap claim without real trap implementation | CLOSED |
-| IN-03 | Duplicate todayIso helpers | CLOSED |
-| IN-04 | PWA install assets not verified | CLOSED (assets confirmed present) |
+| ID    | Description                                         | Status                            |
+| ----- | --------------------------------------------------- | --------------------------------- |
+| WR-03 | Edit form blank when occurrence resolves after open | CLOSED                            |
+| WR-03 | Editing recurring event resets recurrence to 'none' | CLOSED                            |
+| WR-05 | parseDateTime mixes UTC date and local time         | CLOSED                            |
+| WR-07 | Focus trap claim without real trap implementation   | CLOSED                            |
+| IN-03 | Duplicate todayIso helpers                          | CLOSED                            |
+| IN-04 | PWA install assets not verified                     | CLOSED (assets confirmed present) |
 
 ## Self-Check: PASSED
 
 Files exist:
+
 - [x] apps/pwa/src/components/EventForm.tsx — modified
 - [x] apps/pwa/src/components/EventForm.test.tsx — modified
 - [x] apps/pwa/src/store/calendarStore.ts — modified (todayIso exported)
@@ -147,6 +154,7 @@ Files exist:
 - [x] apps/pwa/public/apple-touch-icon.png
 
 Commits exist:
+
 - [x] 02e312a — RED Task 1
 - [x] f0f1361 — GREEN Task 1
 - [x] 4244e8c — RED Task 2

.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-CONTEXT.md

@@ -18,16 +18,18 @@ Requirements: CAL-04 (create timed/all-day), CAL-05 (edit), CAL-06 (delete),
 CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (guided install).
 
 **Out of scope (other phases / later):**
+
 - Single-occurrence and "this-and-following" recurring edits (CAL-09 / CAL-10) — **v1.x**.
 - Shared lists + live SSE sync (Phase 4); Web Push notifications (Phase 5).
 - Wall-display / kiosk theme (v2).
 - SSE as a transport — **must not be relied on in Phase 3** (unverified until Phase 4 gate, D-14).
-</domain>
+  </domain>
 
 <decisions>
 ## Implementation Decisions
 
 ### Target-calendar selection (write target)
+
 - **D-01:** **Default target = remember last-used per member.** Seed/first-time default is
   the **creator's own personal calendar** (always exists; no shared calendar may exist yet, D-16).
 - **D-02:** **Calendar picker is shown only when the member has >1 writable calendar.** With a
@@ -43,6 +45,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   vice-versa) safely.
 
 ### Write feedback & sync (the load-bearing architecture decision)
+
 - **D-05:** **Optimistic-accept + server-side outbox.** On save the UI optimistically reflects
   the change with a "syncing…" indicator; the API writes a **`pending` row to a MariaDB outbox**
   and returns immediately. A **backend worker drains the outbox** against Fastmail.
@@ -52,9 +55,9 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   initial "forced re-sync, then show" — same authoritative-cache guarantee, without a blocking
   spinner.)
 - **D-07:** **Retry policy — backoff transient, fail-fast hard errors.**
-  - *Transient* (network error, 5xx, timeout) → retry with **exponential backoff over a bounded
+  - _Transient_ (network error, 5xx, timeout) → retry with **exponential backoff over a bounded
     window** (a few minutes), keeping the "not synced yet" toast visible.
-  - *Hard* (401/403 auth, 400 validation) → **stop immediately** and surface a real
+  - _Hard_ (401/403 auth, 400 validation) → **stop immediately** and surface a real
     "didn't save" error to the user. (Transient failures must be short; anything non-transient
     is a hard fail that won't self-resolve.)
 - **D-08:** **Edit-conflict handling = detect + warn + reload latest.** Writes send `If-Match`
@@ -67,6 +70,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   is unverified until the Phase 4 entry gate (D-14). Do **not** build Phase 3 sync feedback on SSE.
 
 ### Carried forward — locked, NOT re-discussed
+
 - **D-10:** The **edit/delete surface reuses `EventDetailPopover`** — it was built in Phase 2 with
   a reserved footer action area specifically for this (Phase 2 D-08). Create can reuse the same
   surface shell.
@@ -78,6 +82,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   Authelia verification is the Gate 2 item folded into this phase.
 
 ### Claude's Discretion (researcher / planner decide)
+
 - **Event form & fields** — exact field set (title, start/end, all-day toggle, location,
   description) and layout. Build it into / alongside the reused `EventDetailPopover` surface (D-10).
   Must be slick and low-friction for the non-technical Apple member.
@@ -97,11 +102,13 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
 </decisions>
 
 <canonical_refs>
+
 ## Canonical References
 
 **Downstream agents MUST read these before planning or implementing.**
 
 ### Project decisions & scope
+
 - `.planning/PROJECT.md` — core value, constraints, Key Decisions incl. **D-14** (dev-auth
   bypass; live AUTH + iOS smoke folded into Phase 3), **D-15** (local Newt test rig for Gate 2),
   **D-16** (shared Family calendar is a collection on the operator's primary account, may not
@@ -112,6 +119,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   PWA-01/02 (installable + guided install); v1.x CAL-09/10 (single-occurrence edits — OUT).
 
 ### Phase 1/2 foundation this builds on
+
 - `.planning/phases/02-calendar-display/02-CONTEXT.md` — design-token layer (D-01/02/03),
   `EventDetailPopover` reuse-as-edit-surface (Phase 2 D-08), server-side expansion, color/owner model.
 - `.planning/phases/01-foundation-broker-spike/CAL-08-DECISION.md` — per-member app-password
@@ -120,6 +128,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
   PWA) and the dev-auth bypass context. **Required reading for success criterion 6.**
 
 ### Code this phase extends
+
 - `apps/api/src/broker/client.ts` — tsdav `createDAVClient`; add PUT/DELETE write methods here
   (broker boundary, D-12).
 - `apps/api/src/broker/sync.ts` — REPORT→ical.js→upsert; the targeted single-calendar re-sync
@@ -139,9 +148,11 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
 </canonical_refs>
 
 <code_context>
+
 ## Existing Code Insights
 
 ### Reusable Assets
+
 - `EventDetailPopover` (Phase 2) — read-only detail overlay with a **reserved footer for Phase 3
   edit/delete** (D-10); responsive bottom-sheet/popover, focus trap, XSS-safe plain-text rendering.
 - `apps/pwa/src/api/client.ts` — typed `fetch` client (`fetchMe`, windowed `fetchEvents`,
@@ -151,6 +162,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
 - Design-token layer + Zustand UI store + TanStack Query — server state in Query, UI state in Zustand.
 
 ### Established Patterns
+
 - **Broker boundary (T-03-02):** routes read the MariaDB cache only; never import tsdav in a route.
   Write-back must keep this — endpoint enqueues to the outbox; the broker worker does the CalDAV PUT.
 - **D-13 schema split** for all-day (dtstartDate) vs timed (dtstartUtc) — write-back must produce
@@ -159,6 +171,7 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
 - Hono app exported without auto-start (testable); add write routes + outbox worker in that shape.
 
 ### Integration Points
+
 - **New MariaDB outbox table** (D-05): pending create/edit/delete operations with status, attempt
   count, target calendar URL, payload/UID, etag for If-Match.
 - **Outbox worker** (sibling to the ctag poller) drains the queue, applies D-07 retry/backoff,
@@ -201,5 +214,5 @@ CAL-07 (create recurring — whole-series only), PWA-01 (installable), PWA-02 (g
 
 ---
 
-*Phase: 3-Event Write-Back + PWA Install*
-*Context gathered: 2026-06-05*
+_Phase: 3-Event Write-Back + PWA Install_
+_Context gathered: 2026-06-05_