Document spec gaps: auth, phase scaling, observability, testing

Address 21 previously undefined behaviors across specs:

- Authentication: Replace email/password with OIDC (Pocket-ID)
- Cycle tracking: Add fixed-luteal phase scaling formula with examples
- Calendar: Document period logging behavior (preserve predictions)
- Garmin: Clarify connection is required (no phase-only mode)
- Dashboard: Add UI states, dark mode, onboarding, accessibility
- Notifications: Document timezone batching approach
- New specs: observability.md (health, metrics, logging)
- New specs: testing.md (unit + integration strategy)
- Main spec: Add backup/recovery, known limitations, API updates

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

specs/authentication.md

@@ -2,11 +2,11 @@
 
 ## Job to Be Done
 
-When I access PhaseFlow, I want to securely log in with my email, so that my personal health data remains private.
+When I access PhaseFlow, I want to securely log in with my identity provider, so that my personal health data remains private.
 
 ## Auth Provider
 
-Using PocketBase for authentication and data storage.
+Using PocketBase for authentication and data storage, with OIDC (Pocket-ID) as the primary identity provider.
 
 **Connection:**
 - `POCKETBASE_URL` environment variable
@@ -14,12 +14,30 @@ Using PocketBase for authentication and data storage.
 
 ## Login Flow
 
-### Email/Password Authentication
+### OIDC Authentication (Pocket-ID)
 
-1. User enters email and password on `/login`
-2. App calls PocketBase `authWithPassword`
-3. On success, PocketBase sets auth cookie
-4. User redirected to dashboard
+1. User clicks "Sign In" on `/login`
+2. App redirects to Pocket-ID authorization endpoint
+3. User authenticates with Pocket-ID (handles MFA if configured)
+4. Pocket-ID redirects back with authorization code
+5. PocketBase exchanges code for tokens
+6. User redirected to dashboard
+
+### OIDC Configuration
+
+Configure in PocketBase Admin UI: **Settings → Auth providers → OpenID Connect**
+
+**Required Settings:**
+- `Client ID` - From Pocket-ID application
+- `Client Secret` - From Pocket-ID application
+- `Issuer URL` - Your Pocket-ID instance URL (e.g., `https://id.yourdomain.com`)
+
+**Environment Variables:**
+```env
+POCKETBASE_OIDC_CLIENT_ID=phaseflow
+POCKETBASE_OIDC_CLIENT_SECRET=xxx
+POCKETBASE_OIDC_ISSUER_URL=https://id.yourdomain.com
+```
 
 ### Session Management
 
@@ -32,11 +50,8 @@ Using PocketBase for authentication and data storage.
 ### `/login`
 
 **Elements:**
-- Email input
-- Password input
-- "Sign In" button
+- "Sign In with Pocket-ID" button
 - Error message display
-- Link to password reset (future)
 
 **Behavior:**
 - Redirect to `/` on successful login
@@ -130,18 +145,37 @@ User profile management:
 
 ## Success Criteria
 
-1. Login completes in under 2 seconds
+1. OIDC login flow completes in under 5 seconds (including redirect)
 2. Session persists across browser refreshes
 3. Unauthorized access redirects to login
 4. User data isolated by authentication
 
 ## Acceptance Tests
 
-- [ ] Valid credentials authenticate successfully
-- [ ] Invalid credentials show error message
+- [ ] OIDC redirect initiates correctly
+- [ ] Successful OIDC callback creates/updates user
 - [ ] Session persists after page refresh
 - [ ] Protected routes redirect when not authenticated
 - [ ] GET `/api/user` returns current user data
 - [ ] PATCH `/api/user` updates user record
 - [ ] Logout clears session completely
 - [ ] Auth cookie is HttpOnly and Secure
+
+## Future Enhancements
+
+### Open Registration
+
+When open registration is enabled:
+- Add `/signup` page with OIDC provider selection
+- New users created automatically on first OIDC login
+- Admin approval workflow (optional)
+
+### Additional OAuth2 Providers
+
+PocketBase supports multiple OAuth2 providers. Future options:
+- Google
+- GitHub
+- Apple
+- Other OIDC-compliant providers
+
+Each provider configured separately in PocketBase Admin UI.