docs(10): create phase plan (4 plans, 4 waves) for admin-role-settings

- 10-01 v1.1 DB foundation migration + dev-bypass admin seed
- 10-02 requireAdmin guard + first-login-wins + /api/me extension (TDD)
- 10-03 adminRouter credentials/shared-calendar + member self-service (TDD)
- 10-04 PWA /admin route + nav gating + CredentialSheet + SetupBanner
- filled 10-VALIDATION Per-Task Verification Map (Nyquist compliant)
- finalized ROADMAP Phase 10 plan list

.planning/ROADMAP.md

@@ -170,7 +170,12 @@ Plans:
 
 **Folded-in scope** (from backlog 999.5, self-service member onboarding): the credential surface this phase builds is the same one a member needs on first login. Expose a `needsProviderSetup` signal (member has no `member_credentials` row) and let a member enter/validate (CalDAV PROPFIND) + encrypt their **own** Fastmail app password — the self-service counterpart of the admin-managed flow, sharing the validation/encryption/initial-sync path. Non-technical-friendly instructions (link to Fastmail's app-password page, required Calendars/CalDAV scope) are the hard UX constraint. Member-scoped: a member can only set their own credential; never log/echo the password.
 
-**Plans**: TBD
+**Plans**: 4 plans (4 waves)
+Plans:
+- [ ] 10-01-PLAN.md — v1.1 DB foundation migration (is_admin, provider_type+unique, reminder_lead_minutes, app_config) + dev-bypass admin seed
+- [ ] 10-02-PLAN.md — requireAdmin guard + first-login-wins bootstrap + /api/me isAdmin/needsProviderSetup (TDD)
+- [ ] 10-03-PLAN.md — adminRouter (members/credentials/calendars/shared) + member self-service credential, validate→encrypt→sync (TDD)
+- [ ] 10-04-PLAN.md — PWA /admin route + nav gating + CredentialSheet + SetupBanner (playwright-cli verified)
 **UI hint**: yes
 
 ### Phase 11: Per-Event Reminders
@@ -549,3 +554,16 @@ Plans:
 Plans:
 
 - [ ] TBD (promote with /gsd-review-backlog when ready)
+
+### Phase 999.18: Update dependencies as found during CI (BACKLOG)
+
+**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)

.planning/phases/10-admin-role-settings/10-01-PLAN.md

@@ -0,0 +1,192 @@
+---
+phase: 10-admin-role-settings
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - apps/api/src/db/schema.ts
+  - apps/api/src/db/migrations/0001_v1_1_foundation.sql
+  - apps/api/src/db/migrations/meta/_journal.json
+  - apps/pwa/e2e/global-setup.ts
+autonomous: true
+requirements: [ADMIN-01, ADMIN-02, ADMIN-03]
+must_haves:
+  truths:
+    - "The live dev MariaDB has users.is_admin (boolean, default false), member_credentials.provider_type (varchar, default 'caldav'), member_credentials UNIQUE(user_id), calendar_events.reminder_lead_minutes (int, nullable), and an app_config table"
+    - "Running db:generate then db:migrate applies the migration with no destructive (DROP/TRUNCATE) statement"
+    - "The e2e dev-bypass user (id=1) exists in the users table with is_admin=true so requireAdmin admits it"
+  artifacts:
+    - path: "apps/api/src/db/schema.ts"
+      provides: "v1.1 schema: users.isAdmin, memberCredentials.providerType + unique(user_id), calendarEvents.reminderLeadMinutes, appConfig table"
+      contains: "appConfig"
+    - path: "apps/api/src/db/migrations/0001_v1_1_foundation.sql"
+      provides: "generated ALTER/CREATE DDL for the v1.1 bundle"
+      contains: "is_admin"
+    - path: "apps/pwa/e2e/global-setup.ts"
+      provides: "seeds users row id=1 with is_admin=true for the dev-bypass admin UI verification path"
+      contains: "is_admin"
+  key_links:
+    - from: "apps/api/src/db/schema.ts"
+      to: "apps/api/src/db/migrations/0001_v1_1_foundation.sql"
+      via: "drizzle-kit generate"
+      pattern: "is_admin"
+    - from: "apps/pwa/e2e/global-setup.ts"
+      to: "users table"
+      via: "INSERT seed of id=1 is_admin=true"
+      pattern: "is_admin"
+---
+
+<objective>
+Ship the v1.1 DB foundation migration that all of Phase 10 (and Phases 11/12 downstream) build on: add `users.is_admin`, `member_credentials.provider_type` (the generic provider discriminator, D-04) + a `UNIQUE(user_id)` constraint (D-05), `calendar_events.reminder_lead_minutes`, and a new `app_config` table — in one drizzle-kit `generate`+`migrate` migration (NEVER `push`). Seed the dev-bypass user (id=1) as an admin (D-01 dev note) so local/e2e admin-UI verification works.
+
+Purpose: Every subsequent Phase 10 plan reads these columns (requireAdmin reads `is_admin`, the credential routes read `provider_type` and rely on the per-user UNIQUE for upsert, `/api/me` reads `is_admin`). `reminder_lead_minutes` is created-now / consumed by Phase 11; `app_config.setup_complete` is created-now / consumed by Phase 12. This plan is the head of the wave chain.
+Output: Edited `schema.ts`, a generated `0001_v1_1_foundation.sql` migration file (committed artifact) + updated `_journal.json`, applied to the live dev DB, and a seeded admin row for the e2e dev-bypass user.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/10-admin-role-settings/10-CONTEXT.md
+@.planning/phases/10-admin-role-settings/10-RESEARCH.md
+@.planning/phases/10-admin-role-settings/10-PATTERNS.md
+</context>
+
+<tasks>
+
+<task type="execute">
+  <name>Task 1: Extend schema.ts with the v1.1 column/table bundle</name>
+  <files>apps/api/src/db/schema.ts</files>
+  <read_first>
+    - apps/api/src/db/schema.ts (the file being modified — read the full file; `users` ~line 34, `memberCredentials` lines 55–68, `calendarEvents` ~lines 120–130 incl. `allDay` line 127, `calendars.isShared` line 89, `pushSubscriptions` lines 236–257 for the single-table pattern, the `unique`/`index` import + usage)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/db/schema.ts` (concrete column excerpts + line numbers: copy `allDay` boolean pattern for `is_admin`, `fastmailEmail` varchar pattern for `provider_type`, `pushSubscriptions` table pattern for `app_config`, `calendars` unique pattern for `uniq_member_credential_user`)
+    - .planning/phases/10-admin-role-settings/10-RESEARCH.md §Pattern 6 (provider discriminator, D-04) + §Code Examples "Drizzle Upsert Pattern" schema note (UNIQUE(user_id) rationale)
+  </read_first>
+  <action>
+    In apps/api/src/db/schema.ts make exactly four additive changes, matching the existing column idiom (per 10-PATTERNS.md excerpts — do NOT inline new code styles):
+    1. `users` table: add `isAdmin: boolean('is_admin').default(false).notNull()` (copy the `allDay` boolean idiom).
+    2. `memberCredentials` table: add `providerType: varchar('provider_type', { length: 64 }).notNull().default('caldav')` — the generic provider discriminator per D-04 (generic provider shape, Fastmail/CalDAV the only implemented provider; default 'caldav' for existing rows; no second provider built here). And add `unique('uniq_member_credential_user').on(t.userId)` to the table's index array (keep the existing `idx_member_credentials_user_id` index) — this enforces one-credential-per-member per D-05 and enables `onDuplicateKeyUpdate` upsert.
+    3. `calendarEvents` table: add `reminderLeadMinutes: int('reminder_lead_minutes')` (nullable — no `.notNull()`; created-now / consumed by Phase 11).
+    4. New `appConfig` table (export `const appConfig`), following the single-table `pushSubscriptions` idiom: a single key/value config — `key: varchar('key', { length: 128 }).primaryKey()`, `value: text('value')` (nullable), `updatedAt: timestamp('updated_at').defaultNow().onUpdateNow()`. This holds `setup_complete` (created-now / consumed by Phase 12 — do NOT add setup_complete gating logic here, only the table). Add a `setup_complete` semantics comment so Phase 12 can read/write the `setup_complete` key without a reshape.
+    Do NOT touch `calendars.is_shared` (already exists, line 89). Do NOT change crypto, encrypted_password, or any existing column.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api exec tsc --noEmit 2>&1 | tail -5</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/api/src/db/schema.ts` contains `is_admin`, `provider_type`, `uniq_member_credential_user`, `reminder_lead_minutes`, and an exported `appConfig` table with `key`/`value`/`updated_at`.
+    - `grep -c "export const appConfig" apps/api/src/db/schema.ts` returns 1.
+    - `pnpm --filter @familysync/api exec tsc --noEmit` exits 0 (types compile — note this passes WITHOUT the migration, because Drizzle types come from schema.ts; column existence is verified in Task 2).
+    - `is_admin` uses `.default(false).notNull()`; `provider_type` uses `.notNull().default('caldav')`; `reminder_lead_minutes` is nullable (no `.notNull()`).
+  </acceptance_criteria>
+  <done>schema.ts holds all four v1.1 additions, typechecks clean, no existing column altered.</done>
+</task>
+
+<task type="execute" gate="blocking">
+  <name>Task 2: [BLOCKING] Generate + migrate the v1.1 migration against the live dev DB</name>
+  <files>apps/api/src/db/migrations/0001_v1_1_foundation.sql, apps/api/src/db/migrations/meta/_journal.json</files>
+  <read_first>
+    - apps/api/src/db/migrations/0000_baseline.sql (existing migration format — `--> statement-breakpoint` between DDL statements; the format the generated file must follow)
+    - apps/api/drizzle.config.ts (migration output dir + env-driven DB credentials)
+    - apps/api/package.json (the `db:generate` / `db:migrate` scripts)
+    - .planning/phases/10-admin-role-settings/10-RESEARCH.md §Pattern 3 (generate+migrate workflow, exact commands, DB_HOST=127.0.0.1 dev override) + §Pitfall 4 (why never push)
+    - MEMORY note [[drizzle-mariadb-push-unsafe]] context in 10-CONTEXT.md Claude's Discretion (generate+migrate, never push)
+  </read_first>
+  <action>
+    BLOCKING — this must run AFTER Task 1 (schema.ts complete) and BEFORE any plan that reads the new columns. Bring up the dev MariaDB if not already bound on 3306 (per [[dev-stack-bringup]]: dev compose override exposes 3306). Then:
+    1. Run `pnpm --filter @familysync/api db:generate` to produce `apps/api/src/db/migrations/0001_v1_1_foundation.sql` (drizzle-kit names it; the actual filename may differ — commit whatever drizzle-kit emits as the next sequential migration) and update `meta/_journal.json`. DO NOT hand-write the SQL.
+    2. INSPECT the generated SQL: it MUST be only `ALTER TABLE ... ADD COLUMN` / `ADD UNIQUE` / `CREATE TABLE` statements (additive). If it contains any `DROP TABLE`, `DROP COLUMN`, or `TRUNCATE`, STOP — that is the false-destructive-diff trap; do NOT apply it, and do NOT fall back to `db:push`. Re-derive from schema.ts.
+    3. Apply with `DB_HOST=127.0.0.1` (+ dev DB_USER/DB_PASSWORD/DB_NAME from .env): `cd apps/api && set -a; source ../../.env; set +a; DB_HOST=127.0.0.1 pnpm db:migrate`. NEVER `db:push`.
+    4. Verify the live columns/table exist via a mysql2 query (not just tsc): assert `is_admin` on `users`, `provider_type` + the unique index on `member_credentials`, `reminder_lead_minutes` on `calendar_events`, and the `app_config` table.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && set -a; source .env 2>/dev/null; set +a; DB_HOST=127.0.0.1 node -e "const m=require('mysql2/promise');(async()=>{const c=await m.createConnection({host:'127.0.0.1',port:Number(process.env.DB_PORT||3306),user:process.env.DB_USER||'familysync',password:process.env.DB_PASSWORD||'',database:process.env.DB_NAME||'familysync'});const[u]=await c.query(\"SHOW COLUMNS FROM users LIKE 'is_admin'\");const[mc]=await c.query(\"SHOW COLUMNS FROM member_credentials LIKE 'provider_type'\");const[ce]=await c.query(\"SHOW COLUMNS FROM calendar_events LIKE 'reminder_lead_minutes'\");const[ac]=await c.query(\"SHOW TABLES LIKE 'app_config'\");if(u.length&&mc.length&&ce.length&&ac.length){console.log('MIGRATION OK');process.exit(0)}console.error('MISSING',{u:u.length,mc:mc.length,ce:ce.length,ac:ac.length});process.exit(1)})().catch(e=>{console.error(e.message);process.exit(1)})"</automated>
+  </verify>
+  <acceptance_criteria>
+    - A new migration `.sql` file exists under `apps/api/src/db/migrations/` (sequential after `0000_baseline.sql`) and `meta/_journal.json` references it.
+    - The generated SQL contains NO `DROP TABLE`, `DROP COLUMN`, or `TRUNCATE` statement: `grep -v '^--' <migration.sql> | grep -ciE 'drop (table|column)|truncate'` returns 0.
+    - The live dev MariaDB query above prints `MIGRATION OK` and exits 0 — `users.is_admin`, `member_credentials.provider_type`, the `member_credentials` unique on `user_id`, `calendar_events.reminder_lead_minutes`, and the `app_config` table all exist.
+    - `db:push` was NOT run (no push in command history for this task).
+  </acceptance_criteria>
+  <done>The v1.1 migration is generated (additive-only), committed, and applied to the live dev DB; all new columns/table verified present by a real DB query.</done>
+</task>
+
+<task type="execute">
+  <name>Task 3: Seed the dev-bypass user (id=1) as admin in the e2e global-setup</name>
+  <files>apps/pwa/e2e/global-setup.ts</files>
+  <read_first>
+    - apps/pwa/e2e/global-setup.ts (the file being modified — read the full file; the FK-checks-off TRUNCATE block, the `INSERT IGNORE INTO calendars (id, user_id, ...)` idempotent pattern lines 113–117, the mysql2 connection setup)
+    - apps/api/src/auth/devBypass.ts (DEV_USER id=1, displayName 'Dev User', color '#4A90D9' — the seed row must match this identity so /api/me dev path and the seeded DB row agree)
+    - apps/api/src/db/schema.ts users table (oidc_iss / oidc_sub NOT NULL, color NOT NULL — the seed INSERT must supply non-null values for the required columns)
+    - .planning/phases/10-admin-role-settings/10-RESEARCH.md §Pattern 5 "DEV_AUTH_BYPASS user-1 admin acquisition" (seed approach recommended) + §Pitfall 3 (why requireAdmin 403s without this seed)
+  </read_first>
+  <action>
+    The dev-bypass path injects DEV_USER (id=1) WITHOUT a DB upsert, so the `users` table has no row for id=1 — `requireAdmin` (Plan 02) does a DB lookup and would 403 the bypass admin UI locally and in e2e. Fix the seed per the D-01 dev note: in `apps/pwa/e2e/global-setup.ts`, inside the seed block (after the FK-checks-on, mirroring the existing `INSERT IGNORE INTO calendars` idempotent idiom), add an idempotent seed of the dev user row: `INSERT INTO users (id, oidc_iss, oidc_sub, display_name, color, is_admin) VALUES (1, 'dev-bypass', 'dev-user-1', 'Dev User', '#4A90D9', true) ON DUPLICATE KEY UPDATE is_admin=true`. Supply placeholder non-null oidc_iss/oidc_sub values (the bypass path never reads them; the row only needs to satisfy the NOT NULL constraints and carry is_admin=true). Keep it idempotent so re-runs converge. Do not change the existing TRUNCATE/event/list seeds. Add a comment that this row gives the dev-bypass admin UI a real `is_admin=true` row for requireAdmin's DB lookup.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && grep -c "is_admin" apps/pwa/e2e/global-setup.ts</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/pwa/e2e/global-setup.ts` contains an `INSERT INTO users` ... `is_admin` seed for id=1 with `ON DUPLICATE KEY UPDATE` (idempotent).
+    - `grep -c "is_admin" apps/pwa/e2e/global-setup.ts` returns >= 1.
+    - The seed supplies non-null `oidc_iss`, `oidc_sub`, and `color` (satisfies users NOT NULL constraints).
+    - The existing calendar/event/list seeds are unchanged (the `INSERT IGNORE INTO calendars` and `Seeded Test Event` anchors still present).
+  </acceptance_criteria>
+  <done>global-setup seeds users id=1 with is_admin=true idempotently; the dev-bypass admin UI path now has a DB row requireAdmin will admit.</done>
+</task>
+
+</tasks>
+
+<artifacts_this_phase_produces>
+This plan creates the following new symbols/files (excluded from drift verification — they do not exist before this plan):
+- `users.is_admin` column (boolean, default false)
+- `member_credentials.provider_type` column (varchar(64), default 'caldav') — D-04 generic provider discriminator
+- `member_credentials` UNIQUE constraint `uniq_member_credential_user` on `user_id`
+- `calendar_events.reminder_lead_minutes` column (int, nullable) — consumed by Phase 11
+- `app_config` table (`key` PK, `value`, `updated_at`) — `setup_complete` key consumed by Phase 12
+- exported `appConfig` Drizzle table in `apps/api/src/db/schema.ts`
+- generated migration SQL file `apps/api/src/db/migrations/0001_v1_1_foundation.sql` (or drizzle-kit's emitted sequential name) + `_journal.json` entry
+- seeded `users` row id=1 with `is_admin=true` in `apps/pwa/e2e/global-setup.ts`
+</artifacts_this_phase_produces>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| schema.ts → live MariaDB | DDL applied to a populated production-shaped DB; a wrong (destructive) migration could drop/truncate live data |
+| e2e seed → DB | global-setup TRUNCATEs + INSERTs against whatever DB_* points at |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10-01 | Tampering | drizzle-kit migration on populated MariaDB | mitigate | Task 2 uses generate+migrate (never push); blocks on any DROP/TRUNCATE in the generated SQL (acceptance grep == 0) and verifies columns via a live DB query, not just tsc (false-positive trap) |
+| T-10-02 | Tampering | e2e global-setup TRUNCATE against wrong DB | accept | Pre-existing fail-closed guards (NODE_ENV=production refusal + DEV_AUTH_BYPASS=true requirement) already gate the seed; this plan only adds an idempotent INSERT, no new TRUNCATE surface |
+| T-10-03 | Elevation of Privilege | dev-bypass user gains is_admin | accept | Seed grants is_admin=true ONLY to id=1 ONLY in the dev/e2e bypass DB (guarded by DEV_AUTH_BYPASS + non-production); production users acquire is_admin via first-login-wins (Plan 02), never via this seed |
+| T-10-SC | Tampering | npm/pip/cargo installs | mitigate | No new packages installed this phase (RESEARCH Package Legitimacy Audit: all already in lockfile); no install task, so no [ASSUMED]/[SUS] checkpoint needed |
+</threat_model>
+
+<verification>
+- `pnpm --filter @familysync/api exec tsc --noEmit` passes (schema typechecks).
+- The live DB query in Task 2 prints `MIGRATION OK`.
+- The generated migration SQL is additive-only (no DROP/TRUNCATE).
+- `grep -c is_admin apps/pwa/e2e/global-setup.ts` >= 1.
+</verification>
+
+<success_criteria>
+- All four v1.1 schema items exist in the live dev MariaDB (verified by query, not types).
+- Migration applied via generate+migrate; SQL committed; journal updated; no push used.
+- Dev-bypass user id=1 seeded as admin so downstream requireAdmin verification works.
+- Supports phase Success Criterion 5 (DB migration in place for downstream phases).
+</success_criteria>
+
+<output>
+Create `.planning/phases/10-admin-role-settings/10-01-SUMMARY.md` when done.
+</output>

.planning/phases/10-admin-role-settings/10-02-PLAN.md

@@ -0,0 +1,204 @@
+---
+phase: 10-admin-role-settings
+plan: 02
+type: tdd
+wave: 2
+depends_on: ["10-01"]
+files_modified:
+  - apps/api/src/lib/requireAdmin.ts
+  - apps/api/tests/lib/requireAdmin.test.ts
+  - apps/api/src/auth/user.ts
+  - apps/api/tests/auth/user.test.ts
+  - apps/api/src/routes/me.ts
+  - apps/api/tests/routes/me.test.ts
+autonomous: true
+requirements: [ADMIN-03]
+must_haves:
+  truths:
+    - "requireAdmin returns 403 for an authenticated non-admin user and calls next() for an admin user (role read from the DB, never a client flag)"
+    - "On first login when zero admins exist, upsertUser flags the new user is_admin=true; subsequent users are normal members"
+    - "GET /api/me returns isAdmin and needsProviderSetup for both the dev-bypass path and the OIDC path"
+  artifacts:
+    - path: "apps/api/src/lib/requireAdmin.ts"
+      provides: "MiddlewareHandler that reads c.get('user').id, looks up users.is_admin in the DB, 403s non-admins"
+      exports: ["requireAdmin"]
+      min_lines: 15
+    - path: "apps/api/src/auth/user.ts"
+      provides: "upsertUser extended with first-login-wins is_admin bootstrap (zero-admins → first user is admin)"
+      contains: "isAdmin"
+    - path: "apps/api/src/routes/me.ts"
+      provides: "/api/me response extended with isAdmin + needsProviderSetup (both dev-bypass and OIDC paths)"
+      contains: "needsProviderSetup"
+  key_links:
+    - from: "apps/api/src/lib/requireAdmin.ts"
+      to: "users.is_admin"
+      via: "Drizzle select where eq(users.id, userId)"
+      pattern: "users\\.isAdmin"
+    - from: "apps/api/src/routes/me.ts"
+      to: "member_credentials"
+      via: "needsProviderSetup = no member_credentials row for the user"
+      pattern: "memberCredentials"
+---
+
+<objective>
+Build the server-side admin role primitives that ADMIN-03 depends on: the `requireAdmin` MiddlewareHandler (DB-backed role check, always server-enforced), the first-login-wins `is_admin` bootstrap in `upsertUser` (D-01), and the `/api/me` extension exposing `isAdmin` + `needsProviderSetup` (D-03) for both the dev-bypass and OIDC code paths. TDD: each behavior has a defined input→output contract, so write the failing test first.
+
+Purpose: `requireAdmin` is the single security boundary for every `/api/admin/*` route (Plan 03 mounts it). `isAdmin` on `/api/me` drives PWA nav gating (Plan 04, UX-only). `needsProviderSetup` drives the member self-service banner (Plan 04). First-login-wins is written so Phase 12 can later tighten it to "first login after setup_complete" without a rewrite.
+Output: New `requireAdmin.ts` + tests, extended `user.ts` + tests, extended `me.ts` + tests.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/10-admin-role-settings/10-CONTEXT.md
+@.planning/phases/10-admin-role-settings/10-RESEARCH.md
+@.planning/phases/10-admin-role-settings/10-PATTERNS.md
+@.planning/phases/10-admin-role-settings/10-01-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="tdd" tdd="true">
+  <name>Task 1: requireAdmin middleware (RED→GREEN→REFACTOR)</name>
+  <files>apps/api/src/lib/requireAdmin.ts, apps/api/tests/lib/requireAdmin.test.ts</files>
+  <read_first>
+    - apps/api/src/auth/devBypass.ts (MiddlewareHandler signature + the `c.get('user')`/`c.set('user', DEV_USER)` pattern + the `ContextVariableMap` augmentation, line ~46; the side-effect import idiom)
+    - apps/api/src/lib/ (sibling lib modules — e.g. listAccess.ts — for the lib-file import/style conventions)
+    - apps/api/tests/lib/ + apps/api/tests/auth/devBypass.test.ts (existing test idioms: how a Hono app/middleware is exercised, how c.get('user') is stubbed, how DB is reached in tests per [[api-integration-test-db]])
+    - apps/api/src/db/schema.ts users.isAdmin (from Plan 01) + apps/api/src/db/client.ts (the `db` export)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/lib/requireAdmin.ts` (the exact MiddlewareHandler shape, the DB lookup excerpt, the `import '../auth/devBypass.js'` side-effect import) + 10-RESEARCH.md §Pattern 1 (Pitfall 9) + §Pitfall 3
+  </read_first>
+  <behavior>
+    - Test (RED): an authenticated user whose DB row has is_admin=false → requireAdmin responds 403 `{ error: 'Forbidden' }` and does NOT call next().
+    - Test: an authenticated user whose DB row has is_admin=true → requireAdmin calls next() (request proceeds).
+    - Test: no resolved user on context (c.get('user') undefined) → 403 (never throws).
+    - Test: the role is read from the DB (users.is_admin), NOT from any value on c.get('user') — a context user object claiming isAdmin=true but with a non-admin DB row is still 403 (defence: bypass only skips OIDC, not the DB check).
+  </behavior>
+  <action>
+    Create `apps/api/src/lib/requireAdmin.ts` exporting `requireAdmin: MiddlewareHandler` (per 10-PATTERNS.md excerpt): read `c.get('user')?.id`; if no id → `c.json({ error: 'Forbidden' }, 403)`; else `db.select({ isAdmin: users.isAdmin }).from(users).where(eq(users.id, userId)).limit(1)`; if `!row?.isAdmin` → 403; else `await next()`. Include the `import '../auth/devBypass.js'` side-effect import for the ContextVariableMap augmentation. NEVER log the user object or any credential. Write `apps/api/tests/lib/requireAdmin.test.ts` FIRST (the four behaviors above), confirm RED, then implement to GREEN. Follow the real-DB test conventions in [[api-integration-test-db]] (tests live in tests/, DB_HOST=127.0.0.1 override) if the test exercises the live DB; otherwise stub the db module.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- requireAdmin 2>&1 | tail -15</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/api/src/lib/requireAdmin.ts` exports `requireAdmin` typed as `MiddlewareHandler`.
+    - The 403 response body is `{ error: 'Forbidden' }` (HTTP 403) for a non-admin authenticated user.
+    - The role decision reads `users.isAdmin` from the DB (`grep -q "users.isAdmin" apps/api/src/lib/requireAdmin.ts`); it does NOT branch on a property of `c.get('user')` other than `.id`.
+    - No `console.log`/`console.error` of the user object or credentials in the file.
+    - `pnpm --filter @familysync/api test -- requireAdmin` passes all four cases.
+  </acceptance_criteria>
+  <done>requireAdmin guard exists, DB-backed, 403s non-admins, tests green.</done>
+</task>
+
+<task type="tdd" tdd="true">
+  <name>Task 2: First-login-wins is_admin bootstrap in upsertUser (RED→GREEN→REFACTOR)</name>
+  <files>apps/api/src/auth/user.ts, apps/api/tests/auth/user.test.ts</files>
+  <read_first>
+    - apps/api/src/auth/user.ts (the file being modified — the full `upsertUser` function lines 76–128: the existing-row early-return path, the color assignment, the INSERT `.values({...}).$returningId()` block lines 112–122)
+    - apps/api/tests/auth/user.test.ts (existing upsertUser test idioms — how it seeds/asserts DB state, the real-DB test setup)
+    - apps/api/src/db/schema.ts users.isAdmin (from Plan 01)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/auth/user.ts` (the zero-admin COUNT check + `isAdmin: shouldBeAdmin` in `.values()`, the `import { sql }` addition) + 10-RESEARCH.md §Pattern 5 (Phase-12-safe first-login-wins, the "zero admins exist" check that P12 tightens to "after setup_complete")
+  </read_first>
+  <behavior>
+    - Test (RED): upsertUser inserting a brand-new user when the users table has ZERO admins → the inserted row has is_admin=true.
+    - Test: upsertUser inserting a new user when an admin already exists → the inserted row has is_admin=false.
+    - Test: upsertUser for an EXISTING user (oidc_iss+oidc_sub already present) → is_admin is NOT changed by the upsert (the early-return path is untouched; promotion/demotion is not this function's job).
+  </behavior>
+  <action>
+    In `apps/api/src/auth/user.ts`, before the INSERT in `upsertUser` (after color assignment), add a zero-admin check (per 10-PATTERNS.md excerpt): `db.select({ count: sql<number>\`COUNT(*)\` }).from(users).where(eq(users.isAdmin, true))`; `shouldBeAdmin = Number(count) === 0`; pass `isAdmin: shouldBeAdmin` in the INSERT `.values({...})`. Add `import { sql } from 'drizzle-orm'` if absent. Leave the existing-user early-return path unchanged (do NOT toggle is_admin for existing users). Add a comment marking this as the Phase-12 hook point: "first user when zero admins exist (D-01); Phase 12 tightens to first user after app_config.setup_complete". Write the three test cases in `apps/api/tests/auth/user.test.ts` FIRST, confirm RED, implement to GREEN.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- user 2>&1 | tail -15</automated>
+  </verify>
+  <acceptance_criteria>
+    - A new user inserted with zero pre-existing admins has `is_admin=true`; with an existing admin, `is_admin=false`.
+    - The existing-user early-return path does not modify is_admin (test asserts unchanged).
+    - `grep -q "isAdmin" apps/api/src/auth/user.ts` and the INSERT `.values()` includes `isAdmin`.
+    - A comment in `user.ts` names the Phase-12 tightening hook (first login after setup_complete).
+    - `pnpm --filter @familysync/api test -- user` passes all cases.
+  </acceptance_criteria>
+  <done>First-login-wins bootstrap writes is_admin on first insert, member-count-agnostic, Phase-12-safe, tests green.</done>
+</task>
+
+<task type="tdd" tdd="true">
+  <name>Task 3: Extend /api/me with isAdmin + needsProviderSetup (RED→GREEN→REFACTOR)</name>
+  <files>apps/api/src/routes/me.ts, apps/api/tests/routes/me.test.ts</files>
+  <read_first>
+    - apps/api/src/routes/me.ts (the file being modified — the dev-bypass short-circuit lines 31–43 returning `{ user: { id, displayName, color } }`, the OIDC path lines 60–75 returning the resolved user; both must add isAdmin + needsProviderSetup)
+    - apps/api/tests/routes/me.test.ts (existing /api/me test idioms — both dev-bypass and OIDC response assertions)
+    - apps/api/src/db/schema.ts users.isAdmin + memberCredentials (from Plan 01) + apps/api/src/db/client.ts (`db`)
+    - apps/api/src/auth/user.ts (the resolved `user` shape returned by upsertUser — confirm it now carries isAdmin after Task 2; if not selected, me.ts must select users.isAdmin itself)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/routes/me.ts` (the needsProviderSetup lookup excerpt: `db.select({id: memberCredentials.id}).from(memberCredentials).where(eq(memberCredentials.userId, userId)).limit(1)` → `needsProviderSetup = !cred`) + 10-RESEARCH.md §Code Examples "/api/me Response Extension" + §Open Questions #3 (needsProviderSetup lives on /api/me)
+  </read_first>
+  <behavior>
+    - Test (RED): dev-bypass path (DEV_USER id=1) → response `user` includes `isAdmin` (looked up from the DB row for id=1, NOT hardcoded) and `needsProviderSetup` (true iff no member_credentials row for id=1).
+    - Test: OIDC path → response `user` includes `isAdmin` (from the resolved users row) and `needsProviderSetup` (member_credentials existence for that user id).
+    - Test: a user WITH a member_credentials row → needsProviderSetup=false; a user WITHOUT one → needsProviderSetup=true.
+  </behavior>
+  <action>
+    In `apps/api/src/routes/me.ts`, extend BOTH response paths to include `isAdmin` and `needsProviderSetup`. The dev-bypass path currently short-circuits without a DB lookup — it MUST now query `users.isAdmin` for id=1 (same lookup as requireAdmin) rather than hardcoding, and compute `needsProviderSetup` via the member_credentials existence check (per 10-PATTERNS.md excerpt). The OIDC path uses the resolved user's isAdmin + the same member_credentials existence check. Add the `eq`/`db`/`users`/`memberCredentials` imports as needed. Do NOT add the self-service `/api/me/credential` POST endpoint here — that belongs to Plan 03. Write the three test cases in `apps/api/tests/routes/me.test.ts` FIRST, confirm RED, implement to GREEN.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- me 2>&1 | tail -15</automated>
+  </verify>
+  <acceptance_criteria>
+    - `GET /api/me` response `user` object contains `isAdmin` (boolean) and `needsProviderSetup` (boolean) on BOTH the dev-bypass and OIDC paths.
+    - The dev-bypass path's isAdmin is read from the DB (`grep -q "memberCredentials" apps/api/src/routes/me.ts` and isAdmin not hardcoded `true`/`false` in the dev path).
+    - needsProviderSetup is true exactly when no member_credentials row exists for the user.
+    - No `/api/me/credential` POST route added in this plan.
+    - `pnpm --filter @familysync/api test -- me` passes all cases.
+  </acceptance_criteria>
+  <done>/api/me exposes isAdmin + needsProviderSetup on both paths, DB-backed, tests green.</done>
+</task>
+
+</tasks>
+
+<artifacts_this_phase_produces>
+New symbols/files created by this plan (excluded from drift verification):
+- `apps/api/src/lib/requireAdmin.ts` exporting `requireAdmin` (MiddlewareHandler)
+- `apps/api/tests/lib/requireAdmin.test.ts`
+- first-login-wins `is_admin` bootstrap branch in `upsertUser` (`apps/api/src/auth/user.ts`)
+- `isAdmin` + `needsProviderSetup` fields on the `/api/me` response (`apps/api/src/routes/me.ts`)
+- test additions in `apps/api/tests/auth/user.test.ts` and `apps/api/tests/routes/me.test.ts`
+</artifacts_this_phase_produces>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| client → /api/admin/* (via requireAdmin) | untrusted authenticated request must be proven admin server-side before any admin handler runs |
+| /api/me → browser | the isAdmin flag crosses to the client for UX gating only; never the security boundary |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10-04 | Elevation of Privilege | non-admin invoking admin-gated logic | mitigate | requireAdmin reads users.is_admin from the DB and 403s non-admins (Task 1); decision never trusts a client-supplied or context-attached isAdmin claim, only the DB row |
+| T-10-05 | Elevation of Privilege | DEV_AUTH_BYPASS bypasses the role check | mitigate | requireAdmin and /api/me both DB-lookup users.is_admin even on the bypass path (the bypass skips OIDC, not the DB check); the bypass admin row comes only from the guarded dev seed (Plan 01 Task 3) |
+| T-10-06 | Spoofing/EoP | client trusting its own isAdmin to reach admin features | mitigate | isAdmin on /api/me is documented and used as UX-only; the server-side 403 (requireAdmin, Plan 03) is the real boundary on every /api/admin/* request |
+| T-10-07 | Information Disclosure | logging the resolved user / claims | mitigate | requireAdmin and me.ts must not console.log the user object or any credential (acceptance grep) |
+| T-10-SC | Tampering | npm/pip/cargo installs | mitigate | No new packages this phase (RESEARCH Package Legitimacy Audit); no install task |
+</threat_model>
+
+<verification>
+- `pnpm --filter @familysync/api test -- requireAdmin && pnpm --filter @familysync/api test -- user && pnpm --filter @familysync/api test -- me` all pass.
+- `pnpm --filter @familysync/api exec tsc --noEmit` passes (per [[vitest-passes-tsc-fails]], run tsc separately — vitest stays green on type errors).
+- `grep -q "users.isAdmin" apps/api/src/lib/requireAdmin.ts`.
+</verification>
+
+<success_criteria>
+- requireAdmin 403s authenticated non-admins, admits admins, DB-backed (ADMIN-03 server enforcement; supports Success Criteria 1 & 4).
+- First-login-wins writes is_admin on first insert, role-agnostic / member-count-agnostic (Success Criterion 4).
+- /api/me exposes isAdmin + needsProviderSetup on both paths for downstream PWA gating + self-service.
+</success_criteria>
+
+<output>
+Create `.planning/phases/10-admin-role-settings/10-02-SUMMARY.md` when done.
+</output>

.planning/phases/10-admin-role-settings/10-03-PLAN.md

@@ -0,0 +1,225 @@
+---
+phase: 10-admin-role-settings
+plan: 03
+type: tdd
+wave: 3
+depends_on: ["10-01", "10-02"]
+files_modified:
+  - apps/api/src/broker/outboxWorker.ts
+  - apps/api/src/routes/admin.ts
+  - apps/api/src/routes/me.ts
+  - apps/api/src/index.ts
+  - apps/api/tests/routes/admin.test.ts
+autonomous: true
+requirements: [ADMIN-01, ADMIN-02, ADMIN-03]
+must_haves:
+  truths:
+    - "GET /api/admin/members returns 403 for a non-admin authenticated user and a member+credential-status list for an admin"
+    - "POST /api/admin/credentials validates against CalDAV (PROPFIND), 400 on bad credential with NO submitted password in the body, 200 + encrypted store on success; never logs/echoes the password"
+    - "PUT /api/admin/calendars/:id/shared sets exactly one calendar is_shared=1 and clears any prior shared calendar"
+    - "POST /api/me/credential sets only the current user's credential (ignores any userId in the body); a non-admin cannot POST /api/admin/credentials"
+  artifacts:
+    - path: "apps/api/src/routes/admin.ts"
+      provides: "adminRouter guarded by requireAdmin (.use('*', ...) first); GET /members, POST /credentials, GET /calendars, PUT /calendars/:id/shared"
+      exports: ["adminRouter"]
+      min_lines: 60
+    - path: "apps/api/src/routes/me.ts"
+      provides: "POST /api/me/credential member-scoped self-service (currentUserId only)"
+      contains: "credential"
+    - path: "apps/api/src/index.ts"
+      provides: "app.route('/api/admin', adminRouter) mounted in the existing auth band"
+      contains: "adminRouter"
+  key_links:
+    - from: "apps/api/src/routes/admin.ts"
+      to: "requireAdmin"
+      via: "adminRouter.use('*', requireAdmin) as the first statement (Pitfall 9)"
+      pattern: "adminRouter\\.use\\('\\*', requireAdmin\\)"
+    - from: "apps/api/src/routes/admin.ts"
+      to: "broker validate→encrypt→sync"
+      via: "createFastmailClient + fetchCalendars, encryptPassword, exported triggerTargetedResync/loadClientForUser"
+      pattern: "encryptPassword"
+    - from: "apps/api/src/index.ts"
+      to: "adminRouter"
+      via: "app.route('/api/admin', adminRouter)"
+      pattern: "app.route\\('/api/admin'"
+---
+
+<objective>
+Build the admin API surface (ADMIN-01 credential rotation + ADMIN-02 shared-calendar designation), gated by `requireAdmin` (ADMIN-03), plus the member-scoped self-service credential endpoint (D-07), all sharing one validate→encrypt→initial-sync path. Promote the broker's private resync helpers to exports so both the admin and self-service paths reuse them. TDD: the credential and guard contracts have precise input→output behavior (403 / 400-no-echo / 200), so write the failing tests first.
+
+Purpose: This is the single shared credential + shared-calendar surface (`/api/admin/credentials`, `/api/admin/calendars/:id/shared`) — Phase 12 MUST reuse it, not duplicate it into `/api/setup/*`. The self-service endpoint is the member-scoped counterpart of admin rotation.
+Output: Exported broker helpers, new `admin.ts` router, the `/api/me/credential` self-service endpoint, the index.ts mount, and integration tests covering the Pitfall 7 (no-echo) and Pitfall 9 (403) hard checks.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/10-admin-role-settings/10-CONTEXT.md
+@.planning/phases/10-admin-role-settings/10-RESEARCH.md
+@.planning/phases/10-admin-role-settings/10-PATTERNS.md
+@.planning/phases/10-admin-role-settings/10-01-SUMMARY.md
+@.planning/phases/10-admin-role-settings/10-02-SUMMARY.md
+@apps/api/src/lib/requireAdmin.ts
+</context>
+
+<tasks>
+
+<task type="execute">
+  <name>Task 1: Promote broker resync helpers to exports</name>
+  <files>apps/api/src/broker/outboxWorker.ts</files>
+  <read_first>
+    - apps/api/src/broker/outboxWorker.ts (the file being modified — `loadClientForUser` lines 271–288, `triggerTargetedResync` lines 302–348 incl. the `client.fetchCalendars()` + `syncCalendar` loop ~line 331; confirm neither is exported yet)
+    - apps/api/src/broker/client.ts (createFastmailClient — the CalDAV client the helpers build on) + apps/api/src/broker/sync.ts (syncCalendar signature)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/broker/outboxWorker.ts` (add `export` to both functions; the post-credential-save full sync uses loadClientForUser → fetchCalendars → syncCalendar per davCal) + 10-RESEARCH.md §Pattern 4 + §Open Questions #2 (full per-member poll after a fresh credential save — no known calendarUrl yet) + Assumptions A1
+  </read_first>
+  <action>
+    Add the `export` keyword to `loadClientForUser` and `triggerTargetedResync` in `apps/api/src/broker/outboxWorker.ts` so the admin + self-service credential routes can reuse them (per 10-PATTERNS.md). Do NOT change their bodies or the outbox drain cycle (A1: standalone fetch+sync helpers, no coupling to the drain loop). After a FRESH credential save there is no known calendarUrl, so the credential routes will call `loadClientForUser(userId)` → `client.fetchCalendars()` → `syncCalendar(...)` per returned DAV calendar (the full per-member poll, mirroring poller.ts) rather than `triggerTargetedResync` — but export both for flexibility. Confirm existing broker tests still pass (no behavior change). NEVER reintroduce node-cron ([[node-cron-skips-in-long-running-process]]) — these helpers are setInterval-driven callers' utilities, untouched.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && grep -E "^export (async )?function (loadClientForUser|triggerTargetedResync)" apps/api/src/broker/outboxWorker.ts && pnpm --filter @familysync/api test -- outbox 2>&1 | tail -8</automated>
+  </verify>
+  <acceptance_criteria>
+    - `grep -cE "^export (async )?function (loadClientForUser|triggerTargetedResync)" apps/api/src/broker/outboxWorker.ts` returns 2.
+    - The function bodies are unchanged (only `export` prepended) — `git diff` shows only the two `export` keyword additions.
+    - `pnpm --filter @familysync/api test -- outbox` still passes (no regression to the drain cycle).
+  </acceptance_criteria>
+  <done>Both broker resync helpers are exported, bodies unchanged, broker tests green.</done>
+</task>
+
+<task type="tdd" tdd="true">
+  <name>Task 2: adminRouter — guard + members + credentials + shared-calendar (RED→GREEN→REFACTOR)</name>
+  <files>apps/api/src/routes/admin.ts, apps/api/src/index.ts, apps/api/tests/routes/admin.test.ts</files>
+  <read_first>
+    - apps/api/src/routes/push.ts (closest analog: Hono sub-router, zValidator, resolveUserId, ContextVariableMap side-effect import; the subscribeSchema zValidator usage lines ~60–67)
+    - apps/api/src/routes/events.ts (Drizzle leftJoin + where SELECT lines 165–177; the 400-not-422 zValidator convention; onDuplicateKeyUpdate upsert idiom)
+    - apps/api/src/lib/requireAdmin.ts (from Plan 02 — the guard to apply .use('*', requireAdmin) FIRST)
+    - apps/api/src/broker/crypto.ts (encryptPassword — reuse verbatim, AES-256-GCM, never log the return) + apps/api/src/broker/client.ts (createFastmailClient + the fetchCalendars PROPFIND validation signal) + apps/api/src/broker/outboxWorker.ts (the helpers exported in Task 1)
+    - apps/api/src/db/schema.ts users / memberCredentials (provider_type + uniq_member_credential_user from Plan 01) / calendars.isShared (line 89)
+    - apps/api/src/index.ts (route mount block lines 67–72; the devAuthBypass→oidcAuthMiddleware band already covers /api/*; mount adminRouter AFTER the existing routes)
+    - apps/api/tests/routes/push.test.ts (integration test idioms: import `app` (NOT adminRouter directly — Pitfall 9), how dev-bypass admin vs non-admin is exercised, the real-DB test setup per [[api-integration-test-db]])
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/api/src/routes/admin.ts` + §`apps/api/src/index.ts` (router+guard pattern, credentialSchema, noEchoHook, SELECT/upsert/exclusive-is_shared excerpts) + 10-RESEARCH.md §Pattern 1 (Pitfall 9), §Pattern 2 (Pitfall 7 no-echo hook), §Pattern 7 (exclusive is_shared), §Pitfall 1/2/5/6, §UI-SPEC Surface 2/5 (member-row + picker shapes the GET responses must feed)
+  </read_first>
+  <behavior>
+    - Test (RED, Pitfall 9): GET /api/admin/members as a non-admin authenticated user → 403. As an admin → 200 with a list of members each carrying credential status (has credential / not). Integration test imports `app`, never adminRouter directly.
+    - Test (Pitfall 7): POST /api/admin/credentials with an INVALID app password (CalDAV PROPFIND fails) → 400, and the response body contains NONE of the submitted password value (assert the exact submitted string is absent from the body) and no Zod `received`/`issues`/`value` field.
+    - Test: POST /api/admin/credentials with a VALID credential (CalDAV PROPFIND succeeds) → 200; the stored member_credentials.encrypted_password is NOT the plaintext (encryptPassword applied); response never echoes the password; initial sync is triggered (fire-and-forget).
+    - Test (Pitfall 9): POST /api/admin/credentials as a non-admin → 403.
+    - Test (ADMIN-02, Pitfall 7-adjacent): PUT /api/admin/calendars/:id/shared as admin → exactly one calendar has is_shared=1 afterward (the target), any prior shared calendar cleared. As non-admin → 403.
+    - Test: GET /api/admin/calendars as admin → 200 list of synced calendars (id, name, is_shared). As non-admin → 403.
+  </behavior>
+  <action>
+    Create `apps/api/src/routes/admin.ts` exporting `adminRouter = new Hono()` with `adminRouter.use('*', requireAdmin)` as the VERY FIRST statement (Pitfall 9). Add the side-effect import `'../auth/devBypass.js'`. Routes (paths are planner's call per D — use these): 
+    - `GET /members`: SELECT users LEFT JOIN member_credentials → return id, displayName, color, hasCredential (boolean). Feeds UI-SPEC Surface 2.
+    - `POST /credentials`: `zValidator('json', credentialSchema, noEchoHook)` where credentialSchema = `{ userId: number().int().positive(), providerType: literal('caldav'), fastmailEmail: string().email().max(256), appPassword: string().min(1).max(500) }` and noEchoHook returns `c.json({ error: 'Invalid request' }, 400)` (NEVER `c.json(result.error, ...)`). Handler: validate via `createFastmailClient(email, appPassword)` + `client.fetchCalendars()` (throws on auth failure → return 400 generic, NO password in body); on success `encryptPassword(appPassword)` → upsert member_credentials via `onDuplicateKeyUpdate` (uses the Plan-01 UNIQUE(user_id)) with providerType 'caldav'; then fire-and-forget the initial full per-member sync (loadClientForUser → fetchCalendars → syncCalendar per davCal) and return 200. NEVER `console.log` the body or `c.req.valid('json')`.
+    - `GET /calendars`: SELECT calendars (id, displayName, isShared). Feeds UI-SPEC Surface 5.
+    - `PUT /calendars/:id/shared`: exclusive update (Pattern 7) — `db.update(calendars).set({isShared:false}).where(eq(calendars.isShared,true))` then `db.update(calendars).set({isShared:true}).where(eq(calendars.id, targetId))` (D-06 single-select). Return 200.
+    Mount in `apps/api/src/index.ts`: `app.route('/api/admin', adminRouter)` after the existing route block (no extra app-level middleware — the guard lives inside the router). Write `apps/api/tests/routes/admin.test.ts` FIRST with all six behaviors (import `app`), confirm RED, implement to GREEN. Mock/stub CalDAV (createFastmailClient/fetchCalendars) for the validation outcomes to avoid live Fastmail calls in CI (per [[dev-data-user1-no-calendars]] — route-mocks for credential paths).
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- admin 2>&1 | tail -20</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/api/src/routes/admin.ts` first statement after router creation is `adminRouter.use('*', requireAdmin)` — `grep -nA1 "new Hono()" apps/api/src/routes/admin.ts` shows the `.use('*', requireAdmin)` immediately after.
+    - `apps/api/src/index.ts` contains `app.route('/api/admin', adminRouter)`.
+    - GET /api/admin/members returns 403 for a non-admin authenticated user (integration test importing `app`).
+    - A 400 response from POST /api/admin/credentials with a bad credential contains NO submitted password value and no Zod `received`/`issues` field (test asserts the exact submitted string absent).
+    - On a valid credential, the persisted member_credentials.encrypted_password != the plaintext (encryptPassword applied) and 200 is returned.
+    - After PUT /api/admin/calendars/:id/shared, exactly one calendar row has is_shared=1.
+    - No `console.log`/`console.error` of request bodies in `apps/api/src/routes/admin.ts` (`grep -ciE "console\.(log|error)\(.*(body|valid|password)" apps/api/src/routes/admin.ts` returns 0).
+    - `pnpm --filter @familysync/api test -- admin` passes all six behaviors.
+  </acceptance_criteria>
+  <done>adminRouter exists, guard-first, mounted; members/credentials/calendars/shared routes behave per contract; no-echo + 403 hard checks green.</done>
+</task>
+
+<task type="tdd" tdd="true">
+  <name>Task 3: Member-scoped self-service credential endpoint POST /api/me/credential (RED→GREEN→REFACTOR)</name>
+  <files>apps/api/src/routes/me.ts, apps/api/tests/routes/admin.test.ts</files>
+  <read_first>
+    - apps/api/src/routes/me.ts (the file being modified — the meRouter export, the resolveUserId/dev-bypass + OIDC user resolution already present; the isAdmin/needsProviderSetup response added in Plan 02)
+    - apps/api/src/routes/admin.ts (from Task 2 — reuse the SAME credentialSchema shape minus userId, the SAME noEchoHook, the SAME validate→encrypt→sync sequence; extract any shared helper rather than duplicating the validate/encrypt logic)
+    - apps/api/src/broker/crypto.ts + client.ts + outboxWorker.ts (the shared path)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §Shared Patterns "resolveUserId" + 10-RESEARCH.md §Pattern 4, §Pitfall 6 (cross-member write — endpoint MUST use currentUserId from session, NEVER a body userId), §Architectural Responsibility Map (needsProviderSetup) + §UI-SPEC Surface 4 (self-service onboarding)
+  </read_first>
+  <behavior>
+    - Test (RED, Pitfall 6): POST /api/me/credential as user A with a body that includes `userId` for user B → the credential is written to user A (currentUserId), NOT user B; the body userId is ignored.
+    - Test: POST /api/me/credential with a valid credential → 200, stored encrypted for the current user, needsProviderSetup becomes false on the next /api/me; initial sync triggered.
+    - Test (Pitfall 7): POST /api/me/credential with a bad credential → 400 generic, no password echoed.
+    - Test: the endpoint does NOT require admin (a normal member can set their own credential) but is still behind the auth guard (unauthenticated → 401 from the outer band).
+  </behavior>
+  <action>
+    Add `POST /credential` to the meRouter in `apps/api/src/routes/me.ts` (final path `/api/me/credential`), member-scoped. Schema = the admin credentialSchema WITHOUT `userId` (`{ providerType: literal('caldav'), fastmailEmail, appPassword }`) + the SAME `noEchoHook`. The handler resolves `currentUserId` via the existing resolveUserId/dev-bypass pattern and ALWAYS writes to that id — it MUST NOT read a userId from the body (Pitfall 6). Reuse the SAME validate→encrypt→initial-sync path as admin Task 2 (extract a shared helper, e.g. `validateEncryptAndStoreCredential(userId, email, password)`, to avoid divergence — D-07 "identical path"). Add the self-service test cases to `apps/api/tests/routes/admin.test.ts` (or a sibling me-credential test — planner's call; keep them with the credential-surface tests). Write tests FIRST, confirm RED, implement to GREEN.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api test -- credential 2>&1 | tail -15</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/api/src/routes/me.ts` adds a `POST /credential` route; the final mounted path is `/api/me/credential`.
+    - A POST to /api/me/credential with a body `userId` for another user writes ONLY to the current session user (test proves the other user's credential is untouched).
+    - The self-service path reuses the same validate→encrypt→store logic as the admin path (shared helper; no duplicated encrypt/PROPFIND block) — `grep` shows a single shared function called by both routes.
+    - A bad credential returns 400 generic with no echoed password.
+    - A normal (non-admin) member can succeed on /api/me/credential (no requireAdmin on this route).
+    - `pnpm --filter @familysync/api test -- credential` passes all cases.
+  </acceptance_criteria>
+  <done>Member self-service credential endpoint exists, member-scoped (no cross-member write), shares the admin validate→encrypt→sync path, tests green.</done>
+</task>
+
+</tasks>
+
+<artifacts_this_phase_produces>
+New symbols/files created by this plan (excluded from drift verification):
+- `export` on `loadClientForUser` + `triggerTargetedResync` in `apps/api/src/broker/outboxWorker.ts`
+- `apps/api/src/routes/admin.ts` exporting `adminRouter` with `GET /members`, `POST /credentials`, `GET /calendars`, `PUT /calendars/:id/shared`
+- `requireAdmin` applied as `adminRouter.use('*', requireAdmin)` (consumes the Plan-02 guard)
+- `app.route('/api/admin', adminRouter)` mount in `apps/api/src/index.ts`
+- `POST /api/me/credential` member-scoped self-service endpoint in `apps/api/src/routes/me.ts`
+- shared `validateEncryptAndStoreCredential` helper (admin + self-service)
+- `apps/api/tests/routes/admin.test.ts` (+ self-service credential test cases)
+</artifacts_this_phase_produces>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| client → /api/admin/* | untrusted authenticated request; must pass requireAdmin before any handler |
+| client → /api/me/credential | authenticated member request; must be confined to the caller's own credential row |
+| API → Fastmail CalDAV | the submitted app password leaves the trust boundary only to validate (PROPFIND); it must never be logged or echoed back to the client |
+| app password → MariaDB | plaintext must be AES-256-GCM encrypted before any DB write |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10-08 | Elevation of Privilege | non-admin hitting /api/admin/* | mitigate | adminRouter.use('*', requireAdmin) FIRST (Pitfall 9); integration tests import `app` and assert 403 on every admin route for a non-admin |
+| T-10-09 | Information Disclosure | app password echoed in a Zod/validation error | mitigate | noEchoHook returns `{ error: 'Invalid request' }` with no result.error; test asserts the submitted password string is absent from any 400 body (Pitfall 7) |
+| T-10-10 | Information Disclosure | app password logged | mitigate | No console.log of body/valid()/password in admin.ts or the me credential route (acceptance grep == 0) |
+| T-10-11 | Information Disclosure | plaintext credential at rest | mitigate | encryptPassword (AES-256-GCM via crypto.ts) applied before the DB write; test asserts stored value != plaintext; no new crypto written |
+| T-10-12 | Elevation of Privilege / IDOR | member self-service writes another member's credential | mitigate | /api/me/credential always uses currentUserId from the session and ignores any body userId (Pitfall 6); test proves the other user's row is untouched |
+| T-10-13 | IDOR | admin rotating an arbitrary member's credential | accept | D-05 explicitly allows an admin to rotate ANY member's credential; this is gated by requireAdmin and is the intended capability (the self-service path remains member-scoped) |
+| T-10-SC | Tampering | npm/pip/cargo installs | mitigate | No new packages this phase (RESEARCH Package Legitimacy Audit); no install task |
+</threat_model>
+
+<verification>
+- `pnpm --filter @familysync/api test -- admin && pnpm --filter @familysync/api test -- credential && pnpm --filter @familysync/api test -- outbox` all pass.
+- `pnpm --filter @familysync/api exec tsc --noEmit` passes (run tsc separately per [[vitest-passes-tsc-fails]]).
+- `grep -A1 "new Hono()" apps/api/src/routes/admin.ts` shows `.use('*', requireAdmin)` first.
+- `grep -ciE "console\.(log|error)\(.*(body|valid|password)" apps/api/src/routes/admin.ts` == 0.
+</verification>
+
+<success_criteria>
+- ADMIN-01: admin can rotate any member's credential, CalDAV-validated, encrypted, never echoed/logged (Success Criterion 2).
+- ADMIN-02: admin sets exactly one shared calendar via the API (Success Criterion 3).
+- ADMIN-03: every /api/admin/* route 403s non-admins (Success Criterion 1); guard inside the sub-router (Pitfall 9).
+- D-07: member self-service credential, member-scoped, same path.
+- Single shared surface — no /api/setup/* duplication (Phase 12 reuses these routes).
+</success_criteria>
+
+<output>
+Create `.planning/phases/10-admin-role-settings/10-03-SUMMARY.md` when done.
+</output>

.planning/phases/10-admin-role-settings/10-04-PLAN.md

@@ -0,0 +1,205 @@
+---
+phase: 10-admin-role-settings
+plan: 04
+type: execute
+wave: 4
+depends_on: ["10-02", "10-03"]
+files_modified:
+  - apps/pwa/src/api/client.ts
+  - apps/pwa/src/routes/AdminPage.tsx
+  - apps/pwa/src/components/CredentialSheet.tsx
+  - apps/pwa/src/components/SetupBanner.tsx
+  - apps/pwa/src/components/AppNav.tsx
+  - apps/pwa/src/components/BottomTabBar.tsx
+  - apps/pwa/src/App.tsx
+  - apps/pwa/e2e/admin.spec.ts
+autonomous: true
+requirements: [ADMIN-01, ADMIN-02, ADMIN-03]
+must_haves:
+  truths:
+    - "An admin sees an Admin nav entry, reaches /admin, can list members + credential status, rotate a member credential via the sheet, and pick the shared calendar"
+    - "A non-admin never sees the Admin nav entry and is redirected from /admin to /calendar"
+    - "A member with needsProviderSetup=true sees the self-service SetupBanner and can add their own credential via the same sheet (member-scoped)"
+  artifacts:
+    - path: "apps/pwa/src/routes/AdminPage.tsx"
+      provides: "/admin page: Members section + Shared-Calendar picker, wired to /api/admin/*"
+      min_lines: 60
+    - path: "apps/pwa/src/components/CredentialSheet.tsx"
+      provides: "shared credential bottom sheet (admin rotation + self-service), password never pre-filled, CalDAV validation states"
+      min_lines: 50
+    - path: "apps/pwa/src/components/SetupBanner.tsx"
+      provides: "needsProviderSetup self-service onboarding banner (no dismiss; clears on save)"
+      min_lines: 20
+    - path: "apps/pwa/src/api/client.ts"
+      provides: "MeUser.isAdmin + needsProviderSetup; fetchAdminMembers/saveCredential/fetchAdminCalendars/setSharedCalendar/saveMyCredential"
+      contains: "isAdmin"
+  key_links:
+    - from: "apps/pwa/src/App.tsx"
+      to: "AdminPage / Navigate redirect"
+      via: "meQuery.data.user.isAdmin gate on the /admin Route"
+      pattern: "isAdmin"
+    - from: "apps/pwa/src/components/AppNav.tsx"
+      to: "/admin NavLink"
+      via: "conditional render on isAdmin (ShieldCheck icon)"
+      pattern: "ShieldCheck"
+    - from: "apps/pwa/src/components/CredentialSheet.tsx"
+      to: "/api/admin/credentials | /api/me/credential"
+      via: "TanStack mutation, invalidates ['admin','members'] + ['me']"
+      pattern: "invalidateQueries"
+---
+
+<objective>
+Build the React PWA admin surfaces per the 10-UI-SPEC contract: extend the `/api/me` client type + add admin/self-service fetchers, add the gated `/admin` route (D-02: dedicated gated route, not an extension of SettingsSheet) + conditional nav entries, build the shared CredentialSheet (admin rotation + member self-service) and the needsProviderSetup SetupBanner. Verify the route guard and nav gating in a real Chromium browser with playwright-cli (the desktop-Chromium-drivable behaviors), not a human checkpoint.
+
+Purpose: This is the user-facing half of ADMIN-01/02/03 + the D-07 self-service onboarding. The client `isAdmin` flag is consumed for UX gating only per D-03 (server already enforces 403 on every /api/admin/* route from Plan 03); `needsProviderSetup` drives the self-service banner.
+Output: Extended client.ts, AdminPage.tsx, CredentialSheet.tsx, SetupBanner.tsx, nav-entry edits, the /admin route in App.tsx, and an e2e spec.
+</objective>
+
+<execution_context>
+@$HOME/.claude/gsd-core/workflows/execute-plan.md
+@$HOME/.claude/gsd-core/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/10-admin-role-settings/10-CONTEXT.md
+@.planning/phases/10-admin-role-settings/10-UI-SPEC.md
+@.planning/phases/10-admin-role-settings/10-PATTERNS.md
+@.planning/phases/10-admin-role-settings/10-02-SUMMARY.md
+@.planning/phases/10-admin-role-settings/10-03-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="execute">
+  <name>Task 1: Extend client.ts — MeUser fields + admin/self-service fetchers</name>
+  <files>apps/pwa/src/api/client.ts</files>
+  <read_first>
+    - apps/pwa/src/api/client.ts (the file being modified — `MeUser` interface lines 62–66, `handleAuthResponse` lines 51–58, the `createEvent` fetch pattern lines 221–233 with `credentials:'include'`, `redirect:'manual'`, `SessionExpiredError` handling)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/pwa/src/api/client.ts` (the MeUser field additions + the fetch-function pattern to copy from createEvent for each admin/me endpoint) + §Shared Patterns "handleAuthResponse + redirect:'manual'"
+    - .planning/phases/10-admin-role-settings/10-03-SUMMARY.md (the exact /api/admin/* + /api/me/credential request/response shapes shipped by Plan 03 — match them)
+    - .planning/phases/10-admin-role-settings/10-UI-SPEC.md Surface 2 (member-row fields) + Surface 5 (calendar-picker fields)
+  </read_first>
+  <action>
+    In `apps/pwa/src/api/client.ts`: (1) add `isAdmin: boolean` and `needsProviderSetup: boolean` to the `MeUser` interface (D-03: client consumes isAdmin for UX gating only). (2) Add typed fetch functions matching the Plan-03 contracts, each following the `createEvent` idiom (`credentials:'include'`, `redirect:'manual'`, `handleAuthResponse(res, label)`): `fetchAdminMembers()` → GET /api/admin/members; `saveCredential(payload)` → POST /api/admin/credentials (admin, includes userId); `fetchAdminCalendars()` → GET /api/admin/calendars; `setSharedCalendar(calendarId)` → PUT /api/admin/calendars/:id/shared; `saveMyCredential(payload)` → POST /api/me/credential (self-service, NO userId). Define request/response TS types matching the Plan-03 SUMMARY shapes. NEVER store or log the app password client-side beyond the in-flight request body.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa exec tsc --noEmit 2>&1 | tail -8</automated>
+  </verify>
+  <acceptance_criteria>
+    - `MeUser` includes `isAdmin: boolean` and `needsProviderSetup: boolean` (`grep -c "isAdmin\|needsProviderSetup" apps/pwa/src/api/client.ts` >= 2).
+    - All five fetchers exist and use `credentials:'include'` + `redirect:'manual'` + `handleAuthResponse`.
+    - `saveMyCredential`'s payload type has NO `userId` field; `saveCredential`'s does.
+    - `pnpm --filter @familysync/pwa exec tsc --noEmit` exits 0.
+  </acceptance_criteria>
+  <done>client.ts exposes the new MeUser flags + five typed admin/self-service fetchers, typechecks clean.</done>
+</task>
+
+<task type="execute">
+  <name>Task 2: CredentialSheet + SetupBanner components</name>
+  <files>apps/pwa/src/components/CredentialSheet.tsx, apps/pwa/src/components/SetupBanner.tsx</files>
+  <read_first>
+    - apps/pwa/src/components/SettingsSheet.tsx (EXACT analog for CredentialSheet — the bottom-sheet pattern: role="dialog", aria-modal, Escape handler lines 52–76, focus-on-open, backdrop zIndex 300 / sheet zIndex 301 / borderRadius 12px 12px 0 0 / padding var(--space-6), focus-return-to-trigger)
+    - apps/pwa/src/components/PermissionDeniedBanner.tsx (analog for SetupBanner — conditional banner rendered at App level, role/aria-live pattern)
+    - apps/pwa/src/components/DeleteConfirmationDialog.tsx (the minHeight:48px confirm-button precedent referenced in UI-SPEC)
+    - apps/pwa/src/api/client.ts (saveCredential + saveMyCredential from Task 1; SessionExpiredError)
+    - .planning/phases/10-admin-role-settings/10-UI-SPEC.md Surface 3 (credential sheet: heading variants, member subtitle, password field type="password"/autocomplete="new-password"/never pre-filled, helper text + Fastmail app-password link target="_blank" rel="noopener noreferrer", "Validating against CalDAV…" Loader2 spinner, failure copy, Save/Cancel actions) + Surface 4 (self-service banner: KeyRound icon, copy, "Set up now" CTA, no X/dismiss) + the Copywriting Contract (exact strings) + Accessibility Contracts + Color/Typography/Spacing (all via var(--token), 44px touch targets)
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/pwa/src/components/CredentialSheet.tsx` + §`apps/pwa/src/components/SetupBanner.tsx` (structural + mutation + style excerpts) + §Shared Patterns "CSS token inline style pattern"
+  </read_first>
+  <action>
+    Build `CredentialSheet.tsx` (shared by admin rotation AND self-service per D-07) following the SettingsSheet bottom-sheet pattern: props for mode (admin-rotate / admin-add / self-service), target member (admin) or current user (self-service), open/close. Render the heading variant per UI-SPEC Copywriting Contract ("Rotate Credential" / "Add Credential" / "Add your calendar credential"), the member-name subtitle, a `type="password" autoComplete="new-password"` field NEVER pre-filled, the helper text with the Fastmail app-password link (exact URL + copy from UI-SPEC, opens in new tab), the "Validating against CalDAV…" inline state (Loader2 size 16) during the mutation, the failure error copy on a CalDAV 400, and Cancel (ghost) + Save Credential (accent-filled) actions. Use a TanStack `useMutation` that calls `saveCredential` (admin) or `saveMyCredential` (self-service) and on success invalidates `['admin','members']` + `['me']` (so needsProviderSetup refreshes) and closes the sheet. Build `SetupBanner.tsx` following PermissionDeniedBanner: render only when `meQuery.data?.user.needsProviderSetup === true`, `role="status" aria-live="polite"`, KeyRound icon, the exact heading/body/CTA copy, "Set up now" opening the CredentialSheet in self-service mode; NO dismiss button (it clears when needsProviderSetup becomes false). All styling via `var(--token)`; every interactive element minWidth/minHeight 44px. Never log/echo the password.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa exec tsc --noEmit 2>&1 | tail -8 && grep -l "autocomplete=\"new-password\"\|autoComplete=\"new-password\"" apps/pwa/src/components/CredentialSheet.tsx</automated>
+  </verify>
+  <acceptance_criteria>
+    - `CredentialSheet.tsx` uses `role="dialog"`, `aria-modal`, an Escape handler, and a `type="password"` input with `autoComplete="new-password"` that is never pre-filled (no `value={existingPassword}` from any fetched source).
+    - The helper text contains the Fastmail app-password link with `target="_blank"` and `rel="noopener noreferrer"`.
+    - The success mutation invalidates both `['admin','members']` and `['me']` (`grep -c "invalidateQueries" apps/pwa/src/components/CredentialSheet.tsx` >= 2).
+    - `SetupBanner.tsx` renders conditionally on `needsProviderSetup`, uses `role="status"`/`aria-live`, and has NO dismiss/X button.
+    - Exact UI-SPEC Copywriting Contract strings are present (e.g. "Set up your calendar", "Validating against CalDAV…", "Save Credential").
+    - No hard-coded color/spacing px except the 44px/48px touch-target minimums; values reference `var(--...)`.
+    - `pnpm --filter @familysync/pwa exec tsc --noEmit` exits 0.
+  </acceptance_criteria>
+  <done>CredentialSheet (admin + self-service) and SetupBanner match the UI-SPEC contract, accessible, token-styled, typecheck clean.</done>
+</task>
+
+<task type="execute">
+  <name>Task 3: /admin route + AdminPage + conditional nav entries, with playwright-cli verification</name>
+  <files>apps/pwa/src/routes/AdminPage.tsx, apps/pwa/src/App.tsx, apps/pwa/src/components/AppNav.tsx, apps/pwa/src/components/BottomTabBar.tsx, apps/pwa/e2e/admin.spec.ts</files>
+  <read_first>
+    - apps/pwa/src/App.tsx (the Routes block lines 121–127, the meQuery lines 63–68, the content-area style lines 99–102, where PermissionDeniedBanner-style banners mount — SetupBanner mounts here too)
+    - apps/pwa/src/routes/ListsIndex.tsx (page-level component analog for AdminPage: TanStack Query + sections layout)
+    - apps/pwa/src/components/AppNav.tsx (NavLink + Lucide pattern lines 14–15, the DesktopNav section) + apps/pwa/src/components/BottomTabBar.tsx (tab pattern lines 27–98) — add the conditional Admin entry (ShieldCheck) to both
+    - apps/pwa/e2e/calendar.spec.ts + layout.spec.ts + e2e/README.md (existing spec idioms, selectors, the dev-bypass admin user seeded in global-setup as id=1 is_admin=true from Plan 01)
+    - .claude/skills/playwright-cli/SKILL.md (how to drive the global playwright-cli binary for the browser verification)
+    - .planning/phases/10-admin-role-settings/10-UI-SPEC.md Surface 1 (/admin page: AppNav persistent, ShieldCheck size 18, content maxWidth 640px centered desktop, var(--space-12) vertical padding, "Admin Settings" heading) + Surface 2 (Members section) + Surface 5 (Shared Calendar picker: radio group, "Currently shared" label, two-tap Save, empty state) + Copywriting Contract
+    - .planning/phases/10-admin-role-settings/10-PATTERNS.md §`apps/pwa/src/routes/AdminPage.tsx` + §`apps/pwa/src/App.tsx` + §Shared Patterns "NavLink + Lucide icon"
+  </read_first>
+  <action>
+    Build `AdminPage.tsx` (analog ListsIndex): "Admin Settings" heading (18px/600), a MEMBERS section listing members from `fetchAdminMembers` (avatar swatch + name + credential status badge per UI-SPEC Surface 2 + a "Rotate"/"Add credential" button opening CredentialSheet in admin mode for that member), and a SHARED CALENDAR section (Surface 5) using `fetchAdminCalendars`: an exclusive single-select radio group (D-06), the "Currently shared" label on the active one, a two-tap "Save" button (disabled until selection differs) calling `setSharedCalendar`, and the empty state ("No calendars synced yet") when none synced. Desktop: centered column maxWidth 640px. In `App.tsx`: add the `/admin` Route (D-02: new dedicated gated route) gated by `meQuery.data?.user.isAdmin ? <AdminPage/> : <Navigate to="/calendar" replace/>` — the client redirect is UX-only per D-03 (the server-side 403 from Plan 03 is the real boundary); add a loading gate so an in-flight meQuery doesn't flash-redirect (planner's call per 10-PATTERNS.md note); mount `<SetupBanner/>` above the calendar content (renders only on needsProviderSetup). In `AppNav.tsx` (desktop) and `BottomTabBar.tsx` (mobile): add an Admin entry (ShieldCheck icon, `aria-label="Admin settings"`) rendered ONLY when `meQuery.data?.user.isAdmin === true` (D-03 UX gating). Write `apps/pwa/e2e/admin.spec.ts`: with the dev-bypass admin user (seeded id=1 is_admin=true), assert the Admin nav entry is visible and /admin renders "Admin Settings" + the Members section. Add a non-admin assertion by route-mocking GET /api/me to `isAdmin:false` (per [[dev-data-user1-no-calendars]] route-mock idiom and the lists.spec page.route precedent) and asserting the Admin nav entry is absent and /admin redirects to /calendar. THEN run a playwright-cli browser check against the dev stack to confirm the guard + nav gating + sheet open behaviors interactively (use the playwright-cli skill — this replaces a human-verify checkpoint since it is desktop-Chromium-drivable per CLAUDE.md). All styling via `var(--token)`; 44px touch targets.
+  </action>
+  <verify>
+    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa exec tsc --noEmit 2>&1 | tail -6 && pnpm --filter @familysync/pwa test:e2e -- admin 2>&1 | tail -20</automated>
+  </verify>
+  <acceptance_criteria>
+    - `apps/pwa/src/App.tsx` has a `/admin` Route gated on `meQuery.data?.user.isAdmin` with a `<Navigate to="/calendar" replace/>` fallback for non-admins, and mounts `<SetupBanner/>`.
+    - `AppNav.tsx` and `BottomTabBar.tsx` render the Admin entry (ShieldCheck, `aria-label="Admin settings"`) ONLY when isAdmin is true (`grep -c "ShieldCheck" apps/pwa/src/components/AppNav.tsx apps/pwa/src/components/BottomTabBar.tsx` >= 2).
+    - `AdminPage.tsx` renders "Admin Settings", a MEMBERS list, and a SHARED CALENDAR exclusive radio group with a two-tap Save and an empty state.
+    - `apps/pwa/e2e/admin.spec.ts` asserts: admin sees the nav entry + reaches /admin; a non-admin (route-mocked isAdmin:false) does NOT see it and /admin redirects to /calendar.
+    - `pnpm --filter @familysync/pwa test:e2e -- admin` passes; the playwright-cli interactive check confirms the guard + nav gating (recorded in the SUMMARY).
+    - `pnpm --filter @familysync/pwa exec tsc --noEmit` exits 0.
+  </acceptance_criteria>
+  <done>/admin route gated, AdminPage wired to the admin API, conditional nav entries + SetupBanner mounted, e2e + playwright-cli verification green.</done>
+</task>
+
+</tasks>
+
+<artifacts_this_phase_produces>
+New symbols/files created by this plan (excluded from drift verification):
+- `MeUser.isAdmin` + `MeUser.needsProviderSetup` fields in `apps/pwa/src/api/client.ts`
+- fetchers `fetchAdminMembers`, `saveCredential`, `fetchAdminCalendars`, `setSharedCalendar`, `saveMyCredential`
+- `apps/pwa/src/routes/AdminPage.tsx`
+- `apps/pwa/src/components/CredentialSheet.tsx`
+- `apps/pwa/src/components/SetupBanner.tsx`
+- `/admin` Route + isAdmin gate + `<SetupBanner/>` mount in `apps/pwa/src/App.tsx`
+- conditional Admin nav entry (ShieldCheck) in `apps/pwa/src/components/AppNav.tsx` + `apps/pwa/src/components/BottomTabBar.tsx`
+- `apps/pwa/e2e/admin.spec.ts`
+</artifacts_this_phase_produces>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| browser isAdmin flag → UI gating | the client isAdmin flag controls nav/route visibility only; it is NOT the security boundary |
+| credential sheet → API | the app password is entered in the browser and sent to /api/admin/credentials or /api/me/credential over the in-flight request only |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-10-14 | Elevation of Privilege | a non-admin bypassing the client route guard (e.g. typing /admin) | accept | The client redirect is UX (D-03); the real boundary is the server-side 403 on every /api/admin/* request (Plan 03). A non-admin who forces /admin sees no data — all admin fetches return 403. e2e asserts the redirect anyway |
+| T-10-15 | Information Disclosure | app password persisted/echoed client-side | mitigate | Password field never pre-filled, never written to localStorage/state beyond the in-flight mutation; no console.log of the value (acceptance: never pre-filled) |
+| T-10-16 | Information Disclosure | password autofilled with the current credential | mitigate | autoComplete="new-password" (never "current-password"); the existing credential is never fetched to the client |
+| T-10-SC | Tampering | npm/pip/cargo installs | mitigate | No new packages this phase (lucide-react already at 1.17.0 per RESEARCH Package Legitimacy Audit); no install task |
+</threat_model>
+
+<verification>
+- `pnpm --filter @familysync/pwa exec tsc --noEmit` passes.
+- `pnpm --filter @familysync/pwa test:e2e -- admin` passes (admin sees nav + /admin; non-admin redirected, no nav entry).
+- playwright-cli interactive check confirms the guard + nav gating + sheet open (recorded in SUMMARY).
+- Run the full CI fast-checks gate locally before declaring done (lint + typecheck + test + format:check + md:lint + PWA tests) per [[feedback-run-full-ci-gate-before-push]].
+</verification>
+
+<success_criteria>
+- Admin sees the Admin section, lists members + credential status, rotates a credential via the sheet, picks the shared calendar (Success Criteria 1, 2, 3).
+- Non-admin never sees the entry and is redirected from /admin (Success Criterion 1; client-side UX over the server 403).
+- needsProviderSetup member sees the SetupBanner and can self-serve their own credential (D-07).
+</success_criteria>
+
+<output>
+Create `.planning/phases/10-admin-role-settings/10-04-SUMMARY.md` when done.
+</output>

.planning/phases/10-admin-role-settings/10-CONTEXT.md

@@ -1,6 +1,7 @@
 # Phase 10: Admin Role & Settings - Context
 
 **Gathered:** 2026-06-12
+**Updated:** 2026-06-13 — folded backlog 999.5 self-service onboarding INTO scope (D-07), reconciling with the ROADMAP fold (commit bcc9682, 2026-06-11). The original discuss-phase had listed it as deferred without accounting for that ROADMAP edit.
 **Status:** Ready for planning
 
 <domain>
@@ -14,8 +15,9 @@ Phase 10 introduces an admin role and the role-gated Admin Settings surface, and
 - **Admin role (ADMIN-03):** a role check gating admin routes/UI; non-admins cannot reach or invoke them. First-login-wins bootstrap (see D-01).
 - **App-password / credential management (ADMIN-01):** an admin can view household members and rotate / re-enter a member's provider credential from the UI; validated against the provider (CalDAV PROPFIND for Fastmail) before saving, stored encrypted via the existing `crypto.ts` / `APP_PASSWORD_ENCRYPTION_KEY` path; never displayed, logged, or echoed.
 - **Shared-calendar designation (ADMIN-02):** an admin picks which synced calendar is the shared family calendar (`calendars.is_shared`) from the UI, replacing the manual DB write.
+- **Self-service credential onboarding (folded from backlog 999.5):** a member with no `member_credentials` row gets a `needsProviderSetup` signal and can enter / validate (CalDAV PROPFIND) / encrypt their **own** Fastmail app password on first login — the member-scoped counterpart of the admin-managed flow (see D-07), reusing the same validate→encrypt→initial-sync path. Member-scoped: a member can only set their own credential.
 
-**NOT in this phase:** the Phase 12 setup wizard itself; per-event reminder UI/scheduling (Phase 11); full multi-provider support (backlog 999.1 — only the generic *shape* lands here, Fastmail/CalDAV is the only implemented provider); self-service credential onboarding (backlog 999.5).
+**NOT in this phase:** the Phase 12 setup wizard itself; per-event reminder UI/scheduling (Phase 11); full multi-provider support (backlog 999.1 — only the generic *shape* lands here, Fastmail/CalDAV is the only implemented provider). *(Self-service onboarding from backlog 999.5 is folded IN — see the Delivers bullet above and D-07.)*
 </domain>
 
 <decisions>
@@ -37,6 +39,9 @@ Phase 10 introduces an admin role and the role-gated Admin Settings surface, and
 ### Shared-calendar designation (ADMIN-02)
 - **D-06: Exclusive single-select.** The admin picks exactly one synced calendar as the shared family calendar. Setting a new one clears `is_shared` on any prior shared calendar (single shared calendar, matching the core value). Picker lists the synced calendars; selection is a radio/toggle, not independent multi-toggles.
 
+### Self-service credential onboarding (ADMIN-01 / folded from backlog 999.5)
+- **D-07: Member self-service credential, member-scoped.** A member with no provider credential gets a `needsProviderSetup` signal (no `member_credentials` row) and can enter / validate (CalDAV PROPFIND) / encrypt their **own** Fastmail app password — the self-service counterpart to the admin-managed rotation (D-05), sharing the identical validate→encrypt→initial-sync path. A member can set ONLY their own credential; the cross-member rotation stays admin-only (D-05). Non-technical-friendly instructions are a **hard UX constraint**: link to Fastmail's app-password page and name the required Calendars/CalDAV scope. Never log/echo the password. Folded in per the ROADMAP edit (commit bcc9682). Reuses the same generic provider shape as D-04 (Fastmail/CalDAV only; no second provider here).
+
 ### Claude's Discretion
 - **Migration packaging:** ship the full v1.1 column/table bundle (`is_admin`, `app_config`, `reminder_lead_minutes`) in one Phase-10 migration per the ROADMAP note, so Phases 11/12 don't each carry their own migration. Use `drizzle-kit generate` + `migrate` — never `push` (see [[drizzle-mariadb-push-unsafe]]).
 - **`app_config` shape:** create the table now with at least a `setup_complete` flag (Phase 12). Add other global keys only as Phase 10 actually needs them; keep it a simple key/value or single-row config — planner's call.
@@ -92,6 +97,7 @@ Phase 10 introduces an admin role and the role-gated Admin Settings surface, and
 - `upsertUser` (`auth/user.ts`) → first-login-wins flag write.
 - `calendars.is_shared` write moves from manual DB edit to the ADMIN-02 endpoint; the calendar legend / shared-calendar consumers already read `is_shared`.
 - `app_config.setup_complete` → consumed by Phase 12; `calendar_events.reminder_lead_minutes` → consumed by Phase 11.
+- `needsProviderSetup` signal (member has no `member_credentials` row) → surfaced to the PWA (e.g. on `/api/me` or a dedicated endpoint — planner's call) to drive the member self-service onboarding entry (D-07); reuses the admin flow's validate→encrypt→initial-sync path, member-scoped.
 
 </code_context>
 
@@ -107,7 +113,7 @@ Phase 10 introduces an admin role and the role-gated Admin Settings surface, and
 ## Deferred Ideas
 
 - **Full multi-provider support (Gmail/other)** — backlog 999.1. Phase 10 lands only the generic credential *shape*; actual additional providers + their validation are 999.1.
-- **Self-service credential onboarding** (a member adds their own app password on first login) — backlog 999.5; Phase 10 is admin-managed only.
+- ~~**Self-service credential onboarding**~~ — **folded INTO this phase** (D-07) per the ROADMAP edit (commit bcc9682, 2026-06-11); no longer deferred. The original discuss-phase listed it as deferred without accounting for that ROADMAP fold; reconciled 2026-06-13.
 - **Admin audit log / health dashboard / user CRUD** — explicitly out of scope per REQUIREMENTS.md (scope creep for a small self-hosted app).
 - **Multiple reminders per event** — v1.2 stretch (noted in REQUIREMENTS.md, unrelated to Phase 10).
 

.planning/phases/10-admin-role-settings/10-RESEARCH.md

@@ -0,0 +1,762 @@
+# Phase 10: Admin Role & Settings - Research
+
+**Researched:** 2026-06-13
+**Domain:** Role-gated admin API (Hono sub-router + middleware), Drizzle v1.1 DB migration, encrypted credential rotation (CalDAV PROPFIND), member self-service onboarding, React PWA gated route
+**Confidence:** HIGH
+
+---
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+
+- **D-01: First-login-wins.** When no admin exists, the first user to log in is flagged `is_admin=true`. Member-count-agnostic per-user boolean. Phase 12 interaction: tightened to "first user after `app_config.setup_complete`" (Phase 12 owns that gating, Phase 10 ships the column and the bootstrap logic). Dev note: under `DEV_AUTH_BYPASS`, `DEV_USER` (id 1) is injected without a DB upsert — must decide and document how bypass user acquires `is_admin` for local admin-UI verification.
+- **D-02: New `/admin` route.** A dedicated gated route, not an extension of the existing notifications `SettingsSheet`. An `is_admin` guard redirects non-admins away.
+- **D-03: Expose `isAdmin` on `/api/me`.** PWA uses it for UX gating only; server enforces the role on every `/api/admin/*` route (ADMIN-03 is always server-side).
+- **D-04: Generic provider shape, Fastmail-only implementation.** Provider/type discriminator on the credential model. No second provider built here; Gmail/other providers are wiring for backlog 999.1.
+- **D-05: Per-member provider credential.** `member_credentials` stays per-user. An admin can rotate ANY member's credential. Reuse existing `crypto.ts` encryption path.
+- **D-06: Exclusive single-select shared-calendar designation.** Setting a new shared calendar clears `is_shared` on any prior shared calendar. Radio/toggle, not independent multi-toggles.
+- **D-07: Member self-service credential, member-scoped.** A member with no `member_credentials` row gets a `needsProviderSetup` signal. They can enter/validate (CalDAV PROPFIND)/encrypt their OWN Fastmail app password, sharing the identical validate→encrypt→initial-sync path as admin rotation. Cross-member rotation stays admin-only.
+
+### Claude's Discretion
+
+- **Migration packaging:** ship `is_admin`, `app_config`, `reminder_lead_minutes` in one Phase-10 migration (generate+migrate, never push).
+- **`app_config` shape:** create with at least `setup_complete` flag for Phase 12. Simple key/value or single-row config — planner's call.
+- **`/api/admin/*` route layout:** sub-routes for members/credentials and shared-calendar — planner decides exact paths following existing `routes/*.ts` Hono pattern.
+- **Server-side `requireAdmin` guard shape** — planner's call.
+
+### Deferred Ideas (OUT OF SCOPE)
+
+- **Full multi-provider support (Gmail/other)** — backlog 999.1. Phase 10 lands only the generic credential *shape*.
+- **Admin audit log / health dashboard / user CRUD** — explicitly out of scope per REQUIREMENTS.md.
+- **Multiple reminders per event** — v1.2 stretch (unrelated to Phase 10).
+</user_constraints>
+
+---
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| ADMIN-01 | Admin can view household members and update (rotate/re-enter) a member's Fastmail app password from the UI; validated against CalDAV (PROPFIND) before saving; stored encrypted; never displayed, logged, or echoed. | Credential rotation path, `encryptPassword`, `createFastmailClient`+`fetchCalendars` PROPFIND validation, Zod hook Pitfall 7, self-service counterpart (D-07) |
+| ADMIN-02 | Admin can designate which synced calendar is the shared family calendar (`calendars.is_shared`) from the UI, replacing the manual DB write. | Exclusive `is_shared` update via `drizzle-orm` `db.update`, calendar list endpoint |
+| ADMIN-03 | Admin Settings routes and UI are gated by a role check; a non-admin member cannot reach or invoke them. | `requireAdmin` sub-router middleware (Pitfall 9), `users.is_admin` column, `isAdmin` on `/api/me` |
+</phase_requirements>
+
+---
+
+## Summary
+
+Phase 10 is primarily an API-plus-UI phase: it ships the v1.1 DB migration (three new columns/tables), builds a role-gated `adminRouter` behind `requireAdmin` middleware, exposes two API surfaces (`/api/admin/credentials` for ADMIN-01 and `/api/admin/calendars/:id/shared` for ADMIN-02), and adds a `/admin` route to the React PWA. It also delivers member self-service credential onboarding (D-07) — a member-scoped counterpart sharing the same validate→encrypt→initial-sync path.
+
+The technical approach is well-defined by existing code. `encryptPassword` and `decryptPassword` in `broker/crypto.ts` are used verbatim. Credential validation reuses `createFastmailClient` + `client.fetchCalendars()` (a CalDAV PROPFIND) — the same path the poller and `triggerTargetedResync` already use. The initial-sync after save reuses `triggerTargetedResync` (already extracted in `outboxWorker.ts`). The Drizzle migration workflow is `db:generate` then `db:migrate` (documented in `package.json` scripts); the existing `drizzle.config.ts` and `migrations/` directory are ready for a second migration file.
+
+The single biggest implementation subtlety is Pitfall 7 (password never echoed): the `@hono/zod-validator` `hook` must return `c.json({ error: 'Invalid request' }, 400)` with NO `received` / `value` fields from Zod's error output, and no `console.log` of request bodies anywhere in admin routes. Pitfall 9 (admin guard inside the sub-router) is mechanically straightforward: call `adminRouter.use('*', requireAdmin)` as the first statement of the adminRouter so the guard applies before any route handler runs.
+
+**Primary recommendation:** Build `apps/api/src/routes/admin.ts` as a new Hono sub-router, mount it on `/api/admin` in `index.ts` after the existing auth guards, apply `requireAdmin` with `.use('*', ...)` inside the router, then add the two admin API surfaces plus a member-credential-status endpoint. The self-service credential endpoint lives on `/api/me/credential` (member-scoped). One drizzle-kit migration adds all three v1.1 schema items in a single file.
+
+---
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| DB migration (is_admin, app_config, reminder_lead_minutes) | Database / Storage | — | Schema change; drizzle-kit owns it |
+| Admin role check enforcement | API / Backend | — | Server always enforces; client flag is UX-only |
+| isAdmin signal on /api/me | API / Backend | Browser / Client | Server writes; PWA reads for nav gating |
+| needsProviderSetup signal | API / Backend | Browser / Client | Server knows if member_credentials row exists |
+| First-login-wins admin bootstrap | API / Backend | — | `upsertUser` in `auth/user.ts`; never client-side |
+| DEV_AUTH_BYPASS admin acquisition | API / Backend | — | Seed or bypass flag in `devBypass.ts` / DB seed |
+| Credential validation (CalDAV PROPFIND) | API / Backend | — | Never client-side; credentials never sent to browser |
+| Credential encryption/storage | API / Backend | Database / Storage | `crypto.ts` + `member_credentials` row |
+| Shared-calendar exclusive write | API / Backend | Database / Storage | `calendars.is_shared` single-row transaction |
+| /admin React route + gating | Browser / Client | — | react-router gated by `meQuery.data?.isAdmin` |
+| Credential sheet UI | Browser / Client | — | Forms, validation UX, provider help text |
+| Shared calendar picker UI | Browser / Client | — | Radio group, save button |
+| Self-service onboarding banner | Browser / Client | — | Dismissal tied to needsProviderSetup becoming false |
+| Admin nav entry (conditional) | Browser / Client | — | Rendered only when isAdmin = true |
+
+---
+
+## Standard Stack
+
+No new npm packages are required for this phase. All libraries are already installed. The phase reuses the existing stack exclusively.
+
+### Core (already installed)
+| Library | Installed Version | Purpose | Why |
+|---------|-----------------|---------|-----|
+| hono | 4.12.23 | HTTP framework, sub-router, middleware | Already in use |
+| @hono/zod-validator | 0.8.0 | Zod validation middleware with hook support | Already in use |
+| zod | 3.25.x | Schema validation | Already in use |
+| drizzle-orm | 0.45.2 | MariaDB query layer | Already in use |
+| drizzle-kit | 0.31.10 | Migration generation + execution | Already in use |
+| mysql2 | 3.22.4 | MariaDB driver | Already in use |
+| tsdav | 2.2.2 | CalDAV PROPFIND client (credential validation) | Already in use |
+| react + react-router | 19.x / 7.x | PWA routing for /admin | Already in use |
+| lucide-react | 1.17.0 | Icons (ShieldCheck, KeyRound, etc.) | Already in use |
+| @tanstack/react-query | 5.101.0 | /api/me and /api/admin/* data fetching | Already in use |
+
+### Package Legitimacy Audit
+
+> No new packages are introduced in this phase. All packages listed below were already installed prior to Phase 10.
+
+| Package | Registry | Verdict | Disposition |
+|---------|----------|---------|-------------|
+| hono | npm | OK (SUS flag only because very recent publish; 44M/wk downloads) | Approved — already installed |
+| @hono/zod-validator | npm | OK | Approved — already installed |
+| drizzle-orm | npm | OK | Approved — already installed |
+| drizzle-kit | npm | OK | Approved — already installed |
+| lucide-react | npm | SUS (recent publish; 84M/wk downloads — established package) | Approved — already installed |
+
+**Packages removed due to SLOP verdict:** none
+**Packages flagged as suspicious [SUS]:** `hono` and `lucide-react` flagged only due to recent version publish date; both are established packages with very high download counts and known source repos. No new installs required; risk is negligible since they are already in the lockfile.
+
+---
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+Browser (React PWA)
+  │  GET /api/me → { user: { id, displayName, color, isAdmin, needsProviderSetup } }
+  │  meQuery.data.isAdmin → render Admin NavLink / BottomTab
+  │  /admin route mounted in BrowserRouter (gated by isAdmin redirect on mount)
+  │
+  │  Admin surfaces:
+  │    GET  /api/admin/members          → list members + credential status
+  │    POST /api/admin/credentials      → validate + encrypt + store credential for any member
+  │    GET  /api/admin/calendars        → list synced calendars
+  │    PUT  /api/admin/calendars/:id/shared → set exclusive is_shared flag
+  │
+  │  Self-service surface (member-scoped):
+  │    POST /api/me/credential          → validate + encrypt + store OWN credential only
+  │
+  ▼
+Hono API (apps/api/src)
+  ├── /api/* ── devAuthBypass() → oidcAuthMiddleware() [existing]
+  ├── /api/me  ── meRouter [modified: add isAdmin + needsProviderSetup]
+  │     upsertUser() → now also writes is_admin on first login (first-login-wins)
+  ├── /api/admin/* ── adminRouter [NEW]
+  │     adminRouter.use('*', requireAdmin)  ← Pitfall 9: guard INSIDE the sub-router
+  │     GET  /members          → SELECT users LEFT JOIN member_credentials
+  │     POST /credentials      → zValidator(hook: no-echo) → PROPFIND → encryptPassword → upsert
+  │     GET  /calendars        → SELECT calendars WHERE is_shared known
+  │     PUT  /calendars/:id/shared → exclusive UPDATE (clear others, set one)
+  └── /api/me/credential [NEW, member-scoped self-service]
+        → same validate→encrypt→initial-sync path; userId always currentUser.id
+  
+DB (MariaDB via Drizzle)
+  ├── users.is_admin BOOLEAN NOT NULL DEFAULT false        [v1.1 migration]
+  ├── app_config table (key VARCHAR PK, value TEXT)        [v1.1 migration]
+  ├── calendar_events.reminder_lead_minutes INT NULL        [v1.1 migration]
+  ├── member_credentials.provider_type VARCHAR DEFAULT 'caldav' [v1.1 schema add]
+  └── calendars.is_shared — already exists at schema line 89
+  
+broker/
+  ├── crypto.ts   encryptPassword / decryptPassword    [REUSE, no changes]
+  ├── client.ts   createFastmailClient                 [REUSE, no changes]
+  └── outboxWorker.ts  triggerTargetedResync           [REUSE for initial-sync after save]
+```
+
+### Recommended Project Structure
+
+```
+apps/api/src/
+├── auth/
+│   ├── user.ts          # upsertUser — add is_admin first-login-wins logic
+│   └── devBypass.ts     # DEV_USER — seed is_admin=true or add flag
+├── db/
+│   ├── schema.ts        # add is_admin, app_config table, reminder_lead_minutes, provider_type
+│   └── migrations/
+│       └── 0001_v1_1_foundation.sql  # generated by drizzle-kit generate
+├── routes/
+│   ├── me.ts            # add isAdmin + needsProviderSetup to response
+│   └── admin.ts         # NEW: adminRouter with requireAdmin guard
+└── lib/
+    └── requireAdmin.ts  # NEW: MiddlewareHandler that checks c.get('user').isAdmin
+
+apps/pwa/src/
+├── App.tsx              # add /admin <Route> + gated redirect
+├── api/client.ts        # add isAdmin + needsProviderSetup to MeUser interface
+├── routes/
+│   └── AdminPage.tsx    # NEW: /admin page shell
+└── components/
+    ├── AppNav.tsx        # add conditional Admin NavLink (ShieldCheck icon)
+    ├── BottomTabBar.tsx  # add conditional Admin tab
+    ├── CredentialSheet.tsx  # NEW: shared sheet for admin + self-service
+    └── SetupBanner.tsx   # NEW: needsProviderSetup dismissable banner
+```
+
+### Pattern 1: requireAdmin Middleware Inside adminRouter (Pitfall 9)
+
+**What:** Apply `requireAdmin` as `.use('*', requireAdmin)` as the FIRST call on the adminRouter — NOT only at the parent mount in `index.ts`. This ensures the guard executes for every route on the sub-router and cannot be accidentally bypassed by mounting order.
+
+**When to use:** Every `/api/admin/*` route.
+
+**Example:**
+```typescript
+// Source: Hono docs /websites/hono_dev — sub-router middleware pattern
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+
+// requireAdmin: reads c.get('user') (the same key devAuthBypass and the OIDC path set),
+// checks is_admin on the resolved DB user, returns 403 if not admin.
+// Must NOT log credentials or user claims.
+export const requireAdmin: MiddlewareHandler = async (c, next) => {
+  const user = c.get('user');
+  // Under DEV_AUTH_BYPASS, user.id is DEV_USER.id (1); look up is_admin from DB.
+  // Under OIDC, user comes from c.get('user') set by the existing resolveUserId pattern.
+  // Pull is_admin from the DB users row for the current user id.
+  const row = await db.select({ isAdmin: users.isAdmin })
+    .from(users)
+    .where(eq(users.id, user.id))
+    .limit(1);
+  if (!row[0]?.isAdmin) {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+  await next();
+};
+
+// In apps/api/src/routes/admin.ts:
+export const adminRouter = new Hono();
+adminRouter.use('*', requireAdmin);  // FIRST — guards all sub-routes
+adminRouter.get('/members', async (c) => { ... });
+adminRouter.post('/credentials', zValidator('json', credentialSchema, hook), async (c) => { ... });
+// ...
+
+// In apps/api/src/index.ts (after existing auth guards):
+app.route('/api/admin', adminRouter);
+```
+
+[CITED: https://hono.dev/docs/guides/best-practices — sub-router pattern; [CITED: 10-CONTEXT.md Pitfall 9]
+
+### Pattern 2: Zod Validator Hook — No Password Echo (Pitfall 7)
+
+**What:** The `@hono/zod-validator` `hook` callback intercepts validation failures. Return a generic 400 response with NO `issues`, `received`, or `value` fields — this prevents the submitted password from being reflected back in the error response body or logs.
+
+**When to use:** Every route that accepts a credential (app password) field in the request body.
+
+**Example:**
+```typescript
+// Source: honojs/middleware README — zValidator hook pattern [CITED: https://github.com/honojs/middleware/blob/main/packages/zod-validator/README.md]
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+
+const credentialSchema = z.object({
+  userId: z.number().int().positive(),
+  providerType: z.literal('caldav'),
+  fastmailEmail: z.string().email(),
+  appPassword: z.string().min(1).max(500),
+});
+
+// The hook MUST return a response that never echoes .error.issues (which contains `received`)
+// and never logs the body. Return a generic message only.
+const noEchoHook = (result: SafeParseReturnType<unknown, unknown>, c: Context) => {
+  if (!result.success) {
+    // NEVER: return c.json(result.error, 400)  — that echoes the password
+    // NEVER: console.log(result)
+    return c.json({ error: 'Invalid request' }, 400);
+  }
+};
+
+adminRouter.post(
+  '/credentials',
+  zValidator('json', credentialSchema, noEchoHook),
+  async (c) => {
+    const { userId, fastmailEmail, appPassword } = c.req.valid('json');
+    // appPassword is NEVER logged here — no console.log(c.req.valid('json'))
+    // validate → encrypt → store
+  }
+);
+```
+
+[CITED: https://github.com/honojs/middleware/blob/main/packages/zod-validator/README.md]
+
+### Pattern 3: Drizzle-Kit Generate + Migrate Workflow
+
+**What:** `pnpm --filter @familysync/api db:generate` generates a new `.sql` migration file in `apps/api/src/db/migrations/`. `pnpm --filter @familysync/api db:migrate` applies pending migrations. NEVER run `drizzle-kit push` on a populated MariaDB — it emits false destructive diffs.
+
+**When to use:** Every schema change. This phase ships one migration bundling all three v1.1 items.
+
+**Existing workflow (from codebase):**
+```bash
+# 1. Edit apps/api/src/db/schema.ts (add is_admin, app_config table, reminder_lead_minutes, provider_type)
+# 2. Generate the migration SQL
+cd apps/api && pnpm db:generate
+# → creates apps/api/src/db/migrations/0001_v1_1_foundation.sql
+#   and updates apps/api/src/db/migrations/meta/_journal.json
+
+# 3. Apply to local dev MariaDB (DB_HOST=127.0.0.1 from dev compose override)
+cd apps/api && DB_HOST=127.0.0.1 DB_USER=... DB_PASSWORD=... DB_NAME=... pnpm db:migrate
+# → runs the new migration against the populated DB
+
+# 4. Verify applied
+# MariaDB: SHOW COLUMNS FROM users; SHOW TABLES; 
+# Confirm: is_admin column on users, app_config table, reminder_lead_minutes on calendar_events
+```
+
+[VERIFIED: codebase — apps/api/package.json scripts.db:generate and scripts.db:migrate; apps/api/drizzle.config.ts]
+
+Note: `drizzle.config.ts` reads DB credentials from env at runtime. In CI (Gitea), the `api` job already runs `pnpm db:migrate` via the existing `drizzle-kit migrate` step — Phase 10's new migration file is picked up automatically by the journal.
+
+### Pattern 4: Validate → Encrypt → Initial-Sync (Shared Code Path)
+
+**What:** The exact sequence for both admin credential rotation (D-05) and member self-service (D-07).
+
+**Signature (from existing codebase):**
+```typescript
+// Step 1: Validate credential against CalDAV (PROPFIND)
+// Source: apps/api/src/broker/client.ts createFastmailClient
+// Source: apps/api/src/broker/poller.ts — client.fetchCalendars() is the PROPFIND
+import { createFastmailClient } from '../broker/client.js';
+
+async function validateCredential(email: string, password: string): Promise<boolean> {
+  try {
+    const client = await createFastmailClient(email, password);
+    await client.fetchCalendars();  // throws if auth fails
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Step 2: Encrypt and store
+// Source: apps/api/src/broker/crypto.ts encryptPassword
+import { encryptPassword } from '../broker/crypto.js';
+
+const encrypted = encryptPassword(appPassword);
+// INSERT OR UPDATE member_credentials SET encrypted_password=encrypted, fastmail_email=email
+// Use Drizzle onDuplicateKeyUpdate for upsert pattern (matching existing schema)
+
+// Step 3: Trigger initial sync for the member
+// Source: apps/api/src/broker/outboxWorker.ts triggerTargetedResync
+// That function is private to outboxWorker.ts — extract it to a shared broker utility
+// OR: call the poller's runPoll path via a targeted helper.
+// Simplest approach: call syncCalendar directly after credential save,
+// using the same client+davCalendars flow from poller.ts runPoll.
+// (The outboxWorker already has triggerTargetedResync — promote it to exported or duplicate the pattern.)
+```
+
+[VERIFIED: codebase — apps/api/src/broker/crypto.ts, apps/api/src/broker/client.ts, apps/api/src/broker/outboxWorker.ts:271-348]
+
+**Initial sync after credential save:** `triggerTargetedResync` in `outboxWorker.ts` (lines 302–348) is the canonical post-save sync path. It calls `loadClientForUser`, `client.fetchCalendars()`, then `syncCalendar`. For admin routes, this function is currently private; the planner must either:
+- Export it from `outboxWorker.ts`, or
+- Extract the logic to a new `broker/credentialSync.ts` shared helper.
+The self-service path (member sets own credential) and the admin rotation path call the same function.
+
+### Pattern 5: First-Login-Wins Admin Bootstrap
+
+**What:** In `upsertUser` (`auth/user.ts`), after the `existing[0]` early-return path but before the INSERT, check if zero admin users exist. If yes, set `is_admin=true` on the new user. This is the hook point that Phase 12 will extend by also checking `app_config.setup_complete`.
+
+**Phase-12-safe implementation:**
+```typescript
+// In upsertUser, after color assignment, before INSERT:
+// "first user when zero admins exist" — Phase 12 tightens to "first user after setup_complete"
+// by adding AND(eq(appConfig.setupComplete, true)) to the zero-admin check.
+// Phase 10: simply check for zero existing admins.
+const adminCount = await db.select({ count: sql<number>`COUNT(*)` })
+  .from(users).where(eq(users.isAdmin, true));
+const shouldBeAdmin = adminCount[0].count === 0;
+// Then INSERT with isAdmin: shouldBeAdmin
+```
+
+[VERIFIED: codebase — apps/api/src/auth/user.ts upsertUser function (lines 76–128); existing pattern extended]
+
+**DEV_AUTH_BYPASS user-1 admin acquisition:** `DEV_USER` (id 1) is injected without a DB upsert (see `devBypass.ts` + `me.ts` short-circuit). Options:
+1. **Recommended (seed):** `tests/global-setup.ts` already seeds the dev MariaDB; add `UPDATE users SET is_admin=1 WHERE id=1` to the seed if user 1 exists, or ensure the seed creates user 1 with `is_admin=true`. This is the cleanest because it matches the real DB state.
+2. **Alt (bypass flag):** The `requireAdmin` middleware checks `users.isAdmin` from the DB. For the bypass user (id=1), the DB row already exists from seeding (Phase 7 global-setup). A seed approach makes the bypass admin status durable across restarts without code path changes to `requireAdmin`.
+
+The bypass path short-circuits in `me.ts` before `upsertUser` — `/api/me` returns DEV_USER directly. `requireAdmin` must still look up `users.isAdmin` from the DB for the bypass user; the bypass only skips OIDC, not the DB lookup.
+
+### Pattern 6: Provider Discriminator on member_credentials
+
+**What:** Add a `provider_type` column to `member_credentials` to support the generic shape (D-04). Default `'caldav'` for all existing rows. This makes the model N-provider ready without breaking the existing data.
+
+**Schema addition (in schema.ts):**
+```typescript
+// In memberCredentials table, add:
+providerType: varchar('provider_type', { length: 64 }).notNull().default('caldav'),
+// Existing columns: userId, encryptedPassword, fastmailEmail — all unchanged
+```
+
+The Drizzle migration will `ALTER TABLE member_credentials ADD COLUMN provider_type VARCHAR(64) NOT NULL DEFAULT 'caldav'` — safe on populated MariaDB because it has a default value.
+
+[VERIFIED: codebase — apps/api/src/db/schema.ts memberCredentials table (lines 55–69)]
+
+### Pattern 7: Exclusive is_shared Update (ADMIN-02)
+
+**What:** Setting a new shared calendar must atomically clear `is_shared` on any existing shared calendar and set it on the target. Use two Drizzle UPDATE statements (no MariaDB transaction required for this use case — the worst case of a race is a brief moment with zero or two shared calendars, which resolves on the next render).
+
+```typescript
+// In the PUT /api/admin/calendars/:id/shared handler:
+// Step 1: clear all shared flags
+await db.update(calendars).set({ isShared: false }).where(eq(calendars.isShared, true));
+// Step 2: set the target
+await db.update(calendars).set({ isShared: true }).where(eq(calendars.id, targetCalendarId));
+// Note: if strong atomicity is needed, wrap in db.transaction()
+```
+
+[VERIFIED: codebase — apps/api/src/db/schema.ts calendars.isShared (line 89); Drizzle ORM update pattern from CONVENTIONS.md]
+
+### Anti-Patterns to Avoid
+
+- **Guard only at parent mount:** `app.use('/api/admin/*', requireAdmin)` in `index.ts` alone is NOT sufficient. The guard MUST also be the first `.use('*', ...)` inside `adminRouter` itself (Pitfall 9).
+- **Echoing Zod errors for credential routes:** `return c.json(result.error, 400)` exposes `received` (the submitted password value). Always return a generic message from the hook.
+- **Logging request body in admin routes:** No `console.log(c.req.valid('json'))` or `console.log(body)` anywhere in admin route handlers.
+- **Using drizzle-kit push:** Always `db:generate` then `db:migrate` — never `db:push` on the dev or production MariaDB.
+- **Checking isAdmin only client-side:** The PWA's `isAdmin` flag is for UX (show/hide nav entry, redirect non-admins). The 403 is always server-enforced on every `/api/admin/*` request.
+- **Calling `triggerTargetedResync` before the credential is saved:** Encrypt and upsert first, then trigger the sync; otherwise the poller would attempt to decrypt a not-yet-stored credential.
+- **Duplicating credential endpoints in `/api/setup/*`:** Phase 12 MUST reuse `/api/admin/credentials` — do not create parallel `/api/setup/credentials` routes (CONTEXT.md hard constraint).
+
+---
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| AES-256-GCM encryption | Custom crypto | `encryptPassword` in `broker/crypto.ts` | Already built, tested, used by the poller — no changes needed |
+| CalDAV auth validation | Manual HTTP/XML PROPFIND | `createFastmailClient` + `client.fetchCalendars()` | `tsdav` handles PROPFIND, XML namespaces, error mapping |
+| Zod validation middleware | Custom body parsing | `zValidator` from `@hono/zod-validator` | Already used throughout `routes/events.ts`; hook pattern handles no-echo |
+| DB migration tooling | Raw ALTER TABLE scripts | `drizzle-kit generate` + `migrate` | Already set up; journal-tracked; safe on MariaDB |
+| Role middleware | Custom session/cookie check | `requireAdmin` MiddlewareHandler reading `c.get('user')` + DB lookup | Single point of enforcement; reuses the existing user-context pattern |
+
+**Key insight:** This phase's complexity is almost entirely in the careful wiring of existing primitives, not in building new ones. The crypto, CalDAV client, and migration tooling are mature. The main work is the API route structure, the zod hook discipline, and the guard placement.
+
+---
+
+## Runtime State Inventory
+
+> Not a rename/refactor phase — this section is omitted.
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: App Password Echoed in Error Response (Pitfall 7)
+
+**What goes wrong:** A failing Zod validation on the credential body returns `c.json(result.error, 400)`. Zod's error object contains `issues[].received` which includes the actual submitted value — the app password is now in the HTTP response body and potentially in logs.
+
+**Why it happens:** The default `zValidator` behavior without a hook returns the full Zod error. Developers add `console.log('validation error:', result)` for debugging.
+
+**How to avoid:** Always use the `hook` parameter on credential routes: `zValidator('json', schema, (result, c) => { if (!result.success) return c.json({ error: 'Invalid request' }, 400); })`. No `console.log` of request bodies in any `routes/admin.ts` handler.
+
+**Warning signs:** Test for this by submitting a known-bad password and asserting the 400 response body does NOT contain the submitted value string.
+
+### Pitfall 2: requireAdmin Only at Parent Mount (Pitfall 9)
+
+**What goes wrong:** `app.use('/api/admin/*', requireAdmin)` in `index.ts` does not protect routes if the adminRouter's internal routing bypasses the parent middleware (e.g., via direct import in tests, or future route restructuring).
+
+**Why it happens:** Hono's middleware chain is path-prefix-based at the parent level. If tests import `adminRouter` directly rather than through `app`, the parent guard is never applied.
+
+**How to avoid:** `adminRouter.use('*', requireAdmin)` as the FIRST statement in `admin.ts` — before any route definition. Integration tests must import `app` (not `adminRouter` directly) and assert 403 for a non-admin authenticated user on every admin route.
+
+**Warning signs:** A test that imports `adminRouter` directly and calls admin routes without a 403 check.
+
+### Pitfall 3: DEV_AUTH_BYPASS User Not Admin in DB
+
+**What goes wrong:** DEV_AUTH_BYPASS is active. User id 1 is injected. `requireAdmin` looks up `users.is_admin` from the DB. If the dev seed doesn't include `is_admin=true` for user 1, every `/api/admin/*` request returns 403 locally.
+
+**Why it happens:** The bypass skips `upsertUser`, so the first-login-wins logic never runs for user 1. The DB row for user 1 might not exist at all (or exists with `is_admin=false`).
+
+**How to avoid:** The Phase 7 `global-setup.ts` seed the test/dev DB. Add an upsert of user id 1 with `is_admin=true` to the seed. For local development (not test), ensure the dev `docker-compose` seed SQL creates user 1 with `is_admin=true`.
+
+**Warning signs:** Admin page redirects immediately in dev mode; API returns 403 with DEV_AUTH_BYPASS=true.
+
+### Pitfall 4: drizzle-kit push on Populated MariaDB
+
+**What goes wrong:** Running `drizzle-kit push` on the populated dev/production MariaDB triggers false destructive diffs — it may attempt to DROP and recreate tables that already have data, appearing to need schema reconciliation.
+
+**Why it happens:** drizzle-kit push computes diffs against live schema and emits CREATE/DROP statements for columns it cannot safely ALTER. On MariaDB this can produce false "drop table" statements even for benign additions.
+
+**How to avoid:** ALWAYS `pnpm db:generate` then `pnpm db:migrate`. The migration journal tracks what has been applied. Adding a NOT NULL column WITH a DEFAULT value (e.g. `is_admin BOOLEAN NOT NULL DEFAULT false`) is safe for `ALTER TABLE ADD COLUMN` on populated tables.
+
+**Warning signs:** drizzle-kit push output suggests DROP or TRUNCATE statements.
+
+### Pitfall 5: Initial Sync Not Triggered After Credential Save
+
+**What goes wrong:** Admin saves a credential; the member's calendar does not appear until the next 5-min poller tick.
+
+**Why it happens:** The credential is encrypted and stored, but `syncCalendar` / `triggerTargetedResync` is not called after the save.
+
+**How to avoid:** After a successful credential upsert, call the extracted `triggerTargetedResync` equivalent for the member's userId. This is a fire-and-forget call — the admin route returns 200 immediately; the sync runs in the background. For self-service (D-07), same behavior after the member saves their own credential.
+
+**Warning signs:** No calendars visible immediately after credential save; calendars only appear after the next poll.
+
+### Pitfall 6: Member Self-Service Endpoint Allows Cross-Member Write
+
+**What goes wrong:** `POST /api/me/credential` receives a `userId` parameter in the body and uses it, allowing a member to overwrite another member's credential.
+
+**Why it happens:** Route handler reads `userId` from the request body instead of from the authenticated session.
+
+**How to avoid:** The member self-service endpoint ALWAYS uses `currentUserId` from `resolveUserId(c)` — never from the request body. Only the admin endpoint (`POST /api/admin/credentials`) accepts a `userId` parameter, after the `requireAdmin` guard.
+
+**Warning signs:** Test that a non-admin member cannot POST to `/api/admin/credentials` (403) and that `/api/me/credential` ignores any `userId` in the body.
+
+---
+
+## Code Examples
+
+### Resolved User ID Pattern (existing, for requireAdmin)
+
+```typescript
+// Source: apps/api/src/routes/events.ts resolveUserId — established project pattern
+// [VERIFIED: codebase]
+async function resolveUserId(c: Context): Promise<number | null> {
+  const devUser = c.get('user') as { id: number } | undefined;
+  if (devUser) return devUser.id;
+
+  const auth = await getAuth(c);
+  if (!auth) return null;
+
+  const iss = (auth.iss as string | undefined) ?? '';
+  const sub = auth.sub ?? '';
+  const displayName = deriveDisplayName(auth);
+  const user = await upsertUser(iss, sub, displayName);
+  return user?.id ?? null;
+}
+```
+
+### createFastmailClient + fetchCalendars (CalDAV PROPFIND Validation)
+
+```typescript
+// Source: apps/api/src/broker/client.ts (line 22-35) [VERIFIED: codebase]
+export async function createFastmailClient(
+  email: string,
+  appPassword: string,
+): Promise<FastmailClient> {
+  return createDAVClient({
+    serverUrl: 'https://caldav.fastmail.com',
+    credentials: { username: email, password: appPassword },
+    authMethod: 'Basic',
+    defaultAccountType: 'caldav',
+  });
+}
+// Usage in credential validation:
+// const client = await createFastmailClient(email, appPassword);
+// await client.fetchCalendars();  // throws on auth failure
+```
+
+### encryptPassword Reuse
+
+```typescript
+// Source: apps/api/src/broker/crypto.ts (lines 42-54) [VERIFIED: codebase]
+// Returns JSON string: { iv, authTag, ciphertext } — all hex-encoded
+export function encryptPassword(plaintext: string): string { ... }
+// Usage: encryptPassword(appPassword) → stored in member_credentials.encrypted_password
+// NEVER log plaintext or the return value
+```
+
+### Drizzle Upsert Pattern for member_credentials
+
+```typescript
+// Pattern from events.ts / existing upsert conventions [VERIFIED: codebase — CONVENTIONS.md]
+await db.insert(memberCredentials)
+  .values({
+    userId: targetUserId,
+    encryptedPassword: encrypted,
+    fastmailEmail: email,
+    providerType: 'caldav',
+  })
+  .onDuplicateKeyUpdate({
+    set: {
+      encryptedPassword: encrypted,
+      fastmailEmail: email,
+      providerType: 'caldav',
+    },
+  });
+// Note: member_credentials currently has idx_member_credentials_user_id (not UNIQUE on userId).
+// To use onDuplicateKeyUpdate, need a UNIQUE constraint on user_id (or use SELECT+INSERT/UPDATE).
+// Current schema has only an index, not UNIQUE — migration must add UNIQUE(user_id)
+// OR the admin route uses SELECT then UPDATE/INSERT logic instead.
+```
+
+**Important schema note:** `member_credentials` currently has only an index on `user_id` (not UNIQUE). For D-05 (one credential per member), the v1.1 migration should add `UNIQUE(user_id)` to `member_credentials` to enable the Drizzle upsert pattern and enforce the one-credential-per-member invariant. Alternatively, use a SELECT-then-UPDATE/INSERT pattern without the constraint — planner decides.
+
+### /api/me Response Extension
+
+```typescript
+// Current (apps/api/src/routes/me.ts line 66-73) [VERIFIED: codebase]
+return c.json({
+  user: {
+    id: user.id,
+    displayName: user.displayName,
+    color: user.color,
+    // Add:
+    isAdmin: user.isAdmin,               // boolean from users.is_admin
+    needsProviderSetup: !hasCredential,  // true if no member_credentials row
+  },
+});
+// PWA: MeUser interface in apps/pwa/src/api/client.ts gains isAdmin + needsProviderSetup
+```
+
+---
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|-----------------|--------------|--------|
+| `node-cron` for scheduled tasks | `setInterval` throughout | Phase 9 fix | Don't reintroduce node-cron; schedulers stay on setInterval |
+| `drizzle-kit push` | `drizzle-kit generate` + `migrate` | Documented in MEMORY.md | Never push on populated MariaDB |
+| Manual DB write for is_shared | Admin UI endpoint | Phase 10 (this phase) | Replaces the `UPDATE calendars SET is_shared=1` manual step |
+
+**Deprecated/outdated:**
+- `drizzle-kit push`: documented as unsafe for this project; must never be used (MEMORY.md drizzle-mariadb-push-unsafe).
+- `node-cron 4.2.1`: silently skips ticks in long-running process (MEMORY.md node-cron-skips); replaced with setInterval.
+
+---
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| MariaDB (dev compose) | db:migrate, integration tests | ✓ | Dev compose exposed on 3306 (from MEMORY.md dev-stack-bringup) | — |
+| Node.js 22 LTS | API runtime | ✓ | 22 (confirmed by CI config) | — |
+| pnpm | scripts | ✓ | (CI uses corepack) | — |
+| playwright-cli | Admin UI browser verification | ✓ | /usr/local/bin/playwright-cli | — |
+
+**Missing dependencies with no fallback:** none.
+
+---
+
+## Validation Architecture
+
+### Test Framework
+
+| Property | Value |
+|----------|-------|
+| Framework | Vitest 4.x (apps/api), Vitest 4.x + @playwright/test (apps/pwa e2e) |
+| Config file | apps/api/vitest.config.ts, apps/pwa/playwright.config.ts |
+| Quick run command | `pnpm --filter @familysync/api test` |
+| Full suite command | `pnpm --filter @familysync/api test && pnpm --filter @familysync/pwa test:e2e` |
+
+### Phase Requirements → Test Map
+
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|--------------|
+| ADMIN-03 | `GET /api/admin/members` returns 403 for non-admin authenticated user | integration | `pnpm --filter @familysync/api test -- --reporter=verbose` | ❌ Wave 0 |
+| ADMIN-03 | `requireAdmin` blocks unauthenticated requests (401 from outer guard) | unit | same | ❌ Wave 0 |
+| ADMIN-01 | `POST /api/admin/credentials` validates CalDAV and stores encrypted; returns 200 | integration | same | ❌ Wave 0 |
+| ADMIN-01 | `POST /api/admin/credentials` with bad password returns 400 with no value echo | unit | same | ❌ Wave 0 |
+| ADMIN-01 | `POST /api/me/credential` sets only the current user's credential (not another's) | integration | same | ❌ Wave 0 |
+| ADMIN-02 | `PUT /api/admin/calendars/:id/shared` sets exclusive is_shared | integration | same | ❌ Wave 0 |
+| ADMIN-03 | `/admin` React route redirects to `/calendar` for non-admin user | e2e (playwright-cli) | `pnpm --filter @familysync/pwa test:e2e` | ❌ Wave 0 |
+
+### Sampling Rate
+
+- **Per task commit:** `pnpm --filter @familysync/api test`
+- **Per wave merge:** `pnpm --filter @familysync/api test && pnpm typecheck` (both apps)
+- **Phase gate:** Full CI gate (`pnpm lint && pnpm typecheck && pnpm test && pnpm test:e2e`) before `/gsd-verify-work`
+
+### Wave 0 Gaps
+
+- [ ] `apps/api/tests/routes/admin.test.ts` — covers ADMIN-01, ADMIN-02, ADMIN-03 (403 assertion is a hard pitfall check)
+- [ ] `apps/api/tests/auth/requireAdmin.test.ts` — unit tests for the guard middleware
+- [ ] Admin route e2e in Playwright harness — minimal: assert /admin redirect for non-admin, assert Admin nav entry visible for admin user (requires seeding admin user in global-setup.ts)
+
+---
+
+## Security Domain
+
+> `security_enforcement` is enabled (ASVS Level 1 per config.json).
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | yes (admin bootstrap) | first-login-wins gated by existing OIDC session; no credential stored for auth |
+| V3 Session Management | inherited | @hono/oidc-auth handles session JWT cookies (existing) |
+| V4 Access Control | **yes — primary** | `requireAdmin` middleware on every `/api/admin/*` route; member-scoped self-service endpoint |
+| V5 Input Validation | **yes — primary** | zod + `@hono/zod-validator` hook; no Zod error echo for credential fields |
+| V6 Cryptography | **yes — primary** | AES-256-GCM via `encryptPassword`/`decryptPassword` in `crypto.ts` — NEVER hand-rolled |
+| V7 Error Handling | yes | Generic 400 response for credential validation failures (no value echo) |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| Admin endpoint accessed by non-admin | Elevation of Privilege | `requireAdmin` inside adminRouter (.use('*', ...)) |
+| App password echoed in error response | Information Disclosure | zValidator hook returns generic 400 only |
+| App password logged | Information Disclosure | No console.log of request bodies in admin routes |
+| Non-admin member updates another member's credential | Elevation of Privilege | Self-service endpoint uses `currentUserId` from session only |
+| DEV_AUTH_BYPASS bypasses admin check | Elevation of Privilege | `requireAdmin` always queries DB — DEV_USER gets is_admin from DB row, not from bypass flag |
+| Credential stored in plaintext | Information Disclosure | `encryptPassword` (AES-256-GCM) required before any DB write |
+| `drizzle-kit push` drops live data | Tampering | Enforced by project convention; use generate+migrate |
+
+---
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | `triggerTargetedResync` can be extracted from `outboxWorker.ts` (currently private) or duplicated as a shared utility without breaking the outbox drain cycle | Architecture Patterns §4 | Low risk — function has no side effects that couple it to the drain loop; it's a standalone fetch+sync helper |
+| A2 | Adding `UNIQUE(user_id)` to `member_credentials` is safe on the current data (two members, each with one credential row, no duplicates) | Code Examples §Drizzle Upsert Pattern | Low risk — schema note says only two household members exist; verify before generating migration |
+| A3 | `client.fetchCalendars()` throwing on auth failure is the correct PROPFIND validation signal (as used in poller.ts) | Pattern 4 | Confirmed by poller.ts line 43; LOW risk — tsdav raises on 401/403 from Fastmail |
+
+**If this table were empty:** All claims in this research were verified or cited — no user confirmation needed. A1–A3 are minor implementation choices, not scope risks.
+
+---
+
+## Open Questions
+
+1. **UNIQUE constraint on `member_credentials.user_id`**
+   - What we know: current schema has `idx_member_credentials_user_id` (index, not unique). The one-credential-per-member invariant (D-05) is not currently enforced at the DB level.
+   - What's unclear: whether any existing data would violate a unique constraint on user_id (unlikely given two household members, but unverified).
+   - Recommendation: Add `UNIQUE(user_id)` in the v1.1 migration; enables clean Drizzle `onDuplicateKeyUpdate` for upsert. If data check is needed first, the planner adds a Wave 0 verification step.
+
+2. **Initial-sync scope after credential save**
+   - What we know: `triggerTargetedResync` in `outboxWorker.ts` requires a known `calendarUrl` to target. After a fresh credential save, we don't know the calendar URLs yet.
+   - What's unclear: whether to run a full `runPoll`-style sweep for the member (all their calendars) rather than targeting one URL.
+   - Recommendation: Run the full per-member poll after credential save (create client, `client.fetchCalendars()`, `syncCalendar` for all returned DAV calendars). This is exactly what the poller does per credential. Extract or replicate the loop.
+
+3. **Where `needsProviderSetup` lives on `/api/me`**
+   - What we know: CONTEXT.md says "planner's call" for signal surface.
+   - What's unclear: whether to return it on `/api/me` directly or via a dedicated endpoint.
+   - Recommendation: Return it on `/api/me` alongside `isAdmin` — the PWA already fetches `/api/me` on every mount; adding a boolean field avoids a second round-trip and matches D-03's precedent.
+
+---
+
+## Sources
+
+### Primary (HIGH confidence)
+- `apps/api/src/db/schema.ts` — exact current schema: `users`, `member_credentials`, `calendars`, `calendar_events` (including `is_shared` at line 89)
+- `apps/api/src/broker/crypto.ts` — `encryptPassword`/`decryptPassword` signatures (AES-256-GCM, node:crypto)
+- `apps/api/src/broker/client.ts` — `createFastmailClient` + `fetchCalendars` PROPFIND pattern
+- `apps/api/src/broker/outboxWorker.ts` — `loadClientForUser` + `triggerTargetedResync` (lines 271–348)
+- `apps/api/src/broker/poller.ts` — full credential poll cycle
+- `apps/api/src/auth/user.ts` — `upsertUser` function (lines 76–128); hook point for first-login-wins
+- `apps/api/src/auth/devBypass.ts` — `DEV_USER` id=1 pattern; bypass without DB upsert
+- `apps/api/src/routes/me.ts` — current `/api/me` response shape
+- `apps/api/src/index.ts` — middleware mount order; route registration pattern
+- `apps/api/drizzle.config.ts` — migration config; `src/db/migrations/` as output dir
+- `apps/api/package.json` — `db:generate` and `db:migrate` scripts confirmed
+- `apps/api/src/db/migrations/0000_baseline.sql` — existing migration format reference
+- `apps/pwa/src/App.tsx` — react-router `<Routes>` pattern; existing route mounting
+- `apps/pwa/src/api/client.ts` — `MeUser` / `MeResponse` interfaces; extension points
+- `apps/pwa/src/components/AppNav.tsx` — NavLink + Lucide icon pattern (CalendarDays, List)
+- `apps/pwa/src/components/BottomTabBar.tsx` — tab pattern for Admin tab addition
+- `apps/pwa/src/components/SettingsSheet.tsx` — bottom sheet `role="dialog"` pattern to reuse
+- `.planning/phases/10-admin-role-settings/10-CONTEXT.md` — locked decisions D-01..D-07
+- `.planning/phases/10-admin-role-settings/10-UI-SPEC.md` — design system, surfaces, copy contract
+
+### Secondary (MEDIUM confidence)
+- [CITED: https://github.com/honojs/middleware/blob/main/packages/zod-validator/README.md] — zValidator hook signature and custom error response pattern
+- [CITED: https://hono.dev/docs/guides/best-practices] — sub-router pattern via `app.route()`
+
+### Tertiary (LOW confidence)
+- None — all implementation details grounded in codebase reads or official docs.
+
+---
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — all packages are already installed; versions confirmed in package.json
+- Architecture: HIGH — research grounded in direct codebase reads of all key source files
+- Pitfalls: HIGH — Pitfall 7 and 9 grounded in CONTEXT.md + official docs; others grounded in codebase patterns
+- DB migration: HIGH — drizzle.config.ts, package.json scripts, and baseline migration format all confirmed
+
+**Research date:** 2026-06-13
+**Valid until:** 2026-07-13 (stable stack; no fast-moving dependencies)

.planning/phases/10-admin-role-settings/10-UI-SPEC.md

@@ -0,0 +1,239 @@
+---
+phase: 10
+slug: admin-role-settings
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-06-13
+---
+
+# Phase 10 — Admin Role & Settings UI Design Contract
+
+> Visual and interaction contract for the admin role, credential management, shared-calendar designation, and member self-service credential onboarding surfaces. Generated by gsd-ui-researcher.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none — custom CSS variables only |
+| Preset | not applicable |
+| Component library | none (hand-authored inline styles, `var(--token)` pattern throughout) |
+| Icon library | lucide-react 1.17.0 |
+| Font | `system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` (var(--font-family-base)) |
+
+Source: `apps/pwa/src/styles/tokens.css` (Phase 2, D-01/D-02). No shadcn, no Tailwind — all values are CSS custom properties declared in tokens.css and referenced inline.
+
+---
+
+## Spacing Scale
+
+All spacing must reference `var(--space-N)` tokens, never hard-coded px. Multiples of 4px.
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| --space-1 | 4px | Icon gaps, tight inline padding, border-radius on small elements |
+| --space-2 | 8px | Compact row padding, section-label bottom margin, badge gap |
+| --space-3 | 12px | Row internal padding (toggle rows, member rows), gap between icon and label |
+| --space-4 | 16px | Input horizontal padding, button horizontal padding, nav horizontal padding |
+| --space-6 | 24px | Sheet/page padding, heading bottom margin, section separation |
+| --space-8 | 32px | Major layout gaps between sections |
+| --space-12 | 48px | Page-level top/bottom breathing room on the /admin route |
+
+Exceptions: 44px minimum touch target on all interactive elements (buttons, radio pills, credential rows) — applied as `minWidth: 44px; minHeight: 44px` inline, not a spacing token. Destructive confirm button uses `minHeight: 48px` per the existing DeleteConfirmationDialog precedent.
+
+---
+
+## Typography
+
+All values reference existing `var(--text-*)` tokens from tokens.css. No new sizes or weights.
+
+| Role | Size | Weight | Line Height | Usage in this phase |
+|------|------|--------|-------------|---------------------|
+| Body | 15px (var(--text-body-size)) | 400 (var(--text-body-weight)) | 1.5 (var(--text-body-line-height)) | Member name, credential status description, instruction copy, field labels |
+| Label | 13px (var(--text-label-size)) | 400 (var(--text-label-weight)) | 1.4 (var(--text-label-line-height)) | Section headers (uppercased), status badges, calendar picker option text, helper text under password field |
+| Heading | 18px (var(--text-heading-size)) | 600 (var(--text-heading-weight)) | 1.25 (var(--text-heading-line-height)) | Page heading "Admin Settings", sheet headings ("Rotate Credential", "Set Shared Calendar"), confirmation dialog heading |
+| Display | 24px (var(--text-display-size)) | 600 (var(--text-display-weight)) | 1.2 (var(--text-display-line-height)) | Not used in this phase — reserved for app name in AppNav |
+
+Section labels (e.g. "MEMBERS", "SHARED CALENDAR") follow the established SettingsSheet pattern: 13px / weight 600 / `var(--color-text-muted)` / `textTransform: uppercase` / `letterSpacing: 0.06em`.
+
+---
+
+## Color
+
+All values reference existing tokens from tokens.css. No new colors introduced.
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | #ffffff (var(--color-surface)) | /admin page background, sheet backgrounds, dialog backgrounds |
+| Secondary (30%) | #f7f7f8 (var(--color-surface-dim)) | Member rows background on hover/focus, info/hint banners, credential-setup onboarding card |
+| Accent (10%) | #4a90d9 (var(--color-member-0)) | Save/confirm CTA buttons, active radio selection border, focus ring (var(--color-focus-ring)), selected calendar radio indicator |
+| Destructive | #dc2626 (var(--color-destructive)) | "Remove credential" destructive action button only |
+
+Accent reserved for: Save button ("Save Credential"), selected-calendar radio indicator, text links ("Get an app password" → Fastmail doc link), focus ring on inputs and interactive elements. Never used for nav chrome, page background, or passive text.
+
+Status indicators (member credential state) use the established muted/secondary palette, not accent:
+- Credential set: `var(--color-text-secondary)` + a check icon (lucide `CheckCircle`, size 16)
+- No credential: `var(--color-text-muted)` + warning icon (lucide `AlertCircle`, size 16)
+
+---
+
+## Surfaces & Interaction Patterns
+
+### Surface 1 — /admin Route (full page)
+
+A dedicated route at `/admin`, gated by `isAdmin` from `/api/me`. Non-admin users redirected to `/calendar` immediately on mount.
+
+Layout matches the existing app shell: AppNav persistent sidebar (desktop) or top bar (mobile), BottomTabBar (mobile). The `/admin` content area uses `var(--color-surface)` background with `var(--space-12)` top/bottom padding and `var(--space-6)` horizontal padding on mobile.
+
+Desktop: content in a centered column, `maxWidth: 640px`, `margin: 0 auto`.
+
+The admin route does NOT appear in AppNav nav links by default. Entry point: a new "Admin" `NavLink` in the desktop sidebar and a new tab in the mobile BottomTabBar, rendered only when `meQuery.data?.isAdmin === true`. Use lucide `ShieldCheck` icon (size 18) for the Admin nav entry, matching the `CalendarDays`/`List` pattern in AppNav.
+
+### Surface 2 — Member Credential List Section
+
+A section within `/admin` labeled "MEMBERS" (section-label style).
+
+Each member renders as a row:
+- Avatar color swatch (32px circle, `var(--color-member-N)`) + member display name at body size
+- Credential status badge at label size: "Credential set" (muted green check) or "No credential" (muted warning)
+- An action button: "Rotate" (if credential exists) or "Add credential" (if none)
+- Entire row: `minHeight: 44px`, background `var(--color-surface)`, bottom border `1px solid var(--color-border-subtle)`
+
+Clicking "Rotate" or "Add credential" opens Surface 3 (credential sheet) for that member.
+
+Admin can rotate any member's credential. Members can only manage their own (self-service path via Surface 4 — same sheet, member-scoped API endpoint).
+
+### Surface 3 — Credential Sheet (admin-managed rotation)
+
+A bottom sheet on mobile (same pattern as SettingsSheet: `role="dialog"`, `aria-modal`, zIndex 301, backdrop zIndex 300, `borderRadius: 12px 12px 0 0`, `padding: var(--space-6)`). Centered modal on desktop (`maxWidth: 480px`).
+
+Contents:
+1. Heading: "Rotate Credential" (if existing) or "Add Credential" (if none) — 18px/600
+2. Member name as subtitle — 15px/400/`var(--color-text-secondary)`
+3. Password field (type="password", autocomplete="new-password"):
+   - Label: "App password" — 13px/600/`var(--color-text-primary)`
+   - Input: full-width, `padding: var(--space-3) var(--space-4)`, `border: 1px solid var(--color-border)`, `borderRadius: var(--space-1)`, `fontSize: var(--text-body-size)`, `color: var(--color-text-primary)`, `background: var(--color-surface)`. Error state border: `var(--color-destructive)`.
+   - Never pre-filled; never echoed back after save.
+4. Helper text below field — 13px/400/`var(--color-text-secondary)`:
+   "Enter the Fastmail app password scoped to Calendars/CalDAV. [Get an app password](https://app.fastmail.com/settings/security/devicetokens) — choose the 'Calendars & Contacts (CalDAV)' scope."
+   The link opens in a new tab (`target="_blank" rel="noopener noreferrer"`).
+5. Validation: "Validating against CalDAV…" inline status (13px, muted, spinner `Loader2` size 16) replaces helper text during the PROPFIND call. On failure: red 13px error below field ("Invalid password — CalDAV validation failed. Check the scope is 'Calendars & Contacts (CalDAV)' and try again."). On success: sheet closes.
+6. Actions row (right-aligned, gap `var(--space-3)`):
+   - Cancel: ghost button (background none, 13px/600/`var(--color-text-secondary)`, minHeight 44px)
+   - Save Credential: filled accent button (`var(--color-member-0)` background, #ffffff text, 13px/600, minHeight 44px, `padding: 0 var(--space-4)`, `borderRadius: var(--space-1)`). Disabled while field empty or during validation.
+
+### Surface 4 — Self-Service Credential Onboarding (member-scoped)
+
+Triggered when a member with `needsProviderSetup: true` (from `/api/me`) loads the app. Rendered as a dismissable banner or inline card above the calendar content — NOT a modal (user should be able to continue using the app without completing it immediately).
+
+Card/banner style: `background: var(--color-surface-dim)`, `border: 1px solid var(--color-border)`, `borderRadius: var(--space-2)`, `padding: var(--space-4)`, `margin: var(--space-4)`.
+
+Contents:
+- Icon: lucide `KeyRound` size 20, `var(--color-member-0)`
+- Heading: "Set up your calendar" — 15px/600/`var(--color-text-primary)`
+- Body: "To sync your Fastmail calendar, you need to add an app password. This takes about a minute." — 13px/400/`var(--color-text-secondary)`
+- CTA button: "Set up now" — same accent-filled style as Surface 3 Save button, minHeight 44px
+
+Clicking "Set up now" opens the same credential sheet (Surface 3) but scoped to the current user only, with heading "Add your calendar credential" and simplified copy ("App password for your Fastmail account").
+
+The banner has no X/dismiss button — it stays visible until the credential is successfully saved (needsProviderSetup becomes false after save).
+
+### Surface 5 — Shared Calendar Picker Section
+
+A section within `/admin` labeled "SHARED CALENDAR" (section-label style), below the Members section.
+
+Body copy (15px/400/secondary): "The shared family calendar is visible to all members in the same color lane."
+
+Radio group — one row per synced calendar:
+- Each row: `minHeight: 44px`, flexbox, `gap: var(--space-3)`, `padding: var(--space-2) 0`
+- Radio indicator: a 20px circle — unfilled with `2px solid var(--color-border)` when unselected; filled with `var(--color-member-0)` + inner 8px white dot when selected
+- Calendar name at body size (15px/400/`var(--color-text-primary)`)
+- "Currently shared" label (13px/400/`var(--color-member-0)`) on the currently active selection
+
+Selection is exclusive single-select (D-06). Selecting a row immediately highlights it; a "Save" button below the list confirms the write (two-tap, prevents accidental mis-selection).
+
+Save button: full-width on mobile, right-aligned on desktop; accent-filled style, `minHeight: 44px`. Disabled until selection differs from current saved value.
+
+If no calendars have been synced yet: empty state (see Copywriting Contract below).
+
+---
+
+## Copywriting Contract
+
+| Element | Copy |
+|---------|------|
+| Admin nav label | "Admin" |
+| /admin page heading | "Admin Settings" |
+| Members section label | "MEMBERS" |
+| Shared calendar section label | "SHARED CALENDAR" |
+| Credential status — set | "Credential set" |
+| Credential status — missing | "No credential" |
+| Admin credential row CTA — existing | "Rotate" |
+| Admin credential row CTA — none | "Add credential" |
+| Credential sheet heading — admin rotation (existing) | "Rotate Credential" |
+| Credential sheet heading — admin add (none) | "Add Credential" |
+| Credential sheet heading — self-service | "Add your calendar credential" |
+| Credential sheet member subtitle | "{DisplayName}" |
+| Password field label | "App password" |
+| Password field helper text | "Enter the Fastmail app password scoped to Calendars/CalDAV. [Get an app password] — choose the 'Calendars & Contacts (CalDAV)' scope." |
+| CalDAV validation in-progress | "Validating against CalDAV…" |
+| CalDAV validation failure | "Invalid password — CalDAV validation failed. Check the scope is 'Calendars & Contacts (CalDAV)' and try again." |
+| Save credential button | "Save Credential" |
+| Cancel button | "Cancel" |
+| Self-service banner heading | "Set up your calendar" |
+| Self-service banner body | "To sync your Fastmail calendar, you need to add an app password. This takes about a minute." |
+| Self-service CTA button | "Set up now" |
+| Shared calendar save button | "Save" |
+| Shared calendar currently-active label | "Currently shared" |
+| Shared calendar empty state heading | "No calendars synced yet" |
+| Shared calendar empty state body | "Calendars sync automatically. Check back after the first sync completes." |
+| Calendars picker loading | "Loading calendars…" |
+| Generic save error | "Something went wrong. Please try again." |
+| 403 non-admin redirect | (silent redirect — no error copy shown to the non-admin user) |
+
+Destructive actions in this phase:
+
+| Action | Trigger | Confirmation approach |
+|--------|---------|----------------------|
+| Rotating/replacing a credential | Tapping "Rotate" then "Save Credential" with a new value | Two-step: open sheet (step 1) + explicit "Save Credential" tap (step 2). No separate confirmation dialog — overwrite is acknowledged by the user filling and submitting the new value. The existing credential is never displayed; losing it is not destructive (a new one replaces it). |
+
+No hard-delete of credentials in this phase. "Remove credential" is listed as the destructive color token usage but the action itself is deferred — only add/rotate is in scope for Phase 10.
+
+---
+
+## Accessibility Contracts
+
+- All interactive elements: `minWidth: 44px; minHeight: 44px` (WCAG 2.5.5 Target Size).
+- Credential sheet: `role="dialog"`, `aria-modal="true"`, `aria-label` matching the heading, Escape closes.
+- Password input: `type="password"`, `autocomplete="new-password"`, never `autocomplete="current-password"`.
+- Radio group for calendar picker: each row has `role="radio"` or wraps a native `<input type="radio">` in a visually styled label; `aria-checked` on custom implementations.
+- Admin nav entry: `aria-label="Admin settings"` on the NavLink/button.
+- Self-service banner: `role="status"` or `aria-live="polite"` so screen readers announce it on load.
+- Validation error messages: associated to their input via `aria-describedby`.
+- Focus returns to the trigger element when a sheet closes.
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| shadcn official | none — not initialized | not applicable |
+| Third-party | none | not applicable |
+
+No third-party component registries. All components hand-authored using the existing inline-style pattern. No new npm dependencies for UI are required beyond lucide-react (already installed at 1.17.0).
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

.planning/phases/10-admin-role-settings/10-VALIDATION.md

@@ -0,0 +1,96 @@
+---
+phase: 10
+slug: admin-role-settings
+status: draft
+nyquist_compliant: true
+wave_0_complete: false
+created: 2026-06-13
+---
+
+# Phase 10 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Vitest 4.x (apps/api unit + real-DB integration), Vitest 4.x + Playwright (apps/pwa unit + e2e) |
+| **Config file** | apps/api/vitest.config.ts, apps/pwa/vitest.config.ts, apps/pwa/playwright.config.ts |
+| **Quick run command** | `pnpm --filter @familysync/api test` |
+| **Full suite command** | `pnpm --filter @familysync/api test && pnpm --filter @familysync/pwa test && pnpm --filter @familysync/pwa test:e2e` |
+| **Estimated runtime** | ~60–120 seconds (e2e dominates) |
+
+Notes:
+- API real-DB integration tests need the dev MariaDB bound on 3306 + `DB_HOST=127.0.0.1` + `.env` creds; API tests live in `apps/api/tests/` (never `src/`) — see [[api-integration-test-db]].
+- `tsc --noEmit` MUST be run separately in both apps — vitest stays green on type errors ([[vitest-passes-tsc-fails]]).
+- e2e relies on the dev-bypass admin user (id=1 is_admin=true) seeded by Plan 01 Task 3 in `apps/pwa/e2e/global-setup.ts`.
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `pnpm --filter @familysync/api test` (API tasks) or `pnpm --filter @familysync/pwa exec tsc --noEmit` (PWA tasks).
+- **After every plan wave:** Run `pnpm --filter @familysync/api test && pnpm --filter @familysync/api exec tsc --noEmit && pnpm --filter @familysync/pwa exec tsc --noEmit`.
+- **Before `/gsd-verify-work`:** Full CI fast-checks gate green (lint + typecheck + test + format:check + md:lint + PWA tests + e2e) — [[feedback-run-full-ci-gate-before-push]].
+- **Max feedback latency:** ~15s for the API quick run; ~120s for the full suite.
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 10-01-01 | 01 | 1 | ADMIN-01/02/03 | T-10-01 | schema additive only; no destructive DDL | typecheck | `pnpm --filter @familysync/api exec tsc --noEmit` | ✅ existing | ⬜ pending |
+| 10-01-02 | 01 | 1 | ADMIN-01/02/03 | T-10-01 | generate+migrate (never push); live DB columns verified by query | integration (DB) | mysql2 `SHOW COLUMNS`/`SHOW TABLES` assert (see plan verify) | ✅ existing | ⬜ pending |
+| 10-01-03 | 01 | 1 | ADMIN-03 | T-10-03 | dev-bypass admin row scoped to guarded dev/e2e DB only | source | `grep -c is_admin apps/pwa/e2e/global-setup.ts` | ✅ existing | ⬜ pending |
+| 10-02-01 | 02 | 2 | ADMIN-03 | T-10-04/05/06/07 | requireAdmin 403s non-admin; role from DB not client flag | unit | `pnpm --filter @familysync/api test -- requireAdmin` | ❌ W0 → `apps/api/tests/lib/requireAdmin.test.ts` | ⬜ pending |
+| 10-02-02 | 02 | 2 | ADMIN-03 | T-10-04 | first-login-wins is_admin; member-count-agnostic | integration (DB) | `pnpm --filter @familysync/api test -- user` | ✅ `apps/api/tests/auth/user.test.ts` (extend) | ⬜ pending |
+| 10-02-03 | 02 | 2 | ADMIN-03 | T-10-06/07 | /api/me exposes isAdmin + needsProviderSetup (UX-only flag) | integration | `pnpm --filter @familysync/api test -- me` | ✅ `apps/api/tests/routes/me.test.ts` (extend) | ⬜ pending |
+| 10-03-01 | 03 | 3 | ADMIN-01 | T-10-SC | broker helpers exported; bodies unchanged | unit | `pnpm --filter @familysync/api test -- outbox` | ✅ `apps/api/tests/broker/` | ⬜ pending |
+| 10-03-02 | 03 | 3 | ADMIN-01/02/03 | T-10-08/09/10/11/13 | guard-first 403; no password echo/log; encrypted at rest; exclusive is_shared | integration | `pnpm --filter @familysync/api test -- admin` | ❌ W0 → `apps/api/tests/routes/admin.test.ts` | ⬜ pending |
+| 10-03-03 | 03 | 3 | ADMIN-01 | T-10-09/10/12 | self-service member-scoped; no cross-member write; no echo | integration | `pnpm --filter @familysync/api test -- credential` | ❌ W0 → in `apps/api/tests/routes/admin.test.ts` | ⬜ pending |
+| 10-04-01 | 04 | 4 | ADMIN-01/02/03 | T-10-14 | MeUser flags UX-only; self-service payload has no userId | typecheck | `pnpm --filter @familysync/pwa exec tsc --noEmit` | ✅ existing | ⬜ pending |
+| 10-04-02 | 04 | 4 | ADMIN-01 | T-10-15/16 | password never pre-filled; autocomplete=new-password | typecheck + source | `pnpm --filter @familysync/pwa exec tsc --noEmit` + grep new-password | ✅ existing | ⬜ pending |
+| 10-04-03 | 04 | 4 | ADMIN-03 | T-10-14 | /admin redirect for non-admin; nav entry hidden for non-admin | e2e (playwright) | `pnpm --filter @familysync/pwa test:e2e -- admin` | ❌ W0 → `apps/pwa/e2e/admin.spec.ts` | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+Sampling continuity: every task has an `<automated>` verify; no 3 consecutive tasks lack automated coverage.
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `apps/api/tests/lib/requireAdmin.test.ts` — NEW unit tests for the guard (403 non-admin / next() admin / no-user / DB-not-client-flag). Created in Plan 02 Task 1 (RED first).
+- [ ] `apps/api/tests/routes/admin.test.ts` — NEW integration tests covering ADMIN-01 (credential validate/encrypt/no-echo), ADMIN-02 (exclusive is_shared), ADMIN-03 (403 for non-admin on every admin route — import `app`, never adminRouter directly), and the member self-service credential cases. Created in Plan 03 Tasks 2 & 3 (RED first).
+- [ ] `apps/pwa/e2e/admin.spec.ts` — NEW e2e: admin sees nav entry + reaches /admin; non-admin (route-mocked isAdmin:false) sees no entry and is redirected. Created in Plan 04 Task 3 (RED first).
+- [ ] Extend `apps/api/tests/auth/user.test.ts` — first-login-wins cases (Plan 02 Task 2).
+- [ ] Extend `apps/api/tests/routes/me.test.ts` — isAdmin + needsProviderSetup cases (Plan 02 Task 3).
+
+Existing infrastructure (Vitest + Playwright + real-DB harness + global-setup seed) covers all framework needs — no framework install required.
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Live CalDAV PROPFIND against the real Fastmail account on a real credential save | ADMIN-01 | CI/e2e mock CalDAV (dev-bypass user 1 has no Fastmail credential — [[dev-data-user1-no-calendars]]); a true end-to-end save against Fastmail needs a real app password | At go-live, an admin enters a real Fastmail app password in the credential sheet; confirm 200 + the member's calendar appears after the initial sync. Optional operator spot-check, not a phase gate. |
+
+All other phase behaviors (route guard, no-echo, encryption-at-rest, exclusive is_shared, nav gating, /admin redirect) have automated coverage (Vitest + Playwright/playwright-cli — the route guard and nav gating are desktop-Chromium-drivable per CLAUDE.md, so no human checkpoint).
+
+---
+
+## 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 (requireAdmin.test.ts, admin.test.ts, admin.spec.ts + the two extends)
+- [x] No watch-mode flags
+- [x] Feedback latency < 120s (full) / < 15s (quick)
+- [x] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** approved 2026-06-13