Merge pull request #277 from MBombeck/release/v1.15.2

v1.15.2 — cycle insights crash fix

.dockerignore

@@ -0,0 +1,87 @@
+# Keep the BuildKit build context small and free of secrets / scratch.
+# Mirrors `.gitignore` for the files that matter, with a few additions
+# (planning scratch, e2e storage state) that aren't in version control
+# but live in the working tree.
+
+# Local environment files. The image reads its runtime config from the
+# compose `environment:` block at boot — `.env` should never ship.
+.env
+.env.*
+.env.example
+.env.production.example
+
+# Version control + CI metadata.
+.git
+.github
+.gitignore
+.gitleaks.toml
+
+# Build / install output that gets regenerated inside the builder stage.
+node_modules
+.next
+out
+dist
+coverage
+test-results
+playwright-report
+playwright/.cache
+playwright.config.ts
+vitest.config.mts
+vitest.integration.config.mts
+tests
+tests/
+e2e
+e2e/
+e2e-results
+.eslintcache
+eslint-plugins
+eslint-plugins/
+knip.json
+
+# Generated local cache files
+*.tsbuildinfo
+next-env.d.ts
+public/sw-version.js
+
+# Captures from local debugging sessions.
+*.har
+*.heapsnapshot
+
+# Editor / agent worktrees + caches.
+.claude
+.cursor
+.aider*
+.vscode
+.idea
+.DS_Store
+*.swp
+*.swo
+
+# Logs / Debug
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Docker compose / local ops files
+docker-compose*.yml
+compose*.yml
+Dockerfile
+.dockerignore
+
+# Documentation not needed for runtime image
+README.md
+CHANGELOG.md
+CLAUDE.md
+CONTRIBUTING.md
+CONTRIBUTING-AI.md
+CODE_OF_CONDUCT.md
+SECURITY.md
+# LICENSE / LICENSE.md are deliberately NOT ignored: AGPL-3.0 conveys with
+# the software, so the licence text ships inside the image.
+AGENTS.md
+.planning
+docs
+docs/*.md
+docs/**/*.md

.env.example

@@ -4,10 +4,10 @@
 # Copy this file to .env and fill in the values.
 #   $ cp .env.example .env
 #
-# Required variables: DATABASE_URL or POSTGRES_PASSWORD, SESSION_SECRET,
+# Required variables: DATABASE_URL or POSTGRES_PASSWORD,
 #                     ENCRYPTION_KEY, API_TOKEN_HMAC_KEY
 #
-# Generate the three secrets with:
+# Generate the two secrets with:
 #   $ openssl rand -hex 32                     # any UNIX shell
 #   $ node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))'
 #
@@ -40,13 +40,20 @@ APP_URL="http://localhost:3000"
 # Node environment: "development" for `pnpm dev`, "production" for Docker.
 NODE_ENV="development"
 
+# Session cookie `Secure` flag (v1.5.1).
+# Defaults to NODE_ENV === "production" — the safe choice for any
+# deployment terminated by HTTPS (Caddy / Traefik / Nginx in front).
+# Set to `false` if you intentionally serve plain HTTP on a LAN, VPN,
+# or Tailscale-only surface — the browser otherwise drops the session
+# cookie on HTTP origins and login round-trips fail silently. NEVER
+# set to `false` for a deployment that serves plain HTTP to the open
+# internet; the session cookie crosses the wire in cleartext.
+# SESSION_COOKIE_SECURE="false"
+
 
 # -----------------------------------------------------------------------------
 # Required Secrets — generate with `openssl rand -hex 32`
 # -----------------------------------------------------------------------------
-# Signs session cookies. Rotating it logs out everyone.
-SESSION_SECRET="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
-
 # AES-256-GCM key for encrypting Withings tokens, GitHub PATs, AI provider
 # keys, and VAPID private keys at rest. Rotate carefully — old ciphertexts
 # need re-encryption.
@@ -82,6 +89,13 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # Users bring their own API keys via Settings. No server-side key needed by
 # default. The admin can configure a fallback key in the Admin Panel.
 
+# Maximum number of comprehensive-insight generations a single user can
+# trigger per hour (POST /api/insights/generate). Default 10. The 24h
+# DB cache short-circuits this for read traffic; only force=true and
+# expired-cache regenerations consume tokens. Lower this when running
+# on a tight LLM budget.
+# INSIGHTS_RATE_LIMIT_PER_HOUR="10"
+
 
 # -----------------------------------------------------------------------------
 # Structured Logging — Wide Events (optional, sensible defaults)
@@ -104,3 +118,105 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # LOKI_ENDPOINT="http://loki:3100"
 # LOKI_USERNAME=""
 # LOKI_PASSWORD=""
+
+
+# -----------------------------------------------------------------------------
+# Reverse-proxy trust (optional, defaults match a single-proxy stack)
+# -----------------------------------------------------------------------------
+# When HealthLog sits behind Cloudflare (Tunnel, Workers, classic proxy),
+# the visitor IP arrives in the `CF-Connecting-IP` header — the upstream
+# `X-Forwarded-For` chain stops at the Coolify / Caddy loopback and the
+# admin sign-in geo lookup has no signal to resolve from.
+#
+# Set this to "1" ONLY when every public request to HealthLog terminates
+# at Cloudflare (Tunnel, Workers, classic proxy) before it reaches your
+# origin. Deployments behind nginx, Caddy, Traefik, an AWS ALB, or any
+# direct-to-Next.js exposure MUST leave this off.
+#
+# Security implications when the flag is mis-set:
+#   - `cf-connecting-ip` becomes the IP-rate-limit bucket key for
+#     login / chat / coach. An attacker who can set the header rotates
+#     it per request and defeats every IP-keyed throttle.
+#   - The same value lands in the `audit_logs.ipAddress` column for
+#     every `measurement.create`, `medication.intake`, sign-in, and
+#     admin action. A misconfigured flag lets any caller forge the
+#     IP recorded against their actions across the audit trail.
+#   - The admin sign-in overview's "Standort" column reads the same
+#     value via geo-backfill; a malicious caller can poison the column
+#     with a chosen IP per request.
+#
+# Code-level validation is strict (only "=== '1'" enables, value is
+# regex- and length-bounded), but the gating decision is up to the
+# operator — there is no way for the server to detect whether the flag
+# matches the real deployment topology. When in doubt, leave it off.
+# TRUST_CF_CONNECTING_IP=""
+
+
+# -----------------------------------------------------------------------------
+# Process split (optional, single-container deploys ignore this)
+# -----------------------------------------------------------------------------
+# `all`   — single container runs HTTP + reminder worker (default, legacy).
+# `web`   — HTTP only; pair with a separate `app-worker` service.
+# `worker`— pg-boss only; rejects HTTP traffic with a 503.
+# See docs/self-hosting/scaling.md for the split-stack guide.
+# HEALTHLOG_PROCESS_TYPE="all"
+
+
+# -----------------------------------------------------------------------------
+# Encryption-key versioning (optional — for at-rest key rotation)
+# -----------------------------------------------------------------------------
+# JSON map of key id → 64-hex-char or base64 32-byte key. When set, it
+# supersedes ENCRYPTION_KEY for new writes; old rows continue to decrypt under
+# their original id. ENCRYPTION_ACTIVE_KEY_ID picks which entry encrypt() uses.
+# Run `pnpm tsx scripts/rotate-encryption-key.ts <new-id>` to re-encrypt every
+# existing row under the new key. See docs/ops/encryption-key-rotation.md.
+# ENCRYPTION_KEYS='{"v1":"<old-key>","v2":"<new-key>"}'
+# ENCRYPTION_ACTIVE_KEY_ID="v2"
+
+
+# -----------------------------------------------------------------------------
+# Off-host backup (optional — daily encrypted dumps to an S3-compatible bucket)
+# -----------------------------------------------------------------------------
+# Required ALL-OR-NONE: setting any of these without setting the rest disables
+# the backup silently. The backup runs at 02:30 Europe/Berlin via pg-boss cron.
+# Restore with `pnpm tsx scripts/restore-backup.ts <userId> <YYYY-MM-DD>`.
+# See docs/ops/backup-restore.md for the format spec + step-by-step.
+# BACKUP_S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
+# BACKUP_S3_BUCKET="healthlog-backups"
+# BACKUP_S3_ACCESS_KEY=""
+# BACKUP_S3_SECRET_KEY=""
+# BACKUP_S3_REGION="auto"           # "auto" for Cloudflare R2; real region for AWS S3
+# BACKUP_RETENTION_DAYS="30"        # objects older than this are pruned (best-effort; prefer a bucket lifecycle rule)
+# BACKUP_ENCRYPTION_KEY=""          # 64-hex-char or base64 32-byte; SEPARATE from ENCRYPTION_KEY
+
+
+# -----------------------------------------------------------------------------
+# APNs — Apple Push Notification service (v1.4.23+, optional)
+# -----------------------------------------------------------------------------
+# All four core APNS_* vars must be set together for APNs to fan out to iOS
+# devices. Leaving them unset disables the channel silently — the dispatcher
+# falls back to Telegram → ntfy → Web Push as before.
+#
+# Provision an APNs auth key (.p8) at https://developer.apple.com/account/
+# under Certificates, Identifiers & Profiles → Keys → APNs.
+#
+# APNS_KEY (preferred for 12-factor / Coolify env-block) and APNS_KEY_FILE
+# (filesystem path) are mutually exclusive — pick one. APNS_KEY accepts the
+# multi-line PEM body with literal newlines OR `\n` escapes.
+# APNS_KEY_ID=""                 # 10-char Key ID from Apple Developer (e.g. ABCDE12345)
+# APNS_TEAM_ID=""                # 10-char Team ID from Apple Developer
+# APNS_BUNDLE_ID=""              # iOS app bundle id (e.g. dev.healthlog.ios)
+# APNS_KEY=""                    # APNs auth key as PEM body (multi-line OK with \n escapes); preferred over APNS_KEY_FILE
+# APNS_KEY_FILE=""               # Alternate: filesystem path to .p8 file
+# APNS_PRODUCTION=""             # "true" to force the production gateway; default = mirror Device.apnsEnvironment
+
+
+# -----------------------------------------------------------------------------
+# Auto-deploy webhook (v1.4.15 — phase C2)
+# -----------------------------------------------------------------------------
+# Coolify (or any CI) pings POST /api/internal/deploy-webhook after a deploy
+# attempt with success/failure. We verify the request via this shared secret
+# carried in the `X-Deploy-Webhook-Secret` header (timing-safe compare).
+# Generate with `openssl rand -hex 32`. Configure the SAME value in Coolify's
+# Notifications → Webhook custom-headers panel. See docs/audit/v1415-auto-deploy.md.
+# DEPLOY_WEBHOOK_SECRET=""

.env.production.example

@@ -0,0 +1,117 @@
+# =============================================================================
+# HealthLog -- production .env example
+# =============================================================================
+# Mirrors `scripts/env-manifest.json`. The `pnpm check-env --file
+# .env.production.example` CI step (see `.github/workflows/env-check.yml`)
+# enforces every variable declared `required: true` in the manifest has a
+# non-empty placeholder here, so a contributor who introduces a new
+# required var without updating this file fails the workflow.
+#
+# Placeholders are syntactic only -- replace with real secrets before
+# deploying. The check-env presence rule treats any non-empty,
+# non-whitespace string as "set", so the `<placeholder>` style below
+# satisfies the manifest without leaking a usable credential.
+#
+# Generate the two crypto secrets locally with:
+#   $ openssl rand -hex 32
+# =============================================================================
+
+
+# -----------------------------------------------------------------------------
+# Core -- required for boot
+# -----------------------------------------------------------------------------
+DATABASE_URL="postgresql://healthlog:<password>@db:5432/healthlog?schema=public"
+POSTGRES_PASSWORD="<openssl rand -base64 24>"
+NEXT_PUBLIC_APP_URL="https://healthlog.example.com"
+APP_URL="https://healthlog.example.com"
+ENCRYPTION_KEY="<openssl rand -hex 32>"
+API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
+
+
+# -----------------------------------------------------------------------------
+# Withings OAuth -- optional integration
+# -----------------------------------------------------------------------------
+# WITHINGS_CLIENT_ID=""
+# WITHINGS_CLIENT_SECRET=""
+# WITHINGS_WEBHOOK_SECRET=""
+
+
+# -----------------------------------------------------------------------------
+# WHOOP -- optional integration
+# -----------------------------------------------------------------------------
+# The WHOOP app client id/secret are per-user BYO-keys: each user registers
+# their own WHOOP developer app and pastes the client id/secret into Settings
+# (stored encrypted in the DB). There is therefore no WHOOP_CLIENT_ID/SECRET.
+#
+# WHOOP_WEBHOOK_SECRET is the instance-level secret carried as the trailing
+# path segment of the webhook URL AND used to verify the WHOOP HMAC body
+# signature. WHOOP_REDIRECT_URI overrides the derived
+# `${NEXT_PUBLIC_APP_URL}/api/whoop/callback` when the public URL differs.
+# WHOOP_WEBHOOK_SECRET="<openssl rand -hex 32>"
+# WHOOP_REDIRECT_URI=""
+
+
+# -----------------------------------------------------------------------------
+# APNs -- iOS push (optional, all-or-none)
+# -----------------------------------------------------------------------------
+# APNS_KEY_ID=""
+# APNS_TEAM_ID=""
+# APNS_BUNDLE_ID=""
+# APNS_KEY=""        # OR APNS_KEY_FILE -- either one satisfies the manifest
+# APNS_KEY_FILE=""
+
+
+# -----------------------------------------------------------------------------
+# Deploy webhook -- Coolify -> HealthLog auto-deploy feedback
+# -----------------------------------------------------------------------------
+# DEPLOY_WEBHOOK_SECRET=""
+
+
+# -----------------------------------------------------------------------------
+# TLS leaf pin monitor -- alarm when the pinned leaf certificate rotates
+# -----------------------------------------------------------------------------
+# The native client SPKI-pins the served TLS leaf. Set this to the
+# known-good leaf pin(s) so the monitor can alarm on a rotation. The value
+# is base64(sha256(DER subjectPublicKeyInfo)); comma-separate to hold both
+# the current and the next pin during a dual-pin renewal window. See
+# docs/ops/tls-cert-pin.md for extraction + the re-pin runbook.
+# TLS_LEAF_SPKI_PINS=""
+
+
+# -----------------------------------------------------------------------------
+# Off-host backups -- all-or-none
+# -----------------------------------------------------------------------------
+# BACKUP_S3_ENDPOINT=""
+# BACKUP_S3_BUCKET=""
+# BACKUP_S3_ACCESS_KEY=""
+# BACKUP_S3_SECRET_KEY=""
+# BACKUP_ENCRYPTION_KEY=""
+
+
+# -----------------------------------------------------------------------------
+# FHIR health-record export -- optional
+# -----------------------------------------------------------------------------
+# Per-export ceiling on the number of MedicationAdministration rows in the
+# FHIR Bundle. The report window already scopes the set; this is a coarse
+# safety ceiling on the serialised Bundle size. Bounded 1..50000; any unset
+# or out-of-range value falls back to the default of 5000. Raise it only for
+# an unusual multi-year, many-medication workload.
+# FHIR_MAX_MEDICATION_ADMINISTRATIONS="5000"
+
+
+# -----------------------------------------------------------------------------
+# Dashboard snapshot -- BUILD-TIME toggle (default ON)
+# -----------------------------------------------------------------------------
+# The dashboard hydrates every above-the-fold tile from the single
+# `GET /api/dashboard/snapshot` cell so the whole strip shares one
+# completion moment. This is the default and the desired behaviour.
+#
+# `NEXT_PUBLIC_*` vars are inlined into the client bundle at BUILD time,
+# not read at runtime -- so this has NO effect on the prebuilt GHCR
+# image and is intentionally absent from the `docker-compose.yml`
+# runtime `environment:` whitelist. To fall back to the legacy
+# four-cell path you must rebuild the image with the var set to "false":
+#
+#   $ NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false pnpm build   # or a Dockerfile ARG
+#
+# NEXT_PUBLIC_DASHBOARD_SNAPSHOT="false"

.githooks/pre-commit

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+#
+# v1.4.31 — Pre-commit hook: OpenAPI spec drift check.
+#
+# v1.4.30 PR push failed CI on first attempt because the two new
+# MeasurementType enums (WALKING_STEADINESS, AUDIO_EXPOSURE_EVENT)
+# weren't reflected in `docs/api/openapi.yaml`. A separate
+# `chore(openapi): regenerate the public spec` commit was needed
+# before the checks turned green. This hook catches that drift
+# locally so a contributor sees the regeneration prompt at commit
+# time instead of after a CI round-trip.
+#
+# Behaviour:
+#   - Runs only when the staged diff touches a file that is likely
+#     to invalidate the OpenAPI spec (Zod schemas under
+#     src/lib/openapi/ or src/lib/validations/, or API route
+#     handlers under src/app/api/).
+#   - Reruns `pnpm openapi:generate` quietly and re-stages the
+#     regenerated spec if the file diverged.
+#   - Exits non-zero only if regeneration fails entirely.
+#
+# Install via `bash scripts/install-hooks.sh` (idempotent) or
+# `git config core.hooksPath .githooks` from the repo root.
+
+set -euo pipefail
+
+# Skip in non-interactive contexts (CI doesn't commit through this
+# path anyway — the security.yml workflow runs `pnpm openapi:check`
+# server-side). The check still fires under `git commit` from a
+# terminal.
+if [ -n "${CI:-}" ]; then
+  exit 0
+fi
+
+# Only run when relevant files are staged. The spec is generated
+# from Zod schemas + route registrations; nothing else can
+# legitimately move it.
+staged_files="$(git diff --cached --name-only --diff-filter=ACMRT)"
+if ! echo "$staged_files" | grep -qE '^(src/(lib/openapi|lib/validations|app/api)/|scripts/generate-openapi\.ts$)'; then
+  exit 0
+fi
+
+echo "[openapi pre-commit] Checking the spec against the staged schema changes…"
+
+# Quick path: run the comparison-only `check-openapi.ts`. If the
+# generated and committed forms match, exit fast.
+if pnpm --silent openapi:check >/dev/null 2>&1; then
+  exit 0
+fi
+
+echo "[openapi pre-commit] Drift detected — regenerating docs/api/openapi.yaml."
+if ! pnpm --silent openapi:generate; then
+  echo "::error::pnpm openapi:generate failed. Fix the underlying error before committing."
+  exit 1
+fi
+
+# Re-stage the regenerated spec so the commit-in-flight carries it.
+git add docs/api/openapi.yaml
+echo "[openapi pre-commit] Spec regenerated and re-staged. Continuing the commit."
+exit 0

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# Funding links for the GitHub "Sponsor" button.
+custom: ["https://buymeacoffee.com/mbombeck"]

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,77 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly in HealthLog.
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. Before submitting, please:
+
+        - Check that the issue isn't already in the [issue tracker](https://github.com/MBombeck/HealthLog/issues).
+        - For security issues, do **not** open a public issue — see [SECURITY.md](https://github.com/MBombeck/HealthLog/blob/main/SECURITY.md).
+        - For usage / configuration questions, the [docs](https://docs.healthlog.dev) are usually faster.
+  - type: input
+    id: version
+    attributes:
+      label: HealthLog version
+      description: Output of `/api/version` or the tag of the GHCR image you're running.
+      placeholder: "1.4.19"
+    validations:
+      required: true
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment type
+      options:
+        - Self-hosted (Docker)
+        - Self-hosted (manual)
+        - Local development
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear, concise description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Numbered steps the maintainer can follow to see the bug locally.
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / screenshots
+      description: Paste any relevant log output (redact secrets) or attach screenshots. Wide-event logs from `/admin/app-logs` are useful.
+      render: shell
+  - type: input
+    id: browser
+    attributes:
+      label: Browser / OS (if applicable)
+      placeholder: "Firefox 142 on macOS 14.5 / Chrome 128 on Android 14"
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checks
+      options:
+        - label: I confirmed this is not a duplicate of an existing issue.
+          required: true
+        - label: I redacted any secrets, tokens, or personal data from logs.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://docs.healthlog.dev
+    about: Setup, configuration, and feature documentation. Most usage questions are answered here.
+  - name: Security advisory
+    url: https://github.com/MBombeck/HealthLog/security/advisories/new
+    about: Report a security vulnerability privately. See SECURITY.md for the full policy.
+  - name: Discussions
+    url: https://github.com/MBombeck/HealthLog/discussions
+    about: Open-ended questions, ideas you want to brainstorm, and "is this the right approach?" threads.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,60 @@
+name: Feature request
+description: Suggest a new feature, integration, or enhancement.
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Feature ideas welcome. HealthLog is a personal-health PWA — the bar for inclusion is high (privacy-first, offline-capable, self-hostable). Use this template to propose something concrete; for open-ended discussion, prefer a [Discussion](https://github.com/MBombeck/HealthLog/discussions) thread.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user problem does this feature solve? "I want to track X but..." is a great opening.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would the feature work from the user's perspective? Sketches / mocks welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds exist today, and why are they insufficient?
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      multiple: true
+      options:
+        - Web (PWA)
+        - iOS app (v1.5+)
+        - API
+        - Admin
+        - Notifications
+        - AI Insights
+        - Withings integration
+        - moodLog integration
+        - Self-hosting / Docker
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else the maintainer should know — links, related issues, prior art.
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checks
+      options:
+        - label: I confirmed this is not a duplicate of an existing feature request.
+          required: true
+        - label: I'm proposing a feature, not asking a usage question (those go to Discussions or the docs).
+          required: true

.github/ISSUE_TEMPLATE/translation.yml

@@ -0,0 +1,81 @@
+name: Translation feedback
+description: Report a wording, grammar, or register problem in HealthLog's AI-initial locales (FR / ES / IT / PL).
+title: "[Translation] "
+labels: ["i18n", "translation-feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        HealthLog ships German and English as maintainer-curated translations. French, Spanish, Italian, and Polish ship as **AI-initial translations** — the prose passes the locale-integrity test (full key parity, no empty values) but has not been hand-reviewed for register or regional vocabulary.
+
+        This template captures concrete fixes you would like to see. Phrasing nuance, regional vocabulary (e.g. "Tú" vs "Usted"), gendered forms, and domain-specific health terms are all in scope. The maintainer applies fixes during the regular release cycle.
+
+        For wholly new locale requests (e.g. "please add Portuguese"), open a [Discussion](https://github.com/MBombeck/HealthLog/discussions) instead.
+  - type: dropdown
+    id: locale
+    attributes:
+      label: Locale
+      options:
+        - French (fr)
+        - Spanish (es)
+        - Italian (it)
+        - Polish (pl)
+        - Other (specify under "Surface")
+    validations:
+      required: true
+  - type: textarea
+    id: surface
+    attributes:
+      label: Where you saw it
+      description: |
+        Page / component / dialog name. Include the route (e.g. `/insights`, `/settings/notifications`) and, if possible, the i18n key from the rendered DOM (open DevTools, look for the visible string).
+      placeholder: |
+        Route: /insights/blood-pressure
+        Component: blood-pressure trend card header
+        Key (if known): insights.bp.trendCard.title
+    validations:
+      required: true
+  - type: textarea
+    id: current
+    attributes:
+      label: Current wording
+      description: Paste the exact phrase as it appears in the app today.
+    validations:
+      required: true
+  - type: textarea
+    id: suggested
+    attributes:
+      label: Suggested wording
+      description: |
+        How should it read instead? Include reasoning if the change is more than a typo — register (formal vs. informal), regional vocabulary, medical terminology, or grammar.
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind of issue
+      options:
+        - Grammar / spelling
+        - Wrong word (translation error)
+        - Awkward / unnatural phrasing
+        - Wrong register (too formal / too casual)
+        - Medical terminology
+        - Regional vocabulary
+        - Untranslated string (English fall-through)
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Screenshots, links to related issues, related strings on the same page, etc.
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checks
+      options:
+        - label: I confirmed this is not a duplicate of an existing translation issue.
+          required: true
+        - label: My suggestion respects the maintainer's editorial voice (professional, neutral, plain prose — no marketing-speak).
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,44 @@
+<!-- Thanks for opening a PR. Please fill in the sections below. -->
+
+## Summary
+
+<!-- 1-3 sentences: what changed and why. -->
+
+## Type of change
+
+<!-- Tick all that apply. -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation only
+- [ ] Test / CI / tooling
+- [ ] Refactor (no functional change)
+
+## Test plan
+
+<!-- How was this verified? Manual steps, automated tests, screenshots for UI changes. -->
+
+- [ ]
+- [ ]
+
+## Screenshots (UI changes only)
+
+<!-- Drop before/after screenshots or a short screen recording. Mobile + desktop where relevant. -->
+
+## Checklist
+
+- [ ] Targets the `develop` branch (not `main` — see [CONTRIBUTING.md](../CONTRIBUTING.md))
+- [ ] `pnpm typecheck` passes locally
+- [ ] `pnpm lint` passes locally
+- [ ] `pnpm test` passes locally
+- [ ] `pnpm format:check` passes locally
+- [ ] `pnpm build` passes locally
+- [ ] User-facing strings go through `t("key")` with both `messages/en.json` and `messages/de.json` updated
+- [ ] No secrets, personal data, or maintainer-name references in committed files
+- [ ] Updated `CHANGELOG.md` if user-visible
+- [ ] Updated `docs/audit/` or `docs.healthlog.dev` if behavior or self-hosting docs change
+
+## Linked issues
+
+<!-- Closes #123, Refs #456 -->

.github/dependabot.yml

@@ -10,3 +10,13 @@ updates:
         applies-to: security-updates
         update-types:
           - "patch"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3

.github/workflows/dependabot-auto-merge.yml

@@ -12,11 +12,11 @@ jobs:
     if: github.actor == 'dependabot[bot]'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: "pnpm"

.github/workflows/docker-publish.yml

@@ -1,8 +1,20 @@
 name: Build & Publish Docker Image
 
+# v1.4.34 IW-A — release pipeline fires on tag pushes only. Earlier
+# releases triggered the workflow twice on each cut: the squash-merge
+# to `main` and the corresponding `v*` tag push landed within a second
+# of each other and each kicked off its own build. Both runs ended
+# green and produced the same image at the same SHA with overlapping
+# tag sets (the main run added `latest`, the tag run added the
+# semver tags), but the duplication doubled GHCR CI minutes for
+# every release. Dropping `push.branches: [main]` collapses the
+# pipeline to a single run per release tag. The `latest` rule in
+# the metadata-action (`type=raw,value=latest,...`) now keys on
+# the v* tag presence so each release still refreshes the `latest`
+# alias in the same run. PR + workflow_dispatch triggers stay so
+# the image still builds on PR validation and manual reruns.
 on:
   push:
-    branches: [main]
     tags: ["v*"]
   pull_request:
     branches: [main]
@@ -13,27 +25,69 @@ env:
   IMAGE_NAME: ${{ github.repository }}
 
 # Cancel in-progress runs when a new commit is pushed to the same ref.
+# Different ref types (tag vs PR head) don't share a group, so a tag
+# build and a concurrent PR build won't cancel each other.
 concurrency:
   group: docker-publish-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  build-and-push:
-    name: Build & push multi-arch image
-    runs-on: ubuntu-latest
+  # ── Stage 1 ────────────────────────────────────────────────────────
+  # Build each architecture on its own native GitHub-hosted runner so
+  # Next.js's static-page workers run on real silicon instead of QEMU
+  # user-mode emulation. The v1.4.16 C5 attempt at
+  # `platforms: linux/amd64,linux/arm64` on a single amd64 runner
+  # deterministically SIGILL-crashed Next 15's static export under
+  # qemu-arm64 (`Next.js build worker exited with code: null and signal:
+  # SIGILL`); v8's optimising tier emits instructions qemu cannot
+  # reliably translate. ubuntu-24.04-arm is a standard GitHub-hosted
+  # arm64 runner, free for public repositories, and native — no qemu in
+  # the loop.
+  #
+  # Each platform pushes its layer set by digest only (`outputs: push-by-digest=true`).
+  # The `merge` job below stitches the two digests into a multi-arch
+  # manifest in a third step, so consumers see a single tag that
+  # auto-selects on `docker pull` per local platform.
+  build:
+    name: Build ${{ matrix.platform }}
+    runs-on: ${{ matrix.runner }}
+    # 25 min wall clock — native amd64 build finished inside 12 min
+    # at v1.4.24; the native arm64 path is comparable. The qemu-arm64
+    # hang at 47 min on `[linux/amd64 runner 2/14]` is what motivated
+    # this matrix in the first place.
+    timeout-minutes: 25
     permissions:
       contents: read
       packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+            cache_scope: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            cache_scope: arm64
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up QEMU (multi-arch)
-        uses: docker/setup-qemu-action@v3
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
+
+      # GHCR rejects repository refs with uppercase letters. `IMAGE_NAME`
+      # is derived from `github.repository`, which preserves the case of
+      # the GitHub org/user (`MBombeck/HealthLog`). `docker/metadata-action`
+      # lowercases its `images:` input transparently, so the legacy
+      # single-job workflow worked; the multi-arch matrix now feeds
+      # `outputs:` of build-push-action directly and needs the lowercase
+      # form there too. Resolve it once at the top of the job and reuse
+      # via $GITHUB_ENV.
+      - name: Lowercase image ref
+        run: |
+          echo "IMAGE_REF=${REGISTRY}/${IMAGE_NAME,,}" >> "$GITHUB_ENV"
 
       # Skip login on PRs from forks — they don't have package:write.
       # Image is built but not pushed in that case.
@@ -45,17 +99,202 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Compute image labels
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE_REF }}
+          labels: |
+            org.opencontainers.image.title=HealthLog
+            org.opencontainers.image.description=Self-hosted health-tracking PWA
+            org.opencontainers.image.licenses=AGPL-3.0-only
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+
+      # v1.4.27 B3 — GeoLite2-City + GeoLite2-ASN databases are too large
+      # (~80 MB combined) to vendor in git. `scripts/fetch-geolite2.sh`
+      # downloads both editions into `assets/geolite2/` so the Dockerfile
+      # COPY at line 78 picks them up.
+      #
+      # Two intentional paths:
+      #   - `MAXMIND_LICENSE_KEY` unset → emit a `::warning::`, drop a
+      #     `.empty` marker into the assets directory so the Dockerfile
+      #     COPY still has a non-empty source, and continue cleanly. The
+      #     runtime resolver in `src/lib/geo.ts` detects the marker on
+      #     first lookup and emits a one-shot admin notification — the
+      #     maintainer hears about the gap from the running app rather
+      #     than from a red CI badge that blocks every release.
+      #   - `MAXMIND_LICENSE_KEY` set → run `fetch-geolite2.sh` and
+      #     fail the build if it errors. The "Verify GeoLite2 databases"
+      #     step below adds a belt-and-braces assertion that both MMDB
+      #     files landed in `assets/geolite2/` before the Dockerfile
+      #     COPY reads the directory, so v1.4.28-era silent fallback
+      #     (offlineGeoEnabled: false on both nodes after a tag build)
+      #     can no longer ship.
+      #
+      # To enable the offline feature, set the secret under repo
+      # Settings → Secrets and variables → Actions and redeploy.
+      - name: Fetch GeoLite2 databases
+        env:
+          MAXMIND_LICENSE_KEY: ${{ secrets.MAXMIND_LICENSE_KEY }}
+        run: |
+          if [ -z "$MAXMIND_LICENSE_KEY" ]; then
+            echo "::warning::MAXMIND_LICENSE_KEY secret is unset. The image will ship without the offline GeoLite2 databases; the runtime resolver continues to fall back to the online ipwho.is provider and will send a one-shot admin notification on first use. To enable the offline tier, set MAXMIND_LICENSE_KEY under repo Settings → Secrets and variables → Actions."
+            mkdir -p assets/geolite2
+            touch assets/geolite2/.empty
+            exit 0
+          fi
+          ./scripts/fetch-geolite2.sh
+
+      # Build-time assertion: with the license key present, both MMDB
+      # files must land in `assets/geolite2/` before the Dockerfile
+      # COPY at line 78 picks them up. The fetch script already fails
+      # loud on a curl / tarball error, but a stale `.empty` marker
+      # from a previous keyless run or a workspace-cache surprise could
+      # otherwise survive into the image — this step is the operator
+      # guarantee that "key set" really means "MMDBs in the image".
+      #
+      # `secrets.*` is not available in step-level `if:` expressions,
+      # so we surface the presence flag through env and gate inline.
+      - name: Verify GeoLite2 databases
+        env:
+          MAXMIND_LICENSE_KEY: ${{ secrets.MAXMIND_LICENSE_KEY }}
+        run: |
+          if [ -z "$MAXMIND_LICENSE_KEY" ]; then
+            echo "MAXMIND_LICENSE_KEY unset — verification skipped (offline geo tier intentionally absent on this build)."
+            exit 0
+          fi
+          missing=()
+          for mmdb in GeoLite2-City.mmdb GeoLite2-ASN.mmdb; do
+            if [ ! -s "assets/geolite2/$mmdb" ]; then
+              missing+=("$mmdb")
+            fi
+          done
+          if [ "${#missing[@]}" -gt 0 ]; then
+            echo "::error::MAXMIND_LICENSE_KEY is set but the following GeoLite2 MMDB files are missing or empty in assets/geolite2/: ${missing[*]}. The Dockerfile would COPY them into /opt/geolite2/ in the final image, leaving the offline geo tier disabled at runtime. Investigate the previous 'Fetch GeoLite2 databases' step before retrying."
+            exit 1
+          fi
+          if [ -f assets/geolite2/.empty ]; then
+            echo "::error::Stale .empty marker present in assets/geolite2/ despite MAXMIND_LICENSE_KEY being set. The runtime resolver would treat the image as missing the offline tier. Investigate the previous 'Fetch GeoLite2 databases' step before retrying."
+            exit 1
+          fi
+          city_size="$(stat -c%s assets/geolite2/GeoLite2-City.mmdb)"
+          asn_size="$(stat -c%s assets/geolite2/GeoLite2-ASN.mmdb)"
+          echo "::notice::GeoLite2 MMDBs verified — GeoLite2-City.mmdb ${city_size} bytes; GeoLite2-ASN.mmdb ${asn_size} bytes."
+
+      # Per-ref + per-platform gha cache scope. Tag builds warm-start
+      # off main's last good layer set for the same platform; tag and
+      # main builds at the same SHA do not contend on writes, and
+      # amd64 / arm64 caches stay isolated from each other (a stale
+      # arm64 layer never poisons an amd64 build).
+      - name: Build & push by digest
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # v1.4.43 B11 — thread the tag ref into the build as
+          # NEXT_PUBLIC_APP_VERSION. The Dockerfile picks it up as an
+          # ARG/ENV and /api/version reads it at runtime. The build-arg
+          # becomes part of the BuildKit layer cache key, so a release
+          # tag bump invalidates every downstream layer that depends on
+          # it (`pnpm build`) and the prior release's version string
+          # can never survive a cache hit into the new image.
+          build-args: |
+            NEXT_PUBLIC_APP_VERSION=${{ github.ref_name }}
+          outputs: |
+            type=image,name=${{ env.IMAGE_REF }},push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
+          cache-from: |
+            type=gha,scope=build-${{ matrix.cache_scope }}-${{ github.ref_name }}
+            type=gha,scope=build-${{ matrix.cache_scope }}-main
+          cache-to: type=gha,mode=max,scope=build-${{ matrix.cache_scope }}-${{ github.ref_name }}
+          provenance: true
+          sbom: true
+
+      # Persist the per-platform digest so the `merge` job can stitch
+      # both into a single multi-arch manifest. One artifact per
+      # platform avoids upload races.
+      - name: Export digest
+        if: github.event_name != 'pull_request'
+        run: |
+          mkdir -p /tmp/digests
+          digest='${{ steps.build.outputs.digest }}'
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-artifact@v7
+        with:
+          name: digest-${{ matrix.cache_scope }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ── Stage 2 ────────────────────────────────────────────────────────
+  # Stitch the per-platform digests into a single multi-arch manifest
+  # under all the tags `docker/metadata-action` would normally apply.
+  # `docker buildx imagetools create` is a manifest-only operation —
+  # no layers are re-uploaded, the existing per-platform digests are
+  # referenced in place. This is the same end state as the
+  # single-buildx `platforms:` path would produce, just assembled in
+  # the registry instead of on one cross-emulated runner.
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    needs: [build]
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Download digest artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      # GHCR requires the repository ref to be lowercase. See the same
+      # step in the `build` job above for the longer rationale.
+      - name: Lowercase image ref
+        run: |
+          echo "IMAGE_REF=${REGISTRY}/${IMAGE_NAME,,}" >> "$GITHUB_ENV"
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Compute image tags & labels
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          images: ${{ env.IMAGE_REF }}
           tags: |
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=match,pattern=v(.+),group=1
+            type=ref,event=tag
+            # v1.4.34 IW-A — release pipeline fires on `v*` tag pushes
+            # only (the `push.branches: [main]` trigger was dropped to
+            # eliminate the per-release double-build). `is_default_branch`
+            # is false for tag refs, so the prior condition stopped
+            # refreshing the `latest` alias once main pushes no longer
+            # trigger the workflow. Enable on every release tag that
+            # does not carry a pre-release suffix (`-rc.1`, `-beta.2`,
+            # etc.) so each stable release rotates the `latest` alias
+            # while pre-release tags stay off it.
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-') }}
             type=sha,prefix=sha-,format=short
           labels: |
             org.opencontainers.image.title=HealthLog
@@ -63,16 +302,111 @@ jobs:
             org.opencontainers.image.licenses=AGPL-3.0-only
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
 
-      - name: Build & push image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: ./Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          provenance: true
-          sbom: true
+      - name: Create multi-arch manifest
+        working-directory: /tmp/digests
+        run: |
+          # shellcheck disable=SC2046,SC2086
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.IMAGE_REF }}@sha256:%s ' *)
+
+      - name: Inspect published manifest
+        run: |
+          docker buildx imagetools inspect '${{ env.IMAGE_REF }}:${{ steps.meta.outputs.version }}'
+
+      # Phase C2 (v1.4.15): trigger Coolify deploy automatically once GHCR has
+      # the new image. Removes the manual SSH + force-pull recipe documented
+      # in `.planning/phase-8-report.md`.
+      #
+      # Runs only on the publish path (push to `main` or to a `v*` tag), never
+      # on PRs. `continue-on-error: true` because the image is *already*
+      # published to GHCR by the time we reach this step — a Coolify-side
+      # outage must not retroactively fail the build. Marc still has the
+      # manual recipe as fallback.
+      #
+      # Required GitHub repository secrets (set by the maintainer once):
+      #   COOLIFY_WEBHOOK = full deploy URL incl. ?uuid=...&force=false
+      #   COOLIFY_TOKEN   = Bearer token from Coolify UI -> Keys & Tokens
+      # Both secrets are referenced exclusively here. If either is unset, the
+      # step short-circuits to a skip rather than calling Coolify with empty
+      # auth.
+      #
+      # v1.4.26 P6-3 — maintainer toggle.
+      # Three releases in a row shipped via the host-side SSH-retag fallback
+      # because the secrets above silently absent + the warn-only skip
+      # below let the workflow stay green. The `vars.COOLIFY_AUTO_DEPLOY`
+      # repository variable now distinguishes the two intended modes:
+      #
+      #   COOLIFY_AUTO_DEPLOY=on  →  if secrets present, deploy; if absent,
+      #                              FAIL the step so the maintainer sees the
+      #                              missing-secret gap on the next release.
+      #   COOLIFY_AUTO_DEPLOY=off →  unconditional skip with a notice. Use
+      #                              this when the host-side SSH recipe is
+      #                              the intended deploy path.
+      #   (unset / any other)     →  warn-and-skip (legacy behaviour).
+      #
+      # Set the variable under repo Settings → Secrets and variables →
+      # Actions → Variables (NOT Secrets — it is intentionally readable).
+      - name: Trigger Coolify deploy
+        continue-on-error: true
+        env:
+          COOLIFY_WEBHOOK: ${{ secrets.COOLIFY_WEBHOOK }}
+          COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
+          COOLIFY_AUTO_DEPLOY: ${{ vars.COOLIFY_AUTO_DEPLOY }}
+          IMAGE_VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          mode="${COOLIFY_AUTO_DEPLOY:-}"
+          if [ "$mode" = "off" ]; then
+            echo "::notice::COOLIFY_AUTO_DEPLOY=off — skipping registry deploy hook. Maintainer uses the host-side SSH recipe instead."
+            exit 0
+          fi
+          if [ -z "$COOLIFY_WEBHOOK" ] || [ -z "$COOLIFY_TOKEN" ]; then
+            if [ "$mode" = "on" ]; then
+              echo "::error::COOLIFY_AUTO_DEPLOY=on but COOLIFY_WEBHOOK or COOLIFY_TOKEN secret is missing. Set both under repo Settings → Secrets and variables → Actions, or set COOLIFY_AUTO_DEPLOY=off to silence."
+              exit 1
+            fi
+            echo "::warning::COOLIFY_WEBHOOK or COOLIFY_TOKEN secret missing — skipping auto-deploy. Configure in repo Settings → Secrets to enable, or set the COOLIFY_AUTO_DEPLOY variable to 'off' to silence this warning."
+            exit 0
+          fi
+          # v1.4.31 — wait for GHCR cache propagation before firing
+          # the Coolify webhook. Five releases in a row (v1.4.27
+          # through v1.4.30.1) the webhook reported "finished" but
+          # Coolify still pulled the prior `:latest` digest. The
+          # `docker buildx imagetools create` + `inspect` steps
+          # above confirm the manifest exists at registry-write time,
+          # but GHCR's CDN edges can take 30-90 s to propagate the
+          # new digest. The webhook fires inside that window, so
+          # Coolify pulls "latest" while the edge still serves the
+          # prior digest, gets "no change", and returns success.
+          # See `.planning/round-coolify-auto-deploy-fix-2026-05-16.md`
+          # for the full root-cause + remediation note.
+          echo "Waiting 90 s for GHCR cache propagation before triggering Coolify (image: $IMAGE_VERSION)…"
+          sleep 90
+          # v1.4.22 C3 — force=true tells Coolify to skip its image-cache
+          # and re-pull the registry digest. If the maintainer's secret
+          # URL already carries a `?force=` query, leave it alone;
+          # otherwise append `?force=true` (or `&force=true` if other
+          # query params are present) so doc-only deploys still trigger
+          # a registry-digest check.
+          deploy_url="$COOLIFY_WEBHOOK"
+          if ! echo "$deploy_url" | grep -q "force="; then
+            if echo "$deploy_url" | grep -q "?"; then
+              deploy_url="${deploy_url}&force=true"
+            else
+              deploy_url="${deploy_url}?force=true"
+            fi
+          fi
+          echo "Triggering Coolify deploy for ref ${{ github.ref_name }} (sha ${GITHUB_SHA::7})"
+          response=$(curl --silent --show-error --max-time 30 \
+            --write-out "\n__HTTP_STATUS__:%{http_code}" \
+            --request GET "$deploy_url" \
+            --header "Authorization: Bearer $COOLIFY_TOKEN")
+          status="${response##*__HTTP_STATUS__:}"
+          body="${response%__HTTP_STATUS__:*}"
+          echo "Coolify response (HTTP $status):"
+          echo "$body"
+          if [ "$status" -lt 200 ] || [ "$status" -ge 300 ]; then
+            echo "::error::Coolify deploy webhook returned HTTP $status — image is published, but auto-deploy did not fire. Marc: deploy manually via SSH recipe in .planning/phase-8-report.md."
+            exit 1
+          fi
+          echo "::notice::Coolify auto-deploy webhook fired at $(date -u +%FT%TZ) for ref ${{ github.ref_name }} (sha ${GITHUB_SHA::7}). If /api/version doesn't reach the new tag within ~60s, see .planning/coolify-auto-deploy-howto.md."
+          echo "Coolify deploy queued — awaiting outgoing notification webhook to /api/internal/deploy-webhook for final status."

.github/workflows/e2e.yml

@@ -0,0 +1,81 @@
+name: e2e
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel in-progress runs when a new commit lands on the same PR.
+concurrency:
+  group: e2e-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: healthlog
+          POSTGRES_PASSWORD: healthlog
+          POSTGRES_DB: healthlog
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U healthlog"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgresql://healthlog:healthlog@localhost:5432/healthlog?schema=public
+      ENCRYPTION_KEYS: '{"v1":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'
+      ENCRYPTION_ACTIVE_KEY_ID: v1
+      API_TOKEN_HMAC_KEY: ci-hmac-key-32-bytes-min-padding-x
+      AUTH_RP_NAME: HealthLog
+      AUTH_RP_ID: localhost
+      AUTH_RP_ORIGIN: http://localhost:3000
+      NODE_ENV: production
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm db:migrate:deploy
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            playwright-${{ runner.os }}-
+
+      - run: pnpm exec playwright install --with-deps chromium
+
+      - run: pnpm exec next build
+
+      - run: pnpm exec playwright test
+        env:
+          E2E_BASE_URL: http://localhost:3000
+
+      - name: Upload Playwright HTML report on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.github/workflows/env-check.yml

@@ -0,0 +1,73 @@
+name: Env-manifest <-> example lockstep
+
+# v1.4.43 B5 -- enforce that `.env.production.example` stays in lockstep
+# with `scripts/env-manifest.json`. A contributor adding a new required
+# variable to the manifest must also add a placeholder to the example
+# file in the same PR, otherwise the workflow fails with a grep-friendly
+# list of missing required vars. Optional vars are reported but do not
+# fail the build -- they exist for operator discovery, not deploy
+# blocking.
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  env-check:
+    name: pnpm check-env against .env.production.example
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Assert example file exists
+        run: |
+          if [ ! -f .env.production.example ]; then
+            echo "::error::.env.production.example is missing -- contributors must keep this file in lockstep with scripts/env-manifest.json. See docs/ops/env-check.md."
+            exit 1
+          fi
+
+      # The check-env script exits non-zero when at least one required
+      # variable from the manifest is missing/empty in the example file.
+      # We additionally grep the rendered output for `[MISSING-REQUIRED]`
+      # rows and surface them as GitHub Actions error annotations so the
+      # PR reviewer can see the missing var names without expanding the
+      # log.
+      - name: pnpm check-env --file .env.production.example
+        id: check
+        run: |
+          set +e
+          OUT=$(pnpm --silent check-env --file .env.production.example)
+          EC=$?
+          echo "$OUT"
+          if [ $EC -ne 0 ]; then
+            echo ""
+            echo "::group::Missing required variables"
+            echo "$OUT" | grep -E '^\s*\[MISSING-REQUIRED\]' | while IFS= read -r line; do
+              name=$(echo "$line" | sed -E 's/.*\[MISSING-REQUIRED\] ([A-Z0-9_]+).*/\1/')
+              echo "::error file=.env.production.example::Required env var $name missing from .env.production.example -- add a placeholder so the file stays in lockstep with scripts/env-manifest.json."
+            done
+            echo "::endgroup::"
+            echo ""
+            echo "::error::pnpm check-env reported missing required variables in .env.production.example. Either add a placeholder for each missing var, or downgrade the manifest entry to required:false if the variable is genuinely optional. See docs/ops/env-check.md."
+            exit $EC
+          fi

.github/workflows/integration.yml

@@ -0,0 +1,40 @@
+name: Integration tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm test:integration
+        env:
+          # The integration suite boots a Postgres testcontainer and points
+          # Prisma at it via DATABASE_URL set inside `tests/integration/setup.ts`.
+          # These env vars satisfy code paths that read them at module load.
+          #
+          # ENCRYPTION_KEY MUST be quoted: YAML 1.2 parses an unquoted run of
+          # zeros as the integer 0, which then arrives in `process.env` as the
+          # string "0" — failing crypto's hex/base64 length check and breaking
+          # the backups + integration-status suites for 50+ runs (regression
+          # since v1.4.13). Quoting forces a literal scalar.
+          API_TOKEN_HMAC_KEY: "integration-tests-do-not-use-in-prod"
+          ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
+          SESSION_SECRET: "integration-tests"

.github/workflows/knip.yml

@@ -0,0 +1,36 @@
+name: Knip
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  knip:
+    name: Dead-code gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      # v1.4.42 — exports + types tiers promoted to enforcing. The
+      # `knip.json` ignore-block carries the shadcn UI surface and the
+      # `src/lib/validations/**` contract types; everything else has
+      # to clear or get justified there.
+      - run: pnpm knip --reporter compact

.github/workflows/no-todo-markers.yml

@@ -0,0 +1,39 @@
+name: No TODO markers
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  # Product code is currently zero TODO / FIXME / XXX / HACK markers and
+  # the convention is to keep it that way — open a real follow-up issue
+  # instead of leaving a marker in the source. This gate fails fast if a
+  # future contributor reintroduces the pattern.
+  grep:
+    name: Forbidden marker grep
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Scan src/ for TODO/FIXME/XXX/HACK markers
+        run: |
+          # Tests are exempt — they can legitimately reference an outstanding
+          # ticket via a TODO; `src/generated/` is third-party output from
+          # `prisma generate` and is regenerated on every db:generate.
+          if grep -rEn "\b(TODO|FIXME|XXX|HACK)\b" src/ \
+              --include='*.ts' \
+              --include='*.tsx' \
+              --exclude-dir='__tests__' \
+              --exclude-dir='generated' \
+              --exclude='*.test.ts' \
+              --exclude='*.test.tsx'; then
+            echo "::error::TODO/FIXME/XXX/HACK markers detected in product code — open a follow-up issue instead."
+            exit 1
+          fi
+          echo "::notice::No forbidden markers in product code."

.github/workflows/post-publish-verify.yml

@@ -0,0 +1,144 @@
+name: Post-publish verify
+
+# Informational reachability gate that runs AFTER `Build & Publish Docker
+# Image` finishes a `main` (or tag) build. Pulls the just-published image
+# from GHCR and probes:
+#   - the image manifest is fetchable (i.e. the push actually completed)
+#   - the container starts and `/api/version` returns the expected version
+#   - the container's `/api/health` endpoint reports OK
+#
+# Does NOT block deploys — `continue-on-error` is set on every probe step
+# so a transient registry blip doesn't go red. This is a smoke gate the
+# v1.4.14 release would have caught: the main push appeared to "succeed"
+# from the deploy host's POV, but the host had to pull the tag image
+# because main's manifest never finished pushing.
+#
+# Triggered by `workflow_run` so it only runs after the build workflow
+# actually completes — chaining via `needs:` would force the build into
+# the same workflow file.
+
+on:
+  workflow_run:
+    workflows: ["Build & Publish Docker Image"]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      image_tag:
+        description: "GHCR image tag to verify (defaults to `main`)"
+        required: false
+        default: "main"
+
+permissions:
+  contents: read
+  packages: read
+
+jobs:
+  verify:
+    name: Pull + smoke-test published image
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Skip if the upstream build itself failed — there's nothing to verify.
+    # Manual dispatch always runs.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: healthlog
+          POSTGRES_PASSWORD: healthlog
+          POSTGRES_DB: healthlog
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U healthlog"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - name: Resolve image tag
+        id: tag
+        run: |
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            echo "tag=${{ github.event.inputs.image_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=main" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Pull image
+        id: pull
+        continue-on-error: true
+        run: |
+          IMAGE="ghcr.io/${{ github.repository }}:${{ steps.tag.outputs.tag }}"
+          echo "Pulling $IMAGE"
+          docker pull "$IMAGE"
+          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
+
+      - name: Start container
+        if: steps.pull.outcome == 'success'
+        id: run
+        continue-on-error: true
+        run: |
+          # Minimal env to satisfy the strict-env validators on boot.
+          docker run -d --name healthlog-verify \
+            --network host \
+            -e DATABASE_URL='postgresql://healthlog:healthlog@localhost:5432/healthlog?schema=public' \
+            -e ENCRYPTION_KEYS='{"v1":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}' \
+            -e ENCRYPTION_ACTIVE_KEY_ID=v1 \
+            -e API_TOKEN_HMAC_KEY=verify-hmac-key-32-bytes-padding-x \
+            -e AUTH_RP_NAME=HealthLog \
+            -e AUTH_RP_ID=localhost \
+            -e AUTH_RP_ORIGIN=http://localhost:3000 \
+            -e NODE_ENV=production \
+            -e HEALTHLOG_PROCESS_TYPE=web \
+            -e PORT=3000 \
+            "${{ steps.pull.outputs.image }}"
+
+          # Wait up to 60 s for the server to start answering.
+          for i in $(seq 1 30); do
+            if curl -sf -o /dev/null http://localhost:3000/api/version; then
+              echo "ready after ${i}*2s"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "::warning::Container did not become ready within 60 s"
+          docker logs healthlog-verify || true
+          exit 1
+
+      - name: Probe /api/version
+        if: steps.run.outcome == 'success'
+        continue-on-error: true
+        run: |
+          set -e
+          BODY=$(curl -sf http://localhost:3000/api/version)
+          echo "$BODY" | jq .
+          VER=$(echo "$BODY" | jq -r '.data.version // .version')
+          echo "::notice::published image ${{ steps.tag.outputs.tag }} reports version=$VER"
+
+      - name: Probe /api/health
+        if: steps.run.outcome == 'success'
+        continue-on-error: true
+        run: |
+          curl -sf http://localhost:3000/api/health | jq .
+
+      - name: Container logs (always)
+        if: always() && steps.run.outcome == 'success'
+        continue-on-error: true
+        run: docker logs healthlog-verify | tail -100
+
+      - name: Tear down
+        if: always()
+        continue-on-error: true
+        run: docker rm -f healthlog-verify || true

.github/workflows/security.yml

@@ -15,11 +15,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: "pnpm"
@@ -41,16 +41,32 @@ jobs:
       - name: Unit tests
         run: pnpm test
 
+      # OpenAPI spec drift gate — hard-fail (flipped from warn-only in v1.4.25).
+      #
+      # The Zod registry is the source of truth for the public API contract.
+      # Any route signature change must be reflected in `docs/api/openapi.yaml`
+      # so downstream consumers (notably the v1.5 iOS Swift codegen) stay in
+      # lockstep. If this step fails, run `pnpm openapi:generate` locally and
+      # commit the regenerated spec.
+      - name: OpenAPI spec drift check
+        run: |
+          pnpm openapi:generate
+          if ! git diff --exit-code docs/api/openapi.yaml; then
+            echo "::error::OpenAPI drift detected — regenerate the spec via 'pnpm openapi:generate' and commit the result. The Zod registry under src/lib/openapi/ is the source of truth for the public API contract."
+            exit 1
+          fi
+          echo "::notice::OpenAPI spec in sync with Zod source schemas."
+
   dependency-audit:
     name: Dependency Audit
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: "pnpm"
@@ -66,12 +82,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Gitleaks secret scan
-        uses: gitleaks/gitleaks-action@v2
+        uses: gitleaks/gitleaks-action@v3
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -81,7 +97,7 @@ jobs:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Build Docker image
         run: docker build -t healthlog:scan .

.gitignore

@@ -11,6 +11,15 @@
 # testing
 /coverage
 
+# HAR captures from production debugging (may contain auth headers/cookies)
+*.har
+
+# playwright e2e
+/test-results
+/playwright-report
+/playwright/.cache
+/e2e/setup/storageState.json
+
 # next.js
 /.next/
 /out/
@@ -39,3 +48,35 @@ next-env.d.ts
 
 # prisma generated
 /src/generated/prisma
+
+# v1.4.43 QoL (L3) — generated at build time by
+# scripts/generate-sw-version.mjs; loaded by public/sw.js to key
+# the cache-version baseline.
+/public/sw-version.js
+
+# v1.4.27 B3 — MaxMind GeoLite2 databases are fetched at build time
+# via `scripts/fetch-geolite2.sh`. Too large for git; license key
+# required. The folder + a `.gitkeep` are tracked so the Dockerfile
+# COPY target always exists.
+/assets/geolite2/*.mmdb
+
+# AI session artefacts (kept locally, not committed)
+/docs/superpowers/
+.claude/
+.cursor/
+.codex/
+.aider*
+
+# Planning scratch — all internal per-release reports, QA findings, ad-hoc
+# backlog, and the iOS coordination channel. These are internal working
+# notes; everything user-facing lives in the public surfaces (README,
+# CHANGELOG, docs/). Kept on disk for the working session, never tracked.
+/.planning/
+
+# Docs scratch — temporary spec drafts that live in the repo only
+# while a release is in flight.
+/docs/ios/
+
+# Per-release internal forensic notes — retained locally for
+# traceability across releases but not part of the public docs surface.
+/docs/audit/

.gitleaks.toml

@@ -0,0 +1,33 @@
+# Gitleaks configuration. Extends the built-in default ruleset and adds
+# a project-specific allowlist for false-positives that gitleaks 8.x flags
+# as "generic-api-key" inside test fixtures.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Project-wide ignores for test fixtures and known non-secret tokens"
+
+paths = [
+  # All test files contain hardcoded fake tokens / idempotency-keys.
+  '''(^|/)__tests__/''',
+  '''\.test\.ts$''',
+  # OpenAPI spec contains example tokens (`hlk_example…`) used to document the schema.
+  '''^docs/api/openapi\.yaml$''',
+]
+
+# Substring matches — anything matching is treated as non-secret regardless of file.
+regexes = [
+  # Idempotency-Key request-header values are random UUIDs / opaque strings,
+  # not secrets. The header name itself just trips the generic-api-key rule.
+  '''idempotency-key''',
+  # Allow the placeholder prefix used in OpenAPI examples + docs.
+  '''hlk_example''',
+  # i18n caption keys for the briefing-driven trend charts are dotted message
+  # keys, not secrets — one trips the generic-api-key entropy heuristic.
+  '''insights\.trendsRow\.caption''',
+]
+
+# Specific commit fingerprints from prior false-positive findings (kept for reproducibility).
+# Empty by default; populate via `gitleaks detect --report-path` if a future regression
+# triggers the same false-positive on a stable commit hash.
+stopwords = []

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@latest", "mcp"]
+    }
+  }
+}

AGENTS.md

@@ -6,21 +6,33 @@ Instructions for AI coding agents (OpenAI Codex, Claude Code, Cursor, etc.) work
 
 **HealthLog** — a personal health-tracking web app (weight, blood pressure, pulse, mood, medication compliance) with Withings integration, moodLog.app sync, Dracula-themed UI, mobile-first PWA design.
 
-**Status**: v1.2.0 (Custom Thresholds, Blood Glucose, Dashboard Customization, Built-in Feedback, Multi-Provider AI). See GitHub Issues for open tasks.
+**Status**: v1.4.0 (released) → v1.4.1 in progress. v1.4.0 shipped
+the UI guidelines + Skeleton/EmptyState primitives, medical-citations
+consolidation, the per-route `/settings/[section]` split, the
+status-first admin grid + aggregator endpoint, five new "Test
+connection" buttons, AI insights with inline charts via allowlisted
+metric tokens, off-host encrypted S3 backup, encryption-key
+versioning + rotation CLI, optional `HEALTHLOG_PROCESS_TYPE` worker /
+web split, and short-lived 24h access tokens with refresh-token
+rotation for native API clients. v1.4.1 follows up with per-section
+admin component extraction (the inner monolith into one file per
+panel), a Postgres testcontainers integration test suite, and a
+Playwright + axe-core E2E foundation. See GitHub Releases +
+CHANGELOG.md for the full feature timeline.
 
 ## Tech Stack
 
 | Layer           | Technology           | Version | Notes                                                                   |
 | --------------- | -------------------- | ------- | ----------------------------------------------------------------------- |
 | Framework       | Next.js (App Router) | 16      | TypeScript strict, RSC default, `"use client"` only for interactivity   |
-| ORM             | Prisma               | 7.4     | Uses `PrismaPg` adapter, **not** `url` in schema — see gotchas below    |
+| ORM             | Prisma               | 7.8     | Uses `PrismaPg` adapter, **not** `url` in schema — see gotchas below    |
 | Database        | PostgreSQL           | 16      | Docker Compose service, port 5432, user `healthlog`                     |
 | UI              | shadcn/ui (new-york) | latest  | Components in `src/components/ui/`                                      |
 | Theme           | Dracula              | —       | CSS variables in `globals.css`, dark mode default, `--dracula-*` tokens |
 | CSS             | Tailwind             | 4       | CSS-first config (`@import "tailwindcss"` syntax)                       |
 | Data fetching   | TanStack Query       | 5       | Provider in `src/components/providers.tsx`                              |
 | Validation      | Zod                  | v4      | Import as `zod/v4` (not `zod`)                                          |
-| Testing         | Vitest               | latest  | Config in `vitest.config.ts`                                            |
+| Testing         | Vitest               | latest  | Config in `vitest.config.mts`                                           |
 | Package manager | pnpm                 | latest  | **Not** npm or yarn                                                     |
 | Node            | 20.x                 | via nvm |                                                                         |
 | Job queue       | pg-boss              | 12      | Named import `{ PgBoss }`, see gotchas                                  |
@@ -38,6 +50,11 @@ pnpm lint             # ESLint
 pnpm format           # Prettier format
 pnpm format:check     # Prettier check
 pnpm typecheck        # TypeScript strict check
+pnpm openapi:generate # Regenerate docs/api/openapi.yaml from Zod schemas
+pnpm openapi:check    # Verify the spec is in sync (CI gate)
+
+# Git hooks (one-time per clone)
+bash scripts/install-hooks.sh    # Activates .githooks/, including the OpenAPI pre-commit check
 
 # Tests
 pnpm test             # Run all tests (vitest)
@@ -66,7 +83,7 @@ src/
 │   ├── layout.tsx                # Root layout (viewport-fit: cover for PWA)
 │   ├── page.tsx                  # Dashboard (/) with quick entry dropdown
 │   ├── globals.css               # Dracula theme CSS variables
-│   ├── admin/page.tsx            # Admin panel
+│   ├── admin/page.tsx            # Admin shell — 77 LOC, mounts the per-section components from src/components/admin/
 │   ├── auth/login/page.tsx       # Login
 │   ├── auth/register/page.tsx    # Registration
 │   ├── achievements/page.tsx     # Gamification achievements
@@ -76,10 +93,11 @@ src/
 │   ├── medications/page.tsx      # Medications management
 │   ├── notifications/page.tsx    # Notification preferences matrix
 │   ├── onboarding/page.tsx       # 4-step guided onboarding
-│   ├── settings/page.tsx         # All settings (13 sections, ~2100 lines)
+│   ├── settings/page.tsx         # 308-redirects /settings → /settings/account
+│   ├── settings/[section]/page.tsx  # Per-section route shell (account, integrations, notifications, dashboard, ai, api, advanced, about)
 │   ├── mood/page.tsx             # Mood tracking
 │   ├── targets/page.tsx          # Target values dashboard
-│   └── api/                      # ~60 API route files (see docs/api.md)
+│   └── api/                      # 100+ API route files (admin, auth, measurements, medications, mood, insights, integrations, ingest, dashboard, feedback, tokens, notifications, monitoring, …)
 │       ├── mood-entries/         # Mood CRUD
 │       ├── import/               # JSON data import
 │       ├── doctor-report/        # Doctor report data aggregation
@@ -93,7 +111,10 @@ src/
 │   ├── measurements/             # Measurement form, list
 │   ├── mood/                     # Mood form, mood list
 │   ├── charts/                   # Recharts wrappers, compliance charts
-│   ├── insights/                 # AI insights card
+│   ├── insights/                 # AI insights cards (status, advisor)
+│   ├── gamification/             # Achievement cards, progress
+│   ├── settings/                 # Per-route Settings section components (one per /settings/[section])
+│   ├── admin/                    # Per-route Admin section components (system-status, integrations, monitoring, reminders, users, audit, danger-zone, feedback)
 │   └── monitoring/               # Umami, GlitchTip bootstrap
 ├── lib/
 │   ├── db.ts                     # Prisma client singleton
@@ -109,6 +130,13 @@ src/
 │   ├── notifications/            # Dispatcher, types, senders (telegram, ntfy, web-push)
 │   ├── jobs/                     # pg-boss worker (reminders, insights, backups)
 │   ├── validations/              # Zod schemas (shared between API + client)
+│   ├── ai/                       # Multi-provider client (OpenAI, Anthropic, local OpenAI-compat)
+│   ├── feedback/                 # In-app feedback + optional GitHub escalation
+│   ├── gamification/             # Achievement definitions + progress
+│   ├── insights/                 # Insight pipeline + prompts
+│   ├── logging/                  # Wide Events: builder, context, sampler, transports, background
+│   ├── moodlog/                  # moodLog.app webhook + sync
+│   ├── monitoring/               # Umami / GlitchTip server-side hooks
 │   └── withings/                 # Withings OAuth client + sync service
 ├── hooks/
 │   └── use-auth.ts               # useAuth(), useLogout() hooks
@@ -117,8 +145,8 @@ messages/
 ├── de.json                       # German translations (primary UI language)
 └── en.json                       # English translations
 prisma/
-├── schema.prisma                 # Database schema (23 models)
-└── migrations/                   # Migration files (0001–0018)
+├── schema.prisma                 # Database schema (26 models)
+└── migrations/                   # Migration files (0001–0025; latest: refresh_tokens + user_locale_drift_fix)
 prisma.config.ts                  # Prisma config (DB URL lives here, NOT in schema)
 public/
 ├── sw.js                         # Service worker (Web Push + offline caching)
@@ -165,17 +193,17 @@ These are hard-won lessons. Ignoring them will cause errors:
 - **Zod v4**: Import from `"zod/v4"`, not `"zod"`.
 - **jsPDF**: Client-side only. Import dynamically in browser context. Used with `jspdf-autotable` plugin.
 
-### Settings Page
+### Settings & Admin (per-route layout, v1.4)
 
-- One large file (~2100 lines), 13 sections. Sidebar switches to "settings mode" showing section shortcuts.
-- Sections scroll-to with highlight animation (`section-highlight` CSS class).
-- Section IDs: `profil`, `sprache`, `sicherheit`, `telegram`, `ntfy`, `web-push`, `insights`, `withings`, `api`, `export`, `protokoll`, `daten`.
+- **Settings**: 8 routes under `/settings/[section]` — `account`, `integrations`, `notifications`, `dashboard`, `ai`, `api`, `advanced`, `about`. The legacy `/settings` 308-redirects to `/settings/account`. Sidebar deep-links and the `<a href="/settings#anchor">` patterns from 1.3 still resolve via the redirect.
+- **Admin**: `src/app/admin/page.tsx` is now a 77-LOC shell that mounts the per-section components in `src/components/admin/`. Status-card grid lives in `status-card-grid.tsx`. The aggregator endpoint `/api/admin/status-overview` returns the six-card summaries in one batched query.
+- ESLint `react-hooks/set-state-in-effect` is **strict** now (was non-blocking when the settings monolith carried inline-effect state-setters). Use lazy `useState(() => …)` for localStorage reads, TanStack Query for data fetches.
 
 ### Insights Page
 
-- Large file (~1800+ lines), 7 content sections with AI summaries.
+- Large file (~1750 lines), 7 content sections with AI summaries.
 - Sticky horizontal chip navigation (`InsightsSectionNav` component) with IntersectionObserver for active state tracking.
-- Section IDs: `general`, `bp`, `weight`, `pulse`, `mood`, `medications`, `bmi`.
+- Section IDs: `general`, `bp`, `weight`, `pulse`, `mood`, `meds`, `bmi`.
 - Each section has `scroll-mt-28` for header offset on scroll.
 
 ### Sidebar
@@ -192,8 +220,8 @@ These are hard-won lessons. Ignoring them will cause errors:
 
 ### Notification System
 
-- **Channels**: `TELEGRAM`, `NTFY`, `WEB_PUSH` (DB: `NotificationChannel`).
-- **Event types**: `MEDICATION_REMINDER`, `MEASUREMENT_ANOMALY`, `COMPLIANCE_LOW`, `WITHINGS_SYNC_FAILED`, `SYSTEM_ALERT`.
+- **Channels**: `telegram`, `ntfy`, `web_push` — stored as plain `String` on `NotificationChannel.type` (no Prisma enum; the canonical list lives in `src/lib/notifications/types.ts`).
+- **Event types**: `medication_reminder`, `measurement_anomaly`, `compliance_low`, `withings_sync_failed`, `system_alert` — also `String` on `NotificationPreference.eventType`. Source of truth is the discriminated union in `src/lib/notifications/types.ts`.
 - **Opt-out model**: Preferences default to ON (enabled) when no `NotificationPreference` row exists.
 - **Dispatcher**: `src/lib/notifications/dispatcher.ts` checks channel enabled + preference per event type.
 - **Telegram**: Inline buttons (Take/Skip/Snooze 1h/Snooze 3h), pre-end window reminders (30 min before), message auto-cleanup after 24h.
@@ -207,7 +235,7 @@ These are hard-won lessons. Ignoring them will cause errors:
 
 ## Database Models (Prisma)
 
-23 models: `User`, `Passkey`, `Session`, `AuthChallenge`, `Measurement`, `Medication`, `MedicationSchedule`, `MedicationIntakeEvent`, `ReminderPhaseConfig`, `TelegramReminderMessage`, `TelegramScheduledDeletion`, `ApiToken`, `WithingsConnection`, `MoodEntry`, `AppSettings`, `Feedback`, `AuditLog`, `NotificationChannel`, `NotificationPreference`, `PushSubscription`, `DataBackup`, `UserAchievement`, `RateLimit`.
+26 models: `User`, `Passkey`, `Session`, `AuthChallenge`, `Measurement`, `Medication`, `MedicationSchedule`, `MedicationIntakeEvent`, `ReminderPhaseConfig`, `TelegramReminderMessage`, `TelegramScheduledDeletion`, `ApiToken`, `RefreshToken`, `WithingsConnection`, `MoodEntry`, `AppSettings`, `Feedback`, `AuditLog`, `NotificationChannel`, `NotificationPreference`, `PushSubscription`, `DataBackup`, `UserAchievement`, `RateLimit`, `Device`, `IdempotencyKey`. (`RefreshToken` added in v1.4.0 alongside the native-client 24h access-token / refresh-token rotation flow.)
 
 ## When Making Changes
 

CLAUDE.md

@@ -1,109 +1,195 @@
-# CLAUDE.md
+# Contributor notes
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Working notes for anyone (human or otherwise) editing this repository. Skim before the first PR; refer back when a convention question comes up. Pair with `README.md` (the public face) and `CHANGELOG.md` (the release history); this file is the maintainer's operating manual.
 
-## Project
+## What HealthLog is
 
-HealthLog — a personal health-tracking PWA (weight, blood pressure, pulse, mood, medication compliance) with Withings integration, moodLog.app sync, Dracula-themed UI, mobile-first design, offline caching, and doctor report PDF export.
+Self-hosted personal-health-tracking PWA: weight, blood pressure, pulse, body composition, glucose, sleep, mood, medication compliance. Withings + Apple Health sync, multi-provider AI Insights (BYOK or local), doctor-report PDF, native iOS client in public beta. Single `docker compose up`, Postgres-backed, AES-256-GCM at rest. AGPL-3.0. Current line: v1.12.x.
 
-## Commands
+## Voice and privacy
 
-```bash
-# Development
-pnpm dev              # Start dev server (http://localhost:3000)
-pnpm build            # Production build
-pnpm lint             # ESLint
-pnpm format           # Prettier format
-pnpm format:check     # Prettier check
-pnpm typecheck        # TypeScript strict check
+Hard rules for every committed artefact — commit messages, CHANGELOG entries, PR bodies, code comments, GitHub release notes, docs site copy. Treat these as the project's public face.
 
-# Tests
-pnpm test             # Run all tests (vitest)
-pnpm test:watch       # Watch mode
+- **Voice.** English. Maintainer prose: present-tense, imperative for commits, factual for prose. No marketing tone, no apology tone, no "wow what a cool feature" framing. The voice is one human writing notes for the next.
+- **No assistant / tooling references.** Do not surface AI, agent, assistant, copilot, marathon, phase, wave, round, or session vocabulary into anything that lands on GitHub. The `Co-Authored-By` trailer on commits is fine — it is git metadata and the project accepts that convention; anywhere else, no.
+- **No personal data.** No real names (the maintainer's, a reporter's, or anyone else's). No live health figures, no live tenant identifiers, no real-account anchors. Generalise to "a self-hoster", "a user", "an operator", "an authenticated session", etc. The internal `.planning/*` files are gitignored and exempt; everywhere else in the repo, no.
 
-# Database
-pnpm db:generate      # Generate Prisma client
-pnpm db:migrate       # Create & apply migration (dev)
-pnpm db:migrate:deploy # Apply migrations (production)
-pnpm db:push          # Push schema without migration (prototyping)
-pnpm db:studio        # Prisma Studio GUI
+If a draft commit message or release note would violate one of the three, rewrite it before committing. The `git log` is more durable than today's task.
 
-# Docker
-docker compose up -d          # Start app + postgres
-docker compose logs -f app    # Tail app logs
+## Branch and release model
+
+`main` is the single trunk and is always releasable. There is no long-lived `develop` branch — the former one was retired and archived as the tag `archive/develop-pre-v1.5` (it carried no work absent from `main`; a long-lived integration branch has no role in a single-maintainer shop and only accrued back-merge debt). This is trunk-based development with release tags: short-lived branches off `main`, work always converges back onto `main`, and the immutable `vX.Y.Z` image built from a tag on `main` is the one source of truth — including for the OpenAPI contract the iOS client consumes.
+
+- **Trunk.** `main` always builds, passes CI, and is deployable. Every commit on it is a release commit (`chore(release): vX.Y.Z`), a release-branch merge, or a maintenance commit (docs, gitignore, audit findings) applied directly.
+- **A release** is built on a short-lived `release/vX.Y.Z` branch cut off `main` — built wave-by-wave, then opened as a PR `release/vX.Y.Z` → `main` with green CI, merged (merge-commit), and tagged `vX.Y.Z`. The tag push triggers `docker-publish.yml` (GHCR multi-arch + `:latest`). Deploy is manual (see `docs/ops/deploy.md`); after a deploy, verify `/api/version` (it returns `version` + `buildSha` + `builtAt`) on every target, since the `:latest` pull is the source of truth, not the queued deploy status. Delete the release branch after merge.
+- **Small standalone changes** (a single fix, a docs touch) can go through a short-lived `fix/X` / `feat/X` branch + PR, or directly onto `main` when the maintainer chooses — `main` is the target either way.
+- **Hotfixes** branch from `main` and merge straight back to `main`. There is no second long-lived line to forward-port to, so the old back-merge debt cannot recur by construction.
+- Never force-push `main` or any release branch. Never skip hooks (`--no-verify`). Never `--no-gpg-sign` unless explicitly asked.
+
+## Semver
+
+Prefer patch bumps. A release dominated by bug fixes plus additive features without breaking changes ships as `vX.Y.Z+1`, not `vX.Y+1.0`. Bumping minor is reserved for breaking changes, removed flags, deprecated routes, or multi-feature milestones framed as such (e.g. v1.5 = native iOS client + Apple Health integration). Pre-existing example: a `v1.5.0` cut was rerouted to `v1.4.14` mid-flight when the diff turned out to be bugfix-dominated.
+
+## Tech stack at a glance
+
+| Layer | Tech | Notes |
+|---|---|---|
+| Runtime | Node 22 (Alpine) + pnpm 10.31 | Node version fixed only by the Dockerfile base image; no `.nvmrc` or `engines`. |
+| Framework | Next.js 16.2.6 — App Router, `output: "standalone"` | SWC strips `console.*` in prod except `error/warn`. |
+| Language | TypeScript 6, `strict: true`, `moduleResolution: "bundler"` | Path alias `@/*` → `./src/*`. `scripts/` excluded from typecheck. |
+| UI | React 19.2.5 (exact), Tailwind 4, shadcn/ui (new-york style, zinc base), Radix, Lucide | Recharts 3 for charts — stays; replacement requires explicit approval. |
+| Persistence | PostgreSQL 16 + Prisma 7.8 — 61 models | Generated client at `src/generated/prisma`. Production image ships a separate `/opt/prisma-cli` install + `/opt/pg-boss` runtime install (see `Dockerfile:74-83`). |
+| Queue | pg-boss 12.18 | Cron + retry semantics live in Postgres tables; workers under `src/lib/jobs/`. |
+| Auth | `@simplewebauthn/server` 13, `@node-rs/argon2` 2 | Passkey + Argon2id password, server-side sessions in Postgres. |
+| Notifications | `@parse/node-apn` 8 (APNs), `web-push` 3 (VAPID), raw fetch for Telegram + ntfy | Per-channel `recordPushAttempt` row, hard-reject classification. |
+| Forms / validation | `react-hook-form` 7 + `zod` 4 + `@hookform/resolvers` + `zod-openapi` 5 | The Zod registry is the source of truth for `docs/api/openapi.yaml`. |
+| Testing | Vitest 4 (unit + integration), Playwright 1.60 (e2e), `@axe-core/playwright` | Integration runs against a `testcontainers/postgresql` Postgres 16. |
+| Container | Multi-stage Alpine Dockerfile, GHCR multi-arch (`amd64` + `arm64`) | `pull_policy: always` in `docker-compose.yml` is load-bearing — without it Docker re-uses the stale `:latest` digest. |
+
+More detail in `.planning/codebase/tech.md`, generated as part of the v1.5.2 codebase audit.
+
+## How a request flows
+
+```
+client
+  │ HTTP
+  ▼
+src/proxy.ts                         renamed from middleware.ts. Public-path allowlist,
+  │                                  demo-mode mutation block, server-side onboarding
+  │                                  redirect, worker-only refusal, request-id + nonce
+  │                                  generation, every security header.
+  ▼
+src/app/<route>/route.ts             every API route wraps in `apiHandler(...)`
+  │
+  ▼
+src/lib/api-handler.ts               WideEventBuilder + AsyncLocalStorage, auth resolver
+  │                                  (cookie OR Bearer), idempotency, error envelope,
+  │                                  GlitchTip forwarder. Cookie path can elevate to
+  │                                  admin via requireAdmin(); Bearer never can.
+  ▼
+handler body                         Zod parse (`safeParse` + `returnAllZodIssues`),
+  │                                  business logic, `annotate({ action, meta })`,
+  │                                  `auditLog()` for sensitive ops.
+  ▼
+src/lib/api-response.ts              `apiSuccess(data, meta?)` / `apiError(msg, status,
+  │                                  meta?)` — every response is `{ data, error, meta? }`.
+  ▼
+src/proxy.ts                         security headers attach, request-id echoes.
+  ▼
+client
 ```
 
-## Architecture
+The architecture map in `.planning/codebase/arch.md` walks each layer with file:line citations.
 
-- **Next.js 16** App Router with TypeScript strict. Pages are RSC by default; `"use client"` only for interactivity.
-- **Prisma 7** ORM with PostgreSQL (23 models). Uses `PrismaPg` adapter from `@prisma/adapter-pg`. Client singleton at `src/lib/db.ts`. Generated client at `src/generated/prisma/client` (note the `/client` suffix). Prisma config in `prisma.config.ts` (not in schema.prisma).
-- **shadcn/ui** components (new-york style) in `src/components/ui/`. Add new ones via `pnpm dlx shadcn@latest add <component>`.
-- **Dracula theme** via CSS variables in `globals.css`. Dark mode is default. Use `--dracula-*` tokens for chart colors.
-- **TanStack Query** for client-side data fetching. Provider in `src/components/providers.tsx`.
-- **Zod v4** (`zod/v4`) for all input validation (API routes and forms).
-- **API response envelope**: `{ data, error, meta }` via helpers in `src/lib/api-response.ts`.
-- **apiHandler** wraps ALL API route handlers (`src/lib/api-handler.ts`) — error handling, Wide Event logging, x-request-id propagation.
-- **Structured Logging** (Wide Events) in `src/lib/logging/` — one JSON event per request/operation via `WideEventBuilder` + `AsyncLocalStorage`. Tail sampling, stdout JSON + optional Loki Push.
-- **Vitest** for unit testing. Config in `vitest.config.ts`.
-- **pg-boss** (PostgreSQL-native) for job queue: medication reminders, insight caching, weekly data backups.
-- **jsPDF** + jspdf-autotable for client-side doctor report PDF generation (`src/lib/doctor-report-pdf.ts`).
-- **PWA offline** via service worker caching strategies in `public/sw.js` (cache-first for static, network-first for pages, network-only for API).
-- **Proxy route protection** — `src/proxy.ts` checks session cookie, enforces auth on all non-public paths. Next.js 16 uses proxy.ts (not middleware.ts).
+## Code conventions
 
-## Key Conventions
+- **RSC by default.** Server components are the default; add `"use client"` only when a hook, state, or browser API actually needs it.
+- **Every API route wraps in `apiHandler`.** Verified — zero exceptions in the current tree. Every body-accepting route runs Zod `safeParse` and returns 422 via `returnAllZodIssues` (multi-issue envelope sanitised against echoed input through `sanitiseZodIssues`).
+- **`userId` is always narrowed from session or Bearer.** No route accepts `userId` as a body field — it comes from `requireAuth()` and feeds the Prisma `where`. The batch endpoints (`/api/measurements/batch`, `/api/mood-entries/bulk`, `/api/medications/intake/bulk`, `/api/workouts/batch`) don't even declare a `userId` field in their Zod schemas.
+- **No mass assignment.** Every `prisma.X.{create,update}({ data: ... })` builds its `data` object field-by-field from `parsed.data`, never by spreading the parsed object whole. `tokens.create` hardcodes the narrow scope so the user-facing endpoint can never mint a wildcard token.
+- **`requireAdmin()` is cookie-only.** Bearer tokens — even with `["*"]` scope — cannot reach admin endpoints. This is a structural boundary at `src/lib/api-handler.ts:414-431`, not a runtime check that future code can soften.
+- **Raw SQL is parameter-bound or whitelist-spliced.** Every `$queryRaw` uses tagged-template parameters. Every `$queryRawUnsafe` / `$executeRawUnsafe` either passes positional `$N` placeholders with an argument array OR splices a value already asserted against a closed enum + regex (see `src/lib/rollups/measurement-rollups.ts:330-343`). Inline comments document the whitelist at the splice point.
+- **TanStack Query keys live in the centralised factory.** `src/lib/query-keys.ts` is the only legal source of `queryKey` / `mutationKey` arrays. The in-repo ESLint rule `healthlog/queryKey-factory` (set to `error`) flags any bare array. Same-key + different `queryFn` shape silently poisons the cache; the factory prevents it. Every read unwraps `(await res.json()).data` from the envelope.
+- **`annotate()` on every interesting code path.** Wide-event observability. Action names follow `<surface>.<noun>.<verb>` (`coach.budget.exceeded`, `measurement.batch.ingest`). Don't free-text in `meta` — pin the shape so dashboards stay stable.
+- **i18n keys exist for every `t()` call.** `i18n-call-site-coverage.test.ts` walks every `.ts(x)` under `src/`, extracts every `t("ns.key")` literal, and asserts each key resolves in `messages/en.json`. `i18n-locale-integrity.test.ts` propagates the EN guarantee across `de / en / es / fr / it / pl`. If a guard fails, fix the bundle, don't suppress the test.
+- **OpenAPI registry stays in sync.** Zod schemas carry `.meta()` annotations under `src/lib/openapi/`; `pnpm openapi:generate` emits `docs/api/openapi.yaml`. CI fails on drift. Re-run the generator after touching a request / response schema and commit the YAML alongside the Zod change.
+- **File naming.** Components and lib files: kebab-case (`daily-briefing.tsx`, `secure-cookie.ts`). Hooks: `use-` prefix kebab-case (`use-coach-prefs.ts`). React component exports stay PascalCase regardless of filename. The 18 PascalCase outliers under `src/components/medications/` + `src/components/onboarding/` are pre-existing drift and worth cleaning up when the surrounding files come up for edit.
 
-- Default locale is **English**. All code-level strings in English. UI text via i18n `t()` with German + English translations.
-- Timezone: `Europe/Berlin` for display, UTC in database.
-- Sensitive data (Withings tokens, API keys, VAPID private keys) encrypted with AES-256-GCM (`src/lib/crypto.ts`) before DB storage.
-- Passkeys are primary auth (SimpleWebAuthn v13). Sessions stored server-side in PostgreSQL.
-- All API mutations require authentication. External ingest uses Bearer token (hashed with SHA-256).
-- Rate limiting (in-memory sliding window) on auth and external-facing endpoints.
+## Tests and commands
 
-## File Layout
+- `pnpm typecheck` — `tsc --noEmit`. Required before every commit.
+- `pnpm lint` — ESLint flat config with `eslint-config-next` + the project's `healthlog/queryKey-factory` rule. One harmless warning in `withings/resume/__tests__/route.test.ts` is allowed; everything else should be clean.
+- `pnpm test` — Vitest 4 unit + component suite. Required before pushing a fix; full suite is fast (~30 s).
+- `pnpm test:integration` — Vitest against a `testcontainers/postgresql` Postgres 16. Needs Docker / OrbStack running. Slower but pins the contracts the unit-mocks can't.
+- `pnpm e2e` — Playwright against `pnpm exec next build` + Postgres. Heavy; CI runs it, locally only when touching UI flows.
+- `pnpm openapi:generate` — regenerates `docs/api/openapi.yaml` from the Zod registry. Run after any request / response schema change. CI's `openapi:check` fails the build on drift.
+- `pnpm check-env` — validates that `.env.production.example` covers every required variable. Wired into CI as `env-check.yml`.
+- `pnpm bundle-report` / `ANALYZE=1 pnpm build` — bundle inspection. Use when a feature adds material weight.
+- One-shot scripts live in `scripts/`. Run them via `pnpm dlx tsx scripts/<file>.ts` — the production standalone image strips `tsx` and the bare `pnpm tsx ...` invocation fails inside the container. Recurring tasks belong on pg-boss, not on a CLI script.
 
-- `src/app/` — pages and API routes (App Router)
-- `src/components/ui/` — shadcn/ui primitives
-- `src/components/layout/` — shell (sidebar-nav, topbar, mobile-nav, bottom-nav)
-- `src/components/medications/` — medication form, card, timeline
-- `src/components/measurements/` — measurement form, list
-- `src/components/mood/` — mood form, mood list
-- `src/components/charts/` — Recharts wrappers
-- `src/lib/logging/` — Wide Events structured logging (types, config, event-builder, context, sampler, transports, background)
-- `src/lib/api-handler.ts` — apiHandler wrapper, requireAuth(), requireAdmin(), HttpError
-- `src/lib/` — server utilities (db, crypto, auth, analytics, export, rate-limit, gravatar)
-- `src/lib/export.ts` — CSV/JSON export formatting (measurements, medications, mood)
-- `src/lib/doctor-report-pdf.ts` — client-side PDF generation (jsPDF, European medical format)
-- `src/lib/withings/` — Withings OAuth client and sync service
-- `src/lib/notifications/` — dispatcher, types, senders (telegram, ntfy, web-push)
-- `src/lib/jobs/` — pg-boss reminder worker (reminders, insights, data backups)
-- `src/lib/analytics/` — trend calculations, compliance, correlations
-- `src/lib/i18n/` — i18n context, config, locale detection
-- `src/lib/validations/` — Zod schemas shared between API + client
-- `src/hooks/` — React hooks (`use-auth`)
-- `messages/de.json` + `messages/en.json` — i18n translations
-- `prisma/schema.prisma` — database schema (23 models)
-- `prisma.config.ts` — Prisma config (DB URL here, not in schema)
-- `public/sw.js` — Service worker for Web Push notifications + offline caching
-- `docs/` — architecture, security, assumptions, ops, API docs, ADRs
-- `docs/STATUS.md` — Current project status + open tasks
-- `AGENTS.md` — AI agent instructions (Codex, Cursor, etc.)
+## Critical-files map
 
-## Important Patterns
+| Concern | File | What it owns |
+|---|---|---|
+| HTTP edge | `src/proxy.ts` | Public-path allowlist, demo-mode block, onboarding redirect, request-id + CSP nonce, every security header, worker-only refusal. |
+| API kit | `src/lib/api-handler.ts` (490 LOC) | `apiHandler` wrapper, `requireAuth` / `requireAdmin`, idempotency plumbing, GlitchTip forwarder. |
+| Response envelope | `src/lib/api-response.ts` | `apiSuccess` / `apiError`, `safeJson` (now with opt-in `maxBytes`), trusted-proxy IP resolver, `returnAllZodIssues` + `sanitiseZodIssues`. |
+| Crypto at rest | `src/lib/crypto.ts` | AES-256-GCM with versioned key ids, `extractKeyId`, fail-closed loader, rotation primitives. Rotation CLI: `scripts/rotate-encryption-key.ts`. |
+| Session | `src/lib/auth/session.ts` + `src/lib/auth/secure-cookie.ts` | Postgres-backed sessions, sliding 30-day expiry, `shouldEmitSecureCookie()` the one source of truth for the `Secure` flag (every cookie setter routes through it). |
+| Refresh tokens | `src/lib/auth/refresh-token.ts` | Per-device one-time-use rotation with reuse-detection that revokes the device's token family. |
+| Bearer tokens | `src/lib/auth/hmac.ts` + `src/lib/auth/issue-token.ts` | HMAC-SHA256 hashing under `API_TOKEN_HMAC_KEY`; no plaintext path; `lastUsedAt` updated fire-and-forget. |
+| Rollup tier | `src/lib/rollups/` | DAY / WEEK / MONTH / YEAR pre-aggregations. Read-swap pattern: try the rollup, fall back to live SQL only on coverage miss. Boot-time `rollup-full-backfill` queue handles new accounts. |
+| Compliance | `src/lib/analytics/compliance.ts` | Cadence-aware medication compliance — daysOfWeek + intervalWeeks honoured across the eight call sites that surface a rate (Coach prompt, BP-status gate, dashboard pillar, …). |
+| AI providers | `src/lib/ai/provider-chain.ts` + `src/lib/ai/{openai,anthropic,local,codex,mock}-client.ts` | Five providers, hand-rolled fetch over the documented wire (no vendor SDKs). Mock is not registered in `resolveProvider()` — production cannot reach it. |
+| Notification dispatcher | `src/lib/notifications/dispatcher.ts` + `src/lib/notifications/senders/` | APNs → Telegram → ntfy → Web Push cascade, hard-reject classification, `push_attempts` ledger with 90-day retention. |
+| Coach | `src/app/api/insights/chat/route.ts` + `src/lib/ai/coach/` | SSE stream, budget gate + per-user rate gate, refusal detector, snapshot builder, message persistence with `encryptedContent` Bytes column. |
+| OpenAPI | `src/lib/openapi/registry.ts` + `src/lib/openapi/routes.ts` | Source of truth for `docs/api/openapi.yaml`. |
+| Schema | `prisma/schema.prisma` (61 models) | `cuid()` PKs, `snake_case` columns via `@map`, encrypted columns mostly under `*Encrypted` (search the file). |
+| Compose | `docker-compose.yml` | `app` + `db`. Env-var whitelist under `environment:` — vars not listed never reach the container. `pull_policy: always` is load-bearing. |
 
-- Import Prisma client from `@/generated/prisma/client` (not `@/generated/prisma`)
-- Prisma 7 does NOT support `url = env("...")` in schema.prisma — use `prisma.config.ts`
-- Next.js 16 uses `proxy.ts` (not `middleware.ts`) — having both causes build error
-- SimpleWebAuthn v13 has no `@simplewebauthn/server/script/deps` — define Transport type inline
-- `zxcvbn-typescript` uses default export only (no named `zxcvbnAsync`/`zxcvbnOptions`)
-- pg-boss v12: `{ PgBoss }` named import, `localConcurrency` instead of `teamSize`, handler receives `Job<T>[]` array
-- **i18n**: All UI text uses `useTranslations()` hook with `t("section.key")`. Messages in `messages/en.json` (English, default) + `messages/de.json` (German, user-selectable). Keys missing in the active locale fall back to English; missing from both surfaces the raw key — the `src/lib/__tests__/i18n*.test.ts` suite guards against that. Numbers/dates go through `useFormatters()` — never hand-roll `Intl.*` with a fixed locale.
-- **Notifications**: 3 channels (Telegram, ntfy, Web Push). Dispatcher at `src/lib/notifications/dispatcher.ts`. Opt-out model (all events enabled by default)
-- **Gravatar**: Server-side SHA-256 hash via `src/lib/gravatar.ts`. URL returned in `/api/auth/me` response as `gravatarUrl` field
-- **Sidebar**: Collapsible (localStorage-persisted). Settings mode with section shortcuts. User section at bottom with three-dot dropdown menu
-- **ESLint**: Strict `react-hooks/set-state-in-effect` rule — avoid `setState` inside `useEffect`. Use lazy `useState()` initializer for localStorage reads
-- **Proxy route protection**: `src/proxy.ts` checks `healthlog_session` cookie; PUBLIC_PATHS array bypasses auth. Security headers (CSP, HSTS, X-Frame-Options) applied to all responses
-- **PWA safe area**: Root layout has `viewportFit: "cover"`. Bottom-nav uses `pb-[env(safe-area-inset-bottom)]` for iOS safe area
-- **Doctor report PDF**: Client-side via `src/lib/doctor-report-pdf.ts` (jsPDF). Data from `POST /api/doctor-report`. European medical format, German terminology
-- **Achievements**: Persistent in `UserAchievement` table. Computed on API call, new unlocks written to DB with stable `unlockedAt` timestamps
-- **Data backup**: pg-boss `data-backup` queue runs weekly (Sundays 03:00), stores JSON in `DataBackup` model
-- **Wide Events / Structured Logging**: `apiHandler()` wraps all API routes. Use `annotate()` from `@/lib/logging/context` for business-action annotations. Use `requireAuth()` / `requireAdmin()` from `@/lib/api-handler` (auto-annotates auth). Background jobs use `withBackgroundEvent()`. External calls tracked via `getEvent()?.addExternalCall()`. No `console.log` in production code — use event annotations instead. Env vars: `LOG_LEVEL`, `LOG_SAMPLE_RATE`, `LOG_SLOW_THRESHOLD_MS`, `LOG_INCLUDE_STACK`, `LOKI_ENDPOINT`, `LOKI_USERNAME`, `LOKI_PASSWORD`
+`.planning/codebase/arch.md` carries the full annotated walk for every section.
+
+## Security-relevant patterns
+
+The v1.5.2 audit produced `.planning/security-audit-v1.5.2.md` and a stack of per-domain findings under `.planning/security-audit-findings/`. The patterns worth preserving on future churn:
+
+- **Encryption: fail closed everywhere.** Missing keys, malformed JSON, unknown key ids — every path throws rather than silently writing plaintext. Operators rotating keys must keep the legacy entry in `ENCRYPTION_KEYS` until the rotation script reports zero remaining legacy rows. The script covers every `*Encrypted` column + `CoachMessage.encryptedContent` (Bytes) + `IntegrationStatus.lastError`.
+- **SSRF: input-time `isPublicUrl` is the floor.** The helper in `src/lib/validations/notifications.ts:64` catches every IPv4 / IPv6 alt-notation class (octal / hex / decimal IPv4, IPv4-mapped IPv6, IPv6 ULA, CGNAT, link-local, loopback, metadata). Use it for every outbound URL that comes from a user / admin input. DNS rebinding and the redirect-follow gap remain as architectural follow-ups (issues #217 + #218). Until those land, every NEW outbound `fetch()` that touches a user-controlled host must pin `redirect: "manual"` and an `AbortSignal.timeout`.
+- **Outbound egress goes through `safeFetch`.** `src/lib/safe-fetch.ts` is the one documented egress entry (`redirect: "manual"` + `AbortSignal.timeout(15_000)` defaults; opt into the connect-time DNS-rebinding pin with `requirePublicHost: true` for any operator- or user-supplied host). The in-repo ESLint rule `healthlog/safe-fetch-required` (set to `error`) bans raw `fetch(` under `src/lib/` + `src/app/` outside the wrapper internals and test files; same-origin relative-path (`/api/…`) client fetches are exempt by construction.
+- **Rate limits live in Postgres.** `src/lib/rate-limit.ts` uses a single atomic SQL upsert returning `{count, reset_at}`. Multi-instance correctness is structural. Bucket-key convention: `<surface>:${identifier}` where identifier is `userId` for authenticated routes and the trusted-proxy IP for anonymous. Anonymous auth surfaces use `checkAuthSurfaceRateLimit(...)` so a trust-violation collapses every anonymous caller into a single tight bucket rather than a free-for-all under the unknown-IP bucket.
+- **Webhooks: shared-secret + `timingSafeEqual` + per-source rate limit BEFORE secret verification.** Withings, Telegram, moodLog, the Coolify deploy webhook, and the CSP report endpoint all follow this exact pattern. The Withings path-segment secret is scrubbed from `http.path` / `http.route` by `redactSecrets()` via the `PATH_SECRET_PATHS` registry in `src/lib/logging/redact.ts:40`.
+- **Idempotency keys are user-scoped, length-bounded, and refuse to cache secret-shaped responses.** `src/lib/idempotency.ts`. A client cannot replay another user's idempotency key (composite unique index by `userId_key_method_path`). The cache helper refuses to persist a response body containing `hlk_` / `hlr_` / `sk-` patterns even if a future caller wraps an auth endpoint by mistake.
+- **CSP: strict, per-request nonce, surgical `connect-src`.** Production CSP gates third-party hosts to the routes that need them — AI hosts only on `/settings/ai/*`, `wbsapi.withings.net` only on `/settings/integrations/withings/*` + `/api/withings/*`. Exactly one `dangerouslySetInnerHTML` in the tree (the theme bootstrap in `src/app/layout.tsx`, nonce-bound, file-literal content). No markdown library installed anywhere; Coach / briefing / insights render as plain React text children. Don't add one without a security review of the renderer's HTML-allow defaults.
+- **No CORS headers anywhere.** Same-origin-only by construction. Adding `Access-Control-Allow-Origin: *` anywhere would silently open every authenticated endpoint to cross-origin POST; webhook routes accept cross-origin POSTs but they authenticate by header secret, not cookie.
+- **Redaction at the egress boundary, not at the call site.** `redactSecrets()` + `redactSensitiveFields()` + `redactOptional()` are applied centrally in `WideEventBuilder` and `reportToGlitchtip`. Don't add new redactor calls in handler bodies — extend the central denylists in `src/lib/observability/redact-payload.ts` and `src/lib/logging/redact.ts`.
+
+## Self-hosting gotchas
+
+These keep tripping operators; they're worth knowing before you push something that breaks them.
+
+- **`SESSION_COOKIE_SECURE`** controls the `Secure` flag on every cookie the app issues. Unset → flag tracks `NODE_ENV === "production"`. Set to `false` for LAN / Tailscale / VPN-only HTTP self-hosts where the operator deliberately serves plain HTTP. Set to `true` to force the flag even in dev. The compose `environment:` block must list it explicitly — vars not on the whitelist don't reach the container even when `.env` has them. v1.5.2 closed the missing-whitelist regression.
+- **`pull_policy: always`** in `docker-compose.yml` is load-bearing. Without it Docker keeps a stale `:latest` digest cached and silently skips the registry round-trip on `compose up`.
+- **`ENCRYPTION_KEYS` map vs legacy `ENCRYPTION_KEY`.** The map (`{"v1":"<hex>","v2":"<hex>"}` + `ENCRYPTION_ACTIVE_KEY_ID=v2`) is the modern path. The legacy single-key env var stays accepted as `v1`. Rotation playbook lives at `docs/ops/encryption-key-rotation.md`; do NOT drop a key from the map before the rotation script reports zero remaining rows on that key.
+- **GeoLite2 databases.** Operators run `scripts/fetch-geolite2.sh` with a MaxMind licence key before `docker build`; the image bakes the MMDBs into `/opt/geolite2/`. Without them the resolver falls back to online `ipwho.is` and the admin login overview surfaces "unknown" for offline lookups.
+- **APNs `.p8` key.** v1.4.47.x established `APNS_KEY_B64` as the env-var contract — pasting the PEM body verbatim through Coolify's `env_file` mangled the literal newlines. The key must be scoped "Sandbox & Production" in the Apple Developer Portal; a Sandbox-only key fails with `BadEnvironmentKeyInToken` on production builds.
+
+## iOS handoff
+
+The native SwiftUI client lives in a separate repository and rides public beta via TestFlight. Backend contract the iOS app speaks against is locked in `docs/api/openapi.yaml` and has been continuously validated since v1.4.23. Coordination notes worth knowing on the backend side:
+
+- `POST /api/measurements/batch` recognises `externalId` values starting with `stats:` (e.g. `stats:HKQuantityTypeIdentifierStepCount:YYYY-MM-DD`) as **overwrites** — a re-post replaces the row's value / unit / measuredAt / externalSourceVersion / deviceType / sleepStage. Every other externalId prefix (`uuid-*`, opaque HK identifiers) keeps the first-write-wins immutable contract because each sample is a canonical reading. Per-entry status field carries `"updated"` for an overwrite vs `"inserted"` for a fresh row.
+- Refresh-token rotation is per-device; reuse-detection revokes the family scoped to that device.
+- `requireAdmin()` is cookie-only by construction — a Bearer token, even with `["*"]` scope, cannot reach `/api/admin/*`. The iOS app is not an admin client.
+- The `clientManaged` opt-in on `PATCH /api/auth/me/notification-prefs` suppresses server-side `MEDICATION_REMINDER` APNs for clients that manage their own local reminders. The cron skips dose-due APNs when the flag is `true` and emits a `medication_reminder.suppressed_client_managed` wide-event annotation per skip.
+- `push_attempts` table holds the last 90 days of APNS / Web-Push / Telegram / NTFY delivery attempts (channel + eventType + result + reason + createdAt). The admin diagnostic endpoint at `/api/admin/notifications/diagnostic` surfaces masked device tokens + channel state + last 20 attempts for the calling user.
+- Any request / response schema change must regen `docs/api/openapi.yaml` and commit the result. CI fails on drift.
+
+## DO-NOTs
+
+- **No `--no-verify` on commits.** If a pre-commit hook fails, fix the cause; never bypass.
+- **No `--no-gpg-sign` unless explicitly asked.**
+- **No force-push to `main`** (or to release branches, by extension).
+- **No destructive git operations as shortcuts.** `git reset --hard`, `git clean -fd`, `git checkout .` etc. only when the maintainer asked or the state is unambiguously local-only.
+- **No assistant / planning vocabulary in any committed artefact** — see Voice and privacy above.
+- **No personal names** — the maintainer's, a reporter's, or anyone else's — in any committed artefact, including code comments referring to "the user who reported issue #X".
+- **No secret-shaped strings in `.env.example` or git history.** Pre-existing scan shows clean.
+- **No markdown library in dependencies.** Coach + briefing + insights render as React text children for XSS reasons; adding one is a security decision, not a UX one.
+- **No `Access-Control-Allow-Origin` headers** anywhere except the documented webhook surfaces — and those authenticate via header secret, not cookie.
+- **No `pnpm tsx scripts/foo.ts` in production.** The standalone image strips `tsx`. One-shot scripts run via `pnpm dlx tsx`; recurring tasks belong on pg-boss.
+- **No backwards-compatibility shims for hypothetical callers.** When a change is clean, make it cleanly; do not leave dead branches "in case" something we don't ship needs them.
+
+## Pointers
+
+| What | Where |
+|---|---|
+| Public face | `README.md` |
+| Release history | `CHANGELOG.md` |
+| Codebase audit (v1.5.2) | `.planning/codebase/{tech,arch,quality,concerns}.md` |
+| Security audit (v1.5.2) | `.planning/security-audit-v1.5.2.md` + `.planning/security-audit-findings/*` |
+| Operator runbooks | `docs/ops/` (deploy, encryption-key-rotation, env-check, backup-restore, migrations) |
+| Self-hosting guide | `docs/self-hosting/` |
+| Public API contract | `docs/api/openapi.yaml` |
+| Architecture diagrams | `docs/diagrams/` (rendered through `docs.healthlog.dev`) |
+| iOS coordination notes | `.planning/ios-coord/` |
+| Maintainer working notes | `.planning/PROJECT.md`, `.planning/ROADMAP.md`, `.planning/STATE.md` (gitignored release scratch lives alongside; the patterns are in `.gitignore`) |
+| Personal preferences + collaboration memory | `~/.claude/projects/-Users-marc-Projects-HealthLog/memory/MEMORY.md` (local to the maintainer's working copy; not in the repo) |

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at conduct@bombeck.io. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING-AI.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+HealthLog — a personal health-tracking PWA (weight, blood pressure, pulse, mood, medication compliance) with Withings integration, moodLog.app sync, Dracula-themed UI, mobile-first design, offline caching, and doctor report PDF export.
+
+## Commands
+
+```bash
+# Development
+pnpm dev              # Start dev server (http://localhost:3000)
+pnpm build            # Production build
+pnpm lint             # ESLint
+pnpm format           # Prettier format
+pnpm format:check     # Prettier check
+pnpm typecheck        # TypeScript strict check
+
+# Tests
+pnpm test             # Run all tests (vitest)
+pnpm test:watch       # Watch mode
+
+# Database
+pnpm db:generate      # Generate Prisma client
+pnpm db:migrate       # Create & apply migration (dev)
+pnpm db:migrate:deploy # Apply migrations (production)
+pnpm db:push          # Push schema without migration (prototyping)
+pnpm db:studio        # Prisma Studio GUI
+
+# Docker
+docker compose up -d          # Start app + postgres
+docker compose logs -f app    # Tail app logs
+```
+
+## Architecture
+
+- **Next.js 16** App Router with TypeScript strict. Pages are RSC by default; `"use client"` only for interactivity.
+- **Prisma 7** ORM with PostgreSQL (26 models). Uses `PrismaPg` adapter from `@prisma/adapter-pg`. Client singleton at `src/lib/db.ts`. Generated client at `src/generated/prisma/client` (note the `/client` suffix). Prisma config in `prisma.config.ts` (not in schema.prisma).
+- **shadcn/ui** components (new-york style) in `src/components/ui/`. Add new ones via `pnpm dlx shadcn@latest add <component>`.
+- **Dracula theme** via CSS variables in `globals.css`. Dark mode is default. Use `--dracula-*` tokens for chart colors.
+- **TanStack Query** for client-side data fetching. Provider in `src/components/providers.tsx`.
+- **Zod v4** (`zod/v4`) for all input validation (API routes and forms).
+- **API response envelope**: `{ data, error, meta }` via helpers in `src/lib/api-response.ts`.
+- **apiHandler** wraps ALL API route handlers (`src/lib/api-handler.ts`) — error handling, Wide Event logging, x-request-id propagation.
+- **Structured Logging** (Wide Events) in `src/lib/logging/` — one JSON event per request/operation via `WideEventBuilder` + `AsyncLocalStorage`. Tail sampling, stdout JSON + optional Loki Push.
+- **Vitest** for unit testing. Config in `vitest.config.mts`.
+- **pg-boss** (PostgreSQL-native) for job queue: medication reminders, insight caching, weekly data backups.
+- **jsPDF** + jspdf-autotable for client-side doctor report PDF generation (`src/lib/doctor-report-pdf.ts`).
+- **PWA offline** via service worker caching strategies in `public/sw.js` (cache-first for static, network-first for pages, network-only for API).
+- **Proxy route protection** — `src/proxy.ts` checks session cookie, enforces auth on all non-public paths. Next.js 16 uses proxy.ts (not middleware.ts).
+
+## Key Conventions
+
+- Default locale is **English**. All code-level strings in English. UI text via i18n `t()` with German + English translations.
+- Timezone: `Europe/Berlin` for display, UTC in database.
+- Sensitive data (Withings tokens, API keys, VAPID private keys) encrypted with AES-256-GCM (`src/lib/crypto.ts`) before DB storage.
+- Passkeys are primary auth (SimpleWebAuthn v13). Sessions stored server-side in PostgreSQL.
+- All API mutations require authentication. External ingest uses Bearer token (hashed with HMAC-SHA256 keyed by `API_TOKEN_HMAC_KEY`).
+- Rate limiting (in-memory sliding window) on auth and external-facing endpoints.
+
+## File Layout
+
+- `src/app/` — pages and API routes (App Router)
+- `src/components/ui/` — shadcn/ui primitives
+- `src/components/layout/` — shell (sidebar-nav, topbar, mobile-nav, bottom-nav)
+- `src/components/medications/` — medication form, card, timeline
+- `src/components/measurements/` — measurement form, list
+- `src/components/mood/` — mood form, mood list
+- `src/components/charts/` — Recharts wrappers
+- `src/components/settings/` — per-route Settings section components (one per `/settings/[section]`)
+- `src/components/admin/` — per-route Admin section components (system-status, integrations, monitoring, users, audit, danger-zone, feedback)
+- `src/lib/logging/` — Wide Events structured logging (types, config, event-builder, context, sampler, transports, background)
+- `src/lib/api-handler.ts` — apiHandler wrapper, requireAuth(), requireAdmin(), HttpError
+- `src/lib/` — server utilities (db, crypto, auth, analytics, export, rate-limit, gravatar)
+- `src/lib/export.ts` — CSV/JSON export formatting (measurements, medications, mood)
+- `src/lib/doctor-report-pdf.ts` — client-side PDF generation (jsPDF, European medical format)
+- `src/lib/withings/` — Withings OAuth client and sync service
+- `src/lib/notifications/` — dispatcher, types, senders (telegram, ntfy, web-push)
+- `src/lib/jobs/` — pg-boss reminder worker (reminders, insights, data backups)
+- `src/lib/analytics/` — trend calculations, compliance, correlations
+- `src/lib/i18n/` — i18n context, config, locale detection
+- `src/lib/validations/` — Zod schemas shared between API + client
+- `src/hooks/` — React hooks (`use-auth`)
+- `messages/de.json` + `messages/en.json` — i18n translations
+- `prisma/schema.prisma` — database schema (26 models)
+- `tests/integration/` — Postgres testcontainers integration suite (rate-limit race, idempotency replay, GDPR cascade delete, session lifecycle); `pnpm test:integration`
+- `e2e/` — Playwright + axe-core suite for public smoke checks (version, auth-redirect, login, locale-switch, a11y); `pnpm e2e`
+- `prisma.config.ts` — Prisma config (DB URL here, not in schema)
+- `public/sw.js` — Service worker for Web Push notifications + offline caching
+- `docs/` — long-form audit notes (`docs/audit/`); end-user docs live in the separate site at https://docs.healthlog.dev
+- `AGENTS.md` — AI agent instructions (Codex, Cursor, etc.)
+- `CHANGELOG.md` — release notes per semver tag
+
+## Important Patterns
+
+- Import Prisma client from `@/generated/prisma/client` (not `@/generated/prisma`)
+- Prisma 7 does NOT support `url = env("...")` in schema.prisma — use `prisma.config.ts`
+- Next.js 16 uses `proxy.ts` (not `middleware.ts`) — having both causes build error
+- SimpleWebAuthn v13 has no `@simplewebauthn/server/script/deps` — define Transport type inline
+- `zxcvbn-typescript` uses default export only (no named `zxcvbnAsync`/`zxcvbnOptions`)
+- pg-boss v12: `{ PgBoss }` named import, `localConcurrency` instead of `teamSize`, handler receives `Job<T>[]` array
+- **i18n**: All UI text uses `useTranslations()` hook with `t("section.key")`. Messages in `messages/en.json` (English, default) + `messages/de.json` (German, user-selectable). Keys missing in the active locale fall back to English; missing from both surfaces the raw key — the `src/lib/__tests__/i18n*.test.ts` suite guards against that. Numbers/dates go through `useFormatters()` — never hand-roll `Intl.*` with a fixed locale.
+- **Notifications**: 3 channels (Telegram, ntfy, Web Push). Dispatcher at `src/lib/notifications/dispatcher.ts`. Opt-out model (all events enabled by default)
+- **Gravatar**: Server-side SHA-256 hash via `src/lib/gravatar.ts`. URL returned in `/api/auth/me` response as `gravatarUrl` field
+- **Sidebar**: Collapsible (localStorage-persisted). Settings mode with section shortcuts. User section at bottom with three-dot dropdown menu
+- **Settings vs Admin scope rule (v1.4.16 phase B6 audit)**: `/settings/<slug>` is **per-user** — toggles, credentials, layout, target ranges that affect one account. `/admin/<slug>` is **system-wide** — defaults, feature gating, host metrics, audit log read-access. Two surfaces overlap by design: (a) notification channels — admin can disable a channel system-wide via `/api/settings/global-services`, the user sets their own credentials in `/settings/notifications`; (b) AI providers — admin sets the default Codex/OpenAI key, user can override with their own. **No user-facing toggle should appear in both surfaces.** Keys like `settings.adminAreaTitle` are dead code (planned admin-shortcut tile that never shipped) and stay in JSON marked deprecated until a hygiene PR removes them. See `docs/audit/v1416-settings-audit.md`.
+- **ESLint**: Strict `react-hooks/set-state-in-effect` rule — avoid `setState` inside `useEffect`. Use lazy `useState()` initializer for localStorage reads
+- **Proxy route protection**: `src/proxy.ts` checks `healthlog_session` cookie; PUBLIC_PATHS array bypasses auth. Security headers (CSP, HSTS, X-Frame-Options) applied to all responses
+- **PWA safe area**: Root layout has `viewportFit: "cover"`. Bottom-nav uses `pb-[env(safe-area-inset-bottom)]` for iOS safe area
+- **Doctor report PDF**: Client-side via `src/lib/doctor-report-pdf.ts` (jsPDF). Data from `POST /api/doctor-report`. European medical format, German terminology
+- **Achievements**: Persistent in `UserAchievement` table. Computed on API call, new unlocks written to DB with stable `unlockedAt` timestamps
+- **Data backup**: pg-boss `data-backup` queue runs weekly (Sundays 03:00), stores JSON in `DataBackup` model
+- **Wide Events / Structured Logging**: `apiHandler()` wraps all API routes. Use `annotate()` from `@/lib/logging/context` for business-action annotations. Use `requireAuth()` / `requireAdmin()` from `@/lib/api-handler` (auto-annotates auth). Background jobs use `withBackgroundEvent()`. External calls tracked via `getEvent()?.addExternalCall()`. No `console.log` in production code — use event annotations instead. Env vars: `LOG_LEVEL`, `LOG_SAMPLE_RATE`, `LOG_SLOW_THRESHOLD_MS`, `LOG_INCLUDE_STACK`, `LOKI_ENDPOINT`, `LOKI_USERNAME`, `LOKI_PASSWORD`
+- **Multi-tenant prep (v1.4)**: `HEALTHLOG_PROCESS_TYPE=web|worker|all` (default `all`) splits HTTP and pg-boss workloads; the proxy refuses HTTP traffic with 503 + `X-HealthLog-Process-Type: worker` in worker mode. `ENCRYPTION_KEYS` is a JSON map of versioned keys (`{"v1": "...", "v2": "..."}`) plus `ENCRYPTION_ACTIVE_KEY_ID` for new writes; rotation via `pnpm tsx scripts/rotate-encryption-key.ts <id>`. `BACKUP_S3_*` env block configures off-host weekly encrypted backups (PutObject + GetObject only — retention is the bucket's lifecycle policy, never the worker).
+- **Native API clients (v1.4)**: `POST /api/auth/login` and `/api/auth/passkey/login-verify` issue a 24h access token (`hlk_<64hex>`) AND a refresh token (`hlr_<64hex>`) when `X-Client-Type: native` or the User-Agent starts with `HealthLog-iOS/`. The browser flow is unchanged. Refresh-token reuse-detection revokes every refresh token for the user. The idempotency replay-cache rejects bodies containing `hlk_` OR `hlr_` so cached responses can never echo a token back.
+
+## Headless-Client API Patterns
+
+The iOS app talks to bearer-protected routes while the web PWA uses cookie sessions; both share the same handlers (`requireAuth()` accepts either credential).
+
+- **Bearer-token issuance**: `POST /api/auth/login` and `POST /api/auth/passkey/login-verify` return a `token` field for native clients. `isNativeClientRequest()` (`src/lib/auth/issue-token.ts`) opts in via `X-Client-Type: native` header **or** a `User-Agent` starting with `HealthLog-iOS/`. The raw `hlk_<64-hex>` value is returned exactly once; default lifetime 90 days, permissions `["*"]`.
+- **Token storage**: API tokens are stored as **HMAC-SHA-256** hashes (`hashToken()` in `src/lib/auth/hmac.ts`, keyed by env `API_TOKEN_HMAC_KEY`) — not plain SHA-256. The keyed HMAC defends against precomputed rainbow tables if the DB leaks. Same mechanism is reused for external-ingest token verification.
+- **Idempotency-Key**: `withIdempotency()` (`src/lib/idempotency.ts`) wraps POST/PUT/PATCH/DELETE handlers so retries with the same `Idempotency-Key` (regex `^[A-Za-z0-9_\-:.]{8,128}$`) for the same `(userId, method, path)` replay the original response with `X-Idempotent-Replay: true` for 24h. **NOT cached**: 401, 403, 408, 429, any 5xx, and any body containing `hlk_` (defence against caching a token-issuing response). Validation 4xx (422 etc.) **is** cached so a broken retry doesn't re-hit the DB. `userIdResolver` defaults to the cookie session — pass a 2nd argument for Bearer-only routes.
+- **Device-registration cross-user-hijack guard**: `POST /api/devices` rejects re-registration of an existing APNs token under a different user with **409** (`Device token already registered to another account`) instead of silently transferring ownership. APNs tokens aren't a secret, so trusting wire input would let anyone who learns a token redirect another user's pushes. Audit trail: `device.register.denied` with reason `token_owned_by_other_user`.

CONTRIBUTING.md

@@ -20,13 +20,19 @@ cp .env.example .env
 Edit `.env` and configure at minimum:
 
 ```
-DATABASE_URL="postgresql://healthlog:healthlog@localhost:5432/healthlog"
-SESSION_SECRET=<64-char hex>
+POSTGRES_PASSWORD=<base64, 24 bytes>
+DATABASE_URL="postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog"
 ENCRYPTION_KEY=<64-char hex>
 API_TOKEN_HMAC_KEY=<64-char hex>
 ```
 
-Generate secrets with `openssl rand -hex 32`.
+Generate the three secrets:
+
+```bash
+echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" >> .env
+echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"       >> .env
+echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)"   >> .env
+```
 
 ### With Docker (database only)
 
@@ -47,25 +53,30 @@ docker compose up -d
 ## Development Workflow
 
 ```bash
-pnpm dev            # Start dev server (http://localhost:3000)
-pnpm lint           # ESLint
-pnpm format         # Prettier
-pnpm typecheck      # TypeScript strict mode
-pnpm test           # Vitest
+pnpm dev             # Start dev server (http://localhost:3000)
+pnpm lint            # ESLint
+pnpm format:check    # Prettier (check)
+pnpm typecheck       # TypeScript strict mode
+pnpm test            # Vitest
+pnpm build           # Next.js production build
 ```
 
-All four checks must pass before submitting a PR.
+All five checks must pass before submitting a PR. The full one-liner that mirrors CI:
+
+```bash
+pnpm typecheck && pnpm lint && pnpm test && pnpm format:check && pnpm build
+```
 
 ## Code Conventions
 
-- **TypeScript strict mode** -- no `any` types, no type assertions unless absolutely necessary
-- **UI text in German**, code/comments/docs in English
-- **API responses** follow `{ data, error, meta }` envelope pattern
-- **Zod v4** for input validation (API routes and forms)
-- **shadcn/ui** components (new-york style) for UI primitives
-- **Dracula theme** -- dark mode only, use `--dracula-*` CSS tokens
+- **TypeScript strict mode** -- avoid `any`. Where it's truly unavoidable (e.g. variadic Next.js handler signatures in `src/lib/api-handler.ts`), document the reason inline.
+- **English-default UI** -- the default locale is English. German is user-selectable. Code, comments, commit messages, and docs are English. All user-facing strings go through `t("key")` with translations in both `messages/en.json` and `messages/de.json`. The `i18n-locale-integrity.test.ts` suite blocks merges if keys drift between locales or duplicate at any nesting depth.
+- **API responses** follow the `{ data, error }` envelope via `apiSuccess()` / `apiError()` in `src/lib/api-response.ts`. Wrap every route handler in `apiHandler()` (`src/lib/api-handler.ts`) for error handling, structured Wide-Event logging, and `x-request-id` propagation.
+- **Zod v4** (`import { ... } from "zod/v4"`) for input validation in API routes and forms.
+- **shadcn/ui** components (new-york style) for UI primitives.
+- **Dracula theme** -- dark mode is the default; a `light`/`system` toggle is exposed in the topbar. Chart and accent colors use the `--dracula-*` CSS tokens so both themes stay coherent.
 
-See `CLAUDE.md` for detailed architecture and patterns.
+See `CONTRIBUTING-AI.md` for detailed architecture and patterns.
 
 ## Database Changes
 
@@ -77,13 +88,79 @@ pnpm db:generate    # Regenerates Prisma client
 
 Always include the migration file in your PR.
 
+## Branch Model
+
+HealthLog is trunk-based: `main` is the single long-lived branch and is always releasable. There is no `develop` branch.
+
+```
+   feature/* ──┐
+   fix/*    ──┼──► PR ──► main ──► tag vX.Y.Z ──► GHCR build ──► deploy
+              │
+   release/vX.Y.Z ──► PR (merge-commit) ──► main ──► tag vX.Y.Z ──► GHCR build ──► deploy
+```
+
+The rules:
+
+- **`main` always builds, passes CI, and is deployable.** Every commit on it is a release commit (`chore(release): vX.Y.Z`), a release-branch merge, or a maintenance commit (docs, gitignore, audit findings) applied directly.
+- **A release** is built on a short-lived `release/vX.Y.Z` branch cut off `main`, then opened as a PR `release/vX.Y.Z` → `main` with green CI, merged as a merge-commit, and tagged `vX.Y.Z`. The tag push triggers the GHCR multi-arch image build (and `:latest`). Deploy is manual. Delete the release branch after merge.
+- **Small standalone changes** (a single fix, a docs touch) go through a short-lived `fix/X` / `feat/X` branch + PR targeting `main`.
+- **Hotfixes** branch from `main` and merge straight back to `main`. There is no second long-lived line to forward-port to.
+- Never force-push `main` or any release branch.
+
+End users: track the latest `v*` tag (or `:latest` on GHCR). The `main` branch always equals the latest release.
+
+Contributors: branch off `main`; PRs target `main`.
+
 ## Pull Requests
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/your-feature`)
+2. Create a feature branch off `main` (`git checkout -b feat/your-feature main`)
 3. Make your changes
-4. Ensure all checks pass (`pnpm lint && pnpm typecheck && pnpm test`)
-5. Submit a PR with a clear description of the changes
+4. Ensure all checks pass (`pnpm typecheck && pnpm lint && pnpm test && pnpm format:check && pnpm build`)
+5. Submit a PR against `main` with a clear description of the changes
+
+## Translations
+
+HealthLog ships with English (`en`) and German (`de`) maintained by the project, plus French (`fr`), Spanish (`es`), Italian (`it`), and Polish (`pl`) that are **AI-initial, community-maintained**. The maintained locales are reviewed line-by-line; the community-maintained ones surface a small banner inviting users to improve them.
+
+### Improving an existing locale
+
+Translation files live at `messages/<locale>.json`. Each key matches the same key in `messages/en.json` (which is the source-of-truth — never delete a key here without coordinating).
+
+To suggest a fix or improvement:
+
+1. Fork the repository.
+2. Create a branch like `i18n-fr/<area>` (e.g. `i18n-fr/coach-prompts`, `i18n-pl/dashboard`).
+3. Edit `messages/<locale>.json`. Keep the JSON valid; the i18n integrity test will flag missing or extra keys against `en.json` before CI accepts the PR.
+4. Open a PR titled `i18n(<locale>): <area>`. Describe what was unclear, awkward, or wrong in the previous wording.
+
+### Adding a new locale
+
+If you want to introduce a locale that isn't shipped (e.g. `nl`, `pt-BR`, `cs`):
+
+1. Open an issue first using the **Translation request** template. We'll confirm the locale is in scope and decide whether it joins the AI-initial-community-maintained tier or the maintained tier.
+2. Copy `messages/en.json` to `messages/<locale>.json`.
+3. Translate. AI assistance is welcome as a starting point but the PR description should note whether it's an AI-initial pass or a fully human-reviewed one — that information drives the banner state.
+4. Add the locale to the supported list in `src/lib/i18n/locales.ts` (or wherever the registry lives — grep `SUPPORTED_LOCALES`).
+5. The Coach system prompts at `src/lib/ai/prompts/coach-prompt.ts` and `src/lib/ai/prompts/insight-generator.ts` and the doctor-report PDF strings need translation too. Include those in the same PR.
+6. Run `pnpm test -- i18n-integrity` locally before submitting.
+
+### Style guide for translators
+
+- Tone: warm but reserved, curious not pushy. Examples in EN: "Your blood pressure has settled into the green zone" — not "Awesome, your BP is amazing!"
+- Numbers and units stay numeric: "120/80 mmHg" stays "120/80 mmHg" in every locale.
+- Brand terms stay untranslated: HealthLog, Coach, Tagesbriefing (the DE Coach term — leave as-is in EN if it appears).
+- Medical terms: prefer the language community's native medical vocabulary (e.g. "Blutdruck" in DE, "tensión arterial" in ES, "ciśnienie krwi" in PL). When in doubt, mirror the style used in the country's clinical guidelines.
+- Avoid US-specific units (lb, oz, °F) — HealthLog is metric-first.
+- No PII in copy. No real names, no real readings. Sample data uses round numbers.
+
+### Long-term
+
+When the community grows beyond ad-hoc PRs, we'll spin up a self-hosted [Weblate](https://weblate.org/) instance. That replaces the JSON-PR workflow with a web UI but keeps every translation under our own roof — no third-party telemetry. Tracking issue: `v1.6 — Weblate self-hosted on edge-01`.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant 2.1](CODE_OF_CONDUCT.md). By participating, you agree to uphold its standards. Reports of unacceptable behavior go to `conduct@bombeck.io`.
 
 ## Security
 

Dockerfile

@@ -11,6 +11,17 @@ FROM node:22-alpine AS builder
 RUN corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
+# v1.4.43 B11 — version build-arg threaded into the layer cache key.
+# Pre-v1.4.43 the docker-publish workflow shipped a stale package.json
+# version baked into the bundle because BuildKit reused the `pnpm build`
+# layer across releases (the COPY . . layer key was content-stable when
+# only the version string had changed and the next pnpm install layer
+# was warm). Passing the tag as a build-arg forces a per-release cache
+# miss on this layer and forwards the value into the runtime env so
+# /api/version reads from $NEXT_PUBLIC_APP_VERSION first.
+ARG NEXT_PUBLIC_APP_VERSION
+ENV NEXT_PUBLIC_APP_VERSION=$NEXT_PUBLIC_APP_VERSION
+
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 
@@ -23,12 +34,25 @@ RUN pnpm build
 
 # ── Stage 3: Production runner ─────────────────────────────
 FROM node:22-alpine AS runner
-RUN corepack enable && corepack prepare pnpm@latest --activate
+# `tzdata` is required so Europe/Berlin schedules (pg-boss cron, locale-aware
+# timestamp formatting) resolve to the actual offset instead of silently
+# falling back to UTC on Alpine images that ship without it.
+RUN apk add --no-cache tzdata && \
+    corepack enable && corepack prepare pnpm@latest --activate
 WORKDIR /app
 
 ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV NODE_PATH="/opt/pg-boss/node_modules"
+ENV TZ=Europe/Berlin
+
+# v1.4.43 B11 — forward NEXT_PUBLIC_APP_VERSION from the builder stage
+# into the runner so /api/version reads the build-arg value instead of
+# the package.json fallback. The variable is keyed to the CI tag ref
+# (`v1.4.43`, etc.), so a release that bumps the tag but cache-reuses
+# the prior `pnpm build` layer still surfaces the right runtime version.
+ARG NEXT_PUBLIC_APP_VERSION
+ENV NEXT_PUBLIC_APP_VERSION=$NEXT_PUBLIC_APP_VERSION
 
 RUN addgroup --system --gid 1001 nodejs && \
     adduser --system --uid 1001 nextjs
@@ -50,13 +74,28 @@ COPY --from=builder /app/src/generated ./src/generated
 RUN mkdir -p /opt/pg-boss && \
     cd /opt/pg-boss && \
     npm init -y && \
-    npm install --omit=dev pg-boss@12 @prisma/adapter-pg@7 pg@8
+    npm install --omit=dev pg-boss@12.18 @prisma/adapter-pg@7.8 pg@8.20
 
 # Install Prisma CLI + engines for runtime migrations (isolated from Next standalone tree)
 RUN mkdir -p /opt/prisma-cli && \
     cd /opt/prisma-cli && \
     npm init -y && \
-    npm install --omit=dev prisma@7.4.0 @prisma/engines@7.4.0
+    npm install --omit=dev prisma@7.8 @prisma/engines@7.8
+
+# v1.4.27 B3 — offline GeoLite2 databases for IP→location and IP→ASN
+# lookups. The MMDB files live in `/opt/geolite2/` and are read by
+# `src/lib/geo.ts` via `mmdb-lib`. They are downloaded outside the
+# Docker build by `scripts/fetch-geolite2.sh` (operator runs it before
+# `docker build` with a MaxMind license key) and staged in
+# `assets/geolite2/`. The README + .gitkeep are always present so the
+# COPY target exists; if the maintainer skipped the fetch step the
+# image builds without the DBs and the resolver falls back to the
+# online `ipwho.is` provider — matches v1.4.26 behaviour.
+#
+# Attribution (CC BY-SA 4.0): see `docs/audit/v1427-summary.md` and
+# `/about` in the running app.
+RUN mkdir -p /opt/geolite2
+COPY assets/geolite2/ /opt/geolite2/
 
 # Entrypoint script (runs migrations, then starts app)
 COPY docker-entrypoint.sh ./

README.md

@@ -10,22 +10,63 @@
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" /></a>
-  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/Next.js-16-black?logo=next.js" alt="Next.js 16" />
+  <a href="https://github.com/MBombeck/HealthLog/releases"><img src="https://img.shields.io/github/v/release/MBombeck/HealthLog?sort=semver&color=success&cacheSeconds=60" alt="Latest release" /></a>
+  <a href="https://github.com/MBombeck/HealthLog/actions/workflows/integration.yml"><img src="https://img.shields.io/github/actions/workflow/status/MBombeck/HealthLog/integration.yml?branch=main&label=CI" alt="CI status" /></a>
+  <a href="https://testflight.apple.com/join/bucuTBpa"><img src="https://img.shields.io/badge/iOS-TestFlight-007AFF?logo=apple&logoColor=white" alt="iOS app on TestFlight" /></a>
   <img src="https://img.shields.io/badge/Self--Hosted-yes-success" alt="Self-Hosted" />
-  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" />
+  <img src="https://img.shields.io/badge/Next.js-16-black?logo=next.js" alt="Next.js 16" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
+  <a href="https://github.com/MBombeck/HealthLog/pkgs/container/healthlog"><img src="https://img.shields.io/badge/GHCR-multi--arch-2496ED?logo=docker&logoColor=white" alt="GHCR multi-arch image" /></a>
+  <a href="https://buymeacoffee.com/mbombeck"><img src="https://img.shields.io/badge/Buy_me_a_coffee-FFDD00?logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee" /></a>
 </p>
 
 <p align="center">
-  A self-hosted, privacy-first health tracking PWA.<br/>
-  Weight, blood pressure, mood, medications, AI insights -- all under your control.
+  Self-hosted health tracker. Weight, blood pressure, glucose, mood, medications.<br/>
+  Withings, WHOOP, Google Health/Fitbit, and Apple Health sync, multi-provider AI insights you own, doctor-report PDF.
 </p>
 
 <p align="center">
   <a href="https://healthlog.dev">Website</a> &middot;
   <a href="https://demo.healthlog.dev">Live Demo</a> &middot;
-  <a href="https://docs.healthlog.dev">Documentation</a>
+  <a href="https://docs.healthlog.dev">Documentation</a> &middot;
+  <a href="https://testflight.apple.com/join/bucuTBpa">iOS TestFlight</a>
 </p>
+<img width="2316" height="1207" alt="home" src="https://github.com/user-attachments/assets/aac0931d-5ea2-45b8-9a12-5f2f013d19e5" />
+
+---
+
+## Contents
+
+- [What it is](#what-it-is)
+- [Why HealthLog?](#why-healthlog)
+- [How it compares](#how-it-compares)
+- [Key Features](#key-features)
+- [Quick Start](#quick-start)
+- [Tech Stack](#tech-stack)
+- [Security and Privacy](#security-and-privacy)
+- [Environment Variables](#environment-variables)
+- [Architecture](#architecture)
+- [API Reference](#api-reference)
+- [Integrations](#integrations)
+- [Local Development](#local-development)
+- [Deployment](#deployment)
+- [Documentation](#documentation)
+- [Roadmap](#roadmap)
+- [Native iOS client](#native-ios-client)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## What it is
+
+HealthLog is a self-hosted personal health tracker that runs from a single `docker compose up`. It covers the metrics most people actually log -- weight, blood pressure, pulse, body composition, blood glucose, sleep, mood, and medication compliance -- and brings them together in one dashboard with reference ranges from ESH 2023, ADA 2024, and NICE NG115. Withings, WHOOP, and Google Health/Fitbit devices sync automatically over OAuth2; an `export.zip` import folds your full Apple Health history into the same timeline; a native SwiftUI iOS client (public-beta via [TestFlight](https://testflight.apple.com/join/bucuTBpa)) streams HealthKit live; multi-provider AI insights (BYOK or local) explain what the numbers mean; a doctor-report PDF generates client-side. EN/DE end-to-end. AGPL-3.0.
+
+> **Status**: active. New releases roughly weekly -- see [CHANGELOG](CHANGELOG.md). Current line: v1.12 — a Google Health/Fitbit connection for Fitbit and Pixel wearables (experimental, see [Integrations](#integrations)) and a rebuilt mood log (five-face capture, a structured tag catalog, and rated daily-life factors), on top of the v1.11 mood-relations and sleep-depth insights, a read-only FHIR R4 API with shareable clinician records, the v1.10 derived-metrics tier (fitness-age, vascular-age delta, HRV balance, sleep score, readiness and recovery scores, an early-strain flag), and the v1.7 health-record export (PDF + FHIR R4). The native iOS client is public-beta via [TestFlight](https://testflight.apple.com/join/bucuTBpa).
+
+> **Heavily developed.** HealthLog ships multiple releases per week. Behaviour, API shapes, and database schema can change between minor versions; migrations are forward-only and not all are rehearsed against every legacy fixture. If you self-host, pin a tag, take a backup before every upgrade, and read the [CHANGELOG](CHANGELOG.md) before pulling `latest`. Issue reports and PRs welcome — this is the rough edge where the project gets sharper.
+
+Built for people who want their health data on their own server -- whether that's a NAS, a homelab, or a small VPS -- and who don't want to hand it to a US cloud to read a 7-day weight trend. **Try the [live demo](https://demo.healthlog.dev)** to see what a working install looks like, or skip to [Quick Start](#quick-start) below.
 
 ---
 
@@ -35,39 +76,96 @@ Most health apps lock your data behind proprietary clouds, push subscriptions, a
 
 ---
 
+## How it compares
+
+|                            | HealthLog            | Withings web    | Apple Health  | Oura web    | WHOOP web   | Fitbit web   | Generic CSV |
+| -------------------------- | -------------------- | --------------- | ------------- | ----------- | ----------- | ------------ | ----------- |
+| Self-hosted                | Yes                  | No              | No            | No          | No          | No           | Yes         |
+| Open source                | AGPL-3.0             | No              | No            | No          | No          | No           | n/a         |
+| Withings device sync       | Yes (OAuth2)         | Yes (native)    | Via shortcut  | No          | No          | No           | No          |
+| WHOOP device sync          | Yes (OAuth2, BYO-keys)| No             | No            | No          | Native      | No           | No          |
+| Google Health / Fitbit sync| Yes (experimental)   | No              | No            | No          | No          | Native       | No          |
+| Apple Health import        | Yes (`export.zip`)   | No              | Native        | No          | No          | No           | Manual      |
+| Aggregates many providers  | Yes                  | No              | Partial       | No          | No          | No           | Manual      |
+| Multi-source dedup + priority| Yes (per-metric)   | n/a             | Limited       | n/a         | n/a         | n/a          | No          |
+| Blood pressure + glucose   | First-class          | BP only         | Manual        | No          | No          | Limited      | Manual      |
+| Medication compliance      | Cadence-aware        | No              | No            | No          | No          | No           | Manual      |
+| Derived wellness metrics   | Yes (transparent)    | Limited         | Limited       | Yes (closed)| Yes (closed)| Limited      | No          |
+| Custom clinician targets   | Yes (audit-logged)   | Limited         | No            | No          | No          | No           | n/a         |
+| Doctor-report PDF + FHIR   | Yes (client-side)    | No              | No            | No          | No          | No           | n/a         |
+| AI Insights                | Multi-provider BYOK  | No              | Limited       | Subscription| Subscription| Limited      | n/a         |
+| Encrypted at rest (AES-256-GCM)| Yes (your host)  | Vendor cloud    | Vendor cloud  | Vendor cloud| Vendor cloud| Vendor cloud | Depends     |
+| Subscription required      | No                   | For some metrics| No            | Yes         | Yes         | For some metrics| No       |
+| Your data leaves device    | Never                | Withings cloud  | Apple cloud   | Oura cloud  | WHOOP cloud | Fitbit cloud | Depends     |
+
+### Versus WHOOP / Oura / Fitbit ecosystems
+
+The wrist-band ecosystems are good at what their hardware measures, and HealthLog does not try to be a ring or a strap. It does not ship a sensor, and it does not claim to match one. What it does is take the readings those devices already collect — plus the ones they don't hold, like cuff blood pressure, finger-stick or CGM glucose, and medication intake — and keep them on a server you run.
+
+- **You own the data and the host.** No vendor account, no cloud round-trip, no subscription tier gating a metric you already recorded. AGPL-3.0, single `docker compose up`, encrypted at rest, on your NAS / homelab / VPS.
+- **It aggregates across providers instead of locking you to one.** Withings and WHOOP devices sync over OAuth2, a Google Health/Fitbit connection pulls Fitbit and Pixel data (experimental), an Apple Health `export.zip` folds your full history in, and the native iOS client streams HealthKit live — so a Withings scale, a WHOOP strap, an Apple Watch, and a glucometer land on one timeline instead of four apps. When two providers report the same metric, a per-metric source priority decides which one is canonical, so a dedicated scale outranks a wrist estimate and cumulative metrics like steps are never double-counted (see [Source priority](#source-priority)).
+- **It carries context the wrist bands don't.** Blood pressure, blood glucose, body composition, and cadence-aware medication compliance sit next to the wearable signals, so a trend reads against the whole picture rather than activity and sleep alone.
+- **The derived metrics are transparent, not a black box.** HealthLog computes a fitness-age and vascular-age delta, an HRV-balance and sleep-score band, a daily readiness and recovery score, and a coincident-deviation early-strain flag — each from your own measurements, each citing the inputs and the published method behind it, each degrading honestly to "not enough data" rather than fabricating a number. These are descriptive wellness framings, not clinical or training-grade assessments, and a score is only stored once its minimum inputs are present.
+
+HealthLog is the right fit when you want your wearable and clinical numbers in one place that you control, with explainable analytics on top — not when you want a closed device that scores you and keeps the data.
+
+---
+
 ## Key Features
 
-**Health Metrics** -- Track weight, blood pressure, pulse, body fat, sleep, steps, blood glucose (fasting/postprandial/random/bedtime, mg/dL ↔ mmol/L), total body water, and bone mass with interactive trend charts, moving averages, and traffic-light ranges based on ESC/ESH 2018 and ADA 2024 guidelines. Body-composition metrics sync automatically from Withings Body+ scales.
+**Health Metrics** -- Track weight, blood pressure, pulse, body fat, sleep, steps, blood glucose (fasting/postprandial/random/bedtime, mg/dL ↔ mmol/L), total body water, bone mass, and pulse oximetry (SpO₂) with interactive trend charts, moving averages, and traffic-light ranges based on ESH 2023, ADA 2024, and consensus pulse-oximeter guidance (NICE NG115). Body-composition + SpO₂ metrics sync automatically from Withings Body+ scales and ScanWatch devices. Every stored HealthKit metric now has a chart surface — flights climbed, audio exposure, walking speed/step-length/asymmetry/double-support, respiratory rate, the body-composition family, mobility, daylight, and more — and a metric/imperial display toggle renders walking speed in km/h while storage and exports stay canonical SI.
 
 **Custom Thresholds** -- Override the computed default ranges per metric with the targets your clinician set. Audit-logged. Doctor Report PDF prints both your target and the standard reference.
 
 **Customizable Dashboard** -- Show, hide, and drag-to-reorder every widget. Per-user layout with reset-to-defaults.
 
-**Mood Logging** -- 5-point scale with tags, notes, and trend analytics. Syncs automatically from moodLog.app via webhook.
+**Mood Logging** -- A five-face mood capture (a 1–5 scale) backed by a structured tag catalog and rated daily-life factors. Pick binary tags from categories covering feelings, sleep, health (including nutrition tags like ate-well, fast-food, no-sweets, big-meal), social, work, and hobbies; score rated factors — work, social, sleep quality, stress, and conflict — on their own scale (1–5, or yes/no for conflict), with stress and conflict flagged as inverse so a higher score reads as a worse day. Add a free-text note, then read it back through trend analytics and a mood-relations surface that associates your tags and factors with your other metrics. The standalone moodLog.app webhook is deprecated now that mood is tracked fully inside HealthLog; it stays functional for existing integrations.
 
-**Medication Compliance** -- Flexible scheduling with time windows, recurrence patterns, intake logging (take/skip/snooze), and compliance heatmaps. External API for iOS Shortcuts integration.
+**Medication Compliance** -- Flexible scheduling driven by a single recurrence engine: time windows, day-of-week recurrence, `intervalWeeks`, rolling intervals, RFC-5545 RRULE, one-time doses, as-needed (PRN), and cyclic on/off-week plans — so once-weekly GLP-1 injections, weekday-only doses, and non-daily plans score honestly against their real cadence rather than a daily denominator, everywhere from the dashboard tile to the detail page. Route of administration (oral / injection / other) carries the injection-site picker for any injection. Take / skip / snooze logging, compliance heatmaps, GLP-1 pen-inventory + injection-site rotation, structured side-effect tracking. External API for iOS Shortcuts integration.
 
 **Withings Integration** -- OAuth2 device sync for scales, blood pressure monitors, and activity trackers with automatic deduplication.
 
-**Multi-Provider AI Insights** -- Pick OpenAI, Anthropic Claude, or any local OpenAI-compatible endpoint (Ollama, LM Studio, vLLM). BYOK or admin-shared key. Cached daily. Local endpoints keep all data on your network.
+**WHOOP Integration** -- Connect a WHOOP account with your own WHOOP developer OAuth client (client id/secret pasted into Settings, stored encrypted). Recovery, strain, sleep, body, and workout data sync server-side over OAuth2, with a connection test, manual sync (incremental or full history), and a resume control to recover from a revoked grant.
+
+**Google Health / Fitbit Integration** _(experimental)_ -- Connect Fitbit and Pixel data through Google's Health API on your own Google Cloud OAuth client (client id/secret in Settings, encrypted at rest). Activity (steps, distance, active energy, floors, VO₂ max), health metrics (weight, body fat, SpO₂, resting heart rate, HRV, respiratory rate, wrist temperature, spot heart rate), per-stage sleep, and exercise workouts import server-side with the same connection-test / sync / resume controls as WHOOP. Because the Google Health API is young and several per-type value fields are not yet fully published, this connection is **experimental** — some data types may import nothing until the wire mapping is verified against a live account, and each operator's OAuth client needs Google brand verification plus an annual CASA assessment before it can leave Testing mode.
+
+**Apple Health import** -- Drop your iOS `export.zip` on the import page. A streaming parser handles multi-gigabyte archives (Zip64), folds every `<Record>`, `<Workout>`, `<Correlation>`, and `<ClinicalRecord>` into the same timeline as your other metrics, and stays idempotent on re-upload. Per-type ingestion stats plus a live status endpoint so you can watch the progress on a long historical drain.
+
+**AI Coach + Insights** -- Multi-provider, evidence-grounded health insights: per-metric assessments that read each vital against its reference range, correlations across your metrics, a daily briefing, a weekly report, a Health Score tile, and a conversational Coach grounded in your own data. Pick OpenAI, Anthropic Claude, ChatGPT via Codex device-OAuth (no API key needed), or any OpenAI-compatible local endpoint (Ollama, LM Studio, vLLM). BYOK or admin-shared. Feed the Coach a chosen set of data clusters (cardiovascular, body composition, activity, workouts, sleep, mood, glucose, medication, mobility, environment) with a soft budget cap that degrades the lowest-signal clusters first. Every claim links back to the measurements that produced it. The Coach now reads your history longitudinally — a narrative of how a metric has moved and a per-metric trajectory framing — so an answer reflects the direction of travel rather than only the latest reading. Local endpoints keep all data on your network.
+
+<p align="center">
+  <img src="docs/diagrams/02-coach-pipeline.svg" alt="Coach pipeline: a user question through the snapshot builder and prompt assembler, into the provider chain (ChatGPT OAuth, OpenAI, Anthropic, local, admin-shared), through the response parser, out to a cited reply with mini-charts" width="900" />
+</p>
+
+**Derived wellness metrics** -- A transparent metrics tier computed from your own measurements: a fitness-age band from VO₂max, a vascular-age delta, an HRV-balance band, a sleep score, a daily readiness and a stored recovery score, plus a coincident-deviation early-strain flag. Each one re-frames or blends signals you already recorded against age/sex norms or your personal baseline, cites the inputs and the published method behind it, and returns "not enough data" rather than a fabricated value when its minimum inputs are missing. The recovery score persists as a daily 0–100 series the dashboard, charts, and native client read without recomputing. These are descriptive wellness framings — not clinical or training-grade assessments.
 
 **Doctor Report PDF Export** -- Generate professional medical reports client-side. Locale-aware (English/German), with vital sign summaries, BP/BMI/glucose classification, compliance rates, custom-threshold badges, and optional AI analysis.
 
+**Health-record export (PDF + FHIR R4)** -- `POST /api/export/health-record` produces a selectable export: an enriched clinical PDF, a machine-readable HL7 FHIR R4 document bundle (LOINC-coded observations, a BP panel, medication statements, a diagnostic report), or both packaged as one zip. The selection chooses date range and per-domain sections; both formats read the same aggregator so they describe identical numbers, and the optional AI summary is an explicit opt-in section marked as not clinically validated. Optional patient identity (name, insurer, insurance number) on Account feeds the report cover and the FHIR `Patient`.
+
+**Clinician-grade FHIR API + shareable record** -- A read-only HL7 FHIR R4 REST API (`GET /api/fhir/{metadata,Patient,Observation,MedicationStatement,MedicationAdministration,$everything}`) lets a clinician system pull your record in a standard shape, gated behind a dedicated `fhir:read` token scope. Alongside it, a shareable clinician record: create a scoped, time-limited share link, hand a clinician the read-only `/c/<token>` view, and revoke it when the visit is over. The two are not yet wired together — a share link does not expose the FHIR API (`capabilities.share.fhirApi=false`) — but each stands on its own.
+
 **Built-in Feedback** -- Send bug reports and feature requests from inside the app. Stored in your HealthLog database — no GitHub config required. Optional GitHub escalation for admins.
 
-**PWA with Offline Support** -- Installable on iOS and Android. Service worker with intelligent caching strategies for reliable offline access.
+**PWA with Offline Support** -- Installable on iOS and Android. Service worker with intelligent caching strategies for reliable offline access. A paginated, opaque-cursor sync delta feed (`GET /api/sync/changes`) with measurement tombstones lets native and offline clients reconcile against the server incrementally.
 
-**Multi-Channel Notifications** -- Telegram (with inline action buttons), ntfy (self-hostable), and Web Push. Medication reminders with late/missed escalation.
+**Multi-Channel Notifications** -- Telegram (with inline action buttons), ntfy (self-hostable), Web Push (VAPID), and Apple Push (APNs) for the native iOS client. One dispatcher fans medication reminders out to whichever channels the user has enabled, with late/missed escalation.
 
-**Gamification** -- 30+ persistent achievements across intake streaks, compliance milestones, and healthy metric streaks.
+**Sub-second dashboard** -- A persistent rollup tier pre-aggregates every measurement at DAY / WEEK / MONTH granularity. The dashboard and analytics paths read those buckets first and fall back to live SQL only when a tenant hasn't been backfilled yet, so paint time stays under 500 ms regardless of how many years of history you've imported. The above-the-fold tiles arrive together in a single first-paint snapshot, and a nightly job pre-generates the daily briefing so `/insights` is a cache read rather than a synchronous model call.
 
-**Internationalization** -- English (default) and German UI with 1000+ translation keys. Numbers, dates, units, and AI prompts all locale-aware via `useFormatters()`. Browser-based detection with per-user override.
+**Gamification** -- 59 persistent achievements across intake streaks, compliance milestones, and healthy metric streaks.
+
+**Internationalization** -- English (default) and German UI with 2500+ translation keys each, guarded by a CI integrity test that fails the build on duplicate keys, drift between locales, or call-sites referencing keys that no locale ships. Numbers, dates, units, and AI prompts all locale-aware via `useFormatters()`. Browser-based detection with per-user override.
+
+**Multi-tenant ready** _(v1.4)_ — Off-host AES-GCM-encrypted daily backups to any S3-compatible bucket (R2, B2, MinIO, AWS), encryption-key versioning + zero-downtime rotation CLI (`scripts/rotate-encryption-key.ts`), optional `HEALTHLOG_PROCESS_TYPE=web|worker|all` so HTTP and pg-boss can scale independently, and short-lived 24h access tokens with refresh-token rotation for native API clients. The browser cookie session is unchanged.
+
+**Test connection buttons** _(v1.4)_ — One-click probes for Withings, moodLog.app, Web Push, Glitchtip, and Umami in addition to the existing AI / Telegram / ntfy tests. Each one rate-limited, sanitised against SSRF redirects, and surfaces a localisable `errorCode` so the UI can render the failure in the user's language.
 
 ---
 
 ## Quick Start
 
-Plan ~5 minutes for a working install. The bundled `docker-compose.yml` pulls a pre-built multi-arch image (`linux/amd64` + `linux/arm64`) from [GitHub Container Registry](https://github.com/MBombeck/HealthLog/pkgs/container/healthlog); no build step required for self-hosters. Contributors who want to test local changes can `docker compose up --build`.
+**3 minutes from `git clone` to a working install.** The bundled `docker-compose.yml` pulls a pre-built multi-arch image (`linux/amd64` + `linux/arm64`) from [GitHub Container Registry](https://github.com/MBombeck/HealthLog/pkgs/container/healthlog); no build step required for self-hosters. Contributors who want to test local changes can `docker compose up --build`.
 
 ```bash
 git clone https://github.com/MBombeck/HealthLog.git
@@ -75,11 +173,10 @@ cd HealthLog
 cp .env.example .env
 ```
 
-Generate the four required secrets and paste them into `.env`:
+Generate the three required secrets and paste them into `.env`:
 
 ```bash
 echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" >> .env
-echo "SESSION_SECRET=$(openssl rand -hex 32)"       >> .env
 echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"       >> .env
 echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)"   >> .env
 ```
@@ -102,17 +199,18 @@ Open **http://localhost:3000**. The first registered user becomes admin.
 | ------------- | ------------------------------------------------- |
 | Framework     | Next.js 16 (App Router, React Server Components)  |
 | Language      | TypeScript (strict mode)                          |
-| Database      | PostgreSQL 16 + Prisma 7 (23 models)              |
+| Database      | PostgreSQL 16 + Prisma 7 (61 models)              |
 | Job Queue     | pg-boss 12 (reminders, insights, backups)         |
 | UI            | shadcn/ui, Tailwind CSS 4, Radix UI, Lucide Icons |
 | Charts        | Recharts 3                                        |
 | Data Fetching | TanStack Query 5                                  |
 | Forms         | React Hook Form 7 + Zod 4                         |
 | Auth          | SimpleWebAuthn 13, Argon2id                       |
-| Notifications | Telegram Bot API, ntfy, Web Push (VAPID)          |
+| Notifications | Telegram Bot API, ntfy, Web Push (VAPID), APNs    |
 | PDF           | jsPDF (client-side generation)                    |
 | Testing       | Vitest 4                                          |
 | Deployment    | Docker (multi-stage Alpine)                       |
+| Native client | SwiftUI iOS app — public beta via [TestFlight](https://testflight.apple.com/join/bucuTBpa) |
 
 ---
 
@@ -121,13 +219,21 @@ Open **http://localhost:3000**. The first registered user becomes admin.
 HealthLog is designed for people who take data ownership seriously.
 
 - **Self-hosted** -- Your data never leaves your server. No telemetry, no third-party tracking.
-- **AES-256-GCM encryption** -- All stored secrets (OAuth tokens, API keys, VAPID keys) are encrypted at rest.
+- **AES-256-GCM encryption** -- All stored secrets (OAuth tokens, API keys, VAPID keys, notification credentials, off-host backup payloads) are encrypted at rest.
+- **Your AI, your keys** -- AI insights run on a provider you choose: bring your own OpenAI / Anthropic key, sign in to ChatGPT via Codex device-OAuth, or point at a local OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) so your health data never leaves your network. No model calls are made without a key you supply.
+- **Key versioning + zero-downtime rotation** -- Multiple encryption keys can coexist (`ENCRYPTION_KEYS` map + `ENCRYPTION_ACTIVE_KEY_ID`) and a CLI (`pnpm dlx tsx scripts/rotate-encryption-key.ts`) re-wraps every encrypted column from the old key to the new one without taking the app offline.
 - **Passkey authentication** -- WebAuthn as primary auth with password fallback (Argon2id + zxcvbn strength validation).
 - **Server-side sessions** -- PostgreSQL-backed with 30-day sliding expiry, HttpOnly/SameSite=Strict cookies.
 - **Security headers** -- CSP with nonces, HSTS, X-Frame-Options DENY, Permissions-Policy, Referrer-Policy.
 - **Rate limiting** -- Sliding window on auth and API endpoints.
 - **HMAC-SHA256 API tokens** -- Bearer tokens are hashed before storage.
-- **Audit logging** -- All sensitive operations tracked with IP addresses.
+- **Offline IP geolocation** -- Bundled MaxMind GeoLite2 City + ASN databases resolve admin login-overview IPs without round-tripping to a third party. Public `ipwho.is` is only consulted when the local lookup misses.
+- **Wide-event structured logging** -- Every API route emits a single envelope with `action`, latency, request id, sampled payload (with secret redaction), and an optional Loki transport for self-hosted log aggregation.
+- **Audit logging** -- All sensitive operations tracked with IP addresses, dedup-windowed to keep the ledger compact under bursty writes.
+
+<p align="center">
+  <img src="docs/diagrams/05-security-model.svg" alt="Security model: concentric layers — auth perimeter (passkey plus password fallback), session perimeter (HttpOnly cookie plus Postgres sessions), encrypted core (AES-256-GCM versioned keys), with side rails for the rate limiter, audit log, HMAC tokens, CSP/HSTS, and SSRF guard" width="900" />
+</p>
 
 ---
 
@@ -139,7 +245,6 @@ HealthLog is designed for people who take data ownership seriously.
 | -------------------- | ------------------------------------------------------------- |
 | `POSTGRES_PASSWORD`  | Password for the bundled Postgres service (Docker Compose)    |
 | `DATABASE_URL`       | PostgreSQL connection string (uses `POSTGRES_PASSWORD` above) |
-| `SESSION_SECRET`     | 64-char hex string for session signing                        |
 | `ENCRYPTION_KEY`     | 64-char hex string for AES-256-GCM                            |
 | `API_TOKEN_HMAC_KEY` | 64-char hex string for API token hashing                      |
 
@@ -152,6 +257,9 @@ HealthLog is designed for people who take data ownership seriously.
 | `WITHINGS_CLIENT_SECRET`  | Withings OAuth2 client secret                        |
 | `WITHINGS_REDIRECT_URI`   | OAuth callback URL                                   |
 | `WITHINGS_WEBHOOK_SECRET` | Webhook URL hardening secret                         |
+| `WHOOP_REDIRECT_URI`      | WHOOP OAuth callback URL (client id/secret set in Settings) |
+| `WHOOP_WEBHOOK_SECRET`    | HMAC secret for WHOOP webhook signature verification |
+| `FITBIT_REDIRECT_URI`     | Google Health/Fitbit OAuth callback URL (defaults to `<NEXT_PUBLIC_APP_URL>/api/fitbit/callback`; client id/secret set in Settings) |
 | `TELEGRAM_WEBHOOK_SECRET` | Telegram bot webhook secret                          |
 
 Telegram bot token, ntfy settings, Web Push VAPID keys, Umami, and GlitchTip URLs are configured in the **Admin Panel** and stored encrypted in the database.
@@ -160,33 +268,59 @@ Telegram bot token, ntfy settings, Web Push VAPID keys, Umami, and GlitchTip URL
 
 ## Architecture
 
+Data flows from every source — Withings, an Apple Health `export.zip`, the iPhone's live HealthKit, manual entry, moodLog — through the ingest endpoints into a single `Measurement` table and its pre-aggregated rollups, then back out to the dashboard, insights, Coach, and the doctor-report PDF.
+
+<p align="center">
+  <img src="docs/diagrams/01-data-flow.svg" alt="Data flow: sources (Withings, Apple Health export, iPhone HealthKit, manual, moodLog) into ingest endpoints, into Measurement plus MeasurementRollup, out to dashboard, insights, Coach, and doctor PDF" width="900" />
+</p>
+
 ```
 src/
 ├── app/                    # Next.js App Router pages & API routes
-│   ├── api/                # REST API endpoints (~60 route files)
+│   ├── api/                # REST API endpoints (180+ route files)
 │   ├── admin/              # Admin panel
+│   ├── auth/               # Login, register, passkey enrolment
 │   ├── medications/        # Medication management
 │   ├── measurements/       # Health metric entry
+│   ├── mood/               # Mood log
 │   ├── insights/           # AI-powered analytics
+│   ├── charts/             # Long-form charts
 │   ├── achievements/       # Gamification page
+│   ├── targets/            # Custom thresholds dashboard
+│   ├── notifications/      # Notification preferences matrix
+│   ├── bugreport/          # Built-in feedback / bug report
 │   ├── onboarding/         # 4-step guided setup
-│   └── settings/           # User preferences
+│   └── settings/           # User preferences (8 top-level sections)
 ├── components/
 │   ├── ui/                 # shadcn/ui primitives
 │   ├── layout/             # Shell (sidebar, topbar, bottom nav)
 │   ├── medications/        # Medication cards, forms, timeline
 │   ├── measurements/       # Measurement form, list
 │   ├── mood/               # Mood form, mood list
-│   └── charts/             # Recharts wrappers
+│   ├── charts/             # Recharts wrappers
+│   ├── insights/           # AI insight status / advisor cards
+│   ├── gamification/       # Achievement cards, progress
+│   ├── monitoring/         # Umami / GlitchTip bootstrap
+│   └── settings/           # Settings-page section components
 ├── lib/
 │   ├── auth/               # Session, audit, passkey logic
 │   ├── notifications/      # Dispatcher + channel senders
-│   ├── jobs/               # pg-boss worker
-│   ├── analytics/          # Trend calculations, compliance
+│   ├── jobs/               # pg-boss worker (reminders, insights, backups)
+│   ├── analytics/          # Trend calculations, compliance, correlations
+│   ├── ai/                 # Multi-provider client (OpenAI, Anthropic, Codex, local)
+│   ├── insights/           # Insight pipeline + medical prompts
+│   ├── gamification/       # Achievement definitions
+│   ├── feedback/           # Built-in feedback + GitHub escalation
+│   ├── moodlog/            # moodLog.app webhook + sync
+│   ├── monitoring/         # Umami / GlitchTip server-side hooks
 │   ├── withings/           # OAuth client, sync service
+│   ├── logging/            # Wide Events: builder, context, transports
 │   ├── i18n/               # Translations context & config
 │   ├── validations/        # Shared Zod schemas
+│   ├── api-handler.ts      # apiHandler wrapper, requireAuth/requireAdmin
+│   ├── api-response.ts     # { data, error } envelope helpers
 │   ├── crypto.ts           # AES-256-GCM encrypt/decrypt
+│   ├── rate-limit.ts       # Sliding-window rate limiter
 │   ├── db.ts               # Prisma singleton
 │   └── doctor-report-pdf.ts # Client-side PDF generation
 ├── hooks/                  # React hooks
@@ -196,17 +330,18 @@ src/
 ### Key Patterns
 
 - **RSC by default** -- `"use client"` only for interactive components
-- **API envelope** -- All responses follow `{ data, error, meta }` shape
+- **API envelope** -- All responses follow `{ data, error }` shape via `apiSuccess()` / `apiError()` in `src/lib/api-response.ts`
+- **apiHandler wrapper** -- Every API route wraps its handler in `apiHandler()` (`src/lib/api-handler.ts`) for consistent error handling, Wide-Event structured logging, and `x-request-id` propagation
 - **Encrypted secrets** -- Withings tokens, API keys, VAPID keys, notification credentials
 - **Timezone-aware** -- `Europe/Berlin` for display, UTC in database
-- **Route protection** -- `proxy.ts` checks session cookie, redirects unauthenticated requests
+- **Route protection** -- `proxy.ts` (Next.js 16's renamed middleware) checks session cookie, redirects unauthenticated requests
 - **Client-side PDF** -- Doctor reports generated in browser via jsPDF
 
 ---
 
 ## API Reference
 
-All mutations require authentication via session cookie. External ingest uses Bearer tokens.
+All mutations require authentication via session cookie. External ingest uses Bearer tokens. A machine-readable OpenAPI 3.1 spec for the iOS-locked native subset lives at [`docs/api/openapi.yaml`](docs/api/openapi.yaml) — the source of truth for any client codegen (Swift / Kotlin / OpenAPI Generator).
 
 <details>
 <summary><strong>Health Data</strong></summary>
@@ -232,7 +367,9 @@ All mutations require authentication via session cookie. External ingest uses Be
 | `POST`   | `/api/mood-entries`                 | Create mood entry    |
 | `DELETE` | `/api/mood-entries/:id`             | Delete mood entry    |
 | `GET`    | `/api/mood/analytics`               | Mood trend analytics |
-| `POST`   | `/api/integrations/moodlog/webhook` | moodLog.app webhook  |
+| `GET`    | `/api/mood/tags`                    | Structured mood-tag + rated-factor catalog |
+| `GET`    | `/api/mood/insights`                | Mood-relations associations |
+| `POST`   | `/api/integrations/moodlog/webhook` | moodLog.app webhook (deprecated) |
 
 </details>
 
@@ -254,17 +391,130 @@ All mutations require authentication via session cookie. External ingest uses Be
 <details>
 <summary><strong>Auth and Integrations</strong></summary>
 
-| Method | Endpoint                         | Description             |
-| ------ | -------------------------------- | ----------------------- |
-| `POST` | `/api/auth/register`             | Create account          |
-| `POST` | `/api/auth/login`                | Password login          |
-| `POST` | `/api/auth/logout`               | Destroy session         |
-| `GET`  | `/api/auth/me`                   | Current user profile    |
-| `POST` | `/api/auth/passkey/*`            | WebAuthn flows          |
-| `GET`  | `/api/withings/connect`          | Initiate Withings OAuth |
-| `POST` | `/api/insights/generate`         | Regenerate AI insights  |
-| `GET`  | `/api/gamification/achievements` | Achievement progress    |
-| `GET`  | `/api/health`                    | Docker health check     |
+| Method  | Endpoint                         | Description                         |
+| ------- | -------------------------------- | ----------------------------------- |
+| `POST`  | `/api/auth/register`             | Create account                      |
+| `POST`  | `/api/auth/login`                | Password login                      |
+| `POST`  | `/api/auth/logout`               | Destroy session                     |
+| `GET`   | `/api/auth/me`                   | Current user profile + avatar URL   |
+| `POST`  | `/api/auth/password`             | Change password                     |
+| `PATCH` | `/api/auth/profile`              | Update profile fields               |
+| `POST`  | `/api/user/avatar`               | Upload a profile photo (self-hosted)|
+| `DELETE`| `/api/user/avatar`               | Remove the profile photo            |
+| `POST`  | `/api/auth/passkey/*`            | WebAuthn flows (4 sub-routes)       |
+| `GET`   | `/api/auth/passkeys`             | List enrolled passkeys              |
+| `POST`  | `/api/auth/codex/device-start`   | ChatGPT (Codex) device-OAuth start  |
+| `POST`  | `/api/auth/codex/device-poll`    | Codex device-OAuth poll for token   |
+| `POST`  | `/api/auth/codex/disconnect`     | Revoke the stored Codex session     |
+| `GET`   | `/api/withings/connect`          | Initiate Withings OAuth             |
+| `POST`  | `/api/withings/sync`             | Trigger manual Withings sync        |
+| `POST`  | `/api/withings/webhook`          | Withings notification webhook       |
+| `GET`   | `/api/whoop/connect`             | Initiate WHOOP OAuth                 |
+| `POST`  | `/api/whoop/sync`                | Manual WHOOP sync (`{ fullSync }` for full history) |
+| `POST`  | `/api/integrations/whoop/test`   | Probe a saved WHOOP connection      |
+| `POST`  | `/api/integrations/whoop/resume` | Resume a WHOOP connection after a revoked grant |
+| `GET`   | `/api/fitbit/connect`            | Initiate Google Health/Fitbit OAuth |
+| `POST`  | `/api/fitbit/sync`               | Manual Fitbit sync (`{ fullSync }` for full history) |
+| `POST`  | `/api/integrations/fitbit/test`  | Probe a saved Google Health/Fitbit connection |
+| `POST`  | `/api/integrations/fitbit/resume`| Resume a Fitbit connection after a revoked grant |
+| `POST`  | `/api/insights/generate`         | Regenerate AI insights              |
+| `GET`   | `/api/insights/comprehensive`    | Aggregated insight payload          |
+| `GET`   | `/api/gamification/achievements` | Achievement progress                |
+| `GET`   | `/api/health`                    | Docker health check                 |
+
+</details>
+
+<details>
+<summary><strong>Personalization (Thresholds + Dashboard)</strong></summary>
+
+| Method | Endpoint                   | Description                                    |
+| ------ | -------------------------- | ---------------------------------------------- |
+| `GET`  | `/api/user/thresholds`     | Read per-user threshold overrides              |
+| `PUT`  | `/api/user/thresholds`     | Upsert thresholds (rate-limited, audit-logged) |
+| `GET`  | `/api/insights/targets`    | Effective ranges (defaults + overrides merged) |
+| `GET`  | `/api/dashboard/widgets`   | Read dashboard layout                          |
+| `PUT`  | `/api/dashboard/widgets`   | Persist dashboard layout (show/hide/reorder)   |
+| `POST` | `/api/onboarding/complete` | Mark onboarding finished                       |
+
+</details>
+
+<details>
+<summary><strong>Feedback + API Tokens</strong></summary>
+
+| Method   | Endpoint                | Description                         |
+| -------- | ----------------------- | ----------------------------------- |
+| `POST`   | `/api/feedback`         | Submit in-app feedback              |
+| `GET`    | `/api/bugreport/status` | Check published GitHub issue state  |
+| `GET`    | `/api/tokens`           | List own API tokens                 |
+| `POST`   | `/api/tokens`           | Mint new API token (Bearer, hashed) |
+| `DELETE` | `/api/tokens/:id`       | Revoke API token                    |
+
+</details>
+
+<details>
+<summary><strong>Notifications</strong></summary>
+
+| Method | Endpoint                         | Description                         |
+| ------ | -------------------------------- | ----------------------------------- |
+| `GET`  | `/api/notifications/preferences` | Read per-channel × per-event matrix |
+| `PUT`  | `/api/notifications/preferences` | Update preferences                  |
+| `GET`  | `/api/notifications/vapid`       | VAPID public key for Web Push       |
+| `POST` | `/api/notifications/web-push`    | Register Web Push subscription      |
+| `POST` | `/api/telegram/webhook`          | Telegram bot inline-button callback |
+
+</details>
+
+<details>
+<summary><strong>Admin (admin role required)</strong></summary>
+
+| Method | Endpoint                              | Description                           |
+| ------ | ------------------------------------- | ------------------------------------- |
+| `GET`  | `/api/admin/status`                   | System + integration status           |
+| `GET`  | `/api/admin/users`                    | List users                            |
+| `POST` | `/api/admin/users/:id/reset-password` | Force password reset                  |
+| `GET`  | `/api/admin/feedback`                 | All feedback / bug reports            |
+| `POST` | `/api/admin/feedback/:id/github`      | Escalate feedback to GitHub issue     |
+| `GET`  | `/api/admin/audit-log`                | Audit-log viewer                      |
+| `GET`  | `/api/admin/ai-settings`              | Read shared AI provider config        |
+| `PUT`  | `/api/admin/ai-settings`              | Update shared AI provider config      |
+| `GET`  | `/api/admin/tokens`                   | All issued API tokens                 |
+| `POST` | `/api/admin/notifications/test`       | Send test notification                |
+| `GET`  | `/api/admin/data`                     | Data backups + counts                 |
+| `GET`  | `/api/admin/status-overview`          | Aggregated status for the 6-card grid |
+| `POST` | `/api/admin/backup/test`              | Probe S3-compatible backup target     |
+
+</details>
+
+<details>
+<summary><strong>Public + v1.4 additions</strong></summary>
+
+| Method | Endpoint                           | Description                                     |
+| ------ | ---------------------------------- | ----------------------------------------------- |
+| `GET`  | `/api/version`                     | Public — version + build SHA + license, no auth |
+| `POST` | `/api/integrations/withings/test`  | Probe a saved Withings connection               |
+| `POST` | `/api/integrations/moodlog/test`   | Probe moodLog.app webhook reachability          |
+| `POST` | `/api/notifications/web-push/test` | Send a test Web Push to the current user        |
+| `POST` | `/api/admin/monitoring/glitchtip-test` | Trigger a Glitchtip ingest probe (admin)    |
+| `POST` | `/api/admin/monitoring/umami-test`     | Verify Umami script + website ID resolve (admin) |
+| `POST` | `/api/auth/refresh`                | Native client refresh-token rotation (POST body opts into revoke) |
+
+</details>
+
+<details>
+<summary><strong>FHIR + clinician sharing (v1.11)</strong></summary>
+
+Read-only HL7 FHIR R4 REST API, gated behind the `fhir:read` token scope:
+
+| Method | Endpoint                               | Description                                          |
+| ------ | -------------------------------------- | ---------------------------------------------------- |
+| `GET`  | `/api/fhir/metadata`                   | FHIR CapabilityStatement                             |
+| `GET`  | `/api/fhir/Patient`                    | Patient resource for the token's user                |
+| `GET`  | `/api/fhir/Observation`                | Vitals + labs as LOINC-coded observations            |
+| `GET`  | `/api/fhir/MedicationStatement`        | Medication regimen                                   |
+| `GET`  | `/api/fhir/MedicationAdministration`   | Logged intake events                                 |
+| `GET`  | `/api/fhir/$everything`                | Bundle of every resource above                       |
+
+Clinician share-link lifecycle — create a scoped, time-limited link, hand a clinician the read-only `/c/<token>` view, and revoke it after the visit. Share links do not expose the FHIR API (`capabilities.share.fhirApi=false`).
 
 </details>
 
@@ -272,23 +522,33 @@ All mutations require authentication via session cookie. External ingest uses Be
 
 ## Integrations
 
-| Integration     | Setup         | Purpose                                  |
-| --------------- | ------------- | ---------------------------------------- |
-| **Withings**    | Env vars      | Auto-sync weight, BP, and activity       |
-| **Telegram**    | Admin Panel   | Medication reminders with inline buttons |
-| **ntfy**        | User Settings | Self-hosted push notifications           |
-| **Web Push**    | Admin Panel   | Browser-native VAPID notifications       |
-| **OpenAI**      | User Settings | AI health insights (BYOK)                |
-| **moodLog.app** | User Settings | Mood tracking sync                       |
-| **Umami**       | Admin Panel   | Privacy-friendly analytics               |
-| **GlitchTip**   | Admin Panel   | Sentry-compatible error tracking         |
+| Integration              | Setup         | Purpose                                  |
+| ------------------------ | ------------- | ---------------------------------------- |
+| **Withings**             | Env vars      | Auto-sync weight, BP, and activity       |
+| **WHOOP**                | User Settings | OAuth2 sync of recovery, strain, sleep, body, and workouts (BYO-keys) |
+| **Google Health / Fitbit** | User Settings | OAuth2 sync of activity, health metrics, sleep, and workouts for Fitbit/Pixel (BYO-keys, **experimental**) |
+| **Telegram**             | Admin Panel   | Medication reminders with inline buttons |
+| **ntfy**                 | User Settings | Self-hosted push notifications           |
+| **Web Push**             | Admin Panel   | Browser-native VAPID notifications       |
+| **OpenAI / Anthropic / local** | User Settings | AI health insights (BYOK or local endpoint) |
+| **moodLog.app**          | User Settings | Mood tracking sync (deprecated — mood is now tracked natively) |
+| **Umami**                | Admin Panel   | Privacy-friendly analytics               |
+| **GlitchTip**            | Admin Panel   | Sentry-compatible error tracking         |
+
+### Source priority
+
+When two providers report the same metric — a Withings scale and an Apple Watch both logging weight, or HealthKit and Fitbit both reporting steps — HealthLog keeps every row as an audit trail but applies a per-metric source priority to decide which reading is canonical. Cumulative metrics (steps, distance, active energy, floors) pick exactly one source per day so they are never double-counted; point measurements (weight, blood pressure, HRV) pick a display-preferred source. The default ladder reflects measurement reliability for each metric class: a dedicated scale outranks a wrist estimate for weight, a recovery strap leads the sleep and HRV ladders, and a cuff leads blood pressure. The ladder is per-user adjustable, and an optional device-type tie-break decides between two devices on the same source. The underlying idea is [data fusion](https://en.wikipedia.org/wiki/Data_fusion) — combining several imperfect sensors into a single, more reliable estimate rather than averaging them blindly.
+
+<p align="center">
+  <img src="docs/diagrams/04-source-priority.svg" alt="Source priority: three sources for the same metric on the same day, the resolver picking one canonical row per cumulative-versus-point ladder while the losing rows stay in the audit trail" width="900" />
+</p>
 
 ---
 
 ## Local Development
 
 ```bash
-# Prerequisites: Node.js 20+, pnpm, PostgreSQL
+# Prerequisites: Node.js 22, pnpm, PostgreSQL
 
 cp .env.example .env
 pnpm install
@@ -321,6 +581,86 @@ The included `docker-compose.yml` runs the app and PostgreSQL. The entrypoint au
 
 The app listens on port **3000**. Place it behind Nginx, Caddy, or Traefik for TLS termination. Works out of the box with [Coolify](https://coolify.io/).
 
+<p align="center">
+  <img src="docs/diagrams/03-self-hosting-topology.svg" alt="Self-hosting topology: internet → reverse proxy → Next.js app + pg-boss worker → PostgreSQL, with GHCR image pull and optional Coolify autodeploy and S3 backup" width="900" />
+</p>
+
+For a single-process default the same container hosts both the web and worker (`HEALTHLOG_PROCESS_TYPE=all`, the default). Split them via `HEALTHLOG_PROCESS_TYPE=web` and `HEALTHLOG_PROCESS_TYPE=worker` for horizontal scale. Off-host AES-GCM daily backups to any S3-compatible bucket (R2, B2, MinIO, AWS) are opt-in via the admin panel. See [`docs/self-hosting/`](docs/self-hosting/) and [`docs/ops/`](docs/ops/) for the full operator manual.
+
+---
+
+## Documentation
+
+The full documentation set lives under [`docs/`](docs/) (also published at [docs.healthlog.dev](https://docs.healthlog.dev)). A technical visitor browsing the source will also find a navigational `README.md` in each key code directory (`src/`, `src/lib/`, `src/app/`, `src/components/`, `prisma/`, `scripts/`, `e2e/`).
+
+| Area | Where | What it covers |
+| ---- | ----- | -------------- |
+| Self-hosting | [`docs/self-hosting/`](docs/self-hosting/) | Getting started, reverse-proxy setup, horizontal scaling, [reproductive-health data on your own server](docs/self-hosting/reproductive-health-data.md) |
+| Threat model | [`docs/security/cycle-data-threat-model.md`](docs/security/cycle-data-threat-model.md) | What self-hosting cycle data does and does not protect against |
+| Operator runbooks | [`docs/ops/`](docs/ops/) | Deploy, encryption-key rotation, backup/restore, env check, migrations, TLS pinning |
+| API contract | [`docs/api/`](docs/api/) | OpenAPI 3.1 spec (`openapi.yaml`) for the native client subset |
+| Integrations | [`docs/integrations/`](docs/integrations/) | Withings, WHOOP, Google Health/Fitbit, Apple Health, AI providers |
+| Architecture diagrams | [`docs/diagrams/`](docs/diagrams/) | The five SVG diagrams embedded above |
+| Migration notes | [`docs/migration/`](docs/migration/) | Cross-version upgrade notes |
+| Design records | [`docs/adr/`](docs/adr/), [`docs/ui-guidelines.md`](docs/ui-guidelines.md) | Architecture decision records + UI conventions |
+| Contributor manual | [`CLAUDE.md`](CLAUDE.md), [`CONTRIBUTING.md`](CONTRIBUTING.md) | Conventions, branch/release model, the critical-files map |
+
+---
+
+## Roadmap
+
+| Release line | Focus |
+| ------------ | ----- |
+| **v1.4.x** | Web maturity — Apple Health import, AI Coach, persistent rollup tier, multi-provider AI, doctor PDF, encryption-key rotation, Coolify autodeploy. Roughly weekly cadence. |
+| **v1.5** | Native iOS client (SwiftUI) in public beta via [TestFlight](https://testflight.apple.com/join/bucuTBpa). Backend contract locked in [`docs/api/openapi.yaml`](docs/api/openapi.yaml); the iOS app lives in a separate repository and ingests via the same `/api/measurements/batch` and `/api/auth/refresh` surfaces the web uses. |
+| **v1.6 – v1.7** | Medication editor overhaul + route of administration (v1.6), then health-record export (PDF + HL7 FHIR R4), flexible schedules (RRULE / rolling / interval-weeks / one-time / PRN / cyclic) with cadence-canonical compliance, full HealthKit metric coverage, a metric/imperial display preference, a first-paint dashboard snapshot, and a sync delta feed for offline clients (v1.7). |
+| **v1.8 – v1.10** | Insights redesign with selectable time ranges (v1.8 – v1.9), then a derived-metrics tier (v1.10): fitness-age, vascular-age delta, HRV balance, sleep score, readiness and recovery scores, and a coincident-deviation early-strain flag — each computed from your own measurements, each citing its inputs and degrading to "not enough data" rather than fabricating a value. |
+| **v1.11 – v1.12** (current) | WHOOP device sync, a read-only HL7 FHIR R4 API with shareable clinician records, mood-relations and sleep-depth (hypnogram) insights (v1.11); then a Google Health/Fitbit connection for Fitbit and Pixel wearables (experimental) and a rebuilt mood log — five-face capture, a structured tag catalog, and rated daily-life factors (v1.12). |
+| **v2.x** (planned) | Multi-tenant hardening, expanded device passthrough (Garmin / Polar), opt-in cross-user aggregate research mode (off by default; never enabled without explicit consent). |
+
+Two known limitations carry forward from v1.11: dedup across two sources of the same standard vital is deferred (both rows persist, source priority decides display), and the coach's durable conversation-summary / remembered-facts layer is deferred — each answer reasons from your data afresh rather than from a running memory.
+
+The detailed changelog lives in [`CHANGELOG.md`](CHANGELOG.md).
+
+---
+
+## Native iOS client
+
+<p align="center">
+  <a href="https://testflight.apple.com/join/bucuTBpa"><strong>Join the TestFlight public beta &rarr;</strong></a>
+</p>
+
+A SwiftUI iOS companion that lives on the same `/api` surfaces as the web client — same server, same data, same source of truth. The phone is a view + a write-ahead log; your server is the database. Code lives in a separate repo: [github.com/MBombeck/healthlog-iOS](https://github.com/MBombeck/healthlog-iOS).
+
+### What the phone unlocks
+
+- **HealthKit two-way sync.** Today's step count, weight, blood pressure, HRV, sleep, glucose, etc. read live from Apple Health and round-trip to your server through `HKObserverQuery` + `HKAnchoredObjectQuery` + a `BGProcessingTask` for guaranteed delivery. `HKMetadataKeyExternalUUID` on every iOS-side write keeps the server and Apple Health from echoing each other.
+- **Medication reminders that actually fire.** Local notifications with action buttons (Taken / Snooze 15 min / Skipped) that hit the server's mark-intake endpoint directly — without opening the app.
+- **On-device AI Coach.** A conversational surface powered by Apple's Foundation Models framework on iOS 26+ Apple-Intelligence-eligible iPhones. The prompt and the response never leave the device — your numbers, your health questions, your phone.
+- **Passkey-first auth.** Sign in with Face ID or Touch ID via WebAuthn; email + magic-link is the fallback. SPKI public-key pinning on every authenticated request, Keychain with `afterFirstUnlockThisDeviceOnly`, and a log sanitizer that filters tokens and hostnames out of every line.
+- **Doctor-report export.** Generate a FHIR-flavoured PDF bundle from the iPhone based on the LOINC mappings reviewed on the server's clinician surface.
+
+### Built on Stanford Spezi
+
+The iOS client adopts the [Stanford Spezi](https://spezi.stanford.edu) digital-health framework where it earns its keep — battle-tested code maintained by Stanford's Biodesign Digital Health group rather than rolled by hand:
+
+- **SpeziHealthKit** for the HealthKit-read pipeline (live and historical),
+- **SpeziChat** under the on-device AI Coach surface,
+- **SpeziFHIR** + **HealthKitOnFHIR** for the doctor-report export bundle,
+- **SpeziAccessGuard**, **SpeziScheduler**, **SpeziMedication** queued for the next release line.
+
+Spezi exists because medical-device-grade software needs medical-device-grade primitives — the same modules ship in clinical-trial apps at Stanford Medicine. Adopting them gives the iOS client a quality + security floor a solo-maintainer code-base could not otherwise hit.
+
+### Status
+
+`v0.6.1.x` ships almost daily; the [iOS repo CHANGELOG](https://github.com/MBombeck/healthlog-iOS/blob/main/CHANGELOG.md) and tag list track what landed in each build. German-primary UI with English secondary. iOS 18+ minimum (iOS 26+ for the on-device Coach). AGPL-3.0, same as this repo.
+
+<p align="center">
+  <a href="https://testflight.apple.com/join/bucuTBpa">TestFlight beta</a> &middot;
+  <a href="https://github.com/MBombeck/healthlog-iOS">iOS repo</a> &middot;
+  <a href="https://github.com/MBombeck/healthlog-iOS/issues">iOS issues</a>
+</p>
+
 ---
 
 ## Contributing
@@ -343,5 +683,7 @@ HealthLog is licensed under the [GNU Affero General Public License v3.0](LICENSE
 <p align="center">
   <a href="https://healthlog.dev">healthlog.dev</a> &middot;
   <a href="https://demo.healthlog.dev">Live Demo</a> &middot;
-  <a href="https://docs.healthlog.dev">Docs</a>
+  <a href="https://docs.healthlog.dev">Docs</a> &middot;
+  <a href="https://testflight.apple.com/join/bucuTBpa">iOS TestFlight</a> &middot;
+  <a href="https://buymeacoffee.com/mbombeck">Buy Me A Coffee</a>
 </p>

SECURITY.md

@@ -70,6 +70,6 @@ HealthLog Docker images are built and published from this repository's CI:
 - **Provenance attestation**: each image carries a [SLSA build provenance](https://slsa.dev/spec/v1.0/provenance) statement linking it back to the GitHub Actions run, the commit SHA, and the workflow definition
 - **SBOM**: each image includes a [Software Bill of Materials](https://docs.docker.com/build/metadata/attestations/sbom/) you can inspect with `docker buildx imagetools inspect ghcr.io/mbombeck/healthlog:latest --format '{{ json .SBOM }}'`
 
-To pin to a specific version in production, replace `:latest` with the released tag in your `docker-compose.yml`, e.g. `ghcr.io/mbombeck/healthlog:1.2.0`. Pinning is recommended for self-hosters who want explicit control over upgrades.
+To pin to a specific version in production, replace `:latest` with the released tag in your `docker-compose.yml`, e.g. `ghcr.io/mbombeck/healthlog:1.3.2`. Pinning is recommended for self-hosters who want explicit control over upgrades.
 
 If you discover a tampered or unexpected image, please report it as a vulnerability via the email above.

assets/geolite2/README.md

@@ -0,0 +1,20 @@
+# GeoLite2 databases
+
+`GeoLite2-City.mmdb` and `GeoLite2-ASN.mmdb` are downloaded at build
+time by `scripts/fetch-geolite2.sh` and copied into the Docker image
+at `/opt/geolite2/`. The runtime resolver in `src/lib/geo.ts` reads
+them via `mmdb-lib`.
+
+Run before `docker build`:
+
+```
+MAXMIND_LICENSE_KEY=xxxx ./scripts/fetch-geolite2.sh
+```
+
+Without the key the script exits cleanly and the image builds without
+the databases — the resolver falls back to the `ipwho.is` online
+provider (the v1.4.26 behaviour).
+
+This product includes GeoLite2 data created by MaxMind, available from
+<https://www.maxmind.com>. The databases are licensed under
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).

docker-compose.yml

@@ -1,35 +1,121 @@
 services:
+  # Single-container default (HEALTHLOG_PROCESS_TYPE=all). Existing
+  # self-host deployments stay working with `docker compose up`.
+  # For horizontal scaling switch to the web/worker split below
+  # (HEALTHLOG_PROCESS_TYPE=web on this service + uncomment app-worker).
   app:
-    # Pre-built multi-arch images are published to GHCR by
-    # .github/workflows/docker-publish.yml on every push to main and on
-    # tagged releases. Pin to a specific version in production:
-    # e.g. ghcr.io/mbombeck/healthlog:1.2.0
+    # Tracks the GHCR `:latest` multi-arch image. `pull_policy: always`
+    # is the load-bearing line — without it, Docker keeps a stale
+    # `:latest` digest cached on the host and skips the registry round-
+    # trip on `compose up`, which is what kept Coolify re-deploying the
+    # previous image after every tag push. With pull_policy=always the
+    # compose-up always re-checks the registry digest and pulls when
+    # GHCR has a fresher manifest. The small bandwidth cost on every
+    # `compose up` is the price of digest-correctness.
     image: ghcr.io/mbombeck/healthlog:latest
-    # Fallback build context: if the image is not yet in the registry,
-    # or you want to test local changes, run `docker compose up --build`.
-    build:
-      context: .
-      dockerfile: Dockerfile
+    pull_policy: always
     container_name: healthlog-app
     ports:
       - "3000:3000"
     environment:
-      # Plain ${VAR} interpolation only — no ${VAR:?error} validation
-      # syntax. Some hosting platforms (e.g. Coolify) parse compose files
-      # eagerly and store the *fallback error string* as the literal value
-      # when the env var is unset, which then breaks the deployment.
-      # Validation is enforced by docker-entrypoint.sh before the app starts.
-      DATABASE_URL: "postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog?schema=public"
+      # connection_limit is set explicitly: Prisma's own default is
+      # cpu_count*2+1, which starves the combined web+worker process
+      # (HEALTHLOG_PROCESS_TYPE=all) under background AI/rollup load. Default
+      # 20 suits a small host; raise DB_CONNECTION_LIMIT on a busy one (keep it
+      # below the database's max_connections, leaving headroom for pg-boss,
+      # migrations, and backups). pool_timeout is the seconds a query waits for
+      # a free connection before erroring.
+      DATABASE_URL: "postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog?schema=public&connection_limit=${DB_CONNECTION_LIMIT:-20}&pool_timeout=${DB_POOL_TIMEOUT:-20}"
       NODE_ENV: production
-      SESSION_SECRET: "${SESSION_SECRET}"
       ENCRYPTION_KEY: "${ENCRYPTION_KEY}"
+      ENCRYPTION_KEYS: "${ENCRYPTION_KEYS:-}"
+      ENCRYPTION_ACTIVE_KEY_ID: "${ENCRYPTION_ACTIVE_KEY_ID:-}"
       API_TOKEN_HMAC_KEY: "${API_TOKEN_HMAC_KEY}"
       NEXT_PUBLIC_APP_URL: "${NEXT_PUBLIC_APP_URL:-http://localhost:3000}"
       APP_URL: "${APP_URL:-http://localhost:3000}"
+      # v1.5.1 session-cookie Secure-flag opt-out. Forwarded explicitly so
+      # an operator setting SESSION_COOKIE_SECURE=false in .env actually
+      # reaches the Node process (the compose `environment:` block is a
+      # whitelist — vars not listed here don't propagate from .env into
+      # the container, even though docker-compose reads .env for
+      # `${VAR}` substitution at compose-up time).
+      SESSION_COOKIE_SECURE: "${SESSION_COOKIE_SECURE:-}"
+      # all = bundle web + worker in this container (default, single-host)
+      # web = serve HTTP only; pair with a separate app-worker service
+      HEALTHLOG_PROCESS_TYPE: "${HEALTHLOG_PROCESS_TYPE:-all}"
+      BACKUP_ENCRYPTION_KEY: "${BACKUP_ENCRYPTION_KEY:-}"
+      BACKUP_S3_ENDPOINT: "${BACKUP_S3_ENDPOINT:-}"
+      BACKUP_S3_BUCKET: "${BACKUP_S3_BUCKET:-}"
+      BACKUP_S3_ACCESS_KEY: "${BACKUP_S3_ACCESS_KEY:-}"
+      BACKUP_S3_SECRET_KEY: "${BACKUP_S3_SECRET_KEY:-}"
+      BACKUP_S3_REGION: "${BACKUP_S3_REGION:-auto}"
+      BACKUP_RETENTION_DAYS: "${BACKUP_RETENTION_DAYS:-30}"
+      # Per-export ceiling on MedicationAdministration rows in the FHIR
+      # health-record Bundle. Bounded 1..50000, default 5000. Listed here so
+      # an operator override in .env actually reaches the container (the
+      # `environment:` block is a whitelist).
+      FHIR_MAX_MEDICATION_ADMINISTRATIONS: "${FHIR_MAX_MEDICATION_ADMINISTRATIONS:-}"
+      # WHOOP integration (optional). The app client id/secret are per-user
+      # BYO-keys stored encrypted in the DB, so there is no
+      # WHOOP_CLIENT_ID/SECRET env. WHOOP_WEBHOOK_SECRET is the instance-level
+      # path-segment + HMAC-verification secret for the webhook;
+      # WHOOP_REDIRECT_URI overrides the derived
+      # `${NEXT_PUBLIC_APP_URL}/api/whoop/callback` when the public URL
+      # differs. Listed here so an operator override in .env reaches the
+      # container (the `environment:` block is a whitelist).
+      WHOOP_WEBHOOK_SECRET: "${WHOOP_WEBHOOK_SECRET:-}"
+      WHOOP_REDIRECT_URI: "${WHOOP_REDIRECT_URI:-}"
+      # TLS leaf SPKI-change alarm baseline (optional). The native client
+      # pins the served TLS leaf; this is the known-good pin set the monitor
+      # alarms against on a rotation. Comma-separated for the dual-pin
+      # renewal window. Listed here so an operator value in .env reaches the
+      # container (the `environment:` block is a whitelist). See
+      # docs/ops/tls-cert-pin.md.
+      TLS_LEAF_SPKI_PINS: "${TLS_LEAF_SPKI_PINS:-}"
     depends_on:
       db:
         condition: service_healthy
     restart: unless-stopped
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/version || exit 1",
+        ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+
+  # Optional dedicated worker container — uncomment + set
+  # HEALTHLOG_PROCESS_TYPE=web on `app` to split the deployment.
+  # See docs/self-hosting/scaling.md for the full guide.
+  #
+  # app-worker:
+  #   image: ghcr.io/mbombeck/healthlog:latest
+  #   build:
+  #     context: .
+  #     dockerfile: Dockerfile
+  #   container_name: healthlog-worker
+  #   environment:
+  #     DATABASE_URL: "postgresql://healthlog:${POSTGRES_PASSWORD}@db:5432/healthlog?schema=public"
+  #     NODE_ENV: production
+  #     ENCRYPTION_KEY: "${ENCRYPTION_KEY}"
+  #     ENCRYPTION_KEYS: "${ENCRYPTION_KEYS:-}"
+  #     ENCRYPTION_ACTIVE_KEY_ID: "${ENCRYPTION_ACTIVE_KEY_ID:-}"
+  #     API_TOKEN_HMAC_KEY: "${API_TOKEN_HMAC_KEY}"
+  #     APP_URL: "${APP_URL:-http://localhost:3000}"
+  #     HEALTHLOG_PROCESS_TYPE: "worker"
+  #     BACKUP_ENCRYPTION_KEY: "${BACKUP_ENCRYPTION_KEY:-}"
+  #     BACKUP_S3_ENDPOINT: "${BACKUP_S3_ENDPOINT:-}"
+  #     BACKUP_S3_BUCKET: "${BACKUP_S3_BUCKET:-}"
+  #     BACKUP_S3_ACCESS_KEY: "${BACKUP_S3_ACCESS_KEY:-}"
+  #     BACKUP_S3_SECRET_KEY: "${BACKUP_S3_SECRET_KEY:-}"
+  #     BACKUP_S3_REGION: "${BACKUP_S3_REGION:-auto}"
+  #   depends_on:
+  #     db:
+  #       condition: service_healthy
+  #   restart: unless-stopped
 
   db:
     image: postgres:16-alpine

docker-entrypoint.sh

@@ -9,7 +9,7 @@ set -e
 # Validating here guarantees a clear, deploy-platform-agnostic
 # failure message before we touch the database.
 missing=""
-for var in DATABASE_URL SESSION_SECRET ENCRYPTION_KEY API_TOKEN_HMAC_KEY; do
+for var in DATABASE_URL ENCRYPTION_KEY API_TOKEN_HMAC_KEY; do
   eval "value=\$$var"
   if [ -z "$value" ]; then
     missing="$missing $var"

docs/README.md

@@ -0,0 +1,33 @@
+# `docs/` — internal reference + operator playbooks
+
+The user-facing documentation lives at **<https://docs.healthlog.dev>** —
+that's the canonical surface for self-hosting guides, integration
+walkthroughs, AI-provider setup, and the doctor-report workflow.
+
+The files in this directory are the internal operator playbooks, audit
+notes, and machine-readable specs that ship alongside the source:
+
+- [`api/`](./api/) — the OpenAPI 3.1 spec for the native-client subset
+  (iOS DTO codegen target). See [`api/README.md`](./api/README.md) for
+  the preview commands.
+- [`ops/`](./ops/) — backup / restore + encryption-key-rotation
+  playbooks. These are the runbooks an operator reaches for during an
+  incident.
+- [`self-hosting/`](./self-hosting/) — horizontal-scaling notes
+  (`HEALTHLOG_PROCESS_TYPE=web|worker|all`) and the deploy-pipeline
+  recipe. Routine install steps stay on `docs.healthlog.dev`.
+- [`migration/`](./migration/) — release-by-release migration notes.
+  Read the entry for the version you're upgrading from.
+- [`audit/`](./audit/) — per-release audit summaries archived for
+  forensic traceability.
+- [`apple-store-connect-checklist.md`](./apple-store-connect-checklist.md)
+  — the iOS submission gate.
+- [`doctor-report.md`](./doctor-report.md) — PDF generator design
+  notes.
+- [`codex-protocol-spec.md`](./codex-protocol-spec.md) — Codex / ChatGPT
+  OAuth protocol reverse-engineering notes.
+- [`ui-guidelines.md`](./ui-guidelines.md) — UI / a11y house style.
+
+If you're a self-hoster looking to spin up an instance, start at
+<https://docs.healthlog.dev> or jump to the [Quick Start in the project
+README](../README.md#quick-start).

docs/adr/0001-insights-naming-convention.md

@@ -0,0 +1,82 @@
+# 0001 — Insights naming convention: localised UI, English identifiers
+
+- Status: accepted
+- Date: 2026-05-31
+
+## Context
+
+The Insights surface grew bilingually. The mother page (`/insights`) and its
+routed metric sub-pages were keyed by German slugs (`/insights/blutdruck`,
+`/insights/gewicht`, …) because German was the primary author voice when the
+routed strip first shipped. Over time the surface accumulated a mix: route
+folders, the tile-layout enum, and several internal maps were German, while
+later additions (`hrv`, `oxygenSaturation`, `restingHr`, `activeEnergy`,
+`workouts`) landed in English. The result was an inconsistent identifier space
+where a contributor could not predict whether a given key was German or English.
+
+Identifiers leak. A German route slug shows up in URLs, in browser history, in
+the OpenAPI contract the iOS client reads, and in every internal map that pivots
+on the slug. Mixed-language identifiers make the codebase harder to navigate and
+make the public API contract read inconsistently.
+
+Two surfaces also speak these identifiers across a boundary we do not control:
+
+1. **URLs** — bookmarked and cached by the PWA.
+2. **The tile-layout contract** — `GET/PUT /api/insights/layout`, which the
+   native iOS client persists against. The tile ids in that payload are a
+   client-visible contract.
+
+## Decision
+
+Separate the two naming axes cleanly:
+
+- **UI copy is always localised.** Every visible string resolves through an
+  i18n `t()` key and is translated across all six locales (`de / en / es / fr /
+  it / pl`). The user never sees a raw identifier.
+- **Internal identifiers are English.** Route slugs (`/insights/<slug>`), the
+  tile-layout enum (`INSIGHTS_TILE_IDS`), query keys, and the internal
+  slug→metric / slug→target maps all use established English terms. English is
+  the lingua franca of the codebase and of the public API contract.
+
+Concretely, v1.8.0 migrates the routed Insights slugs and the tile-layout enum
+from German to English (e.g. `blutdruck` → `blood-pressure`, `gewicht` →
+`weight`, `medikamente` → `medications`). The full rename table lives in
+`src/lib/insights/sub-page-metric.ts` (slugs) and `src/lib/insights-layout.ts`
+(tile ids).
+
+## Non-breaking strategy
+
+The migration must not break either client-visible boundary:
+
+- **URLs.** `next.config.ts` `redirects()` emits a `permanent: true` (301)
+  redirect from every legacy German slug to its English target, including a
+  `:path*` variant so any nested route survives. Bookmarks and cached PWA
+  navigation keep resolving.
+- **Tile-layout contract.** The layout endpoint keeps **accepting** the legacy
+  German tile ids on input. The Zod enum is built from
+  `ACCEPTED_INSIGHTS_TILE_IDS` (canonical English ids *plus* the legacy German
+  aliases), so a `PUT` carrying old ids validates rather than tripping a 422.
+  `normalizeInsightsTileId` collapses each legacy id onto its canonical English
+  replacement; this normalisation runs on **both** the read path
+  (`resolveInsightsLayout`) and the write path (`serializeInsightsLayout`), so:
+  - a layout persisted by a `≤ v1.7.x` client surfaces canonical English ids on
+    `GET` without forcing a re-`PUT`;
+  - a `PUT` sending legacy ids persists canonical English ids;
+  - a layout that carries both a legacy and a canonical id for one tile dedupes
+    to a single canonical entry.
+
+  The legacy ids are accepted-but-deprecated. They will be removed from the
+  accepted set in a future major version once telemetry shows clients have
+  migrated. The OpenAPI `InsightsLayoutBody` schema documents the canonical ids,
+  the accepted legacy ids, and the deprecation.
+
+## Consequences
+
+- The Insights identifier space is uniformly English and predictable.
+- No client breaks on upgrade: old URLs redirect, old tile ids normalise.
+- The legacy-alias map and the redirect table are deliberate, finite debt to be
+  retired in a future major. Until then they are covered by tests
+  (`src/app/api/insights/layout/__tests__/route.test.ts`) that assert the
+  non-breaking round-trip.
+- New Insights surfaces follow the convention from the start: English slug,
+  English tile id, localised `t()` copy.

docs/api/README.md

@@ -0,0 +1,76 @@
+# HealthLog API Spec
+
+`openapi.yaml` is the canonical OpenAPI 3.1 description for the HealthLog
+Next.js API. It is the source of truth for the native iOS client's
+DTO codegen.
+
+## Preview locally
+
+Open an interactive Redoc preview in your browser:
+
+```bash
+npx @redocly/cli preview docs/api/openapi.yaml
+```
+
+Generate static HTML for sharing:
+
+```bash
+npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
+```
+
+## Validate
+
+```bash
+npx @redocly/cli lint docs/api/openapi.yaml
+```
+
+The spec is expected to be lint-clean (errors = 0). Some warnings are
+intentional:
+
+- `no-server-example.com` — `http://localhost:3000` is the dev server.
+- `operation-2xx-response` / `operation-4xx-response` — webhook + redirect
+  endpoints intentionally omit one or the other.
+- `no-unused-components` — `ReminderPhase` is exposed for client codegen
+  even though no path response references it directly.
+
+## Layout
+
+- **`info`** — title, version (mirrored from `package.json`), description.
+- **`servers`** — production `https://healthlog.bombeck.io` plus
+  `http://localhost:3000` for local development.
+- **`tags`** — domain groupings (`Auth`, `Measurements`, `Medications`,
+  `Mood`, `Dashboard`, `Insights`, `Achievements`, `DoctorReport`,
+  `Integrations`, `User`, `Tokens`, `Notifications`, `Onboarding`,
+  `Health`, `Settings`, `Analytics`, `Export`, `AuditLog`, `Feedback`,
+  `BugReport`, `Monitoring`, `Webhooks`, `Ingest`, `Admin`).
+- **`securitySchemes`**:
+  - `bearerAuth` — long-lived `hlk_*` API tokens issued via `POST /api/tokens`.
+    Required on `/api/ingest/medication`.
+  - `sessionCookie` — HttpOnly `healthlog_session` cookie set by the
+    password and passkey login flows. Used by the web app and any iOS
+    client running inside a web view.
+- **`components.schemas`** — DTOs for all routes plus the underlying
+  Prisma models (e.g. `Measurement`, `Medication`, `MedicationIntakeEvent`,
+  `MoodEntry`, `User`, `DashboardLayout`, `ApiEnvelope`, `ApiError`).
+- **`paths`** — all routes from `src/app/api/**/route.ts`, including
+  the `/api/admin/*` family which is tagged `Admin` and marked internal.
+
+## Conventions
+
+- Successful responses use the envelope `{ data, error: null }`.
+- Error responses use the envelope `{ data: null, error: '<message>' }`.
+- Pagination uses `limit` + `offset` query parameters and a
+  `meta: { total, limit, offset }` block on the response.
+- All timestamps are ISO 8601 / RFC 3339 (`format: date-time`) in UTC.
+- IDs are CUIDs (opaque strings).
+
+## Updating the spec
+
+When adding or changing routes:
+
+1. Update the relevant route handler under `src/app/api/**/route.ts`.
+2. Mirror the change in `openapi.yaml`. Keep `operationId` camelCase and
+   stable — the iOS codegen keys off it.
+3. Run `npx @redocly/cli lint docs/api/openapi.yaml` and resolve all
+   errors. Warnings are tolerated when documented above.
+4. Bump `info.version` if the change is breaking for clients.

docs/api/cycle-healthkit-mapping.md

@@ -0,0 +1,71 @@
+# Apple Health → cycle mapping
+
+How HealthLog folds Apple Health reproductive samples into the cycle model.
+Both the `export.xml` importer and the iOS batch contract share one mapping
+table: `src/lib/cycle/healthkit-mapping.ts`. This page is the human-readable
+companion — keep the two in sync.
+
+Reproductive samples route into **cycle day-logs** (`CycleDayLog`), never into
+`Measurement`. Each Apple Health day collapses into one canonical day-log per
+`(user, date)`; the importer writes `source = APPLE_HEALTH` with a synthetic
+per-day `externalId` (`hkcycle:<YYYY-MM-DD>`) so a re-import upserts the same
+row. The fold only runs when cycle tracking is enabled for the account.
+
+## Day-log fields
+
+| HealthKit category type | CycleDayLog field | Values |
+|---|---|---|
+| `MenstrualFlow` | `flow` | unspecified→LIGHT, light→LIGHT, medium→MEDIUM, heavy→HEAVY, none→NONE |
+| `IntermenstrualBleeding` | `intermenstrualBleeding` | presence → `true` |
+| `CervicalMucusQuality` | `cervicalMucus` | dry→DRY, sticky→STICKY, creamy→CREAMY, watery→WATERY, eggWhite→EGG_WHITE |
+| `OvulationTestResult` | `ovulationTest` | negative→NEGATIVE, lhSurge→POSITIVE_LH_SURGE, indeterminate→INDETERMINATE, estrogenSurge→ESTROGEN_SURGE |
+| `SexualActivity` | `sexualActivity` + `protectedSex` | presence → `true`; `HKMetadataKeySexualActivityProtectionUsed` → `protectedSex` |
+| `PregnancyTestResult` | `pregnancyTest` | negative→NEGATIVE, positive→POSITIVE, indeterminate→INDETERMINATE |
+| `ProgesteroneTestResult` | `progesteroneTest` | negative→NEGATIVE, positive→POSITIVE, indeterminate→INDETERMINATE |
+| `Contraceptive` | `contraceptive` (+ profile nudge) | unspecified→UNSPECIFIED, implant→IMPLANT, injection→INJECTION, iud→IUD, ring→INTRAVAGINAL_RING, oral→ORAL, patch→PATCH, emergency→EMERGENCY |
+
+HealthLog's `SPOTTING` flow level has no HealthKit counterpart; it is only ever
+produced by a manual entry. HealthKit `unspecified` flow maps to `LIGHT` (a
+logged-but-unspecified bleeding day is at least light flow).
+
+## Symptom category types → seeded symptom keys
+
+Symptom category samples link to the seeded `CycleSymptom` catalogue by key. A
+sample whose severity is *not present* (codepoint 1) does NOT create a link.
+
+| HealthKit category type | CycleSymptom key |
+|---|---|
+| `AbdominalCramps` | `cramps` |
+| `Headache` | `headache` |
+| `Bloating` | `bloating` |
+| `Acne` | `acne` |
+| `BreastPain` | `breast_tenderness` |
+| `Fatigue` | `fatigue` |
+| `LowerBackPain` | `back_pain` |
+| `SleepChanges` | `insomnia` |
+| `MoodChanges` | `mood_swings` |
+| `AppetiteChanges` | `food_cravings` |
+| `Nausea` | `nausea` |
+
+## Profile-level signals
+
+A `Contraceptive` sample asserting an active method also nudges the
+`CycleProfile.goal` to `AVOID_PREGNANCY` — but only when the goal is still on
+its `GENERAL_HEALTH` default, so an explicit user choice is never overwritten.
+
+## Basal body temperature
+
+`basalBodyTemperature` is **not** routed here. It stays a
+`Measurement(BODY_TEMPERATURE)` (the system of record for the rollup tier and
+the cross-source source-priority ladder) and is mirrored onto
+`CycleDayLog.basalBodyTempC` for the cycle chart. Apple Watch wrist/skin
+temperature already flows to `WRIST_TEMPERATURE` / `SKIN_TEMPERATURE` and feeds
+the temperature-trend ovulation method directly from `Measurement`.
+
+## Deferred
+
+| HealthKit category type | Status |
+|---|---|
+| `Pregnancy`, `Lactation` | Deferred — no `CycleProfile` column yet (pregnancy-mode is a later release). |
+| `BleedingDuringPregnancy`, `BleedingAfterPregnancy` | Deferred — pregnancy-mode. |
+| `IrregularMenstrualCycles`, `InfrequentMenstrualCycles`, `ProlongedMenstrualPeriods`, `PersistentIntermenstrualBleeding` | Server-derived from the cycle engine, never ingested. |

docs/apple-store-connect-checklist.md

@@ -0,0 +1,160 @@
+---
+file: docs/apple-store-connect-checklist.md
+purpose: Step-by-step ASC submission checklist for HealthLog iOS — covering medical-device declaration, privacy nutrition labels, and ASC metadata
+audience: Marc (the maintainer) before submitting to App Store
+estimated_read_time: 15 min
+last_updated: 2026-05-15
+---
+
+# App Store Connect Submission Checklist — HealthLog iOS
+
+## TL;DR
+
+Three submission gates that need Marc's hand at ASC:
+1. Regulated-Medical-Device declaration (Guideline 1.4 + 5.1.1(ix))
+2. Privacy Nutrition Labels matching the iOS Privacy Manifest (Guideline 5.1.2)
+3. Standard metadata (name, description, screenshots, categories, age rating)
+
+Plus pre-submit final checks.
+
+## Section 1 — Regulated-Medical-Device declaration
+
+**Where**: App Store Connect → App Information → "Health & Fitness" → "Medical device" toggle
+
+**Decision**: HealthLog is **NOT a medical device** under EU MDR 2017/745 / FDA 21 CFR 880 / Apple's interpretation.
+
+**Recommended wording in the declaration form**:
+> HealthLog is a personal health-data logging and visualization app. It displays user-entered observations + integrates with Apple HealthKit, Withings, and manual entry. It does not diagnose, treat, prescribe, or recommend dosing. The AI Coach surfaces are explicit-refusal-gated (GROUND RULES 9 + 15) against any medical-device-class output. The drug-level estimation chart is display-only behind a versioned MDR-acknowledgment dialog citing EU 2017/745 + MDCG 2021-24. For medical advice, users must consult licensed clinicians.
+
+**What to check**:
+- [ ] Check "No" on the medical-device toggle
+- [ ] Add the description above to the medical-device-justification field if Apple shows one
+- [ ] Cross-reference the in-app `/privacy` page (https://healthlog.bombeck.io/privacy) §7 MDR-boundary
+
+**Why this matters**: Apple's first-submission rejection rate for health apps is ~40%. The most common reason is unclear medical-device classification. The above wording mirrors the in-app disclaimer + the per-feature gating; consistency between the form and the app is what Apple looks for.
+
+## Section 2 — Privacy Nutrition Labels
+
+**Where**: App Store Connect → App Privacy → "Edit" the privacy choices.
+
+**Cross-reference**: every data category here MUST match what the iOS Privacy Manifest (in the iOS repo) declares. iOS-Claude's v0.3.0 release extended the manifest to: Email + OtherUserContent + SensitiveInfo + DeviceID + UserID + AccountManagement-purpose.
+
+### Data categories to declare
+
+For each category below: **Linked to user, used for App Functionality + Account Management**. Optional purposes: never enable Analytics, Tracking, Advertising, or Third-Party Tracking.
+
+**Health & Fitness**
+- Health: yes (all HKQuantityType + HKCategoryType the iOS app reads — see `/privacy` page §2)
+- Fitness: yes (steps, distance, active energy, workouts)
+- Purpose: App Functionality
+- Linked to user: yes
+
+**Contact Info**
+- Email Address: yes (for account login + GDPR data-subject correspondence)
+- Purpose: App Functionality + Account Management
+- Linked to user: yes
+
+**Sensitive Info**
+- Blood pressure, glucose, medications, drug-related observations: yes
+- Purpose: App Functionality
+- Linked to user: yes
+
+**User Content**
+- Emails or Text Messages: NO (the AI Coach is in-app conversation, but iOS does not send emails)
+- Photos or Videos: NO
+- Audio Data: NO (HealthKit audio-exposure is environmental dB; not the user's voice)
+- Customer Support: yes (open-source GitHub Issues; mention in policy)
+- Other User Content: yes (Coach conversation context + medication notes + side-effect free-text)
+- Purpose: App Functionality
+- Linked to user: yes
+
+**Identifiers**
+- User ID: yes (server-side user UUID)
+- Device ID: yes (X-Device-Id Keychain-stored UUID, APNs push token)
+- Purpose: App Functionality + Account Management
+- Linked to user: yes
+
+**Other Data Types**
+- Other Data Types: yes (general medical observations not fitting above)
+- Purpose: App Functionality
+- Linked to user: yes
+
+### Data types to NOT declare (because not collected)
+
+- Browsing History
+- Search History
+- Location (Precise or Coarse) — workout GPS routes are opt-in per-workout; if the iOS app implements them, declare; otherwise omit
+- Purchases
+- Financial Info
+- Diagnostics, Crash Data, Performance Data, Other Diagnostic Data — if iOS uses any analytics SDK, declare; otherwise omit. Verify with iOS-Claude.
+- Advertising Data
+- Other Usage Data
+
+### Tracking declaration
+
+**Tracking**: NO. HealthLog does not link user data with data from other companies' apps and websites for advertising or share data with data brokers. The Privacy Manifest must not declare any tracking-related purposes.
+
+## Section 3 — Standard Metadata Checklist
+
+### App Information
+- [ ] Name: "HealthLog"
+- [ ] Subtitle: 30-char tagline (suggestion: "Personal health-data log + Coach")
+- [ ] Primary category: Health & Fitness
+- [ ] Secondary category: Medical (if Apple accepts non-medical-device classification for it)
+- [ ] Content rights: confirm Marc owns the app rights
+- [ ] Age rating: 17+ (because Sensitive Health Info content)
+
+### Description
+- [ ] Long-form description (4000 char max): cover Insights + Coach + GLP-1 + Withings + Apple HealthKit + open-source nature + EU GDPR compliance
+- [ ] What's New (version-by-version notes): v0.3.0 = "Server-sync, comprehensive Apple HealthKit support across 19 sample types, smart Insights, AI Coach, Health Score, GLP-1 tracking with Research-Mode-gated drug-level chart, interactive charts with drill-down, push notifications, deep links, and account deletion."
+
+### Screenshots
+- [ ] 6.5" iPhone screenshots: cover Onboarding (welcome carousel + permissions), Dashboard (Health Score tile + tile-strip), Insights (sub-page with severity sort), Coach (refusal example to show MDR boundary), Medications (GLP-1 detail stack), Settings (Research Mode toggle + account deletion).
+- [ ] 5.5" iPhone screenshots: same set (Apple's legacy size).
+- [ ] iPad screenshots if supporting iPad.
+
+### URLs
+- [ ] Marketing URL: https://healthlog.bombeck.io (or marketing site once landing repo's v1.4.25 deployed)
+- [ ] Privacy Policy URL: **https://healthlog.bombeck.io/privacy** (ships with v1.4.25.1 hotfix)
+- [ ] Support URL: https://github.com/MBombeck/HealthLog/issues
+
+### App Review Information
+- [ ] Demo account credentials: Marc creates a read-only demo account on `demo.healthlog.dev` and provides credentials in the demo account fields
+- [ ] Review notes: explain MDR boundary + AI Coach safety contract + Research Mode gating; reference `/privacy` §7 MDR-boundary. Apple reviewers DO read this and DO check the in-app behavior matches the claim.
+- [ ] Sign-in required: yes (provide demo credentials)
+
+### Pricing + Availability
+- [ ] Free
+- [ ] Availability: select countries (Marc-decision — recommend EU + US + Canada + Australia + Japan for first launch)
+
+## Section 4 — Pre-Submit Final Check
+
+Run through this list:
+
+- [ ] Privacy Policy URL responds 200 (curl https://healthlog.bombeck.io/privacy)
+- [ ] iOS Privacy Manifest categories match the App Privacy declarations in §2
+- [ ] Demo account works on the demo server
+- [ ] iOS app's TestFlight build is on the latest commit
+- [ ] Marc has the APNs .p8 backed up to 1Password or similar (see `.planning/v15-apns-key-handling.md`)
+- [ ] Marc's Apple Developer Program subscription is active
+
+## Section 5 — Common First-Submission Rejection Reasons (Apple Health-App-Specific)
+
+- Guideline 1.4.1: "Medical claims" — wording in app or screenshots implies diagnosis/treatment → fix: tone down wording, lean on the MDR-boundary disclaimer
+- Guideline 5.1.1(v): "Account Deletion missing" — iOS-Claude added this in v0.3.0
+- Guideline 5.1.2(i): "Third-Party AI consent" — DEFERRED to v0.3.1 per iOS-Claude release notes; resubmission may flag
+- Guideline 5.1.2: "Privacy Manifest mismatch" — see §2; iOS-Claude needs to ensure the manifest matches
+
+## Section 6 — Post-Submit / If Rejected
+
+- Apple's most common rejection language for health apps: "Your app's marketing language and/or in-app content implies the diagnosis or treatment of conditions..."
+- Response template: cite GROUND RULES 9 + 15 + /privacy §7 + the screenshot of the in-app MDR-boundary disclaimer. Apple usually accepts a clear, written delineation.
+- If rejected, do NOT escalate to App Review Board immediately — first iterate on the in-app wording (move "GLP-1" / "drug-level" to back of UI, add more explicit "This is not medical advice" copy at every Coach surface). Most rejections resolve within 1-2 iterations.
+
+---
+
+**Source links**:
+- Apple Health App Guidelines: https://developer.apple.com/app-store/review/guidelines/#health-and-health-research
+- Apple App Privacy Details: https://developer.apple.com/app-store/app-privacy-details/
+- EU MDR 2017/745: https://eur-lex.europa.eu/eli/reg/2017/745/oj
+- MDCG 2021-24 (Software as a Medical Device): https://health.ec.europa.eu/system/files/2021-10/mdcg_2021-24_en_0.pdf

docs/audit/2026-04-26-PLAN.md

@@ -1,235 +0,0 @@
-# HealthLog Audit-Plan — Phasen-Übersicht
-**Datum:** 2026-04-26
-**Audit-Bericht:** `~/infra/reports/healthlog-audit-2026-04-26.md`
-**Status:** Geplant, noch nicht in Execution
-
-## Strategische Decisions
-
-1. **Onboarding-Redesign:** 4-Step-Wizard → 2-Step + Empty-State-Dashboard + Getting-Started-Card.
-2. **Custom-Measurement-Types:** Pragmatic Hardcoding (jetzt #89), Cronometer-Pattern als v1.5+-Roadmap.
-3. **`apiClient`-Refactor vor Onboarding-Redesign**, damit neues Onboarding nicht denselben Silent-Failure-Bug reproduziert.
-
----
-
-## Phasen-Sequenz (10 Phasen)
-
-| # | Phase | Skill | Effort | Issue-Bezug |
-|---|---|---|---|---|
-| **1** | Setup-Notfall + Versions-Sync | `gsd:quick` | ≤4 h | #87 (Pflaster), #88 |
-| **2** | Docker-Image-Pipeline (GHCR-Push + Doc-Konsolidierung) | `gsd:plan-phase` | ~1 d | #88 |
-| **3** | Issue #89 — TBW + Bone Mass hardcoded | `gsd:plan-phase` | ~1 d | #89 |
-| **4** | `apiClient`-Wrapper + geteilte Zod-Schemas | `gsd:research-phase` → `gsd:plan-phase` | 2-3 d | #87 (strukturell) |
-| **3.5** | **Onboarding-Redesign** (2 Steps, TTFV <60s) | `gsd:research-phase` → `gsd:plan-phase` | ~2 d | #87 (strukturell) |
-| **4.5** | Empty-State-Dashboard-Tiles (eine pro Type) | `gsd:plan-phase` | ~1 d | #87, #89 |
-| **4.6** | „Getting Started"-Checklist auf Dashboard | `gsd:plan-phase` | ~4 h | #87 |
-| **5** | Security + Reliability Hardening | `gsd:plan-phase` | 1-2 d | — |
-| **6** | Test-Coverage-Boost (Auth/Passkey/Withings/pg-boss) | `gsd:plan-phase` | 1-2 d | — |
-| **7** | UX/i18n/a11y Polish (Residuals aus #73) | `gsd:quick` | ≤4 h | #73 (Residuals) |
-| **8** | Settings-Page-Splitting (3143 → Sub-Components) | `gsd:research-phase` → `gsd:plan-phase` | 2-3 d | — |
-
-**Reihenfolge:** 1 → 2 → 3 → **4 (apiClient)** → **3.5 (Onboarding nutzt apiClient)** → 4.5 → 4.6 → 5 → 6 → 7 → 8.
-
----
-
-## Phase 1 — Setup-Notfall (≤4 h)
-
-**Goal:** Self-Hoster kann mit `git clone && docker compose up -d` tatsächlich starten + Issue #87 stoppt zu blocken.
-
-- `docker-compose.yml`: `expose:3000` → `ports: "3000:3000"` (DX-002)
-- `docker-compose.yml`: `POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?required}"` (SEC-003)
-- `.env.example`: `localhost:5432` → `db:5432` (DX-003)
-- `package.json`: `"version": "1.2.0"` (DOC-007)
-- `CLAUDE.md` + `AGENTS.md`: 23 Models statt 21/22 (DOC-001)
-- `src/app/onboarding/page.tsx`: `await fetch(...)` mit `.ok`-Check + `toast.error()` (DX-005 Pflaster)
-- README „minutes"-Claim entschärfen (DX-006)
-
-**Verification:** Frischer Clone + neue VM → `cp .env.example .env && set secrets && docker compose up -d` → App auf `http://localhost:3000` erreichbar in <5 min.
-
----
-
-## Phase 2 — Docker-Image-Pipeline (~1 d)
-
-**Goal:** Issue #88 vollständig schließen. Pre-built Image auf GHCR. Docs konsolidiert.
-
-- `.github/workflows/docker-publish.yml`: Multi-Arch (amd64+arm64), Trigger auf Tag-Push + main, GHCR-Push mit GITHUB_TOKEN
-- `healthlog-docs/getting-started/installation.mdx` → Verweis auf `self-hosting/docker.mdx` statt Duplikat (DX-004)
-- Repo-`docker-compose.yml` vs Docs-`docker-compose.yml`: eine Variante als Single-Source-of-Truth (Compose verwendet `image:` aus GHCR; Doc-Snippet wird daraus generiert)
-- `SECURITY.md` + Image-Pull-Instructions
-- `healthlog-landing` prüfen ob „Quick Start" aktualisiert werden muss
-
----
-
-## Phase 3 — Issue #89: TBW + Bone Mass (~1 d)
-
-**Goal:** User-Anfrage von Manschk3rl beantworten. Blueprint = v1.2-Glucose-Migration.
-
-**Touchpoints:**
-1. `prisma/schema.prisma`: `MeasurementType` Enum + 2 neue Werte
-2. `prisma/migrations/0019_*` (additive `ALTER TYPE ... ADD VALUE`)
-3. `src/lib/validations/measurement.ts`: `unitMap`, `VALUE_RANGES`
-4. `src/lib/format.ts` + i18n-Keys (4-6 neue Keys)
-5. `src/lib/doctor-report-pdf.ts`: `TYPE_LABEL_KEYS`, `TYPE_UNIT_KEYS`, `vitalTypes`
-6. `src/components/measurements/measurement-form.tsx`: `MEASUREMENT_TYPES` Array
-7. `src/lib/withings/client.ts` + `sync.ts`: Mapping aus Withings `body_composition`
-8. `src/app/api/dashboard/widgets/route.ts` + `DEFAULT_DASHBOARD_LAYOUT`: 2 neue Widget-IDs
-9. healthlog-docs `health-metrics.mdx` aktualisieren
-10. Optional: `/api/ingest/measurements` Bearer-Endpoint für n8n (analog `/api/ingest/medication`)
-
----
-
-## Phase 4 — `apiClient`-Wrapper (2-3 d)
-
-**Goal:** Silent-Failure-Pattern strukturell eliminieren. Voraussetzung für 3.5.
-
-- `src/lib/api-client.ts`: `apiClient.{get,post,put,delete}<T>(path, body?, schema?) → Result<T, ApiError>`
-- Auto-`.ok`-Check + Toast bei Fehler (mit i18n-Mapping)
-- Geteilte Zod-Schemas: Validations-Module in `src/lib/validations/` werden client-importable
-- Migration: alle ~50 `fetch(...)`-Aufrufe in `src/app/` und `src/components/` → `apiClient.*`
-- Tests für `apiClient` (Mock-Fetch, Error-Mapping, Schema-Validation)
-
----
-
-## Phase 3.5 — Onboarding-Redesign (~2 d)
-
-**Goal:** TTFV <60s, 90% Completion (statt aktuell ~8% global).
-
-**Neuer Flow:**
-- Step 1: Welcome + Anzeigename (optional) + Einheiten + Größe (optional). Sekundärlink „Skip everything → Dashboard".
-- Step 2: Multi-Select-Chips „Was willst du tracken?" (Weight/BP/Pulse/Mood/Glucose/Sleep/Steps/BodyFat/TBW/BoneMass/Medications). Pre-checked Defaults. Speichert in `User.dashboardWidgetsJson`.
-- Routing nach Onboarding: direkt zum Dashboard mit „Getting Started"-Card (s. Phase 4.6).
-
-**Entfällt ersatzlos:** Targets-Step, Notifications-Teaser-Step, Front-loaded-Med-Wizard.
-
-**Permissions deferred:** Notifications nur bei „Add medication → Reminder ein", PWA-Install nur bei Day-2-Return-Visit oder nach 3. Eintrag.
-
----
-
-## Phase 4.5 — Empty-State-Dashboard-Tiles (~1 d)
-
-**Goal:** Mealie/Tandoor/Linear-Pattern. Jede Metric-Tile hat Empty-State mit „Add your first X"-CTA.
-
-- `src/components/dashboard/EmptyStateTile.tsx` als wiederverwendbare Komponente
-- Pro `MeasurementType`: eigene Empty-State-Card (Icon + Headline + CTA-Button → opens MeasurementForm prefilled)
-- `Medications` analog: Empty-State „Add your first medication" → opens MedicationForm mit Default-Schedule (08:00–09:00 daily)
-- Dashboard-Routing: User mit `dashboardWidgetsJson` ohne Daten sieht Empty-States, nicht leeres Grid
-
----
-
-## Phase 4.6 — „Getting Started"-Checklist (~4 h)
-
-**Goal:** Linear-Pattern. Persistent dismissible Card auf Dashboard.
-
-- `User.gettingStartedDismissedAt: DateTime?` (nullable, NULL = noch sichtbar)
-- 4 Items mit Live-Status:
-  - ☐ Log your first measurement (✓ wenn ≥1 Measurement existiert)
-  - ☐ Add a medication (✓ wenn ≥1 Medication existiert)
-  - ☐ Set a target value (✓ wenn `thresholdsJson` non-empty)
-  - ☐ Install HealthLog as App (✓ wenn `beforeinstallprompt` accepted, sonst nur sichtbar bei PWA-fähigen Browsern)
-- „Dismiss"-Button → setzt Timestamp, Card verschwindet
-- Vollständig durchgeklickt → Card verschwindet automatisch
-
----
-
-## Phase 5 — Security + Reliability Hardening (1-2 d)
-
-- SEC-002: SSRF-IPv4-Parser-Härtung (führende Nullen)
-- SEC-004: GitHub-PAT-Logging-Sanitization (Sensitive-Field-Filter)
-- SEC-005: AES-256-GCM Key-Rotation-Doc + optional `keyVersion`
-- SEC-006: Custom-Thresholds-Rate-Limit
-- PERF-001: N+1 in `insights/comprehensive/route.ts:219` per `groupBy` auflösen
-- REL-002: Onboarding-Error-Handling über Pflaster hinaus (via apiClient aus Phase 4)
-- REL-003: pg-boss `process.on('SIGTERM', ...)` für graceful shutdown
-- LOG-001: 6× `console.log()` in `src/lib/jobs/reminder-worker.ts` → Wide-Event-Annotations
-- CI: ESLint+Typecheck `continue-on-error: true` → blocking
-
----
-
-## Phase 6 — Test-Coverage-Boost (1-2 d)
-
-Coverage 35% → 60% auf kritischen Pfaden.
-
-**Top-5-Test-Suites:**
-1. Session-Validation Roundtrip (`src/lib/auth/session.ts`)
-2. Passkey-Register/Verify-Integration (Attestation-Flow)
-3. Notification-Dispatcher Multi-Channel (TELEGRAM/NTFY/WEB_PUSH)
-4. pg-boss Reminder-Worker (Queue-Init, Job-Execution, Cron, Retry)
-5. Withings-OAuth + Sync (`exchangeCode` → `refresh` → `fetchMeasurements`)
-
-**Plus:** TEST-006 Custom-Thresholds-Resolution, TEST-007 AI-Provider-SSRF.
-
----
-
-## Phase 7 — UX/i18n/a11y Polish (≤4 h)
-
-**Residuals aus Issue #73 + neue Findings:**
-- I18N-002: Admin-Page Hardcoded „Web Push" / „Bug Report" → `t(...)`
-- I18N-003: `medication-card.tsx` `Intl.DateTimeFormat("en-CA")` und `toLocaleString("en-US")` → `useFormatters()`
-- A11Y-001: `phase-config-dialog.tsx` Text-Indicator neben Farb-Punkt (WCAG 1.4.1)
-- A11Y-002: Admin StatusItem `aria-label` verifizieren
-- UX-002: Admin-Save-Error-UX (Field-Highlight bei Fehler)
-- UX-003: Bottom-Nav-Touch-Targets `p-2.5` → `p-3` (≥44×44 px)
-
----
-
-## Phase 8 — Settings-Page-Splitting (2-3 d)
-
-**Goal:** 3143 Zeilen → Sub-Components mit klarer Boundary.
-
-- Research-Phase: Sub-Routes (`/settings/profile`, `/settings/notifications`, …) vs Sub-Components in einer Page?
-- Plan-Phase: Migrationsstrategie ohne URL-Bruch
-- Insights-Page (1750 Zeilen) folgt analogem Pattern
-
----
-
-## Issue-Vorschlags-Abdeckung
-
-### Issue #87 (Onboarding-Meds verschwinden)
-- **Pflaster:** Phase 1 (`.ok`-Check + Toast)
-- **Strukturelle Lösung:** Phase 4 (`apiClient`) + Phase 3.5 (neuer Flow ohne Med-Wizard) + Phase 4.5 (Empty-State-Tiles, Meds direkt sichtbar) + Phase 4.6 (Checklist)
-
-### Issue #88 (Setup holprig — 4 Hauptpunkte + 3 Verbesserungsvorschläge)
-| #88 Punkt | Phase | Status |
-|---|---|---|
-| (a) Bundled compose ≠ docs version | Phase 2 (DOC-005) | abgedeckt |
-| (b) ghcr.io 404 (kein Image gepusht) | Phase 2 (DX-001 GHA-Workflow) | abgedeckt |
-| (c) `.env.example` `localhost:5432` vs Compose `db:5432` | Phase 1 (DX-003) | abgedeckt |
-| (d) `expose:3000` statt `ports:3000:3000` | Phase 1 (DX-002) | abgedeckt |
-| Vorschlag: GHA für Image-Push (GHCR/Docker Hub) | Phase 2 | abgedeckt |
-| Vorschlag: Merge „Getting started > Installation" + „Self-Hosting > Docker" | Phase 2 (DX-004) | abgedeckt |
-| Vorschlag: Same presets across compose+docs+.env.example | Phase 1 + Phase 2 | abgedeckt |
-
-### Issue #89 (TBW + Bone Mass)
-- Phase 3 hardcoded mit Withings-Mapping. Optional `/api/ingest/measurements` für n8n in Phase 3.
-
-### Issue #73 (UX-Liste mit 8 Punkten — CLOSED in v1.2)
-| #73 Punkt | v1.2-Status | Residual? |
-|---|---|---|
-| 1. Passkey-Errors unklar | Resolved (Package C, typed errors) | TEST-002 (keine Tests) → Phase 6 |
-| 2. Number-Formatting (DE 70,5 vs US 70.5) | Resolved (Package B, locale-aware formatters) | I18N-003 in `medication-card.tsx` → Phase 7 |
-| 3. Chart-Labels „7P/30P/90P/All" | Resolved (Package A, „7 Pkt"/„7 pts") | — |
-| 4. Dashboard nicht real-time | Resolved (`invalidateKeys` durchgängig) | — |
-| 5. GitHub-Setup-Confusion | Resolved (Built-in Feedback in v1.2) | — |
-| 6. Built-in Feedback | Done in v1.2 | — |
-| 7. Admin-Save ohne Error-UX | Partial (Success-Msg ja, Error-Highlight schwach) | UX-002 → Phase 7 |
-| 8. Blood-Sugar | Done in v1.2 | — |
-
-### Issue #74 (raw locale keys in UI)
-Resolved in v1.2.
-
----
-
-## Time-to-First-Value (TTFV) Ziel
-
-Nach Onboarding-Redesign + Empty-State-Pattern:
-- Login → Dashboard mit Empty-States: 2 Klicks
-- Klick auf „Add your first weight" → Form prefilled „now" → Submit: 30 Sek
-- **TTFV-Ziel: <60 Sekunden** (Branchenvergleich: führende Health-Apps 30-90s)
-
-## Anti-Patterns explizit vermieden
-
-- Permissions-Cold-Prompt (Notifications/PWA) auf Day 1
-- Front-loaded Targets vor erster Messung
-- Multi-Step-Wizard mit identischem Skip-Button
-- `fetch()` ohne `.ok`-Check (apiClient löst strukturell)
-- Mega-Page-Pattern (Phase 8 löst Settings 3143 Z.)
-- Custom-Measurement-Types vorzeitig (40-60h Wartung/Jahr für 50% Feature-Loss)

docs/codex-protocol-spec.md

@@ -0,0 +1,782 @@
+# Codex Backend Protocol Spec — `chatgpt.com/backend-api/codex/responses`
+
+This is a TypeScript-implementer's reference for the Codex CLI's "Responses-over-HTTP" call to the ChatGPT-backed Codex endpoint. Every claim cites a specific Rust source file in `openai/codex` (path is relative to the repo root).
+
+The endpoint is reverse-engineered from the official client, so this document is the authoritative shape — there is no public OpenAPI for this URL.
+
+---
+
+## 0. Endpoint
+
+- **Method**: `POST`
+- **URL**: `https://chatgpt.com/backend-api/codex/responses`
+- **Content-Type**: `application/json`
+- **Accept**: `text/event-stream` (the client always sets this)
+- **Stream**: SSE; non-streaming is not supported on this URL (server returns 400 `"Stream must be set to true"`).
+
+The base URL `https://chatgpt.com/backend-api/codex` is the constant `CHATGPT_CODEX_BASE_URL` in `codex-rs/model-provider-info/src/lib.rs:37`. The path `/responses` is joined onto it by `ResponsesClient::path()` in `codex-rs/codex-api/src/endpoint/responses.rs:102-104` (returns `"responses"`) and the provider's `url_for_path` joins them with a `/`.
+
+The ACCEPT header is forced to `text/event-stream` in `codex-rs/codex-api/src/endpoint/responses.rs:137-140`.
+
+---
+
+## 1. Request body — `ResponsesApiRequest`
+
+Source: `codex-rs/codex-api/src/common.rs:169-190`.
+
+```ts
+interface ResponsesApiRequest {
+  // Required
+  model: string; // e.g. "gpt-5-codex"
+  input: ResponseItem[]; // MUST be a list, not a string
+  tools: unknown[]; // [] is valid
+  tool_choice: string; // "auto" is what core uses
+  parallel_tool_calls: boolean; // bool, no default — must serialize
+  reasoning: Reasoning | null; // null is allowed; field is required
+  store: boolean; // false on chatgpt backend (only true on Azure)
+  stream: true; // MUST be true on this URL
+  include: string[]; // ["reasoning.encrypted_content"] when reasoning is on, else []
+
+  // Optional (skipped when empty/None)
+  instructions?: string; // skipped if "" (serde "skip_serializing_if = String::is_empty")
+  service_tier?: string; // omit unless model supports it
+  prompt_cache_key?: string; // core sets this to thread_id
+  text?: TextControls; // verbosity + JSON-schema output
+  client_metadata?: Record<string, string>; // free-form, see below
+}
+```
+
+Serde rules from `codex-rs/codex-api/src/common.rs:169-190`:
+
+| Field              | Skip-rule                                                         |
+| ------------------ | ----------------------------------------------------------------- |
+| `instructions`     | skipped when empty string                                         |
+| `reasoning`        | always emitted (Option, but no skip attribute → `null` when None) |
+| `service_tier`     | skipped when `None`                                               |
+| `prompt_cache_key` | skipped when `None`                                               |
+| `text`             | skipped when `None`                                               |
+| `client_metadata`  | skipped when `None`                                               |
+
+All other fields are always emitted.
+
+There are NO serde renames — wire keys equal Rust field names verbatim.
+
+### 1a. The `Reasoning` block
+
+Source: `codex-rs/codex-api/src/common.rs:113-119`.
+
+```ts
+interface Reasoning {
+  effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  summary?: "auto" | "concise" | "detailed" | "none";
+}
+```
+
+- `effort` enum: `codex-rs/protocol/src/openai_models.rs:42-52` (lowercase serde). `Medium` is the default if you ask for one.
+- `summary` enum: `codex-rs/protocol/src/config_types.rs:24-36` (lowercase serde). The Codex CLI sets `summary` to `Some(...)` only when the user asked for summaries; `ReasoningSummary::None` is mapped to `None` (omitted) in `codex-rs/core/src/client.rs:697-701`.
+- When the model does not support reasoning summaries, the entire `reasoning` field is set to `None` (i.e. emitted as `null`): `codex-rs/core/src/client.rs:689-705`.
+- When `reasoning` is non-null, the client also sets `include: ["reasoning.encrypted_content"]`. When null, `include: []`. See `codex-rs/core/src/client.rs:721-725`.
+
+### 1b. `TextControls`
+
+Source: `codex-rs/codex-api/src/common.rs:142-148`.
+
+```ts
+interface TextControls {
+  verbosity?: "low" | "medium" | "high"; // codex-rs/codex-api/src/common.rs:150-157
+  format?: TextFormat;
+}
+
+interface TextFormat {
+  type: "json_schema"; // only variant; codex-rs/codex-api/src/common.rs:121-126
+  strict: boolean;
+  schema: unknown; // raw JSON-Schema
+  name: string; // "codex_output_schema" in CLI; arbitrary
+}
+```
+
+`text` is omitted entirely when no verbosity AND no output schema is requested (`codex-rs/codex-api/src/common.rs:279-297`).
+
+### 1c. Minimal valid body
+
+For a plain text turn with no tools and no reasoning, the smallest body the Codex client itself ever sends is:
+
+```json
+{
+  "model": "gpt-5-codex",
+  "instructions": "You are a helpful coding agent.",
+  "input": [
+    {
+      "type": "message",
+      "role": "user",
+      "content": [{ "type": "input_text", "text": "Hello" }]
+    }
+  ],
+  "tools": [],
+  "tool_choice": "auto",
+  "parallel_tool_calls": false,
+  "reasoning": null,
+  "store": false,
+  "stream": true,
+  "include": []
+}
+```
+
+`tools: []` is acceptable — the field is required but may be the empty array. `tool_choice: "auto"` is the literal string the CLI always sends (`codex-rs/core/src/client.rs:750`).
+
+### 1d. `client_metadata`
+
+Free-form `Record<string,string>`. The CLI uses it to forward an installation id and (over WebSocket) trace-context headers — none of these are mandatory for the HTTP path. Safe to omit (`None` → field skipped).
+
+---
+
+## 2. `ResponseItem` (the `input` array)
+
+Source: `codex-rs/protocol/src/models.rs:741-891`.
+
+```rust
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ResponseItem { Message {...}, Reasoning {...}, ... }
+```
+
+So every entry in `input` is an object with a `type` discriminator (snake_case) plus variant-specific fields.
+
+The variants you'll need for outbound traffic are `Message`, `Reasoning`, `FunctionCall`, `FunctionCallOutput`. The server-only variants (`LocalShellCall`, `WebSearchCall`, `ImageGenerationCall`, `ToolSearchCall`, `ToolSearchOutput`, `CustomToolCall*`, `Compaction`, `ContextCompaction`) appear in stream output and only need to round-trip for multi-turn continuations.
+
+### 2a. `Message`
+
+`codex-rs/protocol/src/models.rs:744-756`.
+
+```ts
+interface MessageItem {
+  type: "message";
+  role: "user" | "assistant" | "system" | "developer"; // free string
+  content: ContentItem[];
+  // The `id` field exists in Rust but is `skip_serializing` — never emit it for inbound input
+  // The `phase` field is for SERVER output; do not send it.
+}
+```
+
+Note: `id` has `#[serde(skip_serializing)]` (line 745-747) — set client-side but never put into the request.
+
+### 2b. `ContentItem`
+
+`codex-rs/protocol/src/models.rs:697-712`.
+
+```ts
+type ContentItem =
+  | { type: "input_text"; text: string }
+  | {
+      type: "input_image";
+      image_url: string;
+      detail?: "auto" | "low" | "high" | "original";
+    }
+  | { type: "output_text"; text: string };
+```
+
+- Use `input_text` and `input_image` for user turns.
+- Use `output_text` for assistant-message replays in multi-turn continuations.
+- `image_url` accepts `data:image/png;base64,...` (see `codex-rs/protocol/src/models.rs:2369`) or an HTTPS URL.
+- `detail` enum: `codex-rs/protocol/src/models.rs:715-723` (default `High` when serializing for the CLI).
+
+### 2c. `Reasoning`
+
+`codex-rs/protocol/src/models.rs:757-767`.
+
+```ts
+interface ReasoningItem {
+  type: "reasoning";
+  // `id` is skip_serializing — do not send
+  summary: ReasoningSummary[]; // Vec<ReasoningItemReasoningSummary>
+  content?: ReasoningContent[]; // omitted unless server gave you one
+  encrypted_content: string | null;
+}
+
+type ReasoningSummary = { type: "summary_text"; text: string };
+type ReasoningContent = { type: "reasoning_text" | "text"; text: string };
+```
+
+Sources: `codex-rs/protocol/src/models.rs:1192-1203`.
+
+For the simplest "fresh chat" use, you don't construct `Reasoning` items yourself — they only re-appear in `input` when continuing a turn that the server previously emitted them on. When you do replay them, keep `encrypted_content` verbatim.
+
+### 2d. `FunctionCall` (outbound continuation)
+
+`codex-rs/protocol/src/models.rs:778-791`.
+
+```ts
+interface FunctionCallItem {
+  type: "function_call";
+  // `id` skip_serializing
+  name: string;
+  namespace?: string | null; // omitted when None
+  arguments: string; // JSON-as-string, NOT a parsed object
+  call_id: string; // required
+}
+```
+
+Important: `arguments` is a string containing JSON, not an object — the Responses API mandates this on the wire. See the comment at lines 786-789.
+
+### 2e. `FunctionCallOutput`
+
+`codex-rs/protocol/src/models.rs:809-814`.
+
+```ts
+interface FunctionCallOutputItem {
+  type: "function_call_output";
+  call_id: string;
+  output: string | { content?: string; content_items?: ContentItem[] };
+}
+```
+
+The output payload uses `FunctionCallOutputPayload`, which is a string OR a structured `{ content | content_items }` object — see lines 804-808 for the wire-format note.
+
+### 2f. Other variants you might see in stream output
+
+| `type`                                                           | Notes                                  |
+| ---------------------------------------------------------------- | -------------------------------------- |
+| `local_shell_call`                                               | local-shell tool action (server emits) |
+| `web_search_call`                                                | server emits when web_search ran       |
+| `image_generation_call`                                          | server emits                           |
+| `tool_search_call` / `tool_search_output`                        | dynamic-tool registry                  |
+| `custom_tool_call` / `custom_tool_call_output`                   | user-defined tools                     |
+| `compaction` (alias `compaction_summary`) / `context_compaction` | turn compaction artifacts              |
+
+If you don't intend to round-trip these, keep them out of `input`. The unknown-variant catch-all (`Other`) is `#[serde(other)]` so unrecognized types are deserialized but lossy — don't echo them.
+
+---
+
+## 3. HTTP headers
+
+The Codex CLI sends these on every Responses POST. Required ones are starred.
+
+### 3a. From `BearerAuthProvider::add_auth_headers` — `codex-rs/model-provider/src/bearer_auth_provider.rs:31-46`
+
+| Header               | Required              | Value                                                                                                                                 |
+| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `Authorization`      | \*                    | `Bearer <access_token>` (the OAuth access token, see §6)                                                                              |
+| `ChatGPT-Account-ID` | \* (for ChatGPT auth) | the `chatgpt_account_id` claim from the id_token; obtained via `auth.get_account_id()` (`codex-rs/login/src/auth/manager.rs:339-344`) |
+| `X-OpenAI-Fedramp`   | optional              | `"true"` only for FedRAMP accounts                                                                                                    |
+
+Without `ChatGPT-Account-ID`, `chatgpt_get_request` errors out with "ChatGPT account ID not available, please re-run `codex login`" (`codex-rs/chatgpt/src/chatgpt_client.rs:33-36`).
+
+### 3b. From the default reqwest client — `codex-rs/login/src/auth/default_client.rs:232-248`
+
+| Header                              | Required | Value                                                                                                                                                                                                                         |
+| ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `originator`                        | \*       | default `"codex_cli_rs"` (constant `DEFAULT_ORIGINATOR` at line 36); identifies the client family                                                                                                                             |
+| `User-Agent`                        | \*       | format: `"<originator>/<version> (<os_type> <os_version>; <arch>) <terminal_user_agent>"` — see `get_codex_user_agent()` lines 133-157. Anything sane works (e.g. `"healthlog/1.0 (Node)"` is fine for a third-party client). |
+| `x-openai-internal-codex-residency` | optional | `"us"` only when residency requirement is set                                                                                                                                                                                 |
+
+### 3c. From `build_session_headers` — `codex-rs/codex-api/src/requests/headers.rs:5-16`
+
+Sent on every Responses request when the CLI has a session/thread:
+
+| Header                        | Value                                        |
+| ----------------------------- | -------------------------------------------- |
+| `session_id` and `session-id` | UUID-shaped session id (both spellings sent) |
+| `thread_id` and `thread-id`   | UUID-shaped thread id (both spellings sent)  |
+
+Optional but cheap; the server tolerates them as routing hints. Generate one UUID and use it for both names — duplicates are intentional, see lines 7-13.
+
+### 3d. From `endpoint/responses.rs:91-97`
+
+| Header                | Required | Value                                                                                                       |
+| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `x-client-request-id` | optional | mirror the `thread_id` so it appears as the request-id in OpenAI logs                                       |
+| `x-openai-subagent`   | optional | only set for sub-agent flows (review/compact/memory_consolidation/collab_spawn). Omit for first-party chat. |
+
+### 3e. From `core/src/client.rs:135-148, 1648-1670`
+
+These are Codex-specific extras the CLI adds; the server tolerates them all.
+
+| Header                                           | Value                                                                                                                                                     |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OpenAI-Beta`                                    | only set on the **WebSocket** transport: `"responses_websockets=2026-02-06"` (line 145). NOT sent on HTTP — see line 911 (only the WS handshake adds it). |
+| `x-codex-beta-features`                          | optional, comma-separated feature flags                                                                                                                   |
+| `x-codex-installation-id`                        | UUID-ish, identifies the install — also embedded in `client_metadata` (line 759-762)                                                                      |
+| `x-codex-turn-state`                             | sticky-routing token captured from a prior response's `x-codex-turn-state` response header — replay it on subsequent requests in the same "turn"          |
+| `x-codex-turn-metadata`                          | optional, observability-only                                                                                                                              |
+| `x-codex-window-id` / `x-codex-parent-thread-id` | sub-agent only                                                                                                                                            |
+| `x-openai-memgen-request`                        | `"true"` for memory-consolidation sub-agent only                                                                                                          |
+| `x-responsesapi-include-timing-metrics`          | `"true"` if the client wants timing info in the response                                                                                                  |
+
+### 3f. Minimum third-party header set
+
+For HealthLog's purposes (no sub-agent, no session continuity, no Azure, no sticky routing):
+
+```
+POST /backend-api/codex/responses HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer <oauth_access_token>
+ChatGPT-Account-ID: <account_id>
+Content-Type: application/json
+Accept: text/event-stream
+originator: <something_distinctive>
+User-Agent: <descriptive_string>
+session_id: <uuid>
+thread_id: <uuid>
+```
+
+That's enough for the call to succeed.
+
+### 3g. What the CLI does NOT send on HTTP
+
+- `OpenAI-Beta` header on plain HTTP — only on WebSocket. Don't send it, it's not needed.
+- `OpenAI-Organization` / `OpenAI-Project` — those are for `api.openai.com` only (`codex-rs/model-provider-info/src/lib.rs:333-343`), NOT for the ChatGPT backend.
+
+---
+
+## 4. SSE response
+
+### 4a. Wire format
+
+Standard SSE: `eventsource_stream::Eventsource` is used (`codex-rs/codex-api/src/sse/responses.rs:439`), so the format is:
+
+```
+event: <type>\n
+data: <single-line JSON>\n
+\n
+```
+
+Each event is one frame, separated by a blank line. The implementation tolerates `event:`-only lines without `data:` (used for keep-alives in tests, `codex-rs/codex-api/src/sse/responses.rs:638-642`). There is **no** `data: [DONE]` terminator — the stream ends with a `response.completed` event (or `response.failed`/`response.incomplete`); after that the connection is closed.
+
+If the connection closes without a terminal event, the client surfaces `"stream closed before response.completed"` (line 458).
+
+The data payload is a JSON object with at minimum `{ "type": "<type>", ...}`. The Rust deserializer is forgiving — unknown event kinds are logged at trace level and ignored (`codex-rs/codex-api/src/sse/responses.rs:425-427`).
+
+### 4b. Event types — the complete list
+
+Source: `codex-rs/codex-api/src/sse/responses.rs:300-428`.
+
+The `data:` payload follows the `ResponsesStreamEvent` shape (lines 179-192):
+
+```ts
+interface ResponsesStreamEvent {
+  type: string;
+  headers?: unknown; // map; only present on metadata frames
+  metadata?: unknown; // present on response.metadata
+  response?: unknown; // present on created/completed/failed/incomplete
+  item?: unknown; // present on output_item.* — a ResponseItem
+  item_id?: string;
+  call_id?: string;
+  delta?: string; // text deltas
+  summary_index?: number;
+  content_index?: number;
+  // ... other fields are tolerated and ignored
+}
+```
+
+| Event `type`                            | Carries                                                            | Use it for                                                                                                                 |
+| --------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `response.created`                      | `response: {}` (server may add `id`, `headers.OpenAI-Model`, etc.) | Signals the turn started. The CLI emits `ResponseEvent::Created`.                                                          |
+| `response.metadata`                     | `metadata.openai_verification_recommendation: string[]`            | Optional; CLI uses to surface trust prompts. Ignore for chat.                                                              |
+| `response.output_item.added`            | `item: ResponseItem`                                               | A new top-level item is starting (e.g. assistant message stub, function call).                                             |
+| `response.output_item.done`             | `item: ResponseItem`                                               | The item is complete — this is where the **final** assistant `Message` arrives with its full `content[].text`.             |
+| `response.output_text.delta`            | `delta: string`                                                    | Token-by-token text streaming for the assistant message currently in flight. Concatenate to assemble live text.            |
+| `response.reasoning_summary_text.delta` | `delta: string`, `summary_index: number`                           | Reasoning summary stream (when `reasoning.summary` requested).                                                             |
+| `response.reasoning_summary_part.added` | `summary_index: number`                                            | Marker that a new summary section started.                                                                                 |
+| `response.reasoning_text.delta`         | `delta: string`, `content_index: number`                           | Reasoning text stream.                                                                                                     |
+| `response.custom_tool_call_input.delta` | `item_id: string`, `call_id?: string`, `delta: string`             | Custom tool input streaming (also used for `response.function_call_arguments.delta` per line 806-813 of the test fixture). |
+| `response.completed`                    | `response: { id, usage?, end_turn? }`                              | **Terminal event** — emit your final assembled text + usage.                                                               |
+| `response.failed`                       | `response: { error: { code, message, ... } }`                      | **Terminal event** — error path; see §4c.                                                                                  |
+| `response.incomplete`                   | `response: { incomplete_details: { reason: string } }`             | **Terminal event** — partial result, `reason` may be `max_output_tokens` etc.                                              |
+
+Anything else (`response.in_progress`, `response.content_part.added`, etc.) is currently ignored by the official client (line 425-427); a TS implementation should follow suit and silently drop unknown `type` values.
+
+### 4c. Error event — `response.failed`
+
+Schema of `response.error` (`codex-rs/codex-api/src/sse/responses.rs:122-130`):
+
+```ts
+interface FailedError {
+  type?: string;
+  code?: string; // primary discriminator
+  message?: string;
+  plan_type?: string;
+  resets_at?: number; // unix seconds
+}
+```
+
+Code-to-meaning mapping (`codex-rs/codex-api/src/sse/responses.rs:547-570`):
+
+| `error.code`                         | Meaning                          | Treat as                                                                                                      |
+| ------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `context_length_exceeded`            | input too big                    | fatal, surface to user                                                                                        |
+| `insufficient_quota`                 | account quota                    | fatal                                                                                                         |
+| `usage_not_included`                 | feature not in plan              | fatal                                                                                                         |
+| `invalid_prompt`                     | malformed/safety-rejected prompt | fatal, surface message                                                                                        |
+| `cyber_policy`                       | flagged as security risk         | fatal, message + fallback "This request has been flagged for possible cybersecurity risk." (line 142-143)     |
+| `server_is_overloaded` / `slow_down` | backpressure                     | retry with backoff                                                                                            |
+| `rate_limit_exceeded`                | TPM/RPM limit                    | retry; parse delay from message via regex `(?i)try again in\s*(\d+(?:\.\d+)?)\s*(s\|ms\|seconds?)` (line 586) |
+| anything else                        | unknown server error             | retry                                                                                                         |
+
+### 4d. Token usage — `response.completed`
+
+Source: `codex-rs/codex-api/src/sse/responses.rs:132-167, 392-407`.
+
+```ts
+interface ResponseCompletedData {
+  id: string;
+  end_turn?: boolean; // some providers don't emit; treat None as "unknown"
+  usage?: {
+    input_tokens: number;
+    input_tokens_details?: { cached_tokens: number };
+    output_tokens: number;
+    output_tokens_details?: { reasoning_tokens: number };
+    total_tokens: number;
+  };
+}
+```
+
+Path: `event.data.response.usage.{input_tokens, output_tokens, total_tokens}`. Cached and reasoning-token sub-totals live one level deeper in `*_details`.
+
+### 4e. Assembling the final text
+
+Two valid strategies:
+
+1. **Live streaming**: concatenate every `response.output_text.delta`'s `delta` field. Stop at `response.completed`. (Reasoning deltas come on a separate channel — `response.reasoning_*.delta` — and should NOT be concatenated into the visible answer.)
+2. **End-of-turn snapshot**: ignore deltas, take the `response.output_item.done` whose `item.type == "message"` and `item.role == "assistant"`. Its `item.content[]` will contain `output_text` entries with the full text. This is more robust if you only care about the final answer.
+
+The CLI uses both (deltas drive the live UI; `done` gives the canonical `ResponseItem` for the conversation log).
+
+### 4f. Response headers worth reading
+
+These are on the HTTP response (not in the SSE body). Source: `codex-rs/codex-api/src/sse/responses.rs:69-95`.
+
+| Header                 | Use                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `x-request-id`         | Pass to the user when reporting errors                                                            |
+| `OpenAI-Model`         | The actual model the server routed to (may differ from your request when safety routing kicks in) |
+| `x-reasoning-included` | If present, server already accounted for prior reasoning tokens — don't re-estimate               |
+| `x-codex-turn-state`   | Sticky-routing token — replay in next request's `x-codex-turn-state` header                       |
+| `X-Models-Etag`        | Cache key for the `/models` endpoint                                                              |
+| `cf-ray`               | Cloudflare ray, useful for support                                                                |
+
+### 4g. Idle timeout
+
+The CLI uses an idle timeout per stream (default in `codex-rs/model-provider-info/src/lib.rs` constants); if no SSE event arrives within the window, it emits `"idle timeout waiting for SSE"` and closes. A reasonable TS default is **120 seconds**.
+
+---
+
+## 5. HTTP error responses (non-SSE)
+
+Source: `codex-rs/codex-api/src/api_bridge.rs:36-130`.
+
+If the server fails before the SSE stream begins, it returns a JSON body with shape:
+
+```json
+{ "error": { "type": "...", "code": "...", "message": "..." } }
+```
+
+| Status                                                                                 | Special handling                                                                                         |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `400` with `error.code == "cyber_policy"`                                              | treat as `CyberPolicy` (message or fallback)                                                             |
+| `400` body containing `"The image data you provided does not represent a valid image"` | invalid image                                                                                            |
+| `400` other                                                                            | `InvalidRequest` — e.g. our two seen failures (`"Input must be a list"`, `"Stream must be set to true"`) |
+| `429` with `error.type == "usage_limit_reached"`                                       | parse `plan_type`, `resets_at`, plus rate-limit headers (§5a)                                            |
+| `429` with `error.type == "usage_not_included"`                                        | feature/plan rejection                                                                                   |
+| `429` other                                                                            | retryable rate-limit                                                                                     |
+| `500`                                                                                  | retry                                                                                                    |
+| `503` with `error.code` in `{"server_is_overloaded","slow_down"}`                      | retry with backoff                                                                                       |
+| anything else                                                                          | propagate verbatim                                                                                       |
+
+### 5a. Rate-limit headers
+
+Source: `codex-rs/codex-api/src/rate_limits.rs` (lines 22-345). The Codex backend uses bespoke headers (NOT standard `X-RateLimit-*`). The keys you'll see:
+
+```
+x-codex-active-limit
+x-codex-primary-used-percent
+x-codex-primary-window-minutes
+x-codex-primary-reset-at
+x-codex-secondary-primary-used-percent
+x-codex-secondary-primary-window-minutes
+x-codex-secondary-primary-reset-at
+x-codex-bengalfox-primary-used-percent
+x-codex-bengalfox-limit-name
+x-codex-credits-has-credits
+x-codex-credits-unlimited
+x-codex-credits-balance
+x-codex-promo-message
+```
+
+Surface them to the user when relevant. Never block on them — they're informational.
+
+### 5b. Other error-relevant headers
+
+| Header                              | Source line             | Use                                                                    |
+| ----------------------------------- | ----------------------- | ---------------------------------------------------------------------- |
+| `x-request-id` / `x-oai-request-id` | `api_bridge.rs:136-137` | request id for support                                                 |
+| `cf-ray`                            | `api_bridge.rs:138`     | Cloudflare ray                                                         |
+| `x-openai-authorization-error`      | `api_bridge.rs:139`     | identity-error sub-code                                                |
+| `x-error-json`                      | `api_bridge.rs:140`     | base64-JSON-encoded error envelope; decode with standard b64 then JSON |
+
+---
+
+## 6. Authentication
+
+### 6a. What goes in `Authorization`
+
+The OAuth **access token** issued by `auth.openai.com`. For ChatGPT-mode auth, `CodexAuth::get_token()` returns `tokens.access_token` directly — no swap, no extra exchange (`codex-rs/login/src/auth/manager.rs:325-336`). That's what `BearerAuthProvider` puts in `Bearer <token>`.
+
+The token format is a JWT. The Rust client extracts the expiry from the JWT itself (`parse_jwt_expiration` in `manager.rs:1797`), so there is no `expires_in` to track separately.
+
+### 6b. Where the token comes from (device-code flow)
+
+Source: `codex-rs/login/src/server.rs:711-782` and `codex-rs/login/src/device_code_auth.rs`.
+
+1. Issuer: `https://auth.openai.com` (constant `DEFAULT_ISSUER`, `server.rs:51`).
+2. The device-code flow ends with a PKCE code exchange at `POST {issuer}/oauth/token` with body:
+   ```
+   grant_type=authorization_code
+   code=<authorization_code>
+   redirect_uri=<redirect>
+   client_id=app_EMoamEEZ73f0CkXaXp7hrann
+   code_verifier=<pkce_verifier>
+   ```
+   Content-Type: `application/x-www-form-urlencoded`.
+3. The response is JSON `{ id_token, access_token, refresh_token }` (`server.rs:719-723`). All three are required.
+
+The `client_id` value `app_EMoamEEZ73f0CkXaXp7hrann` is in `codex-rs/login/src/auth/manager.rs:921`.
+
+The OAuth scope is `openid profile email offline_access api.connectors.read api.connectors.invoke` (`codex-rs/login/src/server.rs:493-495`). Plus the non-standard query params `id_token_add_organizations=true`, `codex_cli_simplified_flow=true`, and `originator=<originator>` on the authorize URL (lines 502-506). The token endpoint itself only needs the form fields above.
+
+### 6c. ChatGPT-Account-ID
+
+Read from the `id_token` JWT — specifically the `chatgpt_account_id` claim. The CLI reads it at parse time and exposes it via `CodexAuth::get_account_id()` (`manager.rs:339-344`). For a TS client: decode the JWT (no signature verification needed for our purposes; the server validates), then look at `payload.chatgpt_account_id` (typically nested under `https://api.openai.com/auth.chatgpt_account_id` — see `manager.rs:891` for the namespace).
+
+If you can't find the account id in the id_token, the server returns 401 on the responses POST.
+
+### 6d. Refresh procedure
+
+Source: `codex-rs/login/src/auth/manager.rs:806-848, 906-926`.
+
+```
+POST https://auth.openai.com/oauth/token
+Content-Type: application/json    ← note: refresh uses JSON, not form-encoded
+{
+  "client_id": "app_EMoamEEZ73f0CkXaXp7hrann",
+  "grant_type": "refresh_token",
+  "refresh_token": "<refresh_token>"
+}
+```
+
+Override the URL with env `CODEX_REFRESH_TOKEN_URL_OVERRIDE` if you need a non-default issuer.
+
+Response shape (`manager.rs:913-918`):
+
+```json
+{
+  "id_token": "...", // optional
+  "access_token": "...", // optional but expected
+  "refresh_token": "..." // optional; rotated when present
+}
+```
+
+Persist whichever fields the server returned. **The refresh token is rotated** — the next refresh must use the newly returned `refresh_token` if any; reusing the old one yields `refresh_token_reused` and 401 (lines 856-857).
+
+Failure handling (HTTP 401 body, lines 851-878):
+
+| `error.code` in body        | Treat as                                 |
+| --------------------------- | ---------------------------------------- |
+| `refresh_token_expired`     | permanent — user must re-login           |
+| `refresh_token_reused`      | permanent — concurrent refresh; re-login |
+| `refresh_token_invalidated` | permanent — token revoked; re-login      |
+| anything else               | log and re-login                         |
+
+### 6e. When to refresh
+
+The CLI considers a token "stale" when (`manager.rs:1796-1805`):
+
+1. The JWT's `exp` is `<= now`, OR
+2. `last_refresh < now - 8 days` (constant `TOKEN_REFRESH_INTERVAL = 8` at line 85; `last_refresh` is the wall-clock time of the previous successful refresh).
+
+For a TS client, refresh proactively when the access token's `exp` claim is within ~5 minutes of expiry, and force-refresh on any `401` response from the responses endpoint.
+
+### 6f. Revocation (optional)
+
+`POST https://auth.openai.com/oauth/revoke` revokes a refresh token. Constant: `REVOKE_TOKEN_URL` at `manager.rs:95`. Override env: `CODEX_REVOKE_TOKEN_URL_OVERRIDE` (`manager.rs:97`).
+
+---
+
+## 7. Model strings
+
+The CLI sends the model slug verbatim in the `model` field. There is no enum on the wire — anything the backend recognises works. Slugs the official client knows about (sample, not exhaustive):
+
+| Slug               | Source                                                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `gpt-5-codex`      | `codex-rs/tui/src/model_migration.rs`; `codex-rs/tui/src/bottom_pane/status_line_setup.rs`                                    |
+| `gpt-5-codex-mini` | `codex-rs/tui/src/model_migration.rs`                                                                                         |
+| `gpt-5.3-codex`    | used as a "cyber-restricted" placeholder in tests (`codex-rs/codex-api/src/sse/responses.rs:1374`) — confirms the slug exists |
+| `gpt-5.1`          | shows up in rate-limit error messages in tests (`codex-rs/codex-api/src/sse/responses.rs:875`)                                |
+
+The ChatGPT backend ignores `model` strings the user's account doesn't have entitlements for — the server may safety-route to a different model and report the actual model used in the `OpenAI-Model` response header (§4f). Trust that header, not the request value, when logging.
+
+### 7a. ChatGPT-account-auth allow-list (verified 2026-05-09)
+
+When authenticating via the ChatGPT-OAuth path (Bearer token + `ChatGPT-Account-ID` header, §3a), the backend rejects model slugs that are NOT in the active `codex-rs/models-manager/models.json` bundle. The rejection is HTTP 400 with body:
+
+```json
+{
+  "detail": "The '<slug>' model is not supported when using Codex with a ChatGPT account."
+}
+```
+
+Confirmed-rejected slugs (despite the source-tree references in the table above):
+
+- `gpt-5` — rejected
+- `gpt-5-codex` — rejected (the API-key-auth Codex slug; not the ChatGPT-auth one)
+
+Confirmed-accepted slugs on a ChatGPT Plus subscription (per `available_in_plans` in `models.json`):
+
+- `gpt-5.3-codex` — coding-optimized, accepted; HealthLog uses this as default
+- `gpt-5.5` / `gpt-5.4` / `gpt-5.4-mini` / `gpt-5.2` — also expected to work per plan
+
+The `codex-rs/tui/src/model_migration.rs` references to `gpt-5-codex` etc. are _migration prompts_ shown to existing users — they are NOT the slugs sent on the wire after migration. The wire slugs come from `models.json`. Always cross-check `models.json` (`gh api repos/openai/codex/contents/codex-rs/models-manager/models.json`) before picking a default.
+
+### 7b. Slug-drift defence — fallback chain (HealthLog v1.4.15+)
+
+The ChatGPT-Codex allow-list is rotated by OpenAI without prior notice (`gpt-5-codex` → `gpt-5.3-codex` happened over 48 h in May 2026 and bricked HealthLog twice while the v1.4.7..v1.4.13 saga unrolled). The cause: a single hard-coded slug in `CODEX_MODEL` flips invalid the moment the upstream rotates it. Operator brief, verbatim 2026-05-09: "Die Integration des Slug Drift Risiko darf halt immer überhaupt nicht sein."
+
+To eliminate that risk class, HealthLog's `CodexClient` walks an ordered chain on every fresh request series.
+
+**Chain** (top = first try; default order is the empirically-safest most-current-first ordering as of 2026-05):
+
+```ts
+const DEFAULT_SLUG_FALLBACK_CHAIN = [
+  "gpt-5.3-codex", // current allow-list entry (verified 2026-05-09)
+  "gpt-5-codex", // historical default (rejected as of 2026-05 but safe to retry — backend may flip)
+  "gpt-5", // bare slug — rejected on ChatGPT-auth as of 2026-05 but lives on api-key auth
+  "gpt-4o", // ladder-rung for last-ditch capability
+];
+```
+
+The chain is overridable via the env var `CODEX_MODEL_FALLBACK_CHAIN` (comma-separated). The first env-var-named slug supersedes `CODEX_MODEL`; if both are set, `CODEX_MODEL` is folded into position 0 and de-duplicated.
+
+**Trigger condition** (when to walk to the next slug):
+
+| Status                                                                        | Action                                           |
+| ----------------------------------------------------------------------------- | ------------------------------------------------ |
+| `400` body matches `/not supported when using Codex with a ChatGPT account/i` | walk                                             |
+| `400` body contains `model_not_found`                                         | walk                                             |
+| `400` body contains `does not exist` AND mentions a model name                | walk                                             |
+| `404` (any body)                                                              | walk                                             |
+| `401` first time                                                              | refresh and re-try same slug; do NOT walk        |
+| `401` after refresh, `403`, `429`, `5xx`                                      | propagate (don't walk)                           |
+| `200` with SSE `response.failed.error.code === "invalid_prompt"`              | propagate (request shape is wrong, slug is fine) |
+
+**Positive cache** — when a slug is observed working (HTTP 200 with at least one `response.completed` event), record `(slug, timestamp)` in a process-local Map. On the next request, jump straight to the cached slug. TTL: 1 hour. Cache scope: per-process (no DB write).
+
+**Cache invalidation**: on first 400/404 walk, the cached entry is dropped. The next-best slug is promoted into the cache only after it succeeds.
+
+**All-failed case**: if every slug in the chain rejects with the walk-trigger, the client throws a structured error with `httpStatus: 503` and message `"AI provider unreachable — all configured Codex slugs were rejected"`. The route layer surfaces this to the user with "AI provider unreachable — check Settings".
+
+**Observability**: each attempted slug is recorded in the Wide-Event annotation `codex.slug.attempts: ["gpt-5.3-codex","gpt-5-codex"]` so Loki can answer "which slug carried this request" and "how often did the cache hit". Cache hits emit `codex.slug.cache: "hit" | "miss" | "expired"`.
+
+The implementation lives in `src/lib/ai/codex-client.ts`; the contract is unit-tested in `src/lib/ai/__tests__/codex-client.test.ts`.
+
+---
+
+## 8. Worked example — minimal end-to-end
+
+Outbound:
+
+```http
+POST /backend-api/codex/responses HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer eyJhbGciOi...<oauth-access-token>
+ChatGPT-Account-ID: a1b2c3d4-...
+Content-Type: application/json
+Accept: text/event-stream
+originator: healthlog
+User-Agent: healthlog/1.0
+session_id: 11111111-1111-1111-1111-111111111111
+thread_id: 22222222-2222-2222-2222-222222222222
+```
+
+```json
+{
+  "model": "gpt-5-codex",
+  "instructions": "",
+  "input": [
+    {
+      "type": "message",
+      "role": "user",
+      "content": [{ "type": "input_text", "text": "Say hi in one word." }]
+    }
+  ],
+  "tools": [],
+  "tool_choice": "auto",
+  "parallel_tool_calls": false,
+  "reasoning": null,
+  "store": false,
+  "stream": true,
+  "include": []
+}
+```
+
+Inbound (illustrative — based on `codex-rs/codex-api/src/sse/responses.rs:666-730` test fixtures):
+
+```
+event: response.created
+data: {"type":"response.created","response":{"id":"resp_abc"}}
+
+event: response.output_item.added
+data: {"type":"response.output_item.added","item":{"type":"message","role":"assistant","content":[]}}
+
+event: response.output_text.delta
+data: {"type":"response.output_text.delta","delta":"Hi"}
+
+event: response.output_text.delta
+data: {"type":"response.output_text.delta","delta":"!"}
+
+event: response.output_item.done
+data: {"type":"response.output_item.done","item":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Hi!"}]}}
+
+event: response.completed
+data: {"type":"response.completed","response":{"id":"resp_abc","usage":{"input_tokens":12,"output_tokens":2,"total_tokens":14}}}
+```
+
+A TS client should:
+
+1. Stream-parse SSE.
+2. Concatenate `delta` from each `response.output_text.delta` for live UI.
+3. On `response.output_item.done` with `item.type=="message"` and `item.role=="assistant"`, take `item.content` as the canonical reply.
+4. On `response.completed`, store `response.id` (for follow-up turns) and `response.usage` (for token accounting).
+5. On `response.failed` / `response.incomplete`, surface error per §4c.
+
+---
+
+## 9. Quick reference — the original errors we hit
+
+- **"Input must be a list"** → `input` was a string. Wrap as `[{ type: "message", role: "user", content: [{ type: "input_text", text: "..." }] }]`.
+- **"Stream must be set to true"** → must set `stream: true`. The chatgpt.com endpoint has no non-streaming mode.
+
+Both come back as HTTP 400 with `error.code == "invalid_prompt"` (no `cyber_policy` flag) → mapped to `ApiError::InvalidRequest` per `api_bridge.rs:75-77`.
+
+---
+
+## 10. Source-file index (for re-verification)
+
+All paths relative to `openai/codex` repo:
+
+- `codex-rs/codex-api/src/common.rs` — `ResponsesApiRequest`, `Reasoning`, `TextControls`, `TextFormat`
+- `codex-rs/codex-api/src/endpoint/responses.rs` — request construction, headers, ACCEPT
+- `codex-rs/codex-api/src/requests/headers.rs` — session/thread/sub-agent headers
+- `codex-rs/codex-api/src/sse/responses.rs` — SSE parsing, all event types, error mapping
+- `codex-rs/codex-api/src/api_bridge.rs` — HTTP error mapping
+- `codex-rs/codex-api/src/rate_limits.rs` — rate-limit headers
+- `codex-rs/codex-api/src/auth.rs` — `AuthProvider` trait
+- `codex-rs/protocol/src/models.rs` — `ResponseItem`, `ContentItem`, `MessagePhase`, `ImageDetail`, etc.
+- `codex-rs/protocol/src/openai_models.rs` — `ReasoningEffort` enum
+- `codex-rs/protocol/src/config_types.rs` — `ReasoningSummary`, `Verbosity` enums
+- `codex-rs/model-provider/src/bearer_auth_provider.rs` — `Authorization` + `ChatGPT-Account-ID` headers
+- `codex-rs/model-provider/src/auth.rs` — auth-provider selection
+- `codex-rs/model-provider-info/src/lib.rs` — `CHATGPT_CODEX_BASE_URL`, OpenAI provider creation
+- `codex-rs/login/src/auth/manager.rs` — token storage, refresh, expiry, `CLIENT_ID`
+- `codex-rs/login/src/server.rs` — code exchange (`exchange_code_for_tokens`), authorize URL (scope)
+- `codex-rs/login/src/device_code_auth.rs` — device-code flow
+- `codex-rs/login/src/auth/default_client.rs` — `originator`, `User-Agent`, residency
+- `codex-rs/chatgpt/src/chatgpt_client.rs` — confirms `chatgpt_base_url + path` pattern and `ChatGPT-Account-ID` requirement
+- `codex-rs/core/src/client.rs` — how the CLI builds requests (`build_responses_request`, `build_responses_headers`); the source of `tool_choice="auto"`, `store=false` for chatgpt, `stream=true`, `include=["reasoning.encrypted_content"]` when reasoning is on, `prompt_cache_key=thread_id`

docs/diagrams/01-data-flow.svg

@@ -0,0 +1,170 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
+  <title id="title">HealthLog data flow — device to insight</title>
+  <desc id="desc">Five-stage pipeline: sources (Withings, Apple Health export, iPhone HealthKit, manual entry, moodLog.app) feed ingest endpoints, which write to Postgres Measurement and MeasurementRollup tables, then surface on Dashboard tiles, Insights cards, the AI Coach, and the Doctor PDF.</desc>
+
+  <!-- Dracula background -->
+  <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
+
+  <!-- Title -->
+  <text x="600" y="40" fill="#f8f8f2" font-size="22" font-weight="700" text-anchor="middle">From device to insight</text>
+  <text x="600" y="64" fill="#6272a4" font-size="13" text-anchor="middle">Every reading walks the same five-stage pipeline: source → ingest → store → read → surface</text>
+
+  <!-- Lane headers -->
+  <g font-size="12" fill="#6272a4" font-weight="600" letter-spacing="1">
+    <text x="120" y="105" text-anchor="middle">SOURCES</text>
+    <text x="360" y="105" text-anchor="middle">INGEST</text>
+    <text x="600" y="105" text-anchor="middle">STORE</text>
+    <text x="840" y="105" text-anchor="middle">READ</text>
+    <text x="1080" y="105" text-anchor="middle">SURFACE</text>
+  </g>
+
+  <!-- Lane separators -->
+  <g stroke="#44475a" stroke-dasharray="4 6" stroke-width="1">
+    <line x1="240" y1="120" x2="240" y2="560" />
+    <line x1="480" y1="120" x2="480" y2="560" />
+    <line x1="720" y1="120" x2="720" y2="560" />
+    <line x1="960" y1="120" x2="960" y2="560" />
+  </g>
+
+  <!-- SOURCES (cyan #8be9fd) -->
+  <g font-size="13" fill="#f8f8f2">
+    <rect x="30" y="140" width="180" height="56" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="165" text-anchor="middle" font-weight="600">Withings devices</text>
+    <text x="120" y="183" text-anchor="middle" fill="#bd93f9" font-size="11">Scales · BPM · ScanWatch</text>
+
+    <rect x="30" y="216" width="180" height="56" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="241" text-anchor="middle" font-weight="600">Apple Health export</text>
+    <text x="120" y="259" text-anchor="middle" fill="#bd93f9" font-size="11">export.zip · multi-GB</text>
+
+    <rect x="30" y="292" width="180" height="56" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="317" text-anchor="middle" font-weight="600">iPhone HealthKit</text>
+    <text x="120" y="335" text-anchor="middle" fill="#bd93f9" font-size="11">native batch (v1.5)</text>
+
+    <rect x="30" y="368" width="180" height="56" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="393" text-anchor="middle" font-weight="600">Manual entry</text>
+    <text x="120" y="411" text-anchor="middle" fill="#bd93f9" font-size="11">PWA · iOS Shortcuts</text>
+
+    <rect x="30" y="444" width="180" height="56" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="469" text-anchor="middle" font-weight="600">moodLog.app</text>
+    <text x="120" y="487" text-anchor="middle" fill="#bd93f9" font-size="11">webhook</text>
+  </g>
+
+  <!-- INGEST (orange #ffb86c) -->
+  <g font-size="13" fill="#f8f8f2">
+    <rect x="270" y="170" width="180" height="56" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="360" y="195" text-anchor="middle" font-weight="600">/api/withings/webhook</text>
+    <text x="360" y="213" text-anchor="middle" fill="#bd93f9" font-size="11">+ /sync</text>
+
+    <rect x="270" y="246" width="180" height="56" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="360" y="271" text-anchor="middle" font-weight="600">/import/apple-health-export</text>
+    <text x="360" y="289" text-anchor="middle" fill="#bd93f9" font-size="11">streaming · idempotent</text>
+
+    <rect x="270" y="322" width="180" height="56" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="360" y="347" text-anchor="middle" font-weight="600">/api/measurements/batch</text>
+    <text x="360" y="365" text-anchor="middle" fill="#bd93f9" font-size="11">native batch ingest</text>
+
+    <rect x="270" y="398" width="180" height="56" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="360" y="423" text-anchor="middle" font-weight="600">Dedup + source-priority</text>
+    <text x="360" y="441" text-anchor="middle" fill="#bd93f9" font-size="11">resolver</text>
+  </g>
+
+  <!-- STORE (pink #ff79c6) -->
+  <g font-size="13" fill="#f8f8f2">
+    <rect x="510" y="200" width="180" height="76" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="600" y="227" text-anchor="middle" font-weight="600">Measurement</text>
+    <text x="600" y="247" text-anchor="middle" fill="#bd93f9" font-size="11">one row per sample</text>
+    <text x="600" y="264" text-anchor="middle" fill="#6272a4" font-size="11">(userId, type, source, t)</text>
+
+    <rect x="510" y="296" width="180" height="76" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="600" y="323" text-anchor="middle" font-weight="600">MeasurementRollup</text>
+    <text x="600" y="343" text-anchor="middle" fill="#bd93f9" font-size="11">DAY · WEEK · MONTH</text>
+    <text x="600" y="360" text-anchor="middle" fill="#6272a4" font-size="11">pre-aggregated buckets</text>
+
+    <rect x="510" y="392" width="180" height="56" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="600" y="417" text-anchor="middle" font-weight="600">PostgreSQL 16</text>
+    <text x="600" y="435" text-anchor="middle" fill="#bd93f9" font-size="11">encrypted at rest</text>
+  </g>
+
+  <!-- READ (green #50fa7b) -->
+  <g font-size="13" fill="#f8f8f2">
+    <rect x="750" y="200" width="180" height="56" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="840" y="225" text-anchor="middle" font-weight="600">Rollup probe</text>
+    <text x="840" y="243" text-anchor="middle" fill="#bd93f9" font-size="11">DAY-bucket fast path</text>
+
+    <rect x="750" y="276" width="180" height="56" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="840" y="301" text-anchor="middle" font-weight="600">Live SQL fallback</text>
+    <text x="840" y="319" text-anchor="middle" fill="#bd93f9" font-size="11">slope · r² · sd</text>
+
+    <rect x="750" y="352" width="180" height="56" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="840" y="377" text-anchor="middle" font-weight="600">Wide-event cache</text>
+    <text x="840" y="395" text-anchor="middle" fill="#bd93f9" font-size="11">cache.&lt;name&gt;.outcome</text>
+  </g>
+
+  <!-- SURFACES (purple #bd93f9) -->
+  <g font-size="13" fill="#f8f8f2">
+    <rect x="990" y="170" width="180" height="56" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1080" y="195" text-anchor="middle" font-weight="600">Dashboard tiles</text>
+    <text x="1080" y="213" text-anchor="middle" fill="#bd93f9" font-size="11">trends · ranges</text>
+
+    <rect x="990" y="246" width="180" height="56" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1080" y="271" text-anchor="middle" font-weight="600">Insights cards</text>
+    <text x="1080" y="289" text-anchor="middle" fill="#bd93f9" font-size="11">evidence-grounded</text>
+
+    <rect x="990" y="322" width="180" height="56" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1080" y="347" text-anchor="middle" font-weight="600">AI Coach</text>
+    <text x="1080" y="365" text-anchor="middle" fill="#bd93f9" font-size="11">cited replies</text>
+
+    <rect x="990" y="398" width="180" height="56" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1080" y="423" text-anchor="middle" font-weight="600">Doctor PDF</text>
+    <text x="1080" y="441" text-anchor="middle" fill="#bd93f9" font-size="11">client-side jsPDF</text>
+  </g>
+
+  <!-- Arrows: sources → ingest -->
+  <g stroke="#8be9fd" stroke-width="1.5" fill="none" marker-end="url(#arr-cyan)">
+    <path d="M210 168 C 235 168, 245 198, 270 198" />
+    <path d="M210 244 C 235 244, 245 274, 270 274" />
+    <path d="M210 320 C 235 320, 245 350, 270 350" />
+    <path d="M210 396 C 235 396, 245 426, 270 426" />
+    <path d="M210 472 C 235 472, 245 426, 270 426" />
+  </g>
+
+  <!-- Arrows: ingest → store (all funnel into priority resolver, then to tables) -->
+  <g stroke="#ffb86c" stroke-width="1.5" fill="none" marker-end="url(#arr-orange)">
+    <path d="M450 198 C 480 198, 490 238, 510 238" />
+    <path d="M450 274 C 480 274, 490 238, 510 238" />
+    <path d="M450 350 C 480 350, 490 238, 510 238" />
+    <path d="M450 426 C 480 426, 490 334, 510 334" />
+  </g>
+
+  <!-- Arrow: Measurement → Rollup (worker) -->
+  <g stroke="#ff79c6" stroke-width="1.5" fill="none" marker-end="url(#arr-pink)">
+    <path d="M600 276 C 600 286, 600 286, 600 296" />
+  </g>
+  <text x="612" y="290" fill="#6272a4" font-size="10">pg-boss worker</text>
+
+  <!-- Arrows: store → read -->
+  <g stroke="#50fa7b" stroke-width="1.5" fill="none" marker-end="url(#arr-green)">
+    <path d="M690 334 C 720 334, 730 228, 750 228" />
+    <path d="M690 238 C 720 238, 730 304, 750 304" />
+    <path d="M690 420 C 720 420, 730 380, 750 380" />
+  </g>
+
+  <!-- Arrows: read → surfaces -->
+  <g stroke="#bd93f9" stroke-width="1.5" fill="none" marker-end="url(#arr-purple)">
+    <path d="M930 228 C 960 228, 970 198, 990 198" />
+    <path d="M930 228 C 960 228, 970 274, 990 274" />
+    <path d="M930 304 C 960 304, 970 350, 990 350" />
+    <path d="M930 380 C 960 380, 970 426, 990 426" />
+  </g>
+
+  <!-- Footnote -->
+  <text x="600" y="590" fill="#6272a4" font-size="11" text-anchor="middle">Source-priority ladder runs at ingest. Live SQL is the safety net when the rollup is cold or the metric ask is too slope/variance-heavy for a DAY bucket.</text>
+
+  <defs>
+    <marker id="arr-cyan" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#8be9fd" /></marker>
+    <marker id="arr-orange" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ffb86c" /></marker>
+    <marker id="arr-pink" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff79c6" /></marker>
+    <marker id="arr-green" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#50fa7b" /></marker>
+    <marker id="arr-purple" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bd93f9" /></marker>
+  </defs>
+</svg>

docs/diagrams/02-coach-pipeline.svg

@@ -0,0 +1,148 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
+  <title id="title">AI Coach prompt pipeline</title>
+  <desc id="desc">A user question feeds the snapshot builder, which pulls the recent metric, medication and mood windows. The system prompt assembler combines them with a locale-aware structured-output schema, then the provider chain (ChatGPT OAuth, OpenAI, Anthropic, Local) tries each entry in order. The response parser extracts claims plus citations, validates against the schema, and renders a cited reply with mini-charts.</desc>
+
+  <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
+
+  <text x="600" y="40" fill="#f8f8f2" font-size="22" font-weight="700" text-anchor="middle">AI Coach prompt pipeline</text>
+  <text x="600" y="64" fill="#6272a4" font-size="13" text-anchor="middle">Why every reply cites the measurement it came from — not just an LLM call.</text>
+
+  <!-- USER QUESTION (cyan) -->
+  <g>
+    <rect x="40" y="120" width="200" height="80" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="140" y="148" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">User question</text>
+    <text x="140" y="170" text-anchor="middle" fill="#bd93f9" font-size="11">/insights drawer</text>
+    <text x="140" y="186" text-anchor="middle" fill="#6272a4" font-size="11">"Why is my BP higher this week?"</text>
+  </g>
+
+  <!-- SNAPSHOT BUILDER (orange) -->
+  <g>
+    <rect x="280" y="100" width="220" height="120" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="390" y="128" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Snapshot builder</text>
+    <text x="390" y="152" text-anchor="middle" fill="#bd93f9" font-size="11">last-N days metrics</text>
+    <text x="390" y="170" text-anchor="middle" fill="#bd93f9" font-size="11">+ medication schedule</text>
+    <text x="390" y="188" text-anchor="middle" fill="#bd93f9" font-size="11">+ mood + targets</text>
+    <text x="390" y="208" text-anchor="middle" fill="#6272a4" font-size="11">60s LRU per (userId, scope)</text>
+  </g>
+
+  <!-- PROMPT ASSEMBLER (pink) -->
+  <g>
+    <rect x="540" y="100" width="220" height="120" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="650" y="128" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Prompt assembler</text>
+    <text x="650" y="152" text-anchor="middle" fill="#bd93f9" font-size="11">system prompt</text>
+    <text x="650" y="170" text-anchor="middle" fill="#bd93f9" font-size="11">+ locale (en/de)</text>
+    <text x="650" y="188" text-anchor="middle" fill="#bd93f9" font-size="11">+ Zod citation schema</text>
+    <text x="650" y="208" text-anchor="middle" fill="#6272a4" font-size="11">PROMPT_VERSION 4.36.0</text>
+  </g>
+
+  <!-- PROVIDER CHAIN (purple) -->
+  <g>
+    <rect x="800" y="100" width="360" height="280" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="980" y="128" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Provider chain</text>
+    <text x="980" y="148" text-anchor="middle" fill="#6272a4" font-size="11">first non-error wins · hard fail cascades</text>
+
+    <!-- Entries -->
+    <g font-size="12" fill="#f8f8f2">
+      <rect x="820" y="170" width="320" height="38" rx="8" fill="#282a36" stroke="#bd93f9" stroke-width="1" />
+      <text x="840" y="194" font-weight="600">1.</text>
+      <text x="870" y="194">ChatGPT OAuth (Codex)</text>
+      <text x="1120" y="194" text-anchor="end" fill="#50fa7b" font-size="11">subscription</text>
+
+      <rect x="820" y="216" width="320" height="38" rx="8" fill="#282a36" stroke="#bd93f9" stroke-width="1" />
+      <text x="840" y="240" font-weight="600">2.</text>
+      <text x="870" y="240">OpenAI direct (BYOK)</text>
+      <text x="1120" y="240" text-anchor="end" fill="#ffb86c" font-size="11">per-token</text>
+
+      <rect x="820" y="262" width="320" height="38" rx="8" fill="#282a36" stroke="#bd93f9" stroke-width="1" />
+      <text x="840" y="286" font-weight="600">3.</text>
+      <text x="870" y="286">Anthropic Claude (BYOK)</text>
+      <text x="1120" y="286" text-anchor="end" fill="#ffb86c" font-size="11">per-token</text>
+
+      <rect x="820" y="308" width="320" height="38" rx="8" fill="#282a36" stroke="#bd93f9" stroke-width="1" />
+      <text x="840" y="332" font-weight="600">4.</text>
+      <text x="870" y="332">Local (Ollama · LM Studio · vLLM)</text>
+      <text x="1120" y="332" text-anchor="end" fill="#50fa7b" font-size="11">on network</text>
+
+      <rect x="820" y="354" width="320" height="20" rx="6" fill="#282a36" stroke="#6272a4" stroke-width="1" stroke-dasharray="3 3" />
+      <text x="980" y="368" text-anchor="middle" fill="#6272a4" font-size="11">5. Admin-shared OpenAI (fallback)</text>
+    </g>
+  </g>
+
+  <!-- RESPONSE PARSER (green) -->
+  <g>
+    <rect x="540" y="420" width="220" height="120" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="650" y="448" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Response parser</text>
+    <text x="650" y="472" text-anchor="middle" fill="#bd93f9" font-size="11">Zod schema validate</text>
+    <text x="650" y="490" text-anchor="middle" fill="#bd93f9" font-size="11">extract claims + cites</text>
+    <text x="650" y="508" text-anchor="middle" fill="#bd93f9" font-size="11">server-computed score</text>
+    <text x="650" y="528" text-anchor="middle" fill="#ff5555" font-size="11">corrective retry on 422</text>
+  </g>
+
+  <!-- CITED REPLY (pink) -->
+  <g>
+    <rect x="280" y="420" width="220" height="120" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="390" y="448" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Cited reply</text>
+    <text x="390" y="472" text-anchor="middle" fill="#bd93f9" font-size="11">prose first</text>
+    <text x="390" y="490" text-anchor="middle" fill="#bd93f9" font-size="11">collapsible evidence</text>
+    <text x="390" y="508" text-anchor="middle" fill="#bd93f9" font-size="11">mini-charts</text>
+    <text x="390" y="528" text-anchor="middle" fill="#bd93f9" font-size="11">ESH/ESC/WHO/DGE link</text>
+  </g>
+
+  <!-- DRAWER (cyan) -->
+  <g>
+    <rect x="40" y="430" width="200" height="80" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="140" y="458" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">/insights drawer</text>
+    <text x="140" y="480" text-anchor="middle" fill="#bd93f9" font-size="11">streaming render</text>
+    <text x="140" y="498" text-anchor="middle" fill="#6272a4" font-size="11">source chips · feedback</text>
+  </g>
+
+  <!-- CACHE box -->
+  <g>
+    <rect x="40" y="280" width="200" height="80" rx="10" fill="#44475a" stroke="#ff5555" stroke-width="1.5" stroke-dasharray="4 4" />
+    <text x="140" y="308" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">24h insight cache</text>
+    <text x="140" y="330" text-anchor="middle" fill="#bd93f9" font-size="11">snapshot hash + version</text>
+    <text x="140" y="346" text-anchor="middle" fill="#6272a4" font-size="11">short-circuits provider call</text>
+  </g>
+
+  <!-- Arrows -->
+  <g stroke="#8be9fd" stroke-width="1.5" fill="none" marker-end="url(#a-c)">
+    <path d="M240 160 L 280 160" />
+  </g>
+  <g stroke="#ffb86c" stroke-width="1.5" fill="none" marker-end="url(#a-o)">
+    <path d="M500 160 L 540 160" />
+  </g>
+  <g stroke="#ff79c6" stroke-width="1.5" fill="none" marker-end="url(#a-p)">
+    <path d="M760 160 L 800 160" />
+  </g>
+  <g stroke="#bd93f9" stroke-width="1.5" fill="none" marker-end="url(#a-pu)">
+    <!-- provider chain → parser -->
+    <path d="M820 320 C 780 320, 760 420, 760 480" />
+  </g>
+  <g stroke="#50fa7b" stroke-width="1.5" fill="none" marker-end="url(#a-g)">
+    <path d="M540 480 L 500 480" />
+  </g>
+  <g stroke="#ff79c6" stroke-width="1.5" fill="none" marker-end="url(#a-pi)">
+    <path d="M280 480 L 240 470" />
+  </g>
+
+  <!-- cache loop -->
+  <g stroke="#ff5555" stroke-width="1.5" stroke-dasharray="4 4" fill="none" marker-end="url(#a-r)">
+    <path d="M390 220 L 200 280" />
+    <path d="M200 360 C 250 380, 280 410, 300 420" />
+  </g>
+  <text x="220" y="395" fill="#ff5555" font-size="10">hit → render</text>
+  <text x="290" y="252" fill="#ff5555" font-size="10">miss → assemble</text>
+
+  <!-- Footnote -->
+  <text x="600" y="580" fill="#6272a4" font-size="11" text-anchor="middle">Every claim renders with its source chip (metric · window · n) so the user can audit which slice of data backed each sentence.</text>
+
+  <defs>
+    <marker id="a-c" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#8be9fd" /></marker>
+    <marker id="a-o" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ffb86c" /></marker>
+    <marker id="a-p" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff79c6" /></marker>
+    <marker id="a-pu" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bd93f9" /></marker>
+    <marker id="a-g" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#50fa7b" /></marker>
+    <marker id="a-pi" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff79c6" /></marker>
+    <marker id="a-r" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff5555" /></marker>
+  </defs>
+</svg>

docs/diagrams/03-self-hosting-topology.svg

@@ -0,0 +1,132 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
+  <title id="title">HealthLog self-hosting topology</title>
+  <desc id="desc">Internet traffic terminates at a reverse proxy (Caddy, Traefik or Nginx) for TLS, then reaches the Next.js app on port 3000. The app shares a Postgres 16 database with the pg-boss worker process for reminders, insights, backups and the Apple Health import. GHCR ships the multi-arch image; Coolify watches the digest and pulls; off-host S3-compatible storage is optional for backups.</desc>
+
+  <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
+
+  <text x="600" y="40" fill="#f8f8f2" font-size="22" font-weight="700" text-anchor="middle">Self-hosting topology</text>
+  <text x="600" y="64" fill="#6272a4" font-size="13" text-anchor="middle">What runs where on a single-host install — and what the optional pieces add.</text>
+
+  <!-- Outer: Your host -->
+  <g>
+    <rect x="220" y="100" width="760" height="440" rx="14" fill="none" stroke="#bd93f9" stroke-width="1.5" stroke-dasharray="6 4" />
+    <text x="600" y="124" text-anchor="middle" fill="#bd93f9" font-size="13" font-weight="600">Your host (NAS · homelab · VPS)</text>
+  </g>
+
+  <!-- Internet (cyan) -->
+  <g>
+    <ellipse cx="120" cy="280" rx="80" ry="50" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="120" y="276" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Internet</text>
+    <text x="120" y="296" text-anchor="middle" fill="#bd93f9" font-size="11">browsers · iOS app</text>
+  </g>
+
+  <!-- Reverse proxy (orange) -->
+  <g>
+    <rect x="260" y="240" width="180" height="80" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="350" y="266" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Reverse proxy</text>
+    <text x="350" y="286" text-anchor="middle" fill="#bd93f9" font-size="11">Caddy · Traefik · Nginx</text>
+    <text x="350" y="302" text-anchor="middle" fill="#6272a4" font-size="11">TLS · HSTS · CSP</text>
+  </g>
+
+  <!-- Next.js app (pink) -->
+  <g>
+    <rect x="480" y="200" width="220" height="80" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="590" y="226" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Next.js app</text>
+    <text x="590" y="246" text-anchor="middle" fill="#bd93f9" font-size="11">port 3000 · App Router</text>
+    <text x="590" y="262" text-anchor="middle" fill="#6272a4" font-size="11">HEALTHLOG_PROCESS_TYPE=web</text>
+  </g>
+
+  <!-- pg-boss worker (pink) -->
+  <g>
+    <rect x="480" y="300" width="220" height="80" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="590" y="326" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">pg-boss worker</text>
+    <text x="590" y="346" text-anchor="middle" fill="#bd93f9" font-size="11">reminders · insights · imports</text>
+    <text x="590" y="362" text-anchor="middle" fill="#6272a4" font-size="11">HEALTHLOG_PROCESS_TYPE=worker</text>
+  </g>
+
+  <!-- Postgres (green) -->
+  <g>
+    <rect x="760" y="250" width="200" height="80" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="860" y="276" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">PostgreSQL 16</text>
+    <text x="860" y="296" text-anchor="middle" fill="#bd93f9" font-size="11">26 Prisma models</text>
+    <text x="860" y="312" text-anchor="middle" fill="#6272a4" font-size="11">+ pg-boss queues</text>
+  </g>
+
+  <!-- GHCR (purple) -->
+  <g>
+    <rect x="260" y="420" width="220" height="80" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="370" y="446" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">GitHub Container Registry</text>
+    <text x="370" y="466" text-anchor="middle" fill="#bd93f9" font-size="11">multi-arch image (amd64/arm64)</text>
+    <text x="370" y="482" text-anchor="middle" fill="#6272a4" font-size="11">ghcr.io/mbombeck/healthlog</text>
+  </g>
+
+  <!-- Coolify (purple) -->
+  <g>
+    <rect x="520" y="420" width="180" height="80" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="610" y="446" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Coolify (optional)</text>
+    <text x="610" y="466" text-anchor="middle" fill="#bd93f9" font-size="11">watch digest · pull · deploy</text>
+    <text x="610" y="482" text-anchor="middle" fill="#ff5555" font-size="11">pull_policy: always</text>
+  </g>
+
+  <!-- S3 backup (orange) -->
+  <g>
+    <rect x="740" y="420" width="220" height="80" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="850" y="446" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">S3-compatible backup</text>
+    <text x="850" y="466" text-anchor="middle" fill="#bd93f9" font-size="11">R2 · B2 · MinIO · AWS</text>
+    <text x="850" y="482" text-anchor="middle" fill="#6272a4" font-size="11">AES-GCM weekly off-host</text>
+  </g>
+
+  <!-- Test result probe (right side) -->
+  <g>
+    <rect x="1010" y="240" width="160" height="100" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" stroke-dasharray="4 4" />
+    <text x="1090" y="266" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Withings</text>
+    <text x="1090" y="282" text-anchor="middle" fill="#6272a4" font-size="11">Apple Health</text>
+    <text x="1090" y="298" text-anchor="middle" fill="#6272a4" font-size="11">moodLog.app</text>
+    <text x="1090" y="314" text-anchor="middle" fill="#6272a4" font-size="11">AI provider</text>
+    <text x="1090" y="332" text-anchor="middle" fill="#bd93f9" font-size="11">(per-user)</text>
+  </g>
+
+  <!-- Arrows -->
+  <g stroke="#8be9fd" stroke-width="1.5" fill="none" marker-end="url(#a3-c)">
+    <path d="M200 280 L 260 280" />
+  </g>
+  <text x="220" y="270" fill="#6272a4" font-size="10">HTTPS</text>
+
+  <g stroke="#ffb86c" stroke-width="1.5" fill="none" marker-end="url(#a3-o)">
+    <path d="M440 270 C 460 260, 470 240, 480 240" />
+  </g>
+
+  <g stroke="#ff79c6" stroke-width="1.5" fill="none" marker-end="url(#a3-p)">
+    <path d="M700 240 L 760 270" />
+    <path d="M700 340 L 760 310" />
+    <path d="M590 280 L 590 300" />
+  </g>
+  <text x="510" y="295" fill="#6272a4" font-size="10">shared DB</text>
+
+  <g stroke="#bd93f9" stroke-width="1.5" fill="none" marker-end="url(#a3-pu)">
+    <path d="M480 460 L 520 460" />
+    <path d="M700 440 C 680 380, 640 360, 590 360" />
+  </g>
+  <text x="700" y="395" fill="#6272a4" font-size="10">image pull</text>
+
+  <g stroke="#ffb86c" stroke-width="1.5" fill="none" marker-end="url(#a3-o2)">
+    <path d="M860 420 L 860 330" />
+  </g>
+  <text x="870" y="385" fill="#6272a4" font-size="10">nightly dump</text>
+
+  <g stroke="#8be9fd" stroke-width="1.5" stroke-dasharray="4 4" fill="none" marker-end="url(#a3-c2)">
+    <path d="M700 220 C 800 200, 1000 220, 1080 240" />
+  </g>
+  <text x="900" y="195" fill="#6272a4" font-size="10">outbound integrations</text>
+
+  <text x="600" y="585" fill="#6272a4" font-size="11" text-anchor="middle">Single-process default: web + worker share one container. Split via HEALTHLOG_PROCESS_TYPE for horizontal scale.</text>
+
+  <defs>
+    <marker id="a3-c" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#8be9fd" /></marker>
+    <marker id="a3-o" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ffb86c" /></marker>
+    <marker id="a3-p" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff79c6" /></marker>
+    <marker id="a3-pu" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bd93f9" /></marker>
+    <marker id="a3-o2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ffb86c" /></marker>
+    <marker id="a3-c2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#8be9fd" /></marker>
+  </defs>
+</svg>

docs/diagrams/04-source-priority.svg

@@ -0,0 +1,126 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
+  <title id="title">Source-priority ladder</title>
+  <desc id="desc">Three sources (Apple Watch via HealthKit, Withings device, manual entry) can all submit a reading for the same metric. The resolver picks one canonical value per user-day based on metric type — cumulative metrics (steps, energy, distance) prefer Apple Health, point measurements (weight, BP, SpO₂) prefer Withings. Losing rows stay in the audit trail but drop out of aggregation.</desc>
+
+  <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
+
+  <text x="600" y="40" fill="#f8f8f2" font-size="22" font-weight="700" text-anchor="middle">Source-priority ladder</text>
+  <text x="600" y="64" fill="#6272a4" font-size="13" text-anchor="middle">Why your steps don't triple-count when an iPhone, a Withings watch and a manual entry all log the same day.</text>
+
+  <!-- Day strip background -->
+  <g>
+    <rect x="60" y="100" width="280" height="440" rx="14" fill="#21222c" stroke="#44475a" stroke-width="1" stroke-dasharray="4 4" />
+    <text x="200" y="124" text-anchor="middle" fill="#6272a4" font-size="13" font-weight="600">Same day · same metric · three sources</text>
+  </g>
+
+  <!-- Source 1: Apple Health (cyan) -->
+  <g>
+    <rect x="90" y="150" width="220" height="80" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="200" y="178" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Apple Watch (HK)</text>
+    <text x="200" y="198" text-anchor="middle" fill="#bd93f9" font-size="11">10 432 steps · 76 kg · 132/81 mmHg</text>
+    <text x="200" y="214" text-anchor="middle" fill="#6272a4" font-size="11">source = APPLE_HEALTH</text>
+  </g>
+
+  <!-- Source 2: Withings (orange) -->
+  <g>
+    <rect x="90" y="250" width="220" height="80" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="200" y="278" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Withings scale + BPM</text>
+    <text x="200" y="298" text-anchor="middle" fill="#bd93f9" font-size="11">9 870 steps · 75.8 kg · 134/82 mmHg</text>
+    <text x="200" y="314" text-anchor="middle" fill="#6272a4" font-size="11">source = WITHINGS</text>
+  </g>
+
+  <!-- Source 3: Manual (pink) -->
+  <g>
+    <rect x="90" y="350" width="220" height="80" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
+    <text x="200" y="378" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">Manual entry</text>
+    <text x="200" y="398" text-anchor="middle" fill="#bd93f9" font-size="11">76.0 kg (after-shower weigh-in)</text>
+    <text x="200" y="414" text-anchor="middle" fill="#6272a4" font-size="11">source = MANUAL</text>
+  </g>
+
+  <!-- Source 4: Import (purple, dim) -->
+  <g>
+    <rect x="90" y="450" width="220" height="60" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" stroke-dasharray="3 3" opacity="0.7" />
+    <text x="200" y="476" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Legacy CSV / JSON import</text>
+    <text x="200" y="494" text-anchor="middle" fill="#6272a4" font-size="11">source = IMPORT (lowest rank)</text>
+  </g>
+
+  <!-- Resolver -->
+  <g>
+    <rect x="420" y="220" width="200" height="200" rx="14" fill="#44475a" stroke="#bd93f9" stroke-width="2" />
+    <text x="520" y="248" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="700">Source-priority resolver</text>
+    <text x="520" y="270" text-anchor="middle" fill="#6272a4" font-size="11">src/lib/validations/source-priority.ts</text>
+
+    <text x="520" y="298" text-anchor="middle" fill="#bd93f9" font-size="11" font-weight="600">Cumulative metrics</text>
+    <text x="520" y="316" text-anchor="middle" fill="#f8f8f2" font-size="11">APPLE_HEALTH ≻ WITHINGS</text>
+    <text x="520" y="332" text-anchor="middle" fill="#f8f8f2" font-size="11">≻ MANUAL ≻ IMPORT</text>
+
+    <text x="520" y="360" text-anchor="middle" fill="#bd93f9" font-size="11" font-weight="600">Point measurements</text>
+    <text x="520" y="378" text-anchor="middle" fill="#f8f8f2" font-size="11">WITHINGS ≻ APPLE_HEALTH</text>
+    <text x="520" y="394" text-anchor="middle" fill="#f8f8f2" font-size="11">≻ MANUAL ≻ IMPORT</text>
+  </g>
+
+  <!-- Override box -->
+  <g>
+    <rect x="420" y="450" width="200" height="80" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" stroke-dasharray="3 3" />
+    <text x="520" y="476" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Per-user override</text>
+    <text x="520" y="494" text-anchor="middle" fill="#bd93f9" font-size="11">User.sourcePriorityJson</text>
+    <text x="520" y="510" text-anchor="middle" fill="#6272a4" font-size="11">/settings/thresholds → Sources</text>
+  </g>
+
+  <!-- Output swimlane: kept -->
+  <g>
+    <rect x="700" y="150" width="450" height="160" rx="14" fill="#21222c" stroke="#50fa7b" stroke-width="1.5" />
+    <text x="925" y="174" text-anchor="middle" fill="#50fa7b" font-size="13" font-weight="700">Kept — counted in aggregation</text>
+
+    <rect x="720" y="190" width="200" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="820" y="210" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">Steps → Apple Health</text>
+    <text x="820" y="226" text-anchor="middle" fill="#bd93f9" font-size="11">10 432 (cumulative winner)</text>
+
+    <rect x="940" y="190" width="200" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="1040" y="210" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">Weight → Withings</text>
+    <text x="1040" y="226" text-anchor="middle" fill="#bd93f9" font-size="11">75.8 kg (point winner)</text>
+
+    <rect x="720" y="250" width="200" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="820" y="270" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">BP → Withings</text>
+    <text x="820" y="286" text-anchor="middle" fill="#bd93f9" font-size="11">134/82 mmHg (point winner)</text>
+  </g>
+
+  <!-- Output swimlane: dropped -->
+  <g>
+    <rect x="700" y="340" width="450" height="190" rx="14" fill="#21222c" stroke="#ff5555" stroke-width="1.5" stroke-dasharray="4 4" />
+    <text x="925" y="364" text-anchor="middle" fill="#ff5555" font-size="13" font-weight="700">Dropped from aggregation — audit trail kept</text>
+
+    <rect x="720" y="380" width="200" height="40" rx="8" fill="#44475a" stroke="#ff5555" stroke-width="1" opacity="0.85" />
+    <text x="820" y="404" text-anchor="middle" fill="#f8f8f2" font-size="11">9 870 steps (Withings)</text>
+
+    <rect x="940" y="380" width="200" height="40" rx="8" fill="#44475a" stroke="#ff5555" stroke-width="1" opacity="0.85" />
+    <text x="1040" y="404" text-anchor="middle" fill="#f8f8f2" font-size="11">76 kg (Apple Health)</text>
+
+    <rect x="720" y="430" width="200" height="40" rx="8" fill="#44475a" stroke="#ff5555" stroke-width="1" opacity="0.85" />
+    <text x="820" y="454" text-anchor="middle" fill="#f8f8f2" font-size="11">132/81 mmHg (Apple Health)</text>
+
+    <rect x="940" y="430" width="200" height="40" rx="8" fill="#44475a" stroke="#ff5555" stroke-width="1" opacity="0.85" />
+    <text x="1040" y="454" text-anchor="middle" fill="#f8f8f2" font-size="11">76 kg (Manual)</text>
+
+    <text x="925" y="500" text-anchor="middle" fill="#6272a4" font-size="11">All rows visible in /measurements list. None feed dashboard, insights, or Coach for the conflict day.</text>
+  </g>
+
+  <!-- Arrows from sources to resolver -->
+  <g stroke="#8be9fd" stroke-width="1.5" fill="none" marker-end="url(#a4-c)"><path d="M310 190 C 370 190, 380 280, 420 280" /></g>
+  <g stroke="#ffb86c" stroke-width="1.5" fill="none" marker-end="url(#a4-o)"><path d="M310 290 L 420 310" /></g>
+  <g stroke="#ff79c6" stroke-width="1.5" fill="none" marker-end="url(#a4-p)"><path d="M310 390 C 370 390, 380 350, 420 350" /></g>
+  <g stroke="#bd93f9" stroke-width="1.5" fill="none" marker-end="url(#a4-pu)" opacity="0.7"><path d="M310 480 C 370 480, 380 400, 420 400" /></g>
+
+  <!-- Arrows from resolver to swimlanes -->
+  <g stroke="#50fa7b" stroke-width="1.5" fill="none" marker-end="url(#a4-g)"><path d="M620 270 C 660 240, 670 220, 700 220" /></g>
+  <g stroke="#ff5555" stroke-width="1.5" fill="none" marker-end="url(#a4-r)"><path d="M620 380 C 660 410, 670 420, 700 420" /></g>
+
+  <defs>
+    <marker id="a4-c" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#8be9fd" /></marker>
+    <marker id="a4-o" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ffb86c" /></marker>
+    <marker id="a4-p" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff79c6" /></marker>
+    <marker id="a4-pu" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bd93f9" /></marker>
+    <marker id="a4-g" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#50fa7b" /></marker>
+    <marker id="a4-r" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff5555" /></marker>
+  </defs>
+</svg>

docs/diagrams/05-security-model.svg

@@ -0,0 +1,119 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
+  <title id="title">HealthLog security model</title>
+  <desc id="desc">Three concentric layers: an outer auth perimeter (passkey-first WebAuthn, password fallback with Argon2id), a session perimeter (HttpOnly SameSite=Strict cookie, Postgres-backed sessions with sliding expiry), and the encrypted core (AES-256-GCM with versioned keys for secrets at rest). Side rails cover the rate limiter, audit log, HMAC API tokens, CSP/HSTS headers and SSRF-guarded outbound test endpoints.</desc>
+
+  <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
+
+  <text x="600" y="40" fill="#f8f8f2" font-size="22" font-weight="700" text-anchor="middle">Security model</text>
+  <text x="600" y="64" fill="#6272a4" font-size="13" text-anchor="middle">The path a request takes through the auth, session and encryption layers.</text>
+
+  <!-- Outer auth layer -->
+  <g>
+    <rect x="240" y="100" width="720" height="440" rx="20" fill="none" stroke="#8be9fd" stroke-width="2" />
+    <text x="270" y="124" fill="#8be9fd" font-size="13" font-weight="700">Layer 1 — Auth perimeter (WebAuthn first)</text>
+  </g>
+  <!-- Session layer -->
+  <g>
+    <rect x="320" y="160" width="560" height="320" rx="18" fill="none" stroke="#ffb86c" stroke-width="2" />
+    <text x="350" y="184" fill="#ffb86c" font-size="13" font-weight="700">Layer 2 — Session perimeter (server-side sessions)</text>
+  </g>
+  <!-- Encryption core -->
+  <g>
+    <rect x="420" y="220" width="360" height="220" rx="16" fill="none" stroke="#50fa7b" stroke-width="2" />
+    <text x="450" y="244" fill="#50fa7b" font-size="13" font-weight="700">Layer 3 — Encrypted core (AES-256-GCM)</text>
+
+    <rect x="450" y="265" width="300" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="600" y="285" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">Secrets at rest</text>
+    <text x="600" y="302" text-anchor="middle" fill="#bd93f9" font-size="11">Withings tokens · provider keys · VAPID · Codex</text>
+
+    <rect x="450" y="325" width="140" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="520" y="345" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">Versioned keys</text>
+    <text x="520" y="362" text-anchor="middle" fill="#bd93f9" font-size="11">ENCRYPTION_KEYS</text>
+
+    <rect x="610" y="325" width="140" height="50" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="680" y="345" text-anchor="middle" fill="#f8f8f2" font-size="12" font-weight="600">Online rotation</text>
+    <text x="680" y="362" text-anchor="middle" fill="#bd93f9" font-size="11">rotate-encryption-key</text>
+
+    <rect x="450" y="385" width="300" height="40" rx="8" fill="#44475a" stroke="#50fa7b" stroke-width="1" />
+    <text x="600" y="409" text-anchor="middle" fill="#bd93f9" font-size="11">Bearer tokens stored as HMAC-SHA256 digests</text>
+  </g>
+
+  <!-- Auth nodes (cyan) -->
+  <g>
+    <rect x="260" y="200" width="180" height="60" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="350" y="224" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Passkey (WebAuthn)</text>
+    <text x="350" y="244" text-anchor="middle" fill="#bd93f9" font-size="11">SimpleWebAuthn v13</text>
+
+    <rect x="260" y="280" width="180" height="60" rx="10" fill="#44475a" stroke="#8be9fd" stroke-width="1.5" />
+    <text x="350" y="304" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Password fallback</text>
+    <text x="350" y="324" text-anchor="middle" fill="#bd93f9" font-size="11">Argon2id + zxcvbn</text>
+  </g>
+
+  <!-- Session nodes (orange) -->
+  <g>
+    <rect x="340" y="380" width="220" height="60" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="450" y="404" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">HttpOnly · SameSite=Strict</text>
+    <text x="450" y="424" text-anchor="middle" fill="#bd93f9" font-size="11">cookie · 30d sliding expiry</text>
+
+    <rect x="640" y="380" width="220" height="60" rx="10" fill="#44475a" stroke="#ffb86c" stroke-width="1.5" />
+    <text x="750" y="404" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Postgres sessions</text>
+    <text x="750" y="424" text-anchor="middle" fill="#bd93f9" font-size="11">requireAuth · requireAdmin</text>
+  </g>
+
+  <!-- Side rails -->
+  <g>
+    <rect x="40" y="160" width="180" height="60" rx="10" fill="#44475a" stroke="#ff5555" stroke-width="1.5" />
+    <text x="130" y="184" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Rate limiter</text>
+    <text x="130" y="204" text-anchor="middle" fill="#bd93f9" font-size="11">sliding window · per IP+user</text>
+
+    <rect x="40" y="240" width="180" height="60" rx="10" fill="#44475a" stroke="#ff5555" stroke-width="1.5" />
+    <text x="130" y="264" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Audit log</text>
+    <text x="130" y="284" text-anchor="middle" fill="#bd93f9" font-size="11">every sensitive op + IP</text>
+
+    <rect x="40" y="320" width="180" height="60" rx="10" fill="#44475a" stroke="#ff5555" stroke-width="1.5" />
+    <text x="130" y="344" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">CSP + HSTS</text>
+    <text x="130" y="364" text-anchor="middle" fill="#bd93f9" font-size="11">nonce CSP · X-Frame-Options</text>
+
+    <rect x="40" y="400" width="180" height="60" rx="10" fill="#44475a" stroke="#ff5555" stroke-width="1.5" />
+    <text x="130" y="424" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">SSRF guard</text>
+    <text x="130" y="444" text-anchor="middle" fill="#bd93f9" font-size="11">outbound test endpoints</text>
+
+    <rect x="980" y="160" width="180" height="60" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1070" y="184" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">API tokens</text>
+    <text x="1070" y="204" text-anchor="middle" fill="#bd93f9" font-size="11">hlk_* Bearer · HMAC stored</text>
+
+    <rect x="980" y="240" width="180" height="60" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1070" y="264" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Refresh tokens</text>
+    <text x="1070" y="284" text-anchor="middle" fill="#bd93f9" font-size="11">24h access · rotated refresh</text>
+
+    <rect x="980" y="320" width="180" height="60" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1070" y="344" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Off-host backup</text>
+    <text x="1070" y="364" text-anchor="middle" fill="#bd93f9" font-size="11">AES-GCM · S3-compatible</text>
+
+    <rect x="980" y="400" width="180" height="60" rx="10" fill="#44475a" stroke="#bd93f9" stroke-width="1.5" />
+    <text x="1070" y="424" text-anchor="middle" fill="#f8f8f2" font-size="13" font-weight="600">Per-user scope</text>
+    <text x="1070" y="444" text-anchor="middle" fill="#bd93f9" font-size="11">no cross-account reads</text>
+  </g>
+
+  <!-- Arrows: side rails into perimeters -->
+  <g stroke="#ff5555" stroke-width="1.2" stroke-dasharray="3 3" fill="none" marker-end="url(#a5-r)">
+    <path d="M220 190 L 260 220" />
+    <path d="M220 270 L 320 320" />
+    <path d="M220 350 L 320 350" />
+    <path d="M220 430 L 320 410" />
+  </g>
+  <g stroke="#bd93f9" stroke-width="1.2" stroke-dasharray="3 3" fill="none" marker-end="url(#a5-pu)">
+    <path d="M980 190 L 880 410" />
+    <path d="M980 270 L 880 410" />
+    <path d="M980 350 L 780 280" />
+    <path d="M980 430 L 780 410" />
+  </g>
+
+  <!-- Footnote -->
+  <text x="600" y="585" fill="#6272a4" font-size="11" text-anchor="middle">No data leaves the host unless an integration explicitly asks for it. Bearer tokens never elevate to admin — admin actions require a cookie session.</text>
+
+  <defs>
+    <marker id="a5-r" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#ff5555" /></marker>
+    <marker id="a5-pu" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#bd93f9" /></marker>
+  </defs>
+</svg>

docs/diagrams/README.md

@@ -0,0 +1,27 @@
+# Diagrams
+
+Five SVG diagrams that anchor the architecture story. Hand-drawn-style,
+Dracula palette, no external dependencies. Embed in README and doc-site
+pages as `<img>` tags. Mirrored into `healthlog-docs/src/assets/diagrams/`
+and `healthlog-landing/public/diagrams/` so each surface ships its own
+copy.
+
+| File | Story it tells |
+| ---- | -------------- |
+| `01-data-flow.svg` | Sources (Withings, Apple Health export.zip, iPhone HealthKit, manual, moodLog) → ingest endpoints → Measurement + MeasurementRollup → reads (rollup probe / live SQL fallback / cache) → surfaces (dashboard, insights, Coach, doctor PDF). |
+| `02-coach-pipeline.svg` | User question → snapshot builder → prompt assembler → provider chain (ChatGPT OAuth / OpenAI / Anthropic / local / admin-shared) → response parser → cited reply with mini-charts. |
+| `03-self-hosting-topology.svg` | Internet → reverse proxy (TLS) → Next.js app (port 3000) ↔ pg-boss worker ↔ Postgres 16, plus GHCR image pull, optional Coolify autodeploy, optional S3 off-host backup. |
+| `04-source-priority.svg` | Three sources for the same metric on the same day → resolver picks one canonical row per (cumulative vs point) ladder. Losing rows stay in the audit trail. |
+| `05-security-model.svg` | Three concentric layers — auth perimeter (passkey + password fallback), session perimeter (HttpOnly cookie + Postgres sessions), encrypted core (AES-256-GCM versioned keys). Side rails: rate limiter, audit log, HMAC tokens, CSP/HSTS, SSRF guard. |
+
+## Editing
+
+Open in any text editor. Each file is hand-authored SVG ≤ 12 KB; the
+viewport, the `defs` block of arrow markers, and the labelled groups are
+all readable inline. Keep the Dracula palette (`#282a36` background,
+`#f8f8f2` text, accents `#8be9fd / #ffb86c / #50fa7b / #bd93f9 /
+#ff79c6 / #ff5555`) and the `viewBox="0 0 1200 620"` constraint so the
+diagrams stay consistent across the three sites.
+
+After editing, copy the file to the sister repos so all three surfaces
+ship the updated version.

docs/doctor-report.md

@@ -0,0 +1,76 @@
+# Doctor Report
+
+The doctor report is a printable PDF summary of a user's tracked vitals,
+medication compliance, glucose context, and mood over a configurable window
+(default 90 days, max 365). It is intended as discussion material for a
+doctor's appointment, **not** a medical diagnosis.
+
+## Two endpoints
+
+The same aggregation logic backs both endpoints — `collectDoctorReportData`
+in `src/lib/doctor-report-data.ts` is the single source of truth — so the
+JSON payload and the server-rendered PDF are guaranteed to be in sync.
+
+### `POST /api/doctor-report` — JSON payload
+
+Returns the aggregated `DoctorReportData` envelope. Used by the PWA's
+client-side renderer (`src/lib/doctor-report-pdf.ts`, jsPDF + autotable).
+Best on desktop browsers and on Android, where local generation keeps the
+PDF off the wire and works offline (cached page).
+
+- Auth: session required.
+- Rate-limit: 10/h per user.
+- Body: `{ days?: number }` (default 90).
+- Response: `200 application/json` with envelope `{ data, error: null }`.
+- Audit action: `doctor-report.generate`.
+
+### `POST /api/doctor-report/pdf` — server-rendered PDF
+
+Returns the ready-to-download PDF bytes. Used primarily on iOS/Safari, where
+the client-side jsPDF download UX is unreliable (Safari sometimes opens the
+PDF in a new tab without preserving the filename or fails the blob save).
+
+- Auth: session required (`401` otherwise).
+- Rate-limit: 10/h per user, shared with the JSON endpoint (`429` on excess).
+- Body: `{ days?: number; locale?: "de" | "en" }`. Body is optional — empty
+  bodies are accepted.
+- Locale resolution: explicit `body.locale` wins, then the
+  `Accept-Language` header (`de*` → `de`, anything else → `en`), then the
+  hard fallback `de`.
+- Response: `200 application/pdf` with
+  `Content-Disposition: attachment; filename="healthlog-report-YYYY-MM-DD.pdf"`
+  and `Cache-Control: no-store`. Body is the raw PDF bytes.
+- Errors: JSON envelope `{ data: null, error: "..." }` for `401` and `429`;
+  `500` if rendering fails.
+- Audit action: `doctor-report.pdf.generate`.
+
+## Wellness summary (derived scores)
+
+Since v1.10.0 the report carries a **Wellness summary** section below the
+clinical content, holding the server-derived wellness scores (Recovery,
+Stress, Strain) and the other derived metrics where present. It is kept
+deliberately separate from the clinical vitals table:
+
+- Each entry is labelled **descriptive, not a clinical assessment**, and the
+  scores never enter the vitals table or the clinical aggregations.
+- The Stress score is shown as an HRV-derived proxy, not a sensor-measured
+  stress value.
+- In the FHIR export the same scores are emitted as `survey`-category
+  `Observation`s (text-only `code`, no fabricated LOINC) with a per-Observation
+  non-clinical note — so a downstream system never mistakes them for a vital
+  sign or a diagnosis.
+
+Each derived metric states its inputs, method, and the cited standard it is
+grounded in (the same provenance the in-app explainer shows).
+
+## Implementation notes
+
+- `src/lib/doctor-report-pdf-core.ts` contains the isomorphic renderer.
+  jsPDF runs unchanged in Node — `doc.output("arraybuffer")` returns a valid
+  `%PDF-` byte stream in both environments, so we deliberately avoid headless
+  Chromium (Puppeteer/Playwright) to keep the runtime dependency surface low.
+- `src/lib/doctor-report-pdf.ts` is a thin client façade that returns the
+  raw `jsPDF` instance so the existing settings-page download flow (which
+  calls `doc.save(...)`) keeps working unchanged.
+- Server-side translations come from `messages/{de,en}.json` via
+  `getServerTranslator()` (`src/lib/i18n/server-translator.ts`).

docs/integrations/ai-providers.md

@@ -0,0 +1,245 @@
+# AI providers
+
+HealthLog's Coach, daily briefing, weekly report, and per-metric
+insights all run through a multi-provider AI client. Pick whichever
+provider you prefer — there is no lock-in. The provider is resolved
+per-user via the fallback chain in `src/lib/ai/provider.ts` and
+`src/lib/ai/provider-chain.ts`, so a user with a Claude key and an
+Ollama endpoint can fall back from one to the other automatically.
+
+## Provider matrix
+
+| Provider | Key acquisition | Default model | Endpoint | Privacy stance |
+| -------- | ---------------- | ------------- | -------- | -------------- |
+| `OPENAI` | <https://platform.openai.com/api-keys> | `gpt-4o` | `https://api.openai.com/v1` | Measurement context sent to OpenAI |
+| `ANTHROPIC` | <https://console.anthropic.com/settings/keys> | `claude-sonnet-4-6` | Anthropic SDK default | Measurement context sent to Anthropic |
+| `LOCAL` | None (your endpoint) | `local-model` | OpenAI-compatible URL you control | Stays on your network |
+| `CHATGPT_OAUTH` | Sign in with your ChatGPT account | Codex-routed | `chatgpt.com/backend-api/codex/responses` | Routed via your ChatGPT subscription |
+
+The four spellings above are the canonical `User.aiProvider` enum
+values. Anything else falls through to the admin-shared OpenAI key
+(if configured) or the `NoProvider` stub that surfaces "No AI
+provider configured" to the UI.
+
+## BYOK vs admin-shared
+
+HealthLog supports two key-provisioning modes that coexist:
+
+- **BYOK (Bring Your Own Key)** — each user pastes their personal
+  API key into `/settings/ai`. The key is AES-256-GCM-encrypted at
+  rest and only decrypted in-process when the provider client
+  initialises. Cost falls to the user; no shared budget.
+- **Admin-shared** — the admin panel accepts a single OpenAI key in
+  `AppSettings.adminAiKeyEncrypted`. Users who have not configured
+  their own key fall back to the admin key. This is the last entry
+  in the default provider chain so it acts as a safety net rather
+  than the default route.
+
+Single-user instances usually pick one mode and stop there.
+Multi-user instances tend to run BYOK with the admin-shared key as a
+fallback for users who skip the setup.
+
+## The fallback chain
+
+`User.aiProviderChain` is a JSON array of providers tried in priority
+order. The default is encoded in
+`src/lib/ai/provider-chain.ts:60-66`:
+
+1. `codex` — ChatGPT OAuth (covered by your ChatGPT Plus / Pro
+   subscription; no per-token cost on top).
+2. `openai` — user's own OpenAI API key.
+3. `anthropic` — user's own Anthropic API key.
+4. `local` — self-hosted Ollama / LM Studio / vLLM endpoint.
+5. `admin-openai` — operator's shared key (last-ditch).
+
+Entries the user has no credential for are silently skipped. The
+runner walks the surviving entries in order; the first to return a
+non-error completion wins. A 422 fires only when every entry in the
+resolved chain returned an error.
+
+Edit the order in `/settings/ai`. Disable an entry without removing
+it by toggling its switch — a malformed chain on disk falls back to
+the default rather than 500-ing.
+
+## OpenAI setup
+
+1. Sign in at <https://platform.openai.com/api-keys>.
+2. **Create new secret key.** Scope: "Restricted → Model capabilities
+   → Write" is sufficient for HealthLog's use of the Responses /
+   Chat Completions APIs.
+3. Copy the `sk-…` key.
+4. In HealthLog, open `/settings/ai`. Set provider to **OpenAI**,
+   paste the key, optionally override the model.
+
+The default model is `gpt-4o` (`src/lib/ai/provider.ts:80`) — a
+full-size model that keeps the headline Insights assessments grounded
+and well-reasoned out of the box. Override to a lighter model such as
+`gpt-4o-mini` if you want to trade some reasoning headroom for a lower
+per-token cost.
+
+**Cost expectation.** A daily briefing for an active account runs at
+roughly 4–8k input tokens + ~1k output. At gpt-4o's published rates
+that is a fraction of a US cent per briefing; a heavy user generating
+multiple Coach turns plus a weekly report typically spends a few
+dollars per month. A lighter override drops this further.
+
+## Anthropic setup
+
+1. Sign in at <https://console.anthropic.com/settings/keys>.
+2. **Create Key.** A workspace-scoped key is recommended over an
+   organisation-scoped key.
+3. Copy the `sk-ant-…` key.
+4. In HealthLog, open `/settings/ai`. Set provider to **Anthropic**,
+   paste the key, optionally override the model.
+
+The default model is `claude-sonnet-4-6` (`src/lib/ai/provider.ts`).
+The Anthropic client refuses to forward an Anthropic key to a stale
+`aiBaseUrl` even if one is parked in the shared column — Anthropic
+has no per-tenant base URL the UI exposes; the SDK default is the
+only correct endpoint.
+
+**Cost expectation.** A current Sonnet runs at a higher per-token
+cost than a lightweight OpenAI model but produces noticeably stronger
+reasoning on the more structured Coach prompts. Most BYOK users on
+Claude spend in the low single digits per month.
+
+## Local endpoints (Ollama, LM Studio, vLLM)
+
+Any OpenAI-compatible local endpoint plugs in as the **Local**
+provider. Data stays on your network end-to-end; nothing leaves the
+host running the model.
+
+**Ollama** — `ollama pull qwen2.5:14b-instruct && ollama serve`.
+In `/settings/ai`: provider **Local**, base URL
+`http://localhost:11434/v1` (Ollama exposes the OpenAI-compatible
+shim there), model `qwen2.5:14b-instruct`, leave the API key blank.
+If HealthLog runs in Docker and Ollama runs on the host, swap
+`localhost` for `host.docker.internal` (Mac/Windows) or the host's
+LAN IP (Linux).
+
+**LM Studio** — start the built-in server from the **Local Server**
+tab (usually `http://localhost:1234/v1`) and paste the URL into
+HealthLog the same way.
+
+**vLLM** — production-grade shared inference:
+
+```bash
+vllm serve Qwen/Qwen2.5-14B-Instruct \
+  --host 0.0.0.0 --port 8000 --api-key your-shared-secret
+```
+
+Base URL `http://<vllm-host>:8000/v1`, API key `your-shared-secret`,
+model `Qwen/Qwen2.5-14B-Instruct`. The local-client encrypts the
+API key at rest like every other provider credential.
+
+**SSRF guard.** Local endpoints route through the same validation
+as every other outbound URL HealthLog hits. The guard rejects
+private-IP-range targets by default — set
+`ALLOW_LOCAL_AI_PRIVATE_HOSTS=true` in the container environment to
+allow `localhost`, RFC1918, and link-local destinations
+(`src/lib/ai/provider.ts:456-462`). Leave it unset on public-facing
+instances unless you specifically run an internal endpoint.
+
+**Model sizing.** Roughly: 7-8B for 8 GB GPU / Apple Silicon base
+(briefings fine, deeper Coach reasoning gets terse), 14-24B for
+16-24 GB GPU / M-series Pro/Max (sweet spot for BYOK-style usage),
+70B+ for 48 GB+ / multi-GPU (comparable to mid-tier hosted models).
+
+## ChatGPT OAuth (Codex)
+
+The `CHATGPT_OAUTH` provider routes generations via the
+`chatgpt.com/backend-api/codex/responses` endpoint that the official
+Codex CLI uses. Users authenticate with their existing ChatGPT Plus
+or Pro subscription via device-code OAuth — no API key, no
+per-token billing on top of the subscription.
+
+UI setup:
+
+1. In `/settings/ai`, set provider to **ChatGPT OAuth**.
+2. Click **Connect ChatGPT.** HealthLog calls
+   `POST /api/auth/codex/device-start` to receive a user code and a
+   verification URL.
+3. The UI displays the verification URL and the short user code.
+   Open the URL in any browser signed in to your ChatGPT account
+   and enter the user code.
+4. HealthLog polls `POST /api/auth/codex/device-poll` until ChatGPT
+   confirms the grant. Access and refresh tokens land in
+   `User.codexAccessTokenEncrypted` / `codexRefreshTokenEncrypted`,
+   AES-256-GCM-encrypted at rest. The connection status flips to
+   `connected`.
+5. Token refresh runs automatically; the client triggers a refresh
+   on 401 and persists the new tokens transparently
+   (`src/lib/ai/provider.ts:122-217`).
+
+Disconnect cleanly from `/settings/ai` — `POST /api/auth/codex/disconnect`
+clears the encrypted token columns. The wire-level protocol is
+documented in `docs/codex-protocol-spec.md` for anyone who wants to
+audit the request shape; users who just want the integration to
+work do not need to read it.
+
+## Privacy stance
+
+- **OpenAI** and **Anthropic** see the prompt + structured snapshot
+  HealthLog assembles per generation (recent metrics, target ranges,
+  Coach conversation history). No raw row exports leave the app, but
+  values themselves are visible to the provider for the request's
+  duration. Provider retention policy applies.
+- **LOCAL** keeps everything on your network. Snapshots reach only
+  the endpoint you configured. With Ollama on the same host as
+  HealthLog, nothing leaves the host at all.
+- **CHATGPT_OAUTH** routes via OpenAI's Codex endpoint. Same caveat
+  as OpenAI; the difference is the billing axis (ChatGPT
+  subscription instead of API tokens).
+
+The Coach drawer surfaces a "Local" badge when generation resolves
+to the local provider, so users who pinned a local endpoint can see
+at a glance that their context stayed on the host.
+
+## Caching contract
+
+Two caches sit in front of every provider call so generation budgets
+stay predictable:
+
+1. **24-hour insight cache.** A successful generation is keyed by
+   the upstream measurement snapshot's hash and the prompt version.
+   The next read within 24 hours of the same snapshot returns the
+   cached envelope instead of re-billing the provider. Force-regen
+   on the UI bypasses the cache.
+2. **Snapshot LRU.** The Coach snapshot builder caches per
+   `(userId, scope)` for 60 seconds so a rapid-fire conversation
+   reuses the same upstream context without re-querying Postgres.
+   See `src/lib/ai/coach/snapshot.ts`.
+
+`INSIGHTS_RATE_LIMIT_PER_HOUR` (default `10`) bounds the number of
+`POST /api/insights/generate` calls a single user can fire per hour.
+Lower it when running on a tight budget — the 24h cache already
+short-circuits read traffic; only force-regens and cache-misses cost
+tokens.
+
+## Connection test
+
+`POST /api/ai/test` runs a one-shot probe against the resolved
+provider and returns the latency in milliseconds plus the model the
+provider routed to. The Settings UI surfaces a **Test connection**
+button next to each provider section that fires this endpoint. A
+failed probe surfaces a localisable `errorCode` so the UI renders
+the failure in the user's language rather than the raw upstream
+error.
+
+## Troubleshooting
+
+- **"No AI provider configured."** Either set up at least one BYOK
+  provider in `/settings/ai`, or configure an admin-shared OpenAI
+  key in the admin panel.
+- **Local endpoint rejected as "internal/private host".** Set
+  `ALLOW_LOCAL_AI_PRIVATE_HOSTS=true` in the container environment.
+  Leave it unset on internet-facing instances unless you specifically
+  want to allow private-range targets.
+- **Codex disconnects after a few weeks of inactivity.** ChatGPT
+  refresh tokens lapse after extended idle periods. Reconnect via
+  the **Connect ChatGPT** button — HealthLog re-runs the device-code
+  flow and the new tokens land in the same encrypted columns.
+- **Chain falls through every entry.** Run the per-provider connection
+  test from `/settings/ai` to identify which step is failing. The
+  most common cause is a stale or revoked BYOK key earlier in the
+  chain; remove or disable that entry to skip ahead.

docs/integrations/apple-health.md

@@ -0,0 +1,200 @@
+# Apple Health import
+
+HealthLog accepts a full Apple Health `export.zip` upload and folds
+the contents into the same timeline as every other ingest source.
+The importer is streaming end-to-end — multi-gigabyte exports never
+land in V8 heap — and idempotent on the upload's SHA-256 so
+re-uploading the same archive merges instead of duplicating.
+
+## What you need
+
+- An iPhone with the Apple Health app and at least a few months of
+  history (otherwise there is little to import).
+- A HealthLog account on an instance you can reach from the device
+  or from a workstation. The upload goes over your authenticated
+  browser session — no separate API token to provision.
+- Up to 1.5 GB of upload bandwidth. Apple's largest observed exports
+  sit around 800 MB for a 10-year iCloud-synced account; the parser
+  caps inbound bodies at 1.5 GB
+  (`src/app/api/import/apple-health-export/route.ts:41`).
+
+## 1. Generate `export.zip` on the iPhone
+
+1. Open the **Health** app.
+2. Tap the profile picture in the top-right.
+3. Scroll to the bottom and tap **Export All Health Data**.
+4. iOS spends a few minutes packaging the archive. When it finishes,
+   share-sheet the resulting `export.zip` somewhere you can reach
+   from your HealthLog instance — AirDrop to a workstation, save to
+   iCloud Drive, send via email or any chat app you control.
+
+The archive contains `apple_health_export/export.xml` (the canonical
+record stream) plus a handful of auxiliary files (workout routes,
+clinical records, electrocardiograms). The importer reads
+`export.xml` and ignores the rest.
+
+## 2. Upload to HealthLog
+
+Open the import page from the in-app settings tree. Drop the
+`export.zip` onto the upload control. The browser streams the body
+directly to the server; nothing is buffered into memory on either
+side.
+
+The endpoint is `POST /api/import/apple-health-export`. The handler:
+
+1. Rate-limits to **three uploads per minute per user** to protect
+   against a flood of multi-gigabyte uploads
+   (`src/app/api/import/apple-health-export/route.ts:43-46`).
+2. Enforces the **1.5 GB cap** twice — once cheaply against the
+   declared `Content-Length`, then a second time at the streaming
+   sink so a missing/wrong header cannot bypass it.
+3. Streams the body to a temp file at `/tmp/healthlog-apple-health-import-*`
+   while computing a SHA-256 of the bytes inline.
+4. Looks up any prior `ImportJob` row with the same `userId` +
+   `uploadSha256`. **A re-upload of the same archive short-circuits to
+   the previous job** instead of re-queueing — the response carries
+   `idempotent: true` and the original `jobId`.
+5. Otherwise creates a fresh `ImportJob` row in `queued`, enqueues
+   the `apple-health-import` pg-boss job, and returns the new `jobId`.
+
+The response body is `{ "jobId": "...", "status": "queued" }` with a
+`202 Accepted`.
+
+## 3. Poll the status endpoint
+
+`GET /api/import/apple-health-export/{jobId}/status` returns the
+canonical envelope:
+
+```json
+{
+  "data": {
+    "jobId": "clx123…",
+    "status": "parsing",
+    "startedAt": "2026-05-16T12:34:56.000Z",
+    "completedAt": null,
+    "uploadBytes": 412345678,
+    "exportedAt": "2026-04-30T18:12:00.000Z",
+    "progress": { "records_seen": 124000, "workouts_seen": 230 },
+    "result": null,
+    "failureReason": null
+  },
+  "error": null
+}
+```
+
+The lifecycle is `queued → unpacking → parsing → upserting → done`
+with `failed` as a terminal-error branch
+(`src/app/api/import/apple-health-export/[jobId]/status/route.ts:8-9`).
+The iOS native client polls every two seconds while active and every
+thirty seconds once the job is terminal; the web UI uses the same
+cadence. Authorisation: only the job owner can read it. The admin
+who kicked off an import via the admin variant can also read the row
+they triggered.
+
+## What gets imported
+
+The parser folds four XML element types into the existing HealthLog
+schema (CHANGELOG v1.4.34):
+
+| XML element | Maps to | Notes |
+| ----------- | ------- | ----- |
+| `<Record>` | `Measurement` rows | One row per spot sample. Keyed by `HKMetadataKeyExternalUUID` when present, otherwise a deterministic `sample:<sha256-of-attributes>` fallback so re-imports stay idempotent. |
+| `<Workout>` | `Workout` rows | Activity type + duration + energy + distance. |
+| `<Correlation>` | `Measurement` rows | Compound samples like blood pressure (systolic + diastolic) explode into their per-metric children. |
+| `<ClinicalRecord>` | `Measurement` rows where the type maps | Health-record FHIR snapshots; only the metric-typed fields are ingested. |
+
+The HK quantity types that map to HealthLog metric types live in
+`src/lib/measurements/apple-health-mapping.ts`. Anything outside the
+mapped set (workout routes, ECG voltage traces) is counted in
+`progress.records_skipped` but not stored.
+
+### Cumulative HK type → daily aggregate
+
+Cumulative quantity types — steps, active energy, walking/running
+distance, flights climbed — get **collapsed into one row per
+user-local day** to match the iOS daily-aggregation convention.
+
+- External ID format: `stats:<HKType>:<YYYY-MM-DD>` (e.g.
+  `stats:HKQuantityTypeIdentifierStepCount:2026-05-15`).
+- The day boundary respects the user's timezone preference. The
+  worker defaults to `Europe/Berlin` when no preference is set
+  (`src/lib/jobs/apple-health-import-worker.ts:132-133`).
+- A second import of the same archive re-folds the same days onto
+  the same external IDs — the values update in place rather than
+  duplicating.
+
+### Re-import idempotency
+
+The two-axis idempotency story:
+
+1. **File-level** — re-uploading the same `export.zip` (same SHA-256
+   of bytes) short-circuits to the previous job before the parser
+   even starts.
+2. **Record-level** — when an older `export.zip` is re-exported from
+   iOS (same history, slightly newer device timestamps), every
+   record's external ID stays stable. The upsert path matches on
+   `(userId, externalId)` and updates instead of inserting.
+
+Practically: a user who exports monthly and re-imports each archive
+sees fresh data merged in without duplicates. The job result line
+in the status response reports `recordsInserted` and
+`recordsUpdated` separately.
+
+## Admin variant — import on behalf of another user
+
+`POST /api/admin/import-apple-health-export` is the cookie-only admin
+variant (Bearer tokens never elevate to admin). The multipart body
+adds a `userId` text field naming the target user; everything else
+is identical to the user-facing flow.
+
+The `ImportJob` row carries `triggeredByAdminId = admin.id` so the
+status endpoint admits both the target user and the triggering
+admin. Idempotency is scoped by target user — an admin re-uploading
+the same archive for the same user resolves to the previous job.
+
+Typical use: migrating a friend's history into their HealthLog
+account when they cannot run the import themselves, or backfilling
+a household member's data after the admin received the `export.zip`
+out of band.
+
+## Source-priority interaction
+
+HealthLog's source ladder is **APPLE_HEALTH ≻ WITHINGS ≻ MANUAL ≻
+IMPORT** for cumulative metrics (steps, active energy, distance,
+flights, sleep, HRV, resting HR) and **WITHINGS ≻ APPLE_HEALTH ≻
+MANUAL** for point measurements where the Withings device is the
+primary sensor (weight, BP, body fat, body temperature, SpO₂, VO₂
+max). The defaults live in `src/lib/validations/source-priority.ts:205-220`.
+
+Concrete consequences:
+
+- If you already sync steps from a Withings ScanWatch and also import
+  Apple Health, the Apple-Health-aggregated stream wins for the day —
+  iOS HealthKit folds the watch sensor + iPhone motion data into a
+  single canonical stream, so it is the most complete cumulative
+  source. The Withings rows stay in the database as an audit trail
+  but drop out of the per-day aggregation.
+- If you weigh yourself on a Withings scale and also import Apple
+  Health (which received the same reading via the Health Mate iOS
+  app), the Withings row wins for display. Apple Health is
+  second-hand for that metric.
+- Manual entries always rank below either device source. The IMPORT
+  source tag — the lowest rank — is reserved for legacy CSV/JSON
+  imports that pre-date the Apple Health passthrough.
+
+Override per-user via the Sources section of `/settings/thresholds`.
+
+## Failure modes
+
+| Failure | What you see | Recovery |
+| ------- | ------------ | -------- |
+| Archive is missing `apple_health_export/export.xml` | `failureReason: "Archive is missing the apple_health_export/export.xml member"` | Re-export from the iPhone; a partial AirDrop or a renamed archive can lose the canonical entry. |
+| Archive is encrypted | `failureReason: "Encrypted ZIP entries are not supported"` | Apple does not encrypt the export — this means the file was repacked by a third-party tool. Re-export from iOS directly. |
+| Unsupported compression method | `failureReason: "Unsupported ZIP compression method <n> for export.xml"` | Same recovery — re-export from iOS, which always emits method 0 (stored) or method 8 (deflate). |
+| Worker is not running | `503 Background worker is not running` from the kick-off endpoint | The worker process is down. Check `docker compose ps` for the `app-worker` container (or `HEALTHLOG_PROCESS_TYPE=all` mode on the main `app` container) and restart. |
+| Rate-limited | `429 Too many import uploads, try again later` | Wait sixty seconds; the limit is three uploads per minute per user. |
+
+The wide-event log line `import.apple-health.kickoff` (or
+`import.apple-health.kickoff.denied` on failure) captures every
+attempt with the upload size, SHA-256, and the resolved `ImportJob`
+id for debugging.

docs/integrations/google-health.md

@@ -0,0 +1,79 @@
+# Google Health integration (Fitbit & Pixel)
+
+> **Beta.** Field mapping is still being verified against live Google Health
+> accounts, so some values may be missing or change in a future update.
+
+HealthLog reads Fitbit and Pixel Watch data through the **Google Health API**.
+The OAuth app is therefore a **Google Cloud** OAuth client — not a Fitbit
+developer-console app. Like WHOOP, credentials are brought per user: each user
+registers their own Google Cloud OAuth client and pastes the client id/secret
+into Settings. The internal integration key is `fitbit`.
+
+## 1. Create a Google Cloud OAuth client
+
+1. In <https://console.cloud.google.com> create (or pick) a project and, under
+   **APIs & Services**, enable the **Google Health API**.
+2. Configure the OAuth consent screen for the project.
+3. Under **APIs & Services → Credentials**, create an **OAuth 2.0 Client ID** of
+   type **Web application**.
+4. **Authorized redirect URI:**
+   `https://your-instance.example.com/api/fitbit/callback`
+5. Save. Google issues a **Client ID** and **Client Secret** — keep the secret
+   out of any chat log.
+
+## 2. Scopes
+
+HealthLog requests exactly these read-only scopes:
+
+```
+https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
+https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
+https://www.googleapis.com/auth/googlehealth.sleep.readonly
+https://www.googleapis.com/auth/googlehealth.profile.readonly
+```
+
+Location and intraday scopes are deliberately omitted to keep the
+Restricted-scope review surface minimal. The authorize request sends
+`access_type=offline` + `prompt=consent` — Google's requirement to issue a
+refresh token (the equivalent of WHOOP's `offline` scope).
+
+## 3. Wire the credentials in Settings → Integrations
+
+Credentials are stored per user, not in `.env`. Sign in as the target user, open
+**Settings → Integrations → Google Health**, and paste the client ID and secret.
+They are encrypted AES-256-GCM at rest.
+
+## 4. Connect
+
+Click **Connect with Google Health**. HealthLog redirects to Google's OAuth
+consent screen, exchanges the returned code for an access + refresh token, stores
+them encrypted, and runs an initial sync. There is **no webhook** — Google Health
+syncs on the safety-net cron pull.
+
+## Redirect URI is validated strictly
+
+The resolved `redirect_uri` is asserted at connect time to be absolute, `https`
+(or `http` on localhost), to target exactly `/api/fitbit/callback`, and — when
+`FITBIT_REDIRECT_URI` is set alongside `NEXT_PUBLIC_APP_URL` — to share its
+origin. A misconfigured value fails closed rather than redirecting elsewhere.
+
+## Optional instance env var
+
+```env
+# Only when the callback origin differs from NEXT_PUBLIC_APP_URL:
+FITBIT_REDIRECT_URI="https://your-instance.example.com/api/fitbit/callback"
+```
+
+The Google Cloud client id/secret are per-user (Settings), not env vars.
+
+## Source overlap
+
+If Google Health and another source (Withings, WHOOP, Apple Health) both supply
+the same vital — resting heart rate, blood oxygen, body temperature or
+respiratory rate — you may see both values until a future update settles on a
+single preferred source.
+
+## Disconnect
+
+The Settings **Disconnect** button revokes the stored tokens and removes the
+connection. Previously synced measurements stay in the database.

docs/integrations/whoop.md

@@ -0,0 +1,91 @@
+# WHOOP integration
+
+HealthLog connects to WHOOP via OAuth2 plus HMAC-signed webhooks for
+near-real-time sync of recovery, strain, sleep, and the underlying
+heart-rate / HRV signals. Unlike Withings, WHOOP credentials are
+brought per user: each user (or the operator on their behalf)
+registers their own WHOOP developer app and pastes the client
+id/secret into Settings.
+
+## Why bring your own keys
+
+WHOOP caps the number of users a single developer app may authorise.
+Per-user BYO-keys sidestep that per-app cap: every user authorises
+against their own WHOOP app, so a shared HealthLog instance never
+runs into one app's user ceiling. It also keeps each user's WHOOP
+grant scoped to credentials they control.
+
+## 1. Register a WHOOP developer app
+
+1. Sign in at <https://developer.whoop.com/> and create a new app.
+2. **Redirect URI:** `https://your-instance.example.com/api/whoop/callback`
+   (matches `WHOOP_REDIRECT_URI`, below). Add one entry per
+   environment you connect from.
+3. Request these scopes (the exact set HealthLog asks for):
+
+   ```
+   offline read:recovery read:sleep read:workout read:cycles read:profile read:body_measurement
+   ```
+
+   `offline` is **mandatory** — without it WHOOP issues no refresh token
+   and the connection dies when the first access token expires (~1 hour).
+   The remaining `read:*` scopes are read-only; request all of them so the
+   user grants once and every sync resource is covered.
+4. Save the app. WHOOP issues a **Client ID** and **Client Secret** —
+   keep the secret out of any chat log; it grants read access to the
+   linked account's full WHOOP history.
+
+## 2. Wire the credentials in Settings → Integrations
+
+WHOOP credentials are stored per user, not in `.env`. Sign in as the
+target user, open **Settings → Integrations → WHOOP**, and paste the
+client ID and secret. They are encrypted AES-256-GCM at rest.
+
+## 3. Connect
+
+Click **Connect WHOOP**. The flow:
+
+1. The Connect button redirects to WHOOP's OAuth authorize endpoint.
+2. The user signs in on WHOOP and grants the requested scopes.
+3. WHOOP redirects back to `/api/whoop/callback` with an auth code.
+4. HealthLog exchanges the code for an access + refresh token, stores
+   them encrypted, registers the webhook, and triggers an initial
+   sync of recent history.
+5. Subsequent syncs run on every webhook delivery plus a safety-net
+   cron pull.
+
+## Optional instance env vars
+
+Two server-level env vars tune the OAuth callback and webhook
+verification. They are optional — the per-user client id/secret in
+Settings drive the connection itself.
+
+```env
+WHOOP_REDIRECT_URI="https://your-instance.example.com/api/whoop/callback"
+WHOOP_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+```
+
+- `WHOOP_REDIRECT_URI` — the OAuth callback URL handed to WHOOP. Must
+  match a redirect URI registered in the WHOOP developer app.
+- `WHOOP_WEBHOOK_SECRET` — used twice: as the **trailing path segment**
+  of the webhook URL you register in the WHOOP console, and as the key
+  HealthLog verifies the WHOOP HMAC body signature against. Set the
+  webhook URL in the WHOOP console to:
+
+  ```
+  https://your-instance.example.com/api/whoop/webhook/<WHOOP_WEBHOOK_SECRET>
+  ```
+
+  WHOOP signs each body (`X-WHOOP-Signature` + `X-WHOOP-Signature-Timestamp`,
+  HMAC-SHA256); the handler rejects deliveries older than five minutes and
+  validates the signature before processing. The body signing key on WHOOP's
+  side must equal `WHOOP_WEBHOOK_SECRET`. Generate a fresh random value and
+  restart the `app` container after setting it. Without a webhook, WHOOP
+  still syncs on the safety-net cron pull — only the near-real-time push is
+  lost.
+
+## Disconnect
+
+The Settings page **Disconnect** button revokes the stored tokens and
+removes the connection. Existing measurements synced from WHOOP stay
+in the database — disconnect does not delete data.

docs/integrations/withings.md

@@ -0,0 +1,195 @@
+# Withings integration
+
+HealthLog connects to Withings via OAuth2 plus a push webhook for
+near-real-time sync. Once linked, every Body+ scale weighing, BPM
+blood-pressure reading, ScanWatch sleep stage, and activity sample
+lands in HealthLog within seconds — no polling, no third-party
+relay.
+
+## What gets synced
+
+The Withings client (`src/lib/withings/client.ts`) maps the following
+metric types into `Measurement` rows tagged `source = WITHINGS`:
+
+| Withings meastype | HealthLog `MeasurementType` |
+| ----------------- | --------------------------- |
+| 1 | `WEIGHT` |
+| 5 | `FAT_FREE_MASS` |
+| 9 | `BLOOD_PRESSURE_DIA` |
+| 10 | `BLOOD_PRESSURE_SYS` |
+| 11 | `PULSE` |
+| 54, 35 | `OXYGEN_SATURATION` (ScanWatch / pulse-ox products) |
+| Plus the body-composition family (fat ratio, muscle mass, bone mass, hydration) and sleep / heart-rate variability via the heart-list endpoint |
+
+Activity data (steps, active energy, distance, floors climbed) lands
+via the `user.activity` OAuth scope shipped in v1.4.25. Sleep stages
+arrive via the sleep series endpoint.
+
+## 1. Register a Withings developer app
+
+1. Sign in at <https://developer.withings.com/> and **create a new
+   public-API application**. The "Public" tier is free and supports
+   the OAuth2 flow HealthLog uses; you do not need the partner tier.
+2. **Callback URL:** `https://your-instance.example.com/api/withings/callback`.
+   Withings allows multiple callbacks per app — add one entry per
+   environment (production, staging, local development against a
+   tunnel).
+3. **Scopes:** request `user.metrics` AND `user.activity`. Both are
+   needed — `user.metrics` covers weight / BP / heart-list / sleep /
+   SpO₂ / body comp / temperature / VO₂ max; `user.activity` is the
+   workout-equivalent stream for steps / energy / distance / floors.
+   See `src/lib/withings/client.ts:42` (`WITHINGS_OAUTH_SCOPE`).
+4. Save the application. Withings will issue a **Client ID** and a
+   **Client Secret** — keep the secret out of any chat log; it grants
+   read access to every linked account's full health history.
+
+## 2. Wire the credentials into HealthLog
+
+Paste the client ID and secret into `.env`:
+
+```env
+WITHINGS_CLIENT_ID="your-client-id"
+WITHINGS_CLIENT_SECRET="your-client-secret"
+WITHINGS_REDIRECT_URI="https://your-instance.example.com/api/withings/callback"
+WITHINGS_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+```
+
+`WITHINGS_WEBHOOK_SECRET` is the path-segment token the webhook
+handler validates against. Generate a fresh random value — anything
+that fits in a URL path segment works, but a 64-character hex string
+keeps it indistinguishable from random. Restart the `app` container
+after saving.
+
+Per-user override is also possible: the Settings UI accepts a
+client-ID/secret pair scoped to one user, useful if you want a
+shared instance where every user brings their own Withings app
+credentials. Server-level env vars cover the default case.
+
+## 3. Set the webhook URL
+
+When HealthLog calls Withings `Notify.subscribe()` for a newly-linked
+account, it hands Withings the callback URL constructed by
+`getWithingsWebhookCallbackUrl()` (`src/lib/withings/sync.ts:38-48`).
+The shape is:
+
+```
+https://your-instance.example.com/api/withings/webhook/<WITHINGS_WEBHOOK_SECRET>
+```
+
+Withings has no facility for adding HTTP headers or signing webhook
+bodies, so the callback URL itself is the only authenticity surface
+a subscriber controls. The v1.4.25 W17a migration moved the secret
+from a query parameter (`?secret=…`, captured by every reverse-proxy
+access log) to a path segment, which keeps it out of the
+`query_string` column most proxies log by default
+(`src/app/api/withings/webhook/[token]/route.ts:13-23`).
+
+You do not need to register the webhook URL anywhere in the
+developer portal — HealthLog subscribes per-user during the OAuth
+callback. The portal only owns the OAuth callback URL.
+
+## 4. Link from the Settings page
+
+With env vars in place and the app restarted, sign in as the target
+user and open `/settings/integrations/withings`. Click **Connect
+Withings**. The flow:
+
+1. The Connect button redirects to Withings' `oauth2/authorize`.
+2. The user signs in on Withings and grants the requested scopes.
+3. Withings redirects back to `/api/withings/callback` with an auth
+   code.
+4. HealthLog exchanges the code for an access + refresh token, stores
+   them AES-256-GCM-encrypted at rest, subscribes the webhook URL,
+   and triggers an initial sync of the past 30 days.
+5. The settings page now shows **Connected** with the timestamp of
+   the last successful sync.
+
+Subsequent syncs run automatically on every webhook delivery plus a
+safety-net cron pull every few hours.
+
+## Source-priority interaction
+
+HealthLog's source ladder ranks **WITHINGS ≻ APPLE_HEALTH ≻ MANUAL**
+for point measurements (weight, BP, pulse, body fat, body
+temperature, SpO₂, VO₂ max) and **APPLE_HEALTH ≻ WITHINGS ≻ MANUAL**
+for cumulative metrics (steps, active energy, distance, flights,
+sleep, HRV, resting HR). The defaults live in
+`src/lib/validations/source-priority.ts:205-220`.
+
+Concrete consequences if you run Withings alongside an Apple Health
+import:
+
+- Weight readings from a Withings scale win for display. Apple
+  Health rows for the same metric (received second-hand from Health
+  Mate) stay in the DB as audit trail but drop out of the active
+  display.
+- Steps from a ScanWatch go through HealthKit's daily aggregation
+  when Apple Health is also linked, so the Apple Health stream wins
+  for the cumulative axis. The Withings rows stay in the DB.
+
+Override per-user via the Sources section of `/settings/thresholds`.
+
+## Troubleshooting
+
+### The Connect button errors out
+
+- **`Withings credentials not configured`** — `WITHINGS_CLIENT_ID`
+  or `WITHINGS_CLIENT_SECRET` is missing from `.env`. Confirm both
+  are set in the container's runtime environment (`docker compose
+  exec app env | grep WITHINGS`).
+- **`Callback URI mismatch`** — the URL HealthLog sends to Withings
+  must match an entry in the developer-portal app's callback list.
+  Add the public URL exactly, including the `https://` scheme and
+  the `/api/withings/callback` path.
+
+### The webhook stops firing
+
+Webhook subscriptions can lapse after a token revoke or a portal-
+side cleanup. Re-subscribe by opening `/settings/integrations/withings`
+and clicking **Disconnect** then **Connect Withings** again — the
+callback exchange re-runs `Notify.subscribe()` with a fresh callback
+URL.
+
+Test the inbound path with a HEAD request from outside the host:
+
+```bash
+curl -I https://your-instance.example.com/api/withings/webhook/<WITHINGS_WEBHOOK_SECRET>
+```
+
+A `200 OK` means the path-segment secret matches. A `401` means the
+env var on the running container does not match the secret embedded
+in the URL Withings was handed at subscribe time. Re-subscribing
+fixes the mismatch by updating the URL Withings holds.
+
+### Sync is stuck on "Reauthorisation required"
+
+Withings revokes refresh tokens on password change, app un-authorise,
+or after extended inactivity. The `WithingsConnection` row flips to
+`error_reauth` status and the scheduled sync no-ops until the user
+re-runs the OAuth flow (`src/lib/withings/sync.ts:155-161`).
+Click **Connect Withings** again from the settings page; the
+callback exchanges fresh tokens and the next sync runs through the
+last 30 days of history to catch up.
+
+### Disconnect cleanly
+
+The Settings page **Disconnect** button:
+
+1. Calls `POST /api/withings/disconnect`.
+2. Server-side: revokes the access token via Withings'
+   `Notify.revoke`, deletes the `WithingsConnection` row, and audits
+   the action.
+3. Existing `Measurement` rows tagged `source = WITHINGS` stay in
+   the database — disconnect does not delete data. Re-linking the
+   same Withings account merges back onto the same metric
+   timeline; the upsert path matches on `(userId, type, measuredAt,
+   source)` so previously-synced rows update in place.
+
+## Admin probe
+
+`POST /api/integrations/withings/test` (admin-only) runs a
+read-only round-trip against the user's stored credentials and
+returns the latency in milliseconds. Use it from the admin panel
+when a user reports stale data — a green test plus a stale
+`lastSyncedAt` usually means the webhook URL Withings holds is out
+of sync (re-subscribe per the steps above).

docs/migration/v1.3-to-v1.4.md

@@ -0,0 +1,232 @@
+# Migrating from HealthLog 1.3 to 1.4
+
+v1.4.0 is **drop-in for self-hosters running the GHCR image** — the
+two new migrations (`0025_refresh_tokens`, `0025_user_locale_drift_fix`)
+both apply on container start via `prisma migrate deploy`, and every
+new env var in §Environment variables below has a safe default. This
+guide documents what changes for operators and integrators, in case
+you're extending the API or scaling the deployment.
+
+## TL;DR
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+That's it. The migrations are forward-compatible (`IF NOT EXISTS`
+guards), no env vars are _required_ to be added, and no API contract
+changes shape or status code.
+
+## Database
+
+- **`0025_refresh_tokens`** _(new)_ — adds the `refresh_tokens` table
+  for the native-client 24h access-token / refresh-token rotation
+  flow. Browser cookie sessions don't use it.
+- **`0025_user_locale_drift_fix`** _(new)_ — `ADD COLUMN IF NOT
+EXISTS users.locale TEXT` to backfill an environment that was kept
+  in sync via `prisma db push` rather than `migrate deploy`. No-op
+  on installations that were already current.
+- Both migrations are idempotent. A rollback to 1.3.3 keeps the
+  schema usable; the dropped tables/columns are simply unused.
+
+## Environment variables
+
+### About surface
+
+- **`NEXT_PUBLIC_APP_BUILD_SHA`** _(optional, new)_ — short Git SHA
+  exposed through `/api/version`, rendered on Settings → About.
+- **`NEXT_PUBLIC_APP_BUILT_AT`** _(optional, new)_ — ISO-8601 build
+  timestamp.
+
+Both are optional; without them, the About surface renders
+"development" wording.
+
+### Worker / web split
+
+- **`HEALTHLOG_PROCESS_TYPE`** _(optional, default `all`)_ — set to
+  `web` to disable the pg-boss worker (jobs queue but don't run), or
+  `worker` to refuse all HTTP traffic with `503 + X-HealthLog-Process-Type:
+worker`. Default `all` keeps the single-container behaviour.
+  Only relevant if you're scaling HTTP and the worker independently.
+
+### Encryption-key versioning
+
+- **`ENCRYPTION_KEYS`** _(optional, new)_ — JSON object mapping
+  versioned key IDs to 64-char hex keys, e.g. `{"v1": "...", "v2":
+"..."}`. When present, ciphertexts are written with the
+  `<keyId>.<base64>` format and decrypted by looking up the key ID.
+  Existing 1.3-format ciphertexts (no key prefix) keep decrypting
+  with `ENCRYPTION_KEY` indefinitely.
+- **`ENCRYPTION_ACTIVE_KEY_ID`** _(optional, new)_ — the key ID used
+  for new writes. Must be a key in `ENCRYPTION_KEYS`. Defaults to
+  the legacy single-key behaviour if either is unset.
+- **`ENCRYPTION_KEY`** _(unchanged)_ — still honoured as a fallback
+  when `ENCRYPTION_KEYS` is empty. No action needed for existing
+  installs.
+- Rotation: `pnpm tsx scripts/rotate-encryption-key.ts <newKeyId>`
+  re-encrypts every ciphertext under the new key without downtime.
+  Walk-through in `docs/ops/encryption-key-rotation.md`.
+
+### Off-host backup target _(optional)_
+
+If unset, the existing local `DataBackup` storage continues to work.
+
+- **`BACKUP_S3_ENDPOINT`** — S3-compatible endpoint URL. Leave blank
+  to disable off-host backup.
+- **`BACKUP_S3_BUCKET`** — destination bucket name.
+- **`BACKUP_S3_ACCESS_KEY`**, **`BACKUP_S3_SECRET_KEY`** — IAM
+  credentials. Worker only requests `PutObject` + `GetObject` —
+  never `DeleteObject`. Retention is the bucket's lifecycle policy.
+- **`BACKUP_S3_REGION`** _(default `auto`)_.
+- **`BACKUP_RETENTION_DAYS`** _(default `30`)_ — surfaced in the
+  admin UI; the lifecycle rule on your bucket is the actual enforcer.
+- **`BACKUP_ENCRYPTION_KEY`** — separate 64-char hex key for the
+  AES-GCM envelope of each upload. **Keep offline / in a vault.**
+  Lose this and the off-host backups are unreadable.
+
+### API token hashing _(unchanged but worth re-confirming)_
+
+- **`API_TOKEN_HMAC_KEY`** — 64-char hex string. Used to HMAC
+  Bearer tokens before storage so a DB leak can't be reversed via
+  rainbow table. Same key now also keys the new `RefreshToken` row
+  hashes. **Do not rotate without invalidating every native client.**
+
+## API
+
+### New
+
+- **`GET /api/version`** — public, static, returns
+  `{ version, buildSha, builtAt, license, repository, changelog, docs }`.
+  No authentication.
+- **`POST /api/integrations/withings/test`** — admin-only probe
+  against the saved Withings OAuth connection. Returns `{ ok, latency_ms }`
+  on success.
+- **`POST /api/integrations/moodlog/test`** — admin-only HEAD
+  request against `https://moodlog.app/api/health`. SSRF-guarded.
+- **`POST /api/notifications/web-push/test`** — sends a smoke push
+  notification to the current user's subscribed devices.
+- **`POST /api/monitoring/glitchtip/test`** — fires a benign event
+  at the configured DSN.
+- **`POST /api/monitoring/umami/test`** — verifies the script URL +
+  website ID resolve and respond with the expected payload.
+- **`POST /api/admin/backup/test`** — admin-only round-trip against
+  the configured `BACKUP_S3_*` credentials.
+- **`GET /api/admin/status-overview`** — admin-only aggregator
+  returning the six-card summary the new admin top strip renders in
+  one batched query.
+- **`POST /api/auth/refresh`** — native-client refresh-token
+  rotation. Cookie-session browsers don't use this.
+- **`POST /api/auth/refresh/revoke`** — paired logout-on-device that
+  flips both the refresh row and the matching `ApiToken` row to
+  revoked.
+
+All new admin endpoints are hidden from anonymous traffic by the
+proxy and rate-limited.
+
+### Behaviour-only changes
+
+- **`POST /api/ai/test`** now accepts an optional JSON body that
+  mirrors the AI dropdown in `/settings`. Empty body keeps the
+  pre-1.4 behaviour (test the saved provider). Non-empty body tests
+  the unsaved selection without persisting plaintext keys. The
+  existing rate limit (5/min) and error-leak shielding stay in place.
+- **`GET /api/dashboard/summary`** localises the `streak.label` and
+  `greeting.salutation` fields against the user's stored locale.
+- **`POST /api/insights/targets`** uses a single batched query for
+  per-type latest readings; returns identical payloads.
+
+No `/api/...` route changed shape, status codes, or auth rules. iOS,
+n8n, and Health Connect integrations need no change.
+
+## UI / UX
+
+### Dashboard
+
+- **Tile strip is always one row.** Previously the four-to-five-tile
+  grid wrapped to a second row when many widgets were enabled. v1.4
+  uses a horizontal-scroll strip — total width caps at the chart
+  width below, snap points keep the touch experience deliberate. To
+  reduce the visible tile count, open Settings → Dashboard Layout
+  and toggle widgets off.
+
+### Forms
+
+- **Password managers no longer autofill health-data inputs.**
+  Browsers and LastPass / 1Password were happily filling the user's
+  saved account password into measurement notes, AI tokens, and
+  similar free-text fields. The `<Input>` primitive now defaults to
+  `autoComplete="off"` plus the LastPass / 1Password ignore
+  attributes whenever the caller doesn't pass a semantic value. Auth
+  and profile forms (login, register, change-email) keep autofilling
+  normally because they pass an explicit `autoComplete` (e.g.
+  `"username"`, `"email"`, `"new-password"`).
+
+### Settings
+
+- **AI provider connection-test honours the unsaved selection.** Pick
+  a provider in the dropdown and click "Verbindung testen" without
+  saving first — the test now runs against your in-form selection
+  instead of the saved provider.
+
+### Notifications
+
+- **Telegram, ntfy, and Web Push reminders follow your locale.**
+  Switching the user's locale to English now produces English
+  reminders; the previous build always sent German strings regardless.
+  Telegram callback IDs stay stable (English) so the bot dispatcher
+  keeps matching them.
+
+## Medical defaults
+
+- **Diastolic blood-pressure orange band no longer reaches 60 mmHg.**
+  A reading of 60 mmHg now lands in red instead of yellow. The
+  user-override path is intact — if you set a personal threshold via
+  `/settings#thresholds`, it still applies and is audit-logged.
+- **Body-fat classifier mirrors the ACE table** — readings below the
+  ACE essential floor (M < 2 / F < 10) now classify as
+  "Below essential" (danger), the actual essential band (M 2–5 /
+  F 10–13) as warning, and the realistic healthy range
+  (M 14–24 / F 21–31) as the green band on the dashboard target tile.
+- **Step target unified at 8 000–15 000.** The two surfaces that
+  previously disagreed (7 000–10 000 in `getStepsRange()` versus
+  8 000–15 000 in the effective-range resolver) now use the same
+  band, anchored on Saint-Maurice et al., JAMA 2020.
+
+## URL changes
+
+- **Settings has moved to per-section routes.** `/settings#integrations`
+  → `/settings/integrations`, etc. The legacy `/settings#anchor` URLs
+  still 308-redirect to the new routes; sidebar deep-links and the
+  `<a href="/settings#thresholds">` patterns from 1.3 keep working.
+
+## What landed in v1.4 vs v1.4.1
+
+The v1.3.3 ecosystem audit identified architectural rewrites tracked
+through v1.4. Status as of the v1.4.1 cycle:
+
+| Bucket                                                                                 | Status              |
+| -------------------------------------------------------------------------------------- | ------------------- |
+| Settings page split into `/settings/[section]`                                         | ✓ shipped in v1.4.0 |
+| Admin status-first card grid + aggregator endpoint                                     | ✓ shipped in v1.4.0 |
+| AI insights rework — severity hero + allowlisted inline charts                         | ✓ shipped in v1.4.0 |
+| Multi-tenant prep (off-host backups, key versioning, worker/web split, refresh tokens) | ✓ shipped in v1.4.0 |
+| Per-section admin component extraction (inner monolith → one file per panel)           | ✓ shipped in v1.4.1 |
+| Postgres-backed integration test suite (testcontainers)                                | ✓ shipped in v1.4.1 |
+| Playwright + axe-core E2E foundation                                                   | ✓ shipped in v1.4.1 |
+
+## Rollback
+
+If 1.4.0 surfaces a regression on your install, redeploy the previous
+1.3.3 image:
+
+```bash
+docker compose down
+docker pull ghcr.io/mbombeck/healthlog:1.3.3
+sed -i 's/healthlog:1.4.0/healthlog:1.3.3/' docker-compose.yml
+docker compose up -d
+```
+
+The schema is unchanged so a rollback does not require a database
+restore. File a GitHub issue with the symptom — the v1.4 cycle ran
+multi-pass QA per stage, but no migration is risk-free.

docs/ops/attempt-number-semantics.md

@@ -0,0 +1,52 @@
+# `attemptNumber` audit-row vs alert-signal semantics
+
+Two numbers describe a failing integration sync, and they can diverge.
+On-call operators reading an audit-log row alongside an admin alert
+should expect the alert number to be smaller than (or equal to) the
+audit number, never the other way around.
+
+## The two numbers
+
+`integrations.sync.failed` audit rows write
+`attemptNumber = transient + reauth_required + persistent` — the **sum**
+of all three failure buckets. This is the historical "consecutive
+failures" running total carried by the legacy
+`IntegrationStatus.consecutiveFailures` column (dropped in migration
+`0077`, v1.4.47). Auditors looking at a single row see one integer
+that captures how many failures the bucket ledger has accumulated since
+the last success.
+
+The persistent-failure alert dispatcher in
+`src/lib/integrations/status.ts:453` uses `Math.max(...buckets)` — the
+**max** across the three buckets. A 3-deep persistent streak pages even
+when the transient bucket is empty, and a flapping integration that
+ping-pongs between transient and reauth_required never trips a
+single-bucket threshold even if its sum looks alarming.
+
+## When the two diverge
+
+A typed-failure-streak edge case: integration fails 2× transient, then
+2× reauth_required, then 1× persistent. Audit row shows
+`attemptNumber: 5`. Alert signal is `max(2, 2, 1) = 2`, which is below
+the default threshold of 3, so no page fires. From the audit log this
+looks like a sustained 5-failure outage; from the alert dispatcher it
+looks like three small bumps that never crossed a single-bucket
+ceiling.
+
+Both readings are correct for their purpose. The audit log records what
+happened end-to-end; the alert dispatcher only fires when a single
+failure mode persists, because mixed-bucket streaks usually indicate a
+transient network blip layered on top of an unrelated reauth prompt —
+two problems, neither of which is the "this integration is broken" page
+we want to wake someone up for.
+
+## Runbook implication
+
+If you see an audit row with `attemptNumber >= threshold` but no alert
+was dispatched, check the per-bucket counts on
+`IntegrationStatus.failureBuckets` for that user/integration pair. The
+sum may be high while every individual bucket sits below the threshold.
+This is working as designed; manually investigate only if a single
+bucket is at or above the threshold and `alertedAt` is unset (broken
+dispatcher) or set within the last 24 hours (rate-limited, see the
+`ALERT_REPEAT_WINDOW_MS` constant).

docs/ops/backup-restore.md

@@ -0,0 +1,87 @@
+# Off-host backup & restore
+
+HealthLog ships with an optional daily off-host backup that ships every
+user's JSON dump, encrypted with AES-256-GCM under a SEPARATE key
+(`BACKUP_ENCRYPTION_KEY`), to any S3-compatible bucket — Cloudflare R2,
+AWS S3, Backblaze B2, MinIO, etc.
+
+The backup runs at **02:30 Europe/Berlin** every day from the worker
+container (queue `data-backup-offhost`). Object key layout:
+
+```
+<bucket>/YYYY-MM-DD/user-<userId>.json.enc
+```
+
+## Wire format (binary)
+
+```
+magic   = "HLBK"           (4 bytes, ASCII)
+version = 0x01             (1 byte)
+iv      = 12 random bytes  (AES-GCM nonce)
+authTag = 16 bytes         (AES-GCM tag)
+ciphertext = N bytes       (AES-256-GCM, key = BACKUP_ENCRYPTION_KEY)
+plaintext  = JSON dump (UTF-8)
+```
+
+## Required env vars
+
+| Var                     | Required | Notes                                                                |
+| ----------------------- | -------- | -------------------------------------------------------------------- |
+| `BACKUP_ENCRYPTION_KEY` | yes      | 64 hex chars or 32-byte base64. **Different from `ENCRYPTION_KEY`.** |
+| `BACKUP_S3_ENDPOINT`    | yes      | e.g. `https://<account>.r2.cloudflarestorage.com`                    |
+| `BACKUP_S3_BUCKET`      | yes      |                                                                      |
+| `BACKUP_S3_ACCESS_KEY`  | yes      |                                                                      |
+| `BACKUP_S3_SECRET_KEY`  | yes      |                                                                      |
+| `BACKUP_S3_REGION`      | no       | defaults to `auto` (Cloudflare R2)                                   |
+| `BACKUP_RETENTION_DAYS` | no       | defaults to `30`                                                     |
+
+## Bucket lifecycle (recommended)
+
+The worker prunes objects older than `BACKUP_RETENTION_DAYS`, but the
+storage provider's lifecycle rule is the canonical safety net:
+
+```
+Filter: "" (all objects)
+Action: Expire after 30 days
+```
+
+For Cloudflare R2 add this from the bucket's **Settings → Lifecycle**.
+
+## Smoke test
+
+After deploying, hit `POST /api/admin/backup/test` (admin-only). It
+performs a 1-byte PUT + GET round-trip and returns:
+
+```json
+{
+  "endpoint": "https://...r2.cloudflarestorage.com",
+  "bucket": "healthlog-backups",
+  "region": "auto",
+  "putLatencyMs": 142,
+  "getLatencyMs": 38,
+  "ok": true
+}
+```
+
+The credentials are never returned.
+
+## Restore
+
+Pick a key (e.g. `2026-05-08/user-clx123.json.enc`) from the bucket
+and run:
+
+```bash
+BACKUP_S3_ENDPOINT=https://...r2.cloudflarestorage.com \
+BACKUP_S3_BUCKET=healthlog-backups                     \
+BACKUP_S3_ACCESS_KEY=...                               \
+BACKUP_S3_SECRET_KEY=...                               \
+BACKUP_S3_REGION=auto                                  \
+BACKUP_ENCRYPTION_KEY=$(openssl rand -hex 32)          \
+pnpm tsx scripts/restore-backup.ts \
+  2026-05-08/user-clx123.json.enc \
+  /tmp/restored.json
+```
+
+The script downloads the object, decrypts it, and writes the JSON dump
+to disk. Importing the JSON back into a HealthLog instance is left to
+the operator (use `prisma db seed` or a custom script).

docs/ops/deploy.md

@@ -0,0 +1,92 @@
+# Deploy ordering
+
+Coolify handles the standard deploy ordering automatically: the
+container image is pulled, `docker-entrypoint.sh` runs
+`prisma migrate deploy` against the live database, and only then does
+the Next.js process bind to the listener. This page documents the
+ordering explicitly for manual-rollback and partial-deploy scenarios
+where the operator drives the steps by hand.
+
+## Migration ordering
+
+Migrations land **before** the new app container takes traffic. The
+canonical command sequence on a single-instance host:
+
+```sh
+# 1. Pull the new image.
+docker pull ghcr.io/mbombeck/healthlog:vX.Y.Z
+
+# 2. Run migrations against the live DB using the new image.
+docker run --rm --env-file .env.production \
+  ghcr.io/mbombeck/healthlog:vX.Y.Z \
+  pnpm prisma migrate deploy
+
+# 3. Recreate the app container so it picks up the new image.
+docker compose up -d app
+```
+
+The entrypoint also runs `prisma migrate deploy` on container boot, so
+step 2 is redundant in normal Coolify flow. It's listed explicitly for
+the manual case so an operator can verify the migration result before
+flipping traffic.
+
+### v1.11.0 notes
+
+Migrations `0110`–`0114` are additive (new tables / columns for the
+WHOOP provider hub, the longitudinal coach, and the clinician FHIR
+record). They require no special steps — `prisma migrate deploy` runs
+them in order on boot like any other.
+
+WHOOP introduces two optional instance env vars, `WHOOP_REDIRECT_URI`
+and `WHOOP_WEBHOOK_SECRET` (HMAC secret for WHOOP webhook signature
+verification). Per-user WHOOP client id/secret live in Settings, not
+in the environment. See `docs/integrations/whoop.md`. Add the two vars
+to the compose `environment:` whitelist if you set them — vars not on
+the whitelist never reach the container.
+
+### What goes wrong if you reverse it
+
+If the new app container starts before migrations run, the legacy
+schema is missing the columns / indexes / enum values the new code
+expects. Symptoms: Prisma client throws `P2022 column does not exist`
+on the first query that touches the new shape, the request path 500s,
+and the dispatcher logs fill with the same error until the migration
+catches up. Health checks usually keep the container marked "healthy"
+because `/api/version` doesn't exercise the affected tables — so a
+naïve load balancer will happily route real traffic into the broken
+shell.
+
+### Rollback
+
+Rolling back **migrations** is generally one-way. Prisma's migration
+history table tracks applied migrations by hash; the `down` step is
+not auto-generated and most HealthLog migrations are forward-only
+(column drops, enum additions, index rebuilds). If a release has to
+roll back:
+
+1. Roll back the **app container** to the previous image tag.
+2. Leave the **database schema** at the newer migration. The previous
+   app version reads forward-compatible-ish shapes for nearly every
+   release pair shipped on the v1.4.x line.
+3. If a column-drop migration ships in the rollback target, hand-roll
+   the column back via a fresh forward migration (`pnpm prisma migrate
+   dev --create-only --name vX_Y_Z_rollback_<col>`), edit the SQL,
+   commit, and re-deploy. Never `migrate resolve --rolled-back` against
+   production unless you've taken a fresh `pg_dump` first.
+
+## Verify the served version
+
+The queued-deploy status is **not** the source of truth — the version
+`/api/version` actually answers is. A BuildKit layer-cache hit can
+re-ship the prior image even when Coolify reports a clean deploy, so
+always confirm the served build after a deploy:
+
+```sh
+# Asserts prod + demo serve 1.9.0, prints each target's buildSha,
+# exits non-zero on a mismatch or timeout after a bounded retry loop.
+pnpm dlx tsx scripts/assert-deploy.ts 1.9.0
+```
+
+Pass `--only=prod` / `--only=demo` to check a single target, or
+`--attempts=N --interval=ms` to widen the retry window while a slow
+pull settles.

docs/ops/encryption-key-rotation.md

@@ -0,0 +1,107 @@
+# Encryption-key rotation
+
+HealthLog encrypts sensitive at-rest data (Withings tokens, AI provider keys,
+notification channel configs, web-push subscription secrets, VAPID private
+keys, etc.) with AES-256-GCM under a per-deployment key. v1.4 introduces a
+versioned key format so the key can be rotated without downtime and without
+re-encrypting every row by hand.
+
+## Format
+
+| Layout          | Marker                                          | Where                       |
+| --------------- | ----------------------------------------------- | --------------------------- |
+| Versioned (new) | `<keyId>.<base64(iv \|\| tag \|\| ciphertext)>` | All new writes              |
+| Legacy (v1.3.x) | `<base64(iv \|\| tag \|\| ciphertext)>`         | Existing rows until rotated |
+
+`<keyId>` matches `[A-Za-z0-9_-]{1,32}` and indexes into the `ENCRYPTION_KEYS`
+JSON map. Decryption tries the versioned format first; if no `.` is present
+or the prefix isn't a known id, the row is treated as legacy and decrypted
+under `v1` (the synthetic id assigned to the existing `ENCRYPTION_KEY`).
+
+> **Why a separate `v1` is required.** Legacy ciphertexts have no key id, so
+> the only way to identify them is "no `.` in the value". If you remove the
+> `v1` entry from `ENCRYPTION_KEYS` _before_ every legacy row has been
+> rotated, those rows can't be decrypted any more — the active key won't
+> match the original ciphertext. The decrypt path now refuses to silently
+> fall back to the active key in that scenario; it throws a clear error.
+
+## Rotating from v1.3.x to a new key
+
+1. **Generate the new key** on a machine with `openssl`:
+   ```
+   openssl rand -hex 32
+   ```
+2. **Update environment variables.** Keep the existing `ENCRYPTION_KEY` in
+   place — it's still needed to decrypt legacy rows during the transition:
+   ```
+   ENCRYPTION_KEY="<old key, unchanged>"
+   ENCRYPTION_KEYS='{"v1":"<old key>","v2":"<new key>"}'
+   ENCRYPTION_ACTIVE_KEY_ID="v2"
+   ```
+   Restart the app. New writes are now encrypted under `v2`; existing
+   `v1`-keyed and legacy bare rows still decrypt because the `v1` entry is
+   retained.
+3. **Run the rotation script** to re-encrypt every existing encrypted column
+   under the new active key:
+   ```
+   pnpm tsx scripts/rotate-encryption-key.ts v2
+   ```
+   The script is idempotent — running it again is a no-op for rows already
+   prefixed with `v2.`. It rotates User, WithingsConnection, AppSettings,
+   NotificationChannel, and PushSubscription rows. The summary line at the
+   end shows `scanned`, `rotated`, and `errors` per table+field; treat
+   `errors > 0` as a hard failure and re-run after fixing the cause.
+4. **Drop the old key (optional, recommended).** Once the script has run
+   cleanly:
+   ```
+   ENCRYPTION_KEYS='{"v2":"<new key>"}'
+   ENCRYPTION_ACTIVE_KEY_ID="v2"
+   # ENCRYPTION_KEY can now be removed
+   ```
+   Restart. The legacy single-key fallback is now disconnected; only `v2`
+   exists.
+
+## Adding a third key (v2 → v3)
+
+Same procedure, just shift the labels — keep `v2` in the map until the
+script reports zero `v2.`-prefixed rows remaining.
+
+```
+ENCRYPTION_KEYS='{"v2":"<old>","v3":"<new>"}'
+ENCRYPTION_ACTIVE_KEY_ID="v3"
+pnpm tsx scripts/rotate-encryption-key.ts v3
+ENCRYPTION_KEYS='{"v3":"<new>"}'
+```
+
+## Rollback
+
+> **Important.** Once the rotation script has run, ciphertexts in the
+> database start with `v2.` (or whatever the active id is). The pre-PR
+> v1.3.x image cannot read that prefix — it expects bare base64 — and
+> calling `decrypt()` on those rows will throw.
+
+If you need to revert to the pre-rotation image:
+
+- Either keep the new image. The new code reads both formats, so most
+  rollback scenarios don't need to undo rotation.
+- Or, if you must run the old code, restore a database backup taken
+  _before_ the rotation script ran. There is no script to convert
+  `v2.`-prefixed rows back to legacy format — by design, rotation is a
+  forward-only operation.
+
+This is why we recommend running the rotation in a window where you have a
+fresh DB snapshot and the new image has been smoke-tested in production for
+at least 24 hours.
+
+## Troubleshooting
+
+- `Encryption key id 'v1' is not configured` — the database still contains
+  `v1.`-prefixed rows but `v1` was removed from `ENCRYPTION_KEYS`. Re-add
+  the key, run the rotation script, then remove again.
+- `Found a legacy-format ciphertext but no v1 key is configured` — same
+  cause for legacy bare-base64 rows. Restore `ENCRYPTION_KEY` (or add a
+  `v1` entry to `ENCRYPTION_KEYS`) and run the rotation script before
+  removing it.
+- `Refusing to rotate: argv key id ... does not match the currently active
+id ...` — pass the same id you set in `ENCRYPTION_ACTIVE_KEY_ID`. The
+  guard prevents accidental re-encryption to a non-current key.

docs/ops/env-check.md

@@ -0,0 +1,99 @@
+# Pre-deploy env-var sanity check
+
+`pnpm check-env` reads `scripts/env-manifest.json` and verifies every
+variable declared `required: true` is present + non-empty in the
+runtime environment. Optional groups are surfaced too, so an operator
+can spot the "3 out of 4 vars set" pattern that silently disables a
+feature.
+
+This is the answer to the v1.4.40 AP-2 silent-disable: the `.p8` file
+went missing during a Coolify migration, three of four `APNS_*` vars
+remained set, the app booted cleanly, and APNs notifications stopped
+working — undetected for three days because the dispatcher's fallback
+chain hid the gap behind the Telegram → ntfy → Web Push path.
+
+## Usage
+
+### Against the live shell
+
+```sh
+pnpm check-env
+```
+
+Runs against `process.env` (after the local `.env` / `.env.local` load,
+if any). Exit code 0 on green, 1 on at least one required variable
+missing, 2 on a malformed manifest.
+
+### Against a Coolify export / .env.production
+
+```sh
+pnpm check-env --file /path/to/.env.production
+```
+
+The file is parsed locally (no shell execution, no variable expansion)
+and checked against the manifest. Useful for spot-checking a Coolify
+export without polluting the local shell.
+
+## Output format
+
+Output is one row per declared variable, grouped by section. Three
+states:
+
+| Marker                | Meaning                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `[OK]`                | Variable is set and non-empty.                                                     |
+| `[MISSING-REQUIRED]`  | Variable is required for boot. The script exits 1.                                 |
+| `[missing-optional]`  | Variable is optional. The script reports it but does not fail.                     |
+
+The grep-friendly format lets a CI pipeline do `grep -q
+'\[MISSING-REQUIRED\]'` to gate a deploy. The CI integration itself
+is deferred to v1.4.43 — this release ships the CLI tool only.
+
+## All-or-none groups
+
+Some groups (e.g. off-host backups) are marked `allOrNone: true` in
+the manifest. When such a group is partially populated — some vars
+set, some missing — the script emits a synthetic `<all-or-none>` row
+with severity REQUIRED, even if the surrounding group is `required:
+false`. This is the v1.4.40 AP-2 detection pattern.
+
+Example output for a partial APNs config:
+
+```
+# APNs (iOS push)
+  [OK] APNS_KEY_ID
+  [OK] APNS_TEAM_ID
+  [OK] APNS_BUNDLE_ID
+  [missing-optional] APNS_KEY — Satisfied by any of: APNS_KEY, APNS_KEY_FILE
+```
+
+A reviewer immediately sees that `APNS_KEY` (or its `APNS_KEY_FILE`
+alternative) is missing while the other three APNs vars are set — the
+exact configuration that silently disables iOS push.
+
+## Editing the manifest
+
+The manifest lives at `scripts/env-manifest.json` and is git-tracked
+so changes go through a PR. To add a new variable:
+
+1. Pick the right group (or add a new one if the variable doesn't
+   belong to any existing category).
+2. Decide whether the variable is required for boot, optional, or
+   part of an all-or-none feature group.
+3. Document the variable's `purpose` in one sentence — the operator
+   reads this text when the var shows up as missing.
+4. Run `pnpm check-env` locally against your live shell to confirm
+   the manifest still passes (or fails for the right reason).
+5. Add a regression test under `scripts/__tests__/check-env.test.ts`
+   if the manifest change introduces a new classification branch
+   (anyOf, allOrNone, …).
+
+## Future: CI gate
+
+Deferred to v1.4.43:
+
+- GitHub Actions workflow that runs `pnpm check-env --file
+  .env.production.example` on every PR, blocking changes that
+  introduce new required vars without updating the example file.
+- Coolify pre-deploy hook that runs `pnpm check-env` inside the
+  target container and aborts the deploy on exit code 1.

docs/ops/migrations/0025-down.sql

@@ -0,0 +1,6 @@
+-- 0025_refresh_tokens — down migration (v1.4 G4 rollback).
+-- Forward-compatible: the up migration only ADDS a table, so this is a
+-- safe DROP. Any in-flight refresh tokens are invalidated; native clients
+-- need to re-authenticate.
+
+DROP TABLE IF EXISTS "refresh_tokens";

docs/ops/tls-cert-pin.md

@@ -0,0 +1,127 @@
+# TLS leaf SPKI pin — coupling, alarm, and re-pin runbook
+
+The native client SPKI-pins the server's TLS **leaf** certificate. This is a
+deliberate hardening choice on the client side, but it couples the client to
+the exact leaf keypair the server serves: when that leaf rotates, a client
+that was only ever shipped the old pin refuses to connect. This page explains
+the coupling, the server-side alarm that watches for a rotation, and the
+operator / release-owner steps when it fires.
+
+## The coupling
+
+A SPKI pin is `base64(sha256(DER subjectPublicKeyInfo))` — a hash of the
+certificate's public key, not of the whole certificate. The native client
+carries a set of these pins and rejects any TLS connection whose leaf public
+key is not in the set.
+
+The app host's certificate is issued by Google Trust Services (GTS) and
+auto-renews roughly every 90 days. Each renewal mints a **new leaf keypair**,
+so the SPKI pin changes on every renewal. Intermediate and root rolls have
+the same effect on the leaf chain. Because the client pins the leaf, every
+such change is a hard outage for any client that hasn't been shipped the new
+pin — and there is otherwise no server-side signal that a client is pinning
+the served leaf at all.
+
+## The alarm
+
+A scheduled job (`src/lib/jobs/tls-pin-monitor.ts`) probes the served leaf
+every 6 hours and fails loudly when it changes:
+
+- It derives the public host from `APP_URL` (falling back to
+  `NEXT_PUBLIC_APP_URL`) and opens a raw TLS socket to it — observing exactly
+  the certificate a pinned client would, regardless of how the reverse proxy
+  terminates TLS.
+- It reads the served leaf, computes its SPKI pin
+  (`base64(sha256(DER subjectPublicKeyInfo))`), and compares it against the
+  operator's known-good set in `TLS_LEAF_SPKI_PINS`.
+- On a served pin that is **not** in the known set it emits a
+  `tls.pin.leaf_changed` wide-event annotation (old set + served pin), writes
+  a `system.tls.pin_changed` audit-log row, and fans out a high-priority
+  `SYSTEM_ALERT` to every admin user through the notification dispatcher
+  (Telegram / ntfy / Web Push / APNs, whichever the operator has wired).
+
+A transient TLS or network failure during the probe is annotated
+(`tls.pin.probe_failed`) and never alarms — the alarm fires only on a
+successful probe returning a pin genuinely outside the known set.
+
+### Baseline source: an env var, not auto-learning
+
+`TLS_LEAF_SPKI_PINS` (comma-separated) is the known-good set. The baseline is
+an env var on purpose, **not** a persisted "last-seen" row:
+
+- The pinned client only trusts the pins it was shipped, so the operator must
+  derive the client's pin set from a single explicit source of truth. The env
+  var **is** that source — the same value goes into the client's pin set and
+  into `TLS_LEAF_SPKI_PINS`.
+- A persisted last-seen baseline would silently adopt the first rotated pin
+  and suppress the very alarm the pinned client needs.
+- When the env var is unset, the monitor fails **loud, not open**: it logs
+  the served pin (so you can seed the baseline) and warns "not configured",
+  but never auto-adopts what it observed.
+
+## Setting the baseline
+
+Extract the current leaf SPKI pin from the served certificate:
+
+```sh
+openssl s_client -connect "$APP_HOST:443" -servername "$APP_HOST" </dev/null 2>/dev/null \
+  | openssl x509 -noout -pubkey \
+  | openssl pkey -pubin -outform der 2>/dev/null \
+  | openssl dgst -sha256 -binary \
+  | openssl base64
+```
+
+`$APP_HOST` is the host in your configured `APP_URL` (the host the client
+connects to). The output is the `base64(sha256(DER subjectPublicKeyInfo))`
+pin. Set it in the deployment env:
+
+```
+TLS_LEAF_SPKI_PINS="<current-leaf-pin>"
+```
+
+The variable is on the compose `environment:` whitelist and the
+`scripts/env-manifest.json` optional groups, so `pnpm check-env` will report
+whether it is set. It is optional: without it the monitor still runs and logs
+the served pin, but cannot alarm on a change.
+
+## When the alarm fires — re-pin procedure
+
+When you see a `tls.pin.leaf_changed` alert / `system.tls.pin_changed` audit
+row, the served leaf has rotated. The pinned client will stop connecting once
+its shipped pin no longer matches a served leaf. Act inside the certificate's
+remaining validity, with margin for app review and client roll-out — target
+**≥ 11 days before the old pin's certificate expires** (the alert body and
+audit row both carry the new leaf's `validTo`).
+
+1. **Re-extract the new leaf pin** with the `openssl` pipeline above. It
+   should equal the `servedPin` in the alert.
+2. **Dual-pin.** Add the new pin to the client's pin set **alongside** the old
+   one (do not replace it yet), and update `TLS_LEAF_SPKI_PINS` to the
+   comma-separated pair, e.g.
+   `TLS_LEAF_SPKI_PINS="<old-pin>,<new-pin>"`. Holding both pins means clients
+   on the old build keep working through the cutover and the server-side
+   alarm goes quiet because the served pin is now in the known set. Re-deploy
+   the server so the new env value takes effect.
+3. **Ship the client build** carrying the dual-pin set to TestFlight (and
+   onward to release). Give it long enough to roll out to the installed base
+   before the next renewal.
+4. **Retire the old pin** once the old leaf is no longer served and the
+   dual-pinned client build has reached the installed base: drop the old pin
+   from both the client pin set and `TLS_LEAF_SPKI_PINS`, leaving only the
+   current leaf pin.
+
+Treat the dual-pin window as standing practice: always ship the **next** pin
+before the current leaf rotates, so a renewal never catches a single-pinned
+client. If GTS renews on a fixed cadence, pre-extracting and dual-pinning the
+upcoming leaf ahead of the renewal turns every rotation into a no-op.
+
+## Environment assumption
+
+The monitor speaks TLS directly to the public host from `APP_URL` /
+`NEXT_PUBLIC_APP_URL`, which is correct regardless of the reverse-proxy
+topology — it observes the same leaf a real client does. The one assumption
+is that the host the client connects to is the host in that env var. If the
+client is pinned against a different hostname (e.g. a vanity domain that
+fronts the configured `APP_URL`), point the monitor at that host by setting
+`APP_URL` to it, or extend the job to probe the additional host. Plain-HTTP
+self-hosts have no leaf to pin and the monitor no-ops there by design.

docs/ops/v141-followup-issues.md

@@ -0,0 +1,260 @@
+# v1.4.x follow-up issues
+
+Items identified by the v1.4.1 audit pass that warrant deeper work
+than a hardening release should land. Each one carries enough context
+that a future contributor can pick it up without re-running the audit.
+
+## Security — deferred
+
+### S-FOLLOW-1 — Idempotency-Key concurrent duplicate side-effects (HIGH)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` H1.
+
+The `withIdempotency()` wrapper currently does
+`findCached → handler → persistCached`. Two requests with the same
+`Idempotency-Key` arriving in parallel both miss the SELECT, both
+execute the handler (duplicate measurements / intake events), and
+one INSERT loses on the unique constraint silently. The repo-doc
+contract ("retries with the same Idempotency-Key … replay the
+original response — no second side-effect") is therefore violated
+whenever a flaky mobile client double-sends.
+
+**Fix shape**: acquire the slot before the handler runs.
+`INSERT … ON CONFLICT DO NOTHING RETURNING id` reserving the
+`(userId, key, method, path)` row with a sentinel
+`responseStatus = 0`, then UPDATE on completion; concurrent losers
+SELECT-loop with backoff for the row to be filled. Or wrap the
+whole request in a Postgres advisory lock keyed by hash(userId, key)
+via `pg_advisory_xact_lock`.
+
+Why deferred: needs a careful integration test against the new
+testcontainers suite (two concurrent inserts → exactly one handler
+invocation) and a public-API contract check that the
+sentinel-status row never bleeds into a 2xx replay. Fits a v1.4.2
+PR scope on its own.
+
+---
+
+### S-FOLLOW-2 — Encryption key fallback NODE_ENV gate (MEDIUM)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` M1.
+
+`src/lib/crypto.ts:61-74` only requires the 64-hex production key
+when `process.env.NODE_ENV === "production"`. A fresh Docker run
+that forgets to set `NODE_ENV=production` (raw `node …` invocations,
+some operator setups) silently accepts a 32-character key and pads
+it deterministically with a SHA-256 of itself, halving the entropy
+and making the resulting key recoverable from any leaked partial.
+
+**Fix shape**: invert the gate to `NODE_ENV !== "development" &&
+NODE_ENV !== "test"` — fail-closed by default — or require an
+explicit `ALLOW_WEAK_DEV_KEYS=1` opt-in.
+
+Why deferred: needs a migration note for self-hosters whose `.env`
+files lack `NODE_ENV` (default Coolify deploys do set it; bespoke
+setups may not). Worth a release note + .env.example call-out.
+
+---
+
+### S-FOLLOW-3 — Refresh-token reuse-detection serialisation (MEDIUM)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` M2.
+
+`src/lib/auth/refresh-token.ts` reuse-detection is a `findUnique`
+followed by a non-transactional `findMany + updateMany`. Concurrent
+first-time refreshes can briefly have both clients holding
+unrevoked access tokens before the loser's are revoked, and a
+parallel reuse attempt doubles the audit-log noise.
+
+**Fix shape**: wrap the rotation in a single `prisma.$transaction`
+with `Serializable` isolation, OR reorder to "claim first, mint
+second": `prisma.refreshToken.update({ where: { id, usedAt: null } })`
+fails atomically if the row was already consumed; only after the
+update succeeds, call `issueAccessAndRefresh`.
+
+Why deferred: needs an integration test that fires N parallel
+refreshes for the same token and asserts exactly one new pair is
+issued. The testcontainers suite is the right home; v1.4.2 PR.
+
+---
+
+### S-FOLLOW-4 — moodLog webhook HMAC lookup column (MEDIUM)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` M3.
+
+`src/app/api/integrations/moodlog/webhook/route.ts` performs an
+O(n) AES-GCM decrypt sweep across all enabled users for every
+webhook hit. Side-channels: timing oracle for ordering, DoS
+amplification (30/min IP rate-limit × n decrypts).
+
+**Fix shape**: add a `moodLogWebhookSecretLookupHash` column on
+`User` (HMAC-SHA-256 keyed by `API_TOKEN_HMAC_KEY`, populated
+alongside the encrypted secret on every write). Webhook does a
+single indexed `findUnique` on the lookup hash, bypassing the
+candidate iteration. The encryption stays as defence-in-depth.
+
+Why deferred: schema migration required. Backfill needs a one-off
+script that decrypts every existing row and writes the lookup
+hash. Owners need to approve the migration window. v1.4.2 or
+v1.5.
+
+---
+
+### S-FOLLOW-5 — moodLog `readMoodLogSecret` legacy fallback (MEDIUM)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` M4.
+
+If `decrypt()` throws inside `src/lib/moodlog-secret.ts:27-37`, the
+function returns the stored value as-is. Intent: legacy plaintext
+rows keep working. Side effect: an attacker with read access to
+the DB obtains the ciphertext blob and can submit it as the literal
+webhook secret.
+
+**Fix shape**: detect "looks like a v1.4 envelope"
+(`/^[A-Za-z0-9_-]{1,32}\..+$/`) and refuse the legacy fallback for
+envelope-shaped values. Log a metric so the rotation-on-write
+contract can be verified to drain.
+
+Why deferred: needs a small data-audit run to confirm no production
+row has a non-envelope value before the strict check goes live.
+
+---
+
+### S-FOLLOW-6 — Restore script writes decrypted JSON with default permissions (MEDIUM)
+
+Audit reference: `~/infra/reports/v14-security-audit.md` M5.
+
+`scripts/restore-backup.ts:73-122` writes the decrypted JSON via
+`writeFileSync(out, plaintext, "utf8")` with default mode (0644
+typical). The file contains decrypted PHI for the restored user.
+
+**Fix shape**:
+`writeFileSync(out, plaintext, { encoding: "utf8", mode: 0o600 })`.
+Optional: warn if `out` is in a world-readable directory.
+
+Why deferred: tiny one-line fix; bundling with the next ops-script
+update keeps the PR coherent.
+
+---
+
+## Performance — deferred
+
+### P-FOLLOW-1 — Recharts top-level import on `/insights` (P0)
+
+Audit reference: `~/infra/reports/v14-performance-audit.md` P0.
+
+`src/app/insights/page.tsx:42-50` static-imports
+`{ ScatterChart, Scatter, XAxis, … } from "recharts"` even though
+`HealthChart` and `MoodChart` 8 lines above are already wrapped in
+`dynamic(…, { ssr: false })`. The static import pulls the whole
+recharts bundle into the route's first JS payload, defeating the
+dynamic split.
+
+**Fix shape**: extract the BP-mood scatter into
+`src/components/charts/bp-mood-scatter.tsx` and import it via
+`dynamic(…, { ssr: false })` like the others.
+
+Why deferred: trivial mechanical change but needs a Lighthouse
+before/after to quantify the bundle-size win for the v1.4.2
+release notes.
+
+---
+
+### P-FOLLOW-2 — `/api/insights/targets` unbounded glucose history scan (P0)
+
+Audit reference: `~/infra/reports/v14-performance-audit.md` P0.
+
+`src/app/api/insights/targets/route.ts:600-604` pulls every glucose
+measurement the user ever logged (no `gte: thirtyDaysAgo`) and
+filters in JS. Diabetic users with multi-year history will
+materialise tens of thousands of rows on every targets fetch.
+
+**Fix shape**: split into "latest per context"
+(`distinct: ["glucoseContext"], orderBy: { measuredAt: "desc" }`)
+and a `measuredAt: { gte: thirtyDaysAgo }` window query, mirroring
+the pattern at lines 102-121 for `latestEverByType`.
+
+Why deferred: needs a per-context test asserting the new query
+returns the same payload shape. Pairs nicely with the MoodEntry
+index migration (P-FOLLOW-3).
+
+---
+
+### P-FOLLOW-3 — `MoodEntry @@index` is on `(userId, date)` not `(userId, moodLoggedAt)` (P0)
+
+Audit reference: `~/infra/reports/v14-performance-audit.md` P0.
+
+`prisma/schema.prisma:438` declares `@@index([userId, date])`, but
+active queries sort/filter by `moodLoggedAt`:
+
+- `src/app/api/insights/targets/route.ts:495`
+- `src/app/api/insights/comprehensive/route.ts:52`
+- `src/app/api/export/route.ts:87`
+
+The unique constraint `@@unique([userId, date, moodLoggedAt])` is
+not selectable by Postgres for windowed `moodLoggedAt`-range reads.
+
+**Fix shape**: add `@@index([userId, moodLoggedAt])` (do NOT drop
+the existing index — the unique still serves the moodlog webhook
+upsert path). New migration `0026_moodentry_moodloggedat_index`.
+
+Why deferred: schema migration. Owner approval for the migration
+window.
+
+---
+
+### P-FOLLOW-4 to -7 — P1 / P2 perf items
+
+- N+1 count() per medication on admin reminder-check
+  (`src/app/api/admin/notifications/reminder-check/route.ts:84`).
+  Replace with `groupBy` on `medicationIntakeEvent`.
+- `/api/analytics` 8-parallel full-history scan
+  (`src/app/api/analytics/route.ts:20-40`). Single `findMany` with
+  `type: { in: types }` and JS-side group.
+- `/api/import` sequential `prisma.measurement.create` per row
+  (`src/app/api/import/route.ts:77-96`). Replace with
+  `createMany({ skipDuplicates: true })`.
+- `pairByTimestamp` not used in `/api/analytics` BP correlation
+  (`src/app/api/analytics/route.ts:80-86`). Replace the quadratic
+  loop with the helper from `@/lib/analytics/correlations`.
+
+---
+
+## Test-quality polish (5 minor items)
+
+Audit reference: `~/infra/reports/v14-test-theatre-audit.md`.
+
+- `src/app/api/gamification/__tests__/ios-format.test.ts` L111-112:
+  upgrade `toBeDefined()` to shape predicates.
+- `src/lib/analytics/__tests__/classifications.test.ts` L169-170:
+  add `toMatch(/60/)` body-content assertion to compliance-alert tests.
+- `src/lib/__tests__/idempotency.test.ts` L145: upgrade bare
+  `toHaveBeenCalled()` to `toHaveBeenCalledWith({ where: …key… })`.
+- `src/app/api/telegram/webhook/__tests__/route.test.ts` L457: same
+  shape — upgrade or drop.
+
+---
+
+## i18n hardcoded strings
+
+Audit reference: `~/infra/reports/v14-i18n-drift-audit.md`.
+
+35+ hardcoded strings in `src/components/settings/ai-section.tsx`
+need to be moved into `messages/{en,de}.json` keys. The settings
+section was extracted in #143 with strings inline as a known
+follow-up; this is the cleanup PR.
+
+Why deferred: low blast-radius (only the AI provider settings page
+shows English to a German user; the dashboard, dialogs, and
+critical UX paths all flow through `t(…)`). v1.4.x or v1.5.
+
+---
+
+## Notes
+
+These are the items the v1.4.1 audit identified that the hardening
+release deliberately did NOT take. The audit also found 0 hallucinated
+medical claims, 0 i18n key-parity gaps, and the test theatre rate
+across the entire codebase was low (5 minor patterns). The codebase
+is in healthy shape; this list is the punch-list for the next
+proactive iteration, not a backlog of bugs we know about and ignore.

docs/security/cycle-data-threat-model.md

@@ -0,0 +1,52 @@
+# Cycle-data threat model
+
+A compact statement of what self-hosting HealthLog's cycle tracking
+protects against and what it does not. Pair this with the operator
+guidance in
+[`self-hosting/reproductive-health-data.md`](../self-hosting/reproductive-health-data.md).
+
+The scope here is reproductive-health data specifically (menstrual,
+fertility, pregnancy, contraception, sexual-activity fields), because
+that is the category where the "who can reach my data" question carries
+the highest stakes.
+
+## What self-hosting + encryption-at-rest protects against
+
+- **A cloud vendor holding your data.** There is no SaaS account and no
+  vendor key escrow. No third party can be served process for data it
+  does not have.
+- **A stolen disk or a leaked backup, while the key is held separately.**
+  The intent-revealing fields are AES-256-GCM encrypted at rest; a disk
+  image without the `ENCRYPTION_KEYS` value does not yield them.
+- **Casual lock-screen disclosure.** Discreet notifications collapse
+  every cycle reminder to a generic "HealthLog reminder" so the event is
+  never named on a lock screen.
+- **Third-party analytics / ad-tech leakage.** HealthLog ships no
+  telemetry and no third-party trackers; cycle data is never sent to an
+  analytics or advertising endpoint.
+
+## What it does NOT protect against
+
+- **Seizure or compulsion of your own host.** If the running machine is
+  seized, imaged, or compelled, the data is on it. Encryption at rest
+  does not help against a live host or a key stored beside the data.
+- **Your hosting provider.** A VPS provider can snapshot the disk and
+  can be served process. Self-hosting on rented infrastructure narrows
+  the set of parties that hold the data; it does not eliminate them.
+- **Your own backups.** Any `pg_dump` or off-host export carries the
+  same data and must be protected as part of the same surface.
+- **A compromised or unlocked client device.** A phone or laptop with a
+  live session or cached client holds data locally. Server-side
+  protection does nothing for an unlocked device.
+- **Re-identification from "plaintext" fields.** Flow, basal body
+  temperature, ovulation tests, cervical mucus, and cycle dates stay in
+  plaintext so the engines can read them. They are health observations,
+  not the disclosure-sensitive intent fields — but they are still
+  health data on your host.
+
+## The one-line version
+
+Self-hosting means **no cloud vendor to subpoena**. It does **not** mean
+the data is beyond reach: your own infrastructure, your provider, your
+backups, and your devices are all still part of the surface. Size your
+operator-side hardening to your own threat model.

docs/self-hosting/getting-started.md

@@ -0,0 +1,176 @@
+# Getting started — self-host HealthLog
+
+This walkthrough takes a fresh host from `git clone` to a running
+instance with a working first user. About fifteen minutes if Docker is
+already installed, longer if a TLS-fronted public hostname is in scope
+(see the reverse-proxy guide for that).
+
+## Prerequisites
+
+- **Docker 24+ with Compose v2.** The bundled `docker-compose.yml`
+  pulls a multi-arch image from GitHub Container Registry (linux/amd64
+  + linux/arm64), so a Raspberry Pi 5 or an x86 VPS both work
+  unchanged.
+- **2 GB RAM, 10 GB free disk.** The Postgres data volume grows with
+  measurement history; the Apple Health import worker can briefly
+  hold a 1.5 GB upload in `/tmp` while it parses.
+- **Outbound HTTPS** to `ghcr.io` (image pulls) plus whichever
+  integration endpoints you plan to enable (Withings, OpenAI, etc.).
+- **Optional but recommended:** a reverse proxy that terminates TLS
+  and forwards to `http://localhost:3000` (Caddy, Traefik, Nginx
+  Proxy Manager, Coolify, or bare Nginx — see `reverse-proxy.md`).
+
+## 1. Clone the repository
+
+```bash
+git clone https://github.com/MBombeck/HealthLog.git
+cd HealthLog
+cp .env.example .env
+```
+
+`.env.example` is the canonical reference for every env var the app
+reads. Anything you do not uncomment falls back to a sane default or
+disables the optional subsystem.
+
+## 2. Generate the three required secrets
+
+HealthLog needs three secrets before it will boot. Generate them with
+`openssl` and append to `.env`:
+
+```bash
+echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)" >> .env
+echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"       >> .env
+echo "API_TOKEN_HMAC_KEY=$(openssl rand -hex 32)"   >> .env
+```
+
+| Variable | Purpose | Rotation cost |
+| -------- | ------- | ------------- |
+| `POSTGRES_PASSWORD` | Bundled Postgres password — used by both the `db` service and `DATABASE_URL` | Database restart + connection-string update |
+| `ENCRYPTION_KEY` | AES-256-GCM key for at-rest secrets (Withings tokens, AI provider keys, VAPID secrets) | Coordinated; see `docs/ops/encryption-key-rotation.md` |
+| `API_TOKEN_HMAC_KEY` | HMAC-SHA256 key for hashing Bearer API tokens before storage | Invalidates every issued `hlk_*` token |
+
+Then open `.env` and confirm `DATABASE_URL` includes the password you
+just generated. The default template (`postgresql://healthlog:CHANGE-ME@db:5432/healthlog`)
+references the literal string `CHANGE-ME`; replace it with the value
+you put in `POSTGRES_PASSWORD`, or rewrite the URL to substitute
+explicitly.
+
+## 3. Bring the stack up
+
+```bash
+docker compose up -d
+```
+
+Compose starts two services:
+
+- `db` — PostgreSQL 16 with a named volume for persistence.
+- `app` — HealthLog itself, listening on `localhost:3000`. The image
+  runs `prisma migrate deploy` on boot so the schema lands
+  automatically; subsequent restarts no-op when the database is
+  already current.
+
+The first boot pulls the image (a few hundred megabytes) and runs
+migrations. Once `docker compose logs -f app` shows the Next.js
+banner, the instance is live.
+
+## 4. Create the first user
+
+Open `http://localhost:3000` in a browser. The registration flow asks
+for a username, email, and password. **The first user that registers
+is promoted to admin automatically.** Every subsequent registration
+creates a regular user.
+
+After the first user lands, you can:
+
+- Open `/admin` to review the worker status, audit log, and any
+  optional channels you want to configure (Telegram bot, ntfy, Web
+  Push VAPID keys, AI fallback key).
+- Open `/measurements` and add a weight or blood pressure to confirm
+  the data path is wired end-to-end.
+
+## 5. Point the instance at a public hostname
+
+Local-only is fine for a single-user trial. For anything more — and
+to unlock OAuth callbacks, webhook deliveries, and Web Push — set the
+public URL pair before restarting:
+
+```env
+NEXT_PUBLIC_APP_URL="https://your-instance.example.com"
+APP_URL="https://your-instance.example.com"
+```
+
+Both vars must match. `NEXT_PUBLIC_APP_URL` lands in the client bundle
+at build time and drives every absolute URL the UI emits (OAuth
+redirects, share links, manifest icons). `APP_URL` is the server-side
+mirror used by background jobs that have no request context.
+
+Restart the app container after editing:
+
+```bash
+docker compose up -d
+```
+
+The pre-built image reads both values at startup; no rebuild needed.
+
+## 6. Pick a reverse-proxy
+
+The bundled stack exposes plain HTTP on `localhost:3000`. Production
+deployments terminate TLS in front of the container. The
+`docs/self-hosting/reverse-proxy.md` guide carries copy-paste
+configurations for Caddy, Traefik, Nginx Proxy Manager, Coolify, and
+bare Nginx — including the `X-Forwarded-For` chain shape that the
+rate-limiter trusts and the `TRUST_PROXY_HOPS` env var that pins how
+many hops to read back.
+
+## Build-time feature toggles
+
+A small number of toggles are `NEXT_PUBLIC_*` variables: the framework
+inlines them into the client bundle at **build time**, so the pre-built
+GHCR image cannot read them at runtime. Setting them in `.env` or the
+compose `environment:` block has no effect — they only take hold when
+you build your own image. They are intentionally absent from the
+compose runtime whitelist for that reason.
+
+| Variable | Default | Effect when set |
+| --- | --- | --- |
+| `NEXT_PUBLIC_DASHBOARD_SNAPSHOT` | on | The dashboard hydrates every above-the-fold tile from the single `GET /api/dashboard/snapshot` cell so the whole strip shares one completion moment. Build with `NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false` to fall back to the legacy four-cell path. |
+
+To flip one, rebuild the image with the variable exported:
+
+```bash
+NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false pnpm build
+# or pass it as a Dockerfile build ARG / Docker build --build-arg
+```
+
+## 7. Where to go next
+
+| Next step | File |
+| --------- | ---- |
+| TLS + reverse-proxy configuration | `docs/self-hosting/reverse-proxy.md` |
+| Web/worker process split for horizontal scale | `docs/self-hosting/scaling.md` |
+| Off-host encrypted backups to S3/R2/B2 | `docs/ops/backup-restore.md` |
+| Encryption-key rotation procedure | `docs/ops/encryption-key-rotation.md` |
+| Withings device sync | `docs/integrations/withings.md` |
+| WHOOP device sync (per-user BYO-keys) | `docs/integrations/whoop.md` |
+| Google Health sync — Fitbit & Pixel (per-user BYO-keys) | `docs/integrations/google-health.md` |
+| Apple Health `export.zip` import | `docs/integrations/apple-health.md` |
+| AI provider setup (OpenAI / Anthropic / local / ChatGPT OAuth) | `docs/integrations/ai-providers.md` |
+
+## Troubleshooting
+
+- **`app` container exits with a Prisma migration error.** The
+  Postgres healthcheck races the migration on slow disks. Run
+  `docker compose restart app` once the database has stabilised —
+  migrations are idempotent.
+- **First-user registration shows "registration disabled".** The
+  bundled image ships with registration enabled; the toggle lives in
+  `app_settings.singleton.registrationEnabled`. The admin panel can
+  flip it back if a previous owner closed it.
+- **Service unreachable on `localhost:3000`.** Check `docker compose
+  ps` — the `app` healthcheck polls `/api/version` every 30 seconds
+  and will mark the container unhealthy if Postgres is still
+  starting. Tail `docker compose logs db` to confirm Postgres came up
+  cleanly.
+- **OAuth callbacks loop back to localhost.** Confirm `APP_URL` and
+  `NEXT_PUBLIC_APP_URL` both point at the public hostname, not at
+  `localhost`, and restart `app` after the change.

docs/self-hosting/reproductive-health-data.md

@@ -0,0 +1,103 @@
+# Reproductive-health data on your own server
+
+HealthLog's cycle tracking stores menstrual, fertility, and related
+reproductive-health data the same way it stores every other metric: in
+the PostgreSQL database that runs on the host you control, encrypted at
+rest for the intent-revealing fields. This page explains what that
+arrangement does and does not change about who can reach that data, in
+plain terms and without overstating the protection.
+
+## What self-hosting changes
+
+A consumer cycle-tracking app runs on the vendor's servers. Your
+reproductive-health data lives in their database, under their keys, in
+their jurisdiction. If that vendor receives a subpoena, a civil
+discovery request, or a law-enforcement demand it judges valid, the
+vendor — not you — decides how to respond, and it holds the data and the
+keys needed to comply. Several vendors state in their own privacy
+policies that they comply with valid legal process; that is a factual
+description of where the data sits, not an accusation.
+
+Self-hosting removes that vendor from the picture. There is no cloud
+account holding your cycle data, no vendor key escrow, and no third
+party that can be served process to hand over data it does not have. The
+honest framing is narrow and worth stating precisely:
+
+> Self-hosting means there is no cloud vendor to subpoena for your
+> reproductive-health data. It does **not** make the data
+> unreachable.
+
+The encryption-at-rest layer is real: the intent-revealing day-log
+fields (free-text notes always; pregnancy, contraception, and
+sexual-activity fields by default for this category) are encrypted with
+AES-256-GCM under a key you supply via `ENCRYPTION_KEYS`, and the
+application fails closed rather than ever writing those fields in
+plaintext. Flow, basal body temperature, ovulation-test results,
+cervical-mucus observations, and the cycle dates stay in plaintext
+because the prediction and correlation engines read them; they are
+health observations, not the disclosure-sensitive intent fields.
+
+## The residual threat (read this part)
+
+Self-hosting moves the data onto a box you own. That box can still be
+reached:
+
+- **Physical or legal seizure of your own host.** If the machine
+  running PostgreSQL — your VPS, your home server, your NAS — is seized,
+  imaged, or compelled, the data is on it. Encryption at rest protects
+  against a stolen disk or a leaked backup only while the key is *not*
+  also available; if the host is running, or the key is stored next to
+  the data, that protection is gone.
+- **Your hosting provider.** A VPS provider can snapshot your disk and
+  can be served process the same way a SaaS vendor can. Self-hosting on
+  rented infrastructure narrows the set of parties who hold your data;
+  it does not reduce it to zero.
+- **Your own backups.** Off-host backups (the optional S3 export, or any
+  `pg_dump` you take) carry the same data. Encrypt them, control where
+  they land, and treat them as part of the same threat surface.
+- **The device that talks to the server.** A phone or laptop with a
+  live session, a cached PWA, or the native client holds data locally
+  too. Protecting the server does nothing for an unlocked device.
+
+The promise is therefore specific: **no cloud vendor to subpoena**, not
+**data nobody can ever reach**. If your threat model includes seizure of
+your own infrastructure, encryption at rest plus a key you keep off the
+host is the floor, and the threat-model note below covers the rest.
+
+## Public record
+
+The reason this distinction matters is documented in public legal
+record, not speculation:
+
+- In 2021 the U.S. Federal Trade Commission settled with the maker of a
+  period- and fertility-tracking app over allegations that it shared
+  users' health data with third-party analytics and advertising
+  services despite privacy promises. The settlement is public record.
+- In 2025 a federal jury found that the same app's maker violated a
+  California privacy statute over the sharing of menstrual-tracking
+  data; the verdict and the underlying class action are public record.
+
+These are cited as factual public record to explain *why* the
+"who holds the data" question is the one that matters for this category.
+HealthLog makes no claim about any other product's current practices.
+
+## Practical hardening
+
+If reproductive-health privacy is the reason you self-host, the
+operator-side steps that matter most:
+
+- Keep `ENCRYPTION_KEYS` off the host that runs PostgreSQL where your
+  threat model allows it (an injected secret at boot, not a file next to
+  the database). See `docs/ops/encryption-key-rotation.md`.
+- Turn off any integration you do not need. The fewer outbound paths,
+  the smaller the surface.
+- Encrypt and control your backups. The off-host backup feature uses
+  AES-GCM; the destination bucket and its access are yours to lock down.
+- Use the in-app **discreet notifications** toggle so cycle reminders
+  never name the event on a lock screen, and the **client-managed
+  reminders** path if you want the device, not the server, to own those
+  notifications.
+- Lock the devices that hold a live session.
+
+See also the [threat-model note](../security/cycle-data-threat-model.md)
+for a compact "protects against / does not protect against" summary.

docs/self-hosting/reverse-proxy.md

@@ -0,0 +1,254 @@
+# Reverse proxy configuration
+
+The bundled `docker-compose.yml` exposes HealthLog on plain HTTP at
+`localhost:3000`. Production deployments front the container with a
+reverse proxy that terminates TLS, sets the forwarded headers the
+rate-limiter trusts, and preserves the WebSocket upgrade path the
+streaming Coach surface depends on.
+
+This guide gives copy-paste blocks for five common fronts. Pick one;
+the env-var pairing is identical across them.
+
+## Pre-flight — env vars the proxy interacts with
+
+| Variable | Required for | Notes |
+| -------- | ------------ | ----- |
+| `NEXT_PUBLIC_APP_URL` | Every public-facing absolute URL the UI emits | Must match the hostname the proxy serves |
+| `APP_URL` | Server-side absolute URLs from background jobs | Mirror of the above; both must match |
+| `TRUST_PROXY_HOPS` | `X-Forwarded-For` chain trust | Defaults to `1` — one trusted hop |
+
+Set the URL pair to the public origin (`https://your-instance.example.com`)
+and restart the `app` container. The image reads both at startup; no
+rebuild needed.
+
+### `TRUST_PROXY_HOPS` — what to set it to
+
+`src/lib/api-response.ts` (`getClientIp`) reads the `X-Forwarded-For`
+chain from the **right**, counting back `TRUST_PROXY_HOPS` entries.
+This guards against a client rotating `X-Forwarded-For` per request
+to defeat IP-based rate limits.
+
+| Topology | `TRUST_PROXY_HOPS` |
+| -------- | ------------------ |
+| App is internet-facing with no proxy | `0` (XFF ignored entirely) |
+| Single proxy in front (Caddy / Traefik / Nginx / Coolify) | `1` (default) |
+| Cloudflare → your proxy → app | `2` |
+| Cloudflare → Coolify-Tunnel → Coolify → app | `3` |
+
+A misconfigured count logs a one-shot warning to stderr and collapses
+every anonymous caller into one shared rate-limit bucket. Match the
+value to the actual hop count or set it to `0` and let `x-real-ip`
+drive the IP resolution.
+
+## Caddy
+
+`Caddyfile`:
+
+```
+your-instance.example.com {
+    encode zstd gzip
+    reverse_proxy localhost:3000 {
+        header_up X-Forwarded-For {remote_host}
+        header_up X-Forwarded-Proto {scheme}
+        header_up Host {host}
+        flush_interval -1
+    }
+}
+```
+
+Caddy handles the WebSocket upgrade automatically. `flush_interval -1`
+disables response buffering so the streaming insight events surface
+without batching delays. With Caddy as the only hop, leave
+`TRUST_PROXY_HOPS=1`.
+
+## Traefik
+
+`docker-compose.override.yml` snippet:
+
+```yaml
+services:
+  app:
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.healthlog.rule=Host(`your-instance.example.com`)"
+      - "traefik.http.routers.healthlog.entrypoints=websecure"
+      - "traefik.http.routers.healthlog.tls.certresolver=letsencrypt"
+      - "traefik.http.services.healthlog.loadbalancer.server.port=3000"
+      - "traefik.http.middlewares.healthlog-headers.headers.customrequestheaders.X-Forwarded-Proto=https"
+      - "traefik.http.routers.healthlog.middlewares=healthlog-headers"
+```
+
+Traefik forwards `X-Forwarded-For` by default and respects the WebSocket
+upgrade. Pair with `TRUST_PROXY_HOPS=1`. If Traefik sits behind
+Cloudflare, set it to `2` so the rate-limiter reads the real client IP
+that Cloudflare placed in the chain.
+
+## Nginx Proxy Manager
+
+In the NPM UI:
+
+1. **Proxy Hosts → Add Proxy Host.**
+2. **Domain Names:** `your-instance.example.com`.
+3. **Scheme:** `http`; **Forward Hostname / IP:** the Docker host or
+   internal hostname; **Forward Port:** `3000`.
+4. Enable **Websockets Support** (required for streaming Coach
+   responses).
+5. **SSL tab:** request a Let's Encrypt certificate, force SSL.
+6. **Advanced tab — Custom Nginx Configuration:**
+
+   ```nginx
+   proxy_set_header X-Real-IP $remote_addr;
+   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+   proxy_set_header X-Forwarded-Proto $scheme;
+   proxy_set_header Host $host;
+   proxy_http_version 1.1;
+   proxy_set_header Upgrade $http_upgrade;
+   proxy_set_header Connection "upgrade";
+   proxy_read_timeout 300s;
+   ```
+
+   The 300-second read timeout matters for long-running insight
+   generations — anything shorter will cut streamed responses mid-flight.
+
+Pair with `TRUST_PROXY_HOPS=1`.
+
+## Coolify
+
+Coolify's bundled Traefik handles most of this. The pieces that need
+operator attention:
+
+1. **Application → Domains:** set `https://your-instance.example.com`.
+   Coolify provisions the certificate and adds the Traefik labels.
+2. **Application → Environment Variables:** set
+   `NEXT_PUBLIC_APP_URL`, `APP_URL`, and any optional secrets
+   (`WITHINGS_*`, `APNS_*`, `LOKI_*`).
+3. **Application → General → Pull policy:** `always`. The bundled
+   `docker-compose.yml` declares this explicitly (v1.4.34.2 fix) so
+   Coolify re-checks the GHCR digest on every redeploy instead of
+   reusing the cached `:latest` layer.
+4. **Notifications → Webhook:** point at `/api/internal/deploy-webhook`
+   with the `X-Deploy-Webhook-Secret` header set to
+   `DEPLOY_WEBHOOK_SECRET`. The app gates the endpoint with a
+   timing-safe compare against that env var.
+
+### DO NOT set as runtime env vars
+
+The following variables are **build-time only** — they are injected
+via `--build-arg` by the `docker-publish` workflow and baked into the
+shipped image. Setting them under Coolify's *Environment Variables*
+panel has zero effect on the running container, and the stale value
+becomes a misleading artefact next time someone audits the deploy
+config:
+
+- `NEXT_PUBLIC_APP_VERSION` — sourced from the GHCR tag at build
+  time. Next.js inlines the value into both the client bundle (so
+  the `<VersionPoller>` self-healing reload compares against the
+  shipped shell) and the `/api/version` server route (so the public
+  endpoint returns the same string). The `env: {…}` block in
+  `next.config.ts` short-circuits the runtime `process.env` read.
+- `NEXT_PUBLIC_APP_BUILD_SHA`, `NEXT_PUBLIC_APP_BUILT_AT` — same
+  pattern. The CI workflow stamps the short SHA and build timestamp
+  into the image during `pnpm build`.
+
+If you spot any of these in the Coolify panel, delete the entry. The
+image already carries the correct value.
+
+Coolify-Tunnel adds one hop to the chain; pair with
+`TRUST_PROXY_HOPS=2`. If you front Coolify itself with Cloudflare,
+bump to `3`.
+
+## Bare Nginx
+
+`/etc/nginx/sites-available/healthlog`:
+
+```nginx
+upstream healthlog {
+    server 127.0.0.1:3000;
+    keepalive 16;
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name your-instance.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/your-instance.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-instance.example.com/privkey.pem;
+
+    client_max_body_size 1600M;  # Apple Health export.zip cap is 1.5 GB
+
+    location / {
+        proxy_pass http://healthlog;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 300s;
+        proxy_buffering off;
+    }
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name your-instance.example.com;
+    return 301 https://$host$request_uri;
+}
+```
+
+`client_max_body_size 1600M` is the load-bearing setting if you plan
+to support Apple Health `export.zip` uploads — the app caps the
+upload at 1.5 GB and Nginx will reject the body before the app sees
+it otherwise. `proxy_buffering off` keeps streamed insight events
+flowing without buffer pauses. Pair with `TRUST_PROXY_HOPS=1`.
+
+## Verifying the proxy chain
+
+Once the proxy is in front, hit `https://your-instance.example.com/api/version`
+from outside the host and check `docker compose logs app` for the
+request. The wide-event log line should carry a non-null client IP
+that matches your real source address. A `null` IP or a single
+`unknown` rate-limit bucket means `TRUST_PROXY_HOPS` is set higher
+than the actual proxy hop count, or the proxy is dropping the
+`X-Forwarded-For` header entirely.
+
+The one-shot stderr warning `[getClientIp] TRUST_PROXY_HOPS=N but
+X-Forwarded-For carried M entries` confirms a mismatch. Adjust the
+env var down to the actual chain length and restart.
+
+## Running over plain HTTP on a LAN (no reverse proxy)
+
+The session cookie carries the `Secure` flag by default under
+`NODE_ENV=production`, which is what the bundled Docker image runs.
+On a plain-HTTP origin that is not `localhost` / `127.0.0.1` / `::1`,
+modern browsers silently drop a `Secure` cookie before sending the
+next request — the login round-trip looks like it succeeds (the
+server returns 200 + `Set-Cookie`) but the very next page load
+401s and bounces back to `/auth/login`.
+
+If you genuinely want to serve HealthLog on `http://10.0.0.42:3000`
+or `http://healthlog.lan:3000` (NAS, homelab, Tailscale-only
+surface) and trust the network the traffic crosses, set:
+
+```
+SESSION_COOKIE_SECURE=false
+```
+
+in your `.env`. The session, onboarding-hint, Withings OAuth state,
+and Codex device-OAuth state cookies all stop emitting `Secure` and
+login works over HTTP. The trade-off is explicit: the session
+cookie crosses the wire unencrypted, so the network it traverses
+needs to be one you control.
+
+**Do not set this on a deployment that ever serves plain HTTP to the
+open internet.** Anyone with passive network access can capture the
+session cookie and impersonate the user. The right answer for any
+public-facing host is the reverse proxy + Let's Encrypt path
+documented above.
+
+The default behaviour is unchanged when this variable is unset —
+deployments behind an HTTPS-terminating proxy keep setting `Secure`
+exactly as before.

docs/self-hosting/scaling.md

@@ -0,0 +1,122 @@
+# Scaling: web/worker container split
+
+The default `docker compose up` launches a single container that runs
+both the Next.js HTTP server AND the pg-boss worker. That works fine
+for a personal deployment but is hard to scale horizontally because
+every replica also runs the full reminder/insight cron schedule.
+
+v1.4 introduces an environment-variable gate so the same image can be
+deployed in three modes:
+
+| `HEALTHLOG_PROCESS_TYPE` | Web | Worker | Use when                  |
+| ------------------------ | --- | ------ | ------------------------- |
+| `all` (default)          | ✅  | ✅     | single-host self-hosting  |
+| `web`                    | ✅  | ❌     | scaling HTTP horizontally |
+| `worker`                 | ❌  | ✅     | dedicated job worker      |
+
+## How to split
+
+1. Edit `docker-compose.yml`: set `HEALTHLOG_PROCESS_TYPE=web` on the
+   `app` service and uncomment the `app-worker` service block at the
+   bottom (it ships with `HEALTHLOG_PROCESS_TYPE=worker` baked in).
+2. Make sure both containers see the same `DATABASE_URL`,
+   `ENCRYPTION_KEY` (or `ENCRYPTION_KEYS`), and `API_TOKEN_HMAC_KEY`.
+3. `docker compose up -d --build`.
+
+Both containers connect to the same Postgres. pg-boss claims jobs
+atomically via row-level locking, so it is safe to run multiple worker
+replicas — they will share the load.
+
+## Healthchecks
+
+- `app` (web) healthcheck: `wget /api/version` every 30s.
+- `app-worker` does not expose a port; its liveness is reported into
+  the `worker_status` table on every reminder pass and surfaced through
+  `/api/admin/worker-status`.
+
+The web container does NOT depend on the worker, and vice versa, so
+neither container's startup can deadlock the other. The shared
+dependency is Postgres; both wait on `db: condition: service_healthy`.
+
+## Caveats
+
+- Background tasks that touch user-scoped Wide Events (e.g. reminder
+  notifications) emit telemetry from the worker; configure `LOKI_*`
+  env vars on the worker if you want them.
+- The off-host backup job runs in the worker only. The admin
+  `POST /api/admin/backup/test` endpoint runs in the web container and
+  exercises the same S3 credentials — set `BACKUP_*` env vars on BOTH.
+- The startup gate (`assertSubsystemEnabled`) refuses to boot the
+  reminder worker when `HEALTHLOG_PROCESS_TYPE=web`, so an accidental
+  cross-mode invocation aborts immediately instead of silently doubling
+  cron load.
+
+## Postgres connection-pool sizing
+
+Every container that boots the HealthLog image opens its own
+`pg.Pool` against the configured `DATABASE_URL`. The pool ceiling is
+**20 connections per container by default** (raised from the library
+default of 10 in v1.4.40 to keep the dashboard's analytics fan-out
+from starving every other query during a cold mount).
+
+Plan total Postgres slots as **container_count × `DATABASE_POOL_MAX`**.
+A stock Postgres 16 container ships with `max_connections = 100`, so
+the safe envelope is:
+
+| Web replicas | Worker replicas | Total containers | Pool slots used | Headroom under 100 |
+| ------------ | --------------- | ---------------- | --------------- | ------------------ |
+| 1            | 0               | 1                | 20              | 80                 |
+| 1            | 1               | 2                | 40              | 60                 |
+| 2            | 1               | 3                | 60              | 40                 |
+| 3            | 1               | 4                | 80              | 20                 |
+| 4            | 1               | 5                | 100             | 0 (do not exceed)  |
+
+Once the table tips into the "0 headroom" row, every other client of
+the same Postgres — `psql` sessions, ad-hoc backups, the Prisma CLI
+during a migration deploy — will get `FATAL: sorry, too many clients
+already`. Either raise `max_connections` on the Postgres side, lower
+`DATABASE_POOL_MAX`, or front the database with PgBouncer in
+transaction-pooling mode.
+
+### Overriding the per-container pool ceiling
+
+Set `DATABASE_POOL_MAX` to a positive integer on every container that
+needs a non-default ceiling — both web and worker pick up the same
+env var:
+
+```yaml
+# docker-compose.yml — example for a 6-container deployment
+services:
+  app:
+    image: ghcr.io/mbombeck/healthlog:latest
+    environment:
+      DATABASE_POOL_MAX: "12"     # 6 containers × 12 = 72 < 100
+      HEALTHLOG_PROCESS_TYPE: web
+```
+
+Rules of thumb:
+
+- Each web replica's hottest path (`/api/analytics` fan-out, capped at
+  `p-limit(4)`) consumes 4 concurrent slots. Keep
+  `DATABASE_POOL_MAX ≥ 8` so a single power-user request never
+  exhausts the pool of one container.
+- Worker replicas mostly use 1 connection per active pg-boss job;
+  `DATABASE_POOL_MAX = 8` is plenty unless you raised the pg-boss
+  `teamConcurrency`.
+- If you raise Postgres `max_connections` past 100, prefer raising
+  `DATABASE_POOL_MAX` over adding more containers — fewer, fatter
+  Node processes amortise the V8 footprint better than many thin
+  ones.
+
+### Why the default is 20
+
+The v1.4.39 empirical cold-mount trace showed thick `/api/analytics`
+holding ≥ 8 of the 10 default pool slots for 6.5 s on a 347 k-row
+tenant, starving every other dashboard query for the duration. The
+20-slot default — paired with the `p-limit(4)` cap on the analytics
+fan-out — keeps 16 slots free for the rest of the dashboard while
+still sitting well under Postgres's 100-slot stock ceiling.
+
+The implementation lives in `src/lib/db.ts → getPoolMax()`; the
+20-slot default was chosen after measuring on a 4-CPU production
+container — see the inline rationale in `getPoolMax()`.

docs/superpowers/specs/2026-04-06-codex-oauth-insights-design.md

@@ -1,359 +0,0 @@
-# Codex OAuth + Medizinische Insights — Design Spec
-
-**Datum:** 2026-04-06
-**Status:** Approved
-**Scope:** Replace OpenAI API-Key flow with ChatGPT Codex OAuth, improve medical insight prompts
-
-## 1. Problem
-
-HealthLog uses user-provided OpenAI API keys for AI-powered health insights. The API quota ran out (`insufficient_quota`), breaking all insight generation and background jobs. Users shouldn't need to manage API billing.
-
-## 2. Solution
-
-Replace the API-key model with **OpenAI Codex OAuth** — users authenticate with their ChatGPT Pro/Max subscription, and insights run against their flat-rate plan. An admin-level API key serves as a global fallback.
-
-## 3. Provider Hierarchy
-
-```
-1. User has Codex OAuth connection → Codex Responses API (gpt-5.3-codex)
-2. Admin key configured → Standard OpenAI Chat Completions API (configurable model)
-3. Nothing configured → Local fallback texts (no-key-fallbacks.ts)
-```
-
-## 4. Architecture
-
-### New Files
-
-```
-src/lib/ai/
-  provider.ts          — resolveProvider(userId) → { type, client, model }
-  codex-oauth.ts       — PKCE generation, token exchange, refresh
-  codex-client.ts      — Codex Responses API client with auto-refresh
-  openai-client.ts     — Standard OpenAI client (admin key, configurable base URL)
-  types.ts             — Shared types (InsightResult, ProviderConfig, etc.)
-  prompts/
-    base-system.ts     — Shared medical context, role, constraints
-    general-status.ts  — Holistic health assessment prompt
-    blood-pressure.ts  — ESC/ESH guideline-based BP analysis
-    weight.ts          — BMI context, trend analysis, plateau detection
-    pulse.ts           — Resting HR trends, stress correlation
-    bmi.ts             — WHO classification, age-adjusted
-    medication-compliance.ts — Intake patterns, efficacy correlation
-    schema.ts          — Zod schema for InsightResult validation
-```
-
-### Modified Files
-
-```
-src/app/api/auth/codex/authorize/route.ts    — NEW: Start OAuth flow
-src/app/api/auth/codex/callback/route.ts     — NEW: Handle OAuth callback
-src/app/api/auth/codex/disconnect/route.ts   — NEW: Remove tokens
-src/app/api/admin/ai-settings/route.ts       — NEW: Admin key management
-src/app/api/insights/generate/route.ts       — MODIFY: Use provider abstraction
-src/app/api/insights/settings/route.ts       — MODIFY: Show Codex status instead of API key
-src/app/api/insights/*/route.ts              — MODIFY: New output schema
-src/lib/insights/*.ts                        — MODIFY: Use new prompts + provider
-src/lib/jobs/reminder-worker.ts              — MODIFY: Use provider with auto-refresh
-src/proxy.ts                                 — MODIFY: Add /api/auth/codex/callback to PUBLIC_PATHS
-prisma/schema.prisma                         — MODIFY: New fields, remove openaiKeyEncrypted
-```
-
-### Removed Files/Code
-
-```
-src/app/api/insights/settings/route.ts       — OpenAI key PUT handler (replaced)
-src/lib/insights/prompt.ts                   — Single prompt file (replaced by prompts/)
-User.openaiKeyEncrypted                      — DB field removed
-```
-
-## 5. OAuth Flow
-
-### Authorization (User-initiated)
-
-```
-1. User clicks "Mit ChatGPT verbinden" in Settings
-2. GET /api/auth/codex/authorize
-   - Generate PKCE code_verifier (128 bytes, base64url)
-   - Compute code_challenge = SHA-256(code_verifier), base64url
-   - Generate random state parameter
-   - Store code_verifier + state in session
-   - Redirect to: chatgpt.com/authorize?
-       response_type=code
-       &code_challenge=<challenge>
-       &code_challenge_method=S256
-       &redirect_uri=https://healthlog.bombeck.io/api/auth/codex/callback
-       &state=<state>
-3. User logs in at ChatGPT, grants access
-4. Redirect to /api/auth/codex/callback?code=...&state=...
-5. Validate state against session
-6. Exchange code for tokens (POST chatgpt.com/oauth/token)
-7. Encrypt access_token + refresh_token with AES-256-GCM
-8. Store in User record with expiresAt
-9. Redirect to /settings with success toast
-```
-
-### Token Refresh (Automatic)
-
-```
-Before every API call:
-  if codexTokenExpiresAt < now + 5min:
-    POST chatgpt.com/oauth/token (grant_type=refresh_token)
-    Store new encrypted tokens + new expiresAt
-    If refresh fails:
-      Increment failCount
-      If failCount >= 3 over 72h:
-        Set codexConnectionStatus = 'expired'
-        Fall back to admin key silently
-      Else:
-        Retry on next call
-
-On 401 response:
-  Refresh token immediately, retry request once
-```
-
-### Disconnect
-
-```
-DELETE /api/auth/codex/disconnect
-  - Delete tokens from DB
-  - Revoke at OpenAI if endpoint exists
-  - Audit log entry
-```
-
-## 6. Database Changes
-
-### Prisma Schema
-
-```prisma
-model User {
-  // REMOVE:
-  // openaiKeyEncrypted    String?
-
-  // ADD:
-  codexAccessTokenEncrypted   String?
-  codexRefreshTokenEncrypted  String?
-  codexTokenExpiresAt         DateTime?
-  codexConnectedAt            DateTime?
-  codexConnectionStatus       String    @default("disconnected")
-  // Values: "connected", "disconnected", "expired"
-}
-
-model AppSettings {
-  // ADD:
-  adminAiKeyEncrypted   String?
-  adminAiModel          String   @default("gpt-4o-mini")
-  adminAiBaseUrl        String   @default("https://api.openai.com/v1")
-}
-```
-
-### Migration
-
-```sql
--- Add new columns
-ALTER TABLE users ADD COLUMN codex_access_token_encrypted TEXT;
-ALTER TABLE users ADD COLUMN codex_refresh_token_encrypted TEXT;
-ALTER TABLE users ADD COLUMN codex_token_expires_at TIMESTAMP;
-ALTER TABLE users ADD COLUMN codex_connected_at TIMESTAMP;
-ALTER TABLE users ADD COLUMN codex_connection_status TEXT NOT NULL DEFAULT 'disconnected';
-
-ALTER TABLE app_settings ADD COLUMN admin_ai_key_encrypted TEXT;
-ALTER TABLE app_settings ADD COLUMN admin_ai_model TEXT NOT NULL DEFAULT 'gpt-4o-mini';
-ALTER TABLE app_settings ADD COLUMN admin_ai_base_url TEXT NOT NULL DEFAULT 'https://api.openai.com/v1';
-
--- Remove old column
-ALTER TABLE users DROP COLUMN openai_key_encrypted;
-```
-
-## 7. Insight Output Schema
-
-### New InsightResult (replaces old changed/stable/drivers/nextSteps)
-
-```typescript
-interface InsightResult {
-  summary: string
-  classification: 'optimal' | 'gut' | 'grenzwertig' | 'erhoht' | 'kritisch'
-  findings: {
-    label: string
-    value: string
-    assessment: 'positive' | 'neutral' | 'attention' | 'warning'
-    guideline?: string
-  }[]
-  correlations: {
-    factor: string
-    effect: string
-    confidence: 'hoch' | 'mittel' | 'gering'
-  }[]
-  recommendations: string[]
-  dataQuality: {
-    coverage: string
-    gaps: string[]
-    confidence: 'hoch' | 'mittel' | 'gering'
-  }
-  disclaimer: string
-}
-```
-
-### Zod Validation
-
-Every AI response is validated against a Zod schema before being stored.
-Invalid responses are logged as errors and the user gets a generic fallback.
-
-## 8. Prompt Design
-
-### Base System Prompt
-
-```
-Du bist ein klinischer Gesundheitsanalyst mit Expertise in Innerer Medizin
-und Präventivmedizin. Deine Analyse basiert auf aktuellen Leitlinien
-(ESC/ESH 2023, WHO, DGE, DEGAM).
-
-Regeln:
-- Evidenzbasiert: Referenziere Grenzwerte und Leitlinien explizit
-- Muster erkennen: Tageszeit, Wochentag, saisonale Trends
-- Korrelationen: Wechselwirkungen zwischen Medikation und Vitalwerten benennen
-- Limitationen: Klar kommunizieren was die Datenlage hergibt und was nicht
-- Kein Ersatz für ärztliche Diagnose — immer explizit als Disclaimer
-- Sprache: Deutsch, medizinisch präzise aber allgemeinverständlich
-- Antworte ausschließlich im vorgegebenen JSON-Schema
-```
-
-### Per-Type Specialization
-
-Each insight type adds domain-specific instructions:
-
-- **Blood Pressure**: ESC/ESH classification (optimal <120/80, normal <130/85, ...), morning surge detection, white-coat vs. masked hypertension hints, medication correlation
-- **Weight**: BMI-adjusted analysis, 7/30/90-day slope, plateau detection (±0.5kg over 14+ days), realistic goal projection
-- **Pulse**: Resting HR zones (bradycardia <50, athletic 50-60, normal 60-100, tachycardia >100), trend stability, stress/recovery indicators
-- **BMI**: WHO classification, waist-to-height hints if available, age context
-- **Medication Compliance**: Pattern analysis (morning vs evening adherence), streak tracking, correlation with vital sign improvements
-- **General Status**: Cross-domain synthesis, risk stratification, most impactful change recommendation
-
-## 9. UI Changes
-
-### User Settings (/settings)
-
-Replace "OpenAI API Key" section with:
-
-```
-KI-Insights
-┌─────────────────────────────────────────┐
-│ Status: 🟢 Verbunden mit ChatGPT       │
-│ Verbunden seit: 02.04.2026             │
-│                                         │
-│ [Trennen]                               │
-│                                         │
-│ ℹ️ Insights werden über dein ChatGPT-   │
-│ Abo generiert (keine zusätzlichen       │
-│ Kosten).                                │
-└─────────────────────────────────────────┘
-```
-
-Or when disconnected:
-
-```
-KI-Insights
-┌─────────────────────────────────────────┐
-│ Status: ⚪ Nicht verbunden              │
-│                                         │
-│ [Mit ChatGPT verbinden]                 │
-│                                         │
-│ ℹ️ Verbinde dein ChatGPT Pro/Max-Konto  │
-│ um KI-gestützte Gesundheitsanalysen zu  │
-│ erhalten.                               │
-└─────────────────────────────────────────┘
-```
-
-### Admin Settings (/settings — ADMIN only)
-
-```
-KI-Anbieter (Global)
-┌─────────────────────────────────────────┐
-│ API Key:  [sk-...****________] [Testen] │
-│ Modell:   [gpt-4o-mini ▾]              │
-│ Base URL: [https://api.openai.com/v1]   │
-│                                         │
-│ ℹ️ Wird als Fallback verwendet, wenn    │
-│ ein User keine eigene ChatGPT-          │
-│ Verbindung hat.                         │
-│                                         │
-│ [Speichern]                             │
-└─────────────────────────────────────────┘
-```
-
-### Insights Display
-
-Update insight cards to render the richer InsightResult:
-- Classification badge with color (green/yellow/orange/red)
-- Findings list with assessment icons
-- Collapsible correlations section
-- Data quality indicator (small badge)
-- Disclaimer footer (smaller text)
-
-## 10. Security
-
-### OAuth Security
-- PKCE (S256) prevents authorization code interception
-- State parameter prevents CSRF
-- Tokens encrypted at rest (AES-256-GCM via existing crypto.ts)
-- Tokens never sent to client/browser
-- Refresh token rotation on every refresh
-- Callback route validates state against session
-
-### Admin Key Security
-- Only ADMIN role can read/write
-- Key displayed masked in UI (sk-...****)
-- Rate limiting on admin key usage (prevents abuse by many users)
-- Encrypted at rest
-
-### Audit Trail
-- Every OAuth connect/disconnect logged
-- Every insight generation logs: provider type, user, model, duration
-- Admin key changes logged
-
-### Security Audits (3x)
-1. **Pre-Implementation**: OAuth flow validated against OWASP OAuth Security Checklist
-2. **Post-Implementation**: Code review agent checks all new files for injection, token leaks, unencrypted secrets
-3. **Post-Deploy**: Penetration test of OAuth endpoints (CSRF, token theft, callback manipulation)
-
-## 11. Testing Strategy (TDD)
-
-### Unit Tests (vitest)
-
-| Suite | Coverage |
-|-------|----------|
-| `ai/provider.test.ts` | Provider hierarchy, correct client selection |
-| `ai/codex-oauth.test.ts` | PKCE generation, token exchange, refresh, error scenarios |
-| `ai/codex-client.test.ts` | Request format, auto-refresh on 401, retry with backoff |
-| `ai/openai-client.test.ts` | Chat completions format, custom base URL, error handling |
-| `ai/prompts/*.test.ts` | Prompt assembly per type, output schema validation with Zod |
-| `insights/*.test.ts` | Updated generators with new output schema |
-| `api/codex-callback.test.ts` | State validation, CSRF protection, token storage |
-| `api/admin-settings.test.ts` | ADMIN-only access, key encryption, validation |
-
-### Integration Tests
-- OAuth flow end-to-end (mocked ChatGPT endpoint)
-- Background job token refresh + insight generation
-- Provider fallback chain under different DB states
-
-## 12. CSP Changes
-
-```diff
-- connect-src 'self' https://api.openai.com https://wbsapi.withings.net
-+ connect-src 'self' https://api.openai.com https://chatgpt.com https://wbsapi.withings.net
-```
-
-## 13. Migration Path
-
-1. Deploy new code with both old (openaiKeyEncrypted) and new fields
-2. Run migration to add new columns
-3. Remove old column in follow-up migration
-4. Users see "Nicht verbunden" in settings, can connect via OAuth
-5. Admin can configure fallback key immediately
-6. Old cached insights remain visible until refreshed
-
-## 14. Out of Scope
-
-- Multiple AI providers per user (only Codex OAuth OR admin key)
-- Custom model selection per user (model is fixed per provider)
-- Streaming responses (batch only, like current implementation)
-- OpenAI API key input for individual users (removed entirely)

docs/superpowers/specs/2026-04-18-blood-glucose-tracking-design.md

@@ -1,207 +0,0 @@
-# Blood Glucose Tracking — Design Spec
-
-**Datum:** 2026-04-18
-**Status:** Draft
-**Scope:** Add `BLOOD_GLUCOSE` as a first-class measurement type with context-aware classification (fasting / postprandial / random / bedtime), user-selectable display unit (mg/dL ↔ mmol/L), reference ranges from ADA 2024 and DGIM 2023, and full integration across form, charts, targets, doctor PDF, and insights.
-
-## 1. Problem Statement
-
-Users repeatedly request blood-sugar logging — most recently in **GitHub issue #73, point 8**. Diabetics, pre-diabetics, and people on metabolic-impacting medication (steroids, atypical antipsychotics) need a single place to log glucose alongside weight, BP, and pulse so the doctor PDF reflects the complete metabolic picture. Today they fall back to spreadsheets or vendor-locked apps. Adding glucose to HealthLog closes the largest remaining gap in the "vital sign" set and unlocks correlation insights (e.g. weight ↔ fasting glucose, sleep ↔ glucose variability).
-
-## 2. Scope
-
-In v1 we ship:
-
-- A new `BLOOD_GLUCOSE` measurement type stored canonically in **mg/dL**.
-- A required **context tag** per reading: `FASTING`, `POSTPRANDIAL`, `RANDOM`, `BEDTIME`.
-- A user preference `glucoseUnit` (`MG_DL` | `MMOL_L`, default `MG_DL` for `de` users, can flip in settings) — display only; storage is canonical.
-- Context-aware classification (see §4) and a target card on `/targets` for fasting glucose; secondary line for postprandial when data exists.
-- Health chart with diabetes/pre-diabetes band overlays.
-- Doctor PDF row + classification line.
-- Insights descriptor "glucose control" (fasting avg + variability).
-
-**Stretch (v1.1, not in this spec):** HbA1c as a separate measurement type with its own classification (<5.7% / 5.7–6.4% / ≥6.5%, ADA 2024). Schema is forward-compatible (just add another enum value).
-
-## 3. Data Model
-
-```prisma
-enum MeasurementType {
-  WEIGHT
-  BLOOD_PRESSURE_SYS
-  BLOOD_PRESSURE_DIA
-  PULSE
-  BODY_FAT
-  SLEEP_DURATION
-  ACTIVITY_STEPS
-  BLOOD_GLUCOSE          // NEW
-}
-
-enum GlucoseContext {     // NEW
-  FASTING
-  POSTPRANDIAL
-  RANDOM
-  BEDTIME
-
-  @@map("glucose_context")
-}
-
-model Measurement {
-  // ...existing fields
-  glucoseContext GlucoseContext? @map("glucose_context")  // NEW, only set when type = BLOOD_GLUCOSE
-}
-
-model User {
-  // ...existing fields
-  glucoseUnit String @default("MG_DL") @map("glucose_unit")  // "MG_DL" | "MMOL_L"
-}
-```
-
-Migration `20260418_add_blood_glucose`:
-1. `ALTER TYPE measurement_type ADD VALUE 'BLOOD_GLUCOSE';`
-2. `CREATE TYPE glucose_context AS ENUM (...);`
-3. `ALTER TABLE measurements ADD COLUMN glucose_context glucose_context;`
-4. `ALTER TABLE users ADD COLUMN glucose_unit text NOT NULL DEFAULT 'MG_DL';`
-5. Add `CHECK ((type = 'BLOOD_GLUCOSE') = (glucose_context IS NOT NULL))` to enforce coupling.
-
-The unique constraint `(userId, type, measuredAt, source)` already prevents duplicates; context is intentionally **not** part of the key — the same timestamp can't legally carry two contexts.
-
-Storage unit is always **mg/dL** (`unit = "mg/dL"` in the row) so downstream analytics, exports, and Withings ingest don't need to branch.
-
-## 4. Classifications (`src/lib/analytics/classifications.ts`)
-
-New helpers, ranges from **ADA Standards of Care 2024** (Diabetes Care, Vol. 47, Suppl. 1) and **DGIM/DDG S3-Leitlinie 2023**:
-
-```ts
-export type GlucoseContext = "FASTING" | "POSTPRANDIAL" | "RANDOM" | "BEDTIME";
-
-export interface GlucoseClassification {
-  category: string;
-  color: string;
-  severity: "info" | "normal" | "warning" | "danger";
-}
-
-export function classifyGlucose(
-  mgdl: number,
-  context: GlucoseContext,
-): GlucoseClassification;
-```
-
-Boundaries (mg/dL — mmol/L conversion shown for traceability):
-
-| Context | Hypo (<70 / <3.9) | Normal | Pre-diabetes | Diabetes |
-|---------|-------------------|--------|--------------|----------|
-| FASTING | danger            | 70–99 (3.9–5.5) normal | 100–125 (5.6–6.9) warning | ≥126 (≥7.0) danger |
-| POSTPRANDIAL (2h) | danger | <140 (<7.8) normal | 140–199 (7.8–11.0) warning | ≥200 (≥11.1) danger |
-| RANDOM | danger | <140 normal | 140–199 warning | ≥200 danger |
-| BEDTIME | danger | 90–150 normal (info if outside) | — | ≥250 danger |
-
-Color tokens reuse the existing Dracula palette (`#50fa7b` normal, `#f1fa8c` info, `#ffb86c` / `#ff79c6` warning, `#ff5555` danger). Add `getGlucoseFastingRange()` returning `{ min: 70, max: 99 }` for the target card range bar, and `getGlucosePostprandialRange()` for the optional secondary bar.
-
-## 5. UI
-
-**Measurement form (`src/components/measurements/measurement-form.tsx`):**
-- New entry in `MEASUREMENT_TYPES`: `{ value: "BLOOD_GLUCOSE", labelKey: "measurements.typeGlucose", unitKey: "measurements.unitGlucose", placeholder: "95" }`.
-- When `type === "BLOOD_GLUCOSE"`, render an additional `<Select>` for context (4 options). Default = `FASTING` between 04:00–10:00 local time, else `RANDOM`.
-- Unit suffix is resolved via `useGlucoseUnit()` hook reading `user.glucoseUnit`; the input value is converted to mg/dL before POST.
-- Min 20, max 600 mg/dL (or equivalent mmol/L); inputs accept 1 decimal in mmol/L mode, integers in mg/dL mode.
-
-**Targets page (`src/app/targets/page.tsx`):**
-- New `TYPE_ICONS["BLOOD_GLUCOSE"]` = `Droplet` (Lucide), color token `text-dracula-yellow`.
-- Card title "Fasting glucose" with `RangeBar` 70–99, orangeMin 100, orangeMax 125 (puts pre-diabetes in yellow zone, diabetes in red).
-- If postprandial data exists in last 30 days, render a second labelled `RangeBar` below using `getGlucosePostprandialRange()`, mirroring the BP-diastolic pattern already in `TargetCard`.
-- Source link → `https://diabetesjournals.org/care/issue/47/Supplement_1` (ADA 2024).
-
-**Health chart (`src/components/charts/health-chart.tsx`):**
-- New chart preset on `/charts` page: `types: ["BLOOD_GLUCOSE"]`, color `var(--dracula-yellow)`, `valueBands` for pre-diabetes (100–125) and diabetes (≥126) overlays, plus a `ReferenceLine` at 70 (hypo).
-- Filter chips for context (All / Fasting / Postprandial / Random / Bedtime) — implemented as a client-side filter on the dataset, not a new API call.
-- Y-axis unit follows user pref (mg/dL or mmol/L); points are converted on render.
-
-**Insights:** Add `glucose-control.ts` insight returning `{ avgFasting, fastingInTargetPct, postprandialPeak, variability, classification }`. AI-friendly descriptor injected into the general-status prompt: `"glucose control: avg fasting {avg} mg/dL ({class}), {pct}% of fasting readings in target."`
-
-**Doctor PDF (`src/lib/doctor-report-pdf.ts`):**
-- `TYPE_LABEL_KEYS["BLOOD_GLUCOSE"] = "doctorReport.typeGlucose"`.
-- `TYPE_UNIT_KEYS["BLOOD_GLUCOSE"]` resolves to user pref via a new `unitFor(type, ctx)` extension.
-- Add `BLOOD_GLUCOSE` to `vitalTypes` array — table row appears automatically.
-- New optional section "Glukose-Klassifikation" below the BP block: shows fasting average + classification key, plus postprandial average if `count > 0`, with i18n keys `doctorReport.glucoseClassificationTitle`, `doctorReport.glucoseFastingRow`, `doctorReport.glucosePostprandialRow`.
-- Distribution table per context (n per FASTING/POSTPRANDIAL/RANDOM/BEDTIME) so the GP sees coverage.
-
-## 6. API
-
-No new endpoints. `POST /api/measurements` already accepts `type`, `value`, `measuredAt`, `notes` — extend the Zod schema in `src/lib/validations/measurement.ts` with optional `glucoseContext: z.enum([...])` and a refinement: `BLOOD_GLUCOSE` requires the context, other types reject it. The form sends mg/dL; conversion happens client-side.
-
-`/api/analytics` and `/api/insights/targets` add `BLOOD_GLUCOSE` to their type whitelists and emit a `glucose` summary object with per-context aggregates when ≥1 reading exists.
-
-`PATCH /api/auth/me` (already exists for profile updates) gains an optional `glucoseUnit` field.
-
-## 7. Conversion Helpers
-
-New module `src/lib/glucose.ts`:
-
-```ts
-export const GLUCOSE_FACTOR = 18.0182; // mg/dL per mmol/L (molar mass of glucose)
-
-export function mgdlToMmol(mgdl: number): number {
-  return Math.round((mgdl / GLUCOSE_FACTOR) * 10) / 10; // 1 decimal
-}
-
-export function mmolToMgdl(mmol: number): number {
-  return Math.round(mmol * GLUCOSE_FACTOR); // integer
-}
-
-export function formatGlucose(mgdl: number, unit: GlucoseUnit, t: T): string;
-```
-
-Round-trip rule: `mmolToMgdl(mgdlToMmol(x))` must be within ±1 mg/dL of `x` for x ∈ [40, 400]. Tested in §9.
-
-## 8. i18n Keys (`messages/de.json` + `messages/en.json`)
-
-| Key | DE | EN |
-|---|---|---|
-| `measurements.typeGlucose` | Blutzucker | Blood glucose |
-| `measurements.unitGlucose.mgdl` | mg/dL | mg/dL |
-| `measurements.unitGlucose.mmol` | mmol/L | mmol/L |
-| `measurements.glucoseContextLabel` | Kontext | Context |
-| `measurements.glucoseContextFasting` | Nüchtern | Fasting |
-| `measurements.glucoseContextPostprandial` | Nach dem Essen (2 h) | Post-meal (2h) |
-| `measurements.glucoseContextRandom` | Zufällig | Random |
-| `measurements.glucoseContextBedtime` | Vor dem Schlafen | Bedtime |
-| `targets.glucoseFastingTitle` | Nüchtern-Blutzucker | Fasting glucose |
-| `targets.glucosePostprandialTitle` | 2-h-Postprandial | 2h post-meal |
-| `targets.glucoseSourceAda` | ADA 2024 / DGIM 2023 | ADA 2024 / DGIM 2023 |
-| `classifications.glucoseHypo` | Hypoglykämie | Hypoglycemia |
-| `classifications.glucoseNormal` | Normal | Normal |
-| `classifications.glucosePrediabetes` | Prädiabetes | Pre-diabetes |
-| `classifications.glucoseDiabetes` | Diabetes-Bereich | Diabetes range |
-| `doctorReport.typeGlucose` | Blutzucker | Blood glucose |
-| `doctorReport.glucoseClassificationTitle` | Glukose-Klassifikation | Glucose classification |
-| `doctorReport.glucoseFastingRow` | Ø Nüchtern: {avg} {unit} — {class} | Avg fasting: {avg} {unit} — {class} |
-| `doctorReport.glucosePostprandialRow` | Ø Postprandial: {avg} {unit} — {class} | Avg postprandial: {avg} {unit} — {class} |
-| `settings.glucoseUnitLabel` | Blutzucker-Einheit | Blood glucose unit |
-| `insights.glucoseControlTitle` | Glukose-Kontrolle | Glucose control |
-
-## 9. Nyquist Validation
-
-- **Unit conversion**: property test — for every integer mg/dL in [40, 400], `mmolToMgdl(mgdlToMmol(x))` differs from `x` by ≤1.
-- **Classification boundaries**: assert `classifyGlucose(99, "FASTING").severity === "normal"`, `classifyGlucose(100, "FASTING").severity === "warning"`, `classifyGlucose(125, ...) === "warning"`, `classifyGlucose(126, ...) === "danger"`, `classifyGlucose(69, "FASTING").severity === "danger"` (hypo). Same for postprandial at 139/140/199/200.
-- **Schema refinement**: `POST /api/measurements` with `BLOOD_GLUCOSE` and missing `glucoseContext` returns 400; with non-glucose type and a `glucoseContext` returns 400.
-- **End-to-end smoke**: form submit → DB row → chart render → PDF generation; assert mg/dL stored regardless of UI unit, assert PDF row appears in `vitalRows`.
-- **Doctor PDF snapshot test**: render with mixed contexts, assert classification line and per-context distribution rows.
-
-## 10. Risks
-
-- **Hypoglycemia notifications**: showing "severe low — seek help" on every reading <54 mg/dL could panic users with sensor noise or delayed entries. Notifications are **opt-in** via NotificationPreference (`MEASUREMENT_ANOMALY` event), default off, and the message text always ends with "HealthLog ist kein Medizinprodukt — bei akuten Symptomen 112 anrufen."
-- **Unit confusion**: a user flipping the unit pref must not reinterpret historical mg/dL values as mmol/L. Migration sets a default; UI shows the unit suffix on every value.
-- **Withings overlap**: Withings supports glucose via some BGM integrations. Document that Withings sync stays disabled for glucose in v1 (out of scope) to avoid double-entry races.
-- **Context defaulting**: auto-selecting `FASTING` based on time of day is a heuristic; the user must always be able to override before save.
-
-## 11. Out of Scope
-
-- CGM (Dexcom / Libre) live integration.
-- Ketone (β-hydroxybutyrate) tracking.
-- Insulin dose log and bolus calculator.
-- Carb counting / meal logging.
-- HbA1c (deferred to v1.1, schema is ready).
-
-## 12. Effort
-
-**M (medium).** Roughly: schema + migration (S), classifications + conversion lib + tests (S), form/context selector + unit pref (M), targets card + chart preset (S), insight + PDF row + i18n (M), Nyquist tests (S). Estimate 1.5–2 dev-days end-to-end including review. No external dependencies, no new infra.

docs/superpowers/specs/2026-04-18-builtin-feedback-design.md

@@ -1,162 +0,0 @@
-# Built-in Feedback System — Design Spec
-
-**Status:** Proposed (v1.2+)
-**Date:** 2026-04-18
-**Owner:** TBD
-**Tracking:** GitHub issue #73 (point 6)
-**Effort:** M
-
-## 1. Problem Statement
-
-The current bug-report flow (`src/app/bugreport/page.tsx` + `src/app/api/bugreport/route.ts`) is gated on a GitHub token and repository configured by an admin. The status route returns `configured: false` when those are missing, and the UI degrades to an "ask your admin to configure GitHub" screen — so a non-technical owner of a self-hosted HealthLog instance cannot collect feedback at all without first procuring a GitHub PAT and dedicating a repo.
-
-Verbatim from issue #73, point 6: *"Provide a simple built-in feedback system where users can submit reports without GitHub accounts, repositories, or tokens. The app should handle issue creation automatically in the background. Alternatively, provide a pre-configured default repository maintained by the developer."*
-
-We need a feedback path that **works with zero external configuration**, while keeping the existing GitHub integration available as an **optional escalation** for instance owners who do want public issues.
-
-## 2. Approach
-
-- **Primary store: Postgres.** Every submission lands in a new `Feedback` table managed by Prisma. No external dependency required.
-- **Admin inbox UI** at `/admin#feedback` lists, filters and triages submissions.
-- **GitHub stays optional and per-item.** The admin can press "Publish to GitHub issue" on any feedback row; the existing route logic in `src/app/api/bugreport/route.ts` is refactored into a reusable helper and called from the new admin endpoint. If GitHub isn't configured, the button is hidden — the rest of the flow is unaffected.
-- **v1 admin notification: email** via the existing `src/lib/notifications/dispatcher.ts` (Telegram / ntfy / web-push reuse the same dispatcher). Optional; silent if no admin channel is configured.
-- **Existing `/api/bugreport` is deprecated but kept** for two release cycles so any external automation still works. Internally it forwards to the new feedback pipeline.
-
-## 3. Data Model
-
-New Prisma model in `prisma/schema.prisma`, additive only:
-
-```prisma
-enum FeedbackCategory { BUG FEATURE_REQUEST QUESTION OTHER }
-enum FeedbackStatus   { OPEN ACK RESOLVED ARCHIVED }
-
-model Feedback {
-  id                String           @id @default(cuid())
-  userId            String?          // nullable — see auth note below
-  user              User?            @relation(fields: [userId], references: [id], onDelete: SetNull)
-  email             String?          // snapshot of submitter email at time of submission
-  category          FeedbackCategory @default(BUG)
-  subject           String           @db.VarChar(200)
-  description       String           @db.Text  // ≤ 5000 chars enforced in Zod
-  screenshotBase64  String?          @db.Text  // ≤ 5 MB; later moved to object storage
-  metadata          Json?            // { url, userAgent, locale, appVersion, viewport, timestamp }
-  status            FeedbackStatus   @default(OPEN)
-  adminNote         String?          @db.Text
-  gitHubIssueUrl    String?
-  notifiedEmail     Boolean          @default(false)
-  createdAt         DateTime         @default(now())
-  updatedAt         DateTime         @updatedAt
-
-  @@index([status, createdAt])
-  @@index([userId])
-}
-```
-
-Notes:
-- `userId` is nullable to keep the door open for anonymous public-instance submissions in a later iteration; **v1 still requires auth** (`requireAuth()`), so the column will always be populated. The `email` snapshot survives user deletion for triage continuity.
-- `metadata` is a free-form JSON envelope mirroring the same context we'd otherwise paste into a GitHub issue body — we capture it once at submission time so the admin doesn't have to ask "what page were you on?".
-- An `AuditLog` row (`feedback.submit`, `feedback.status_change`, `feedback.publish_github`) follows the existing pattern in `src/lib/auth/audit.ts`.
-
-## 4. API
-
-All routes use `apiHandler` (Wide Events + x-request-id) and return the standard `{ data, error, meta }` envelope.
-
-| Method | Path | Auth | Purpose |
-|---|---|---|---|
-| `POST` | `/api/feedback` | user | Submit feedback. Rate-limited 5/h per `user.id`. Zod-validated. Returns `{ id, confirmationNumber }`. |
-| `GET`  | `/api/admin/feedback` | admin | Paginated list. Query params: `status`, `category`, `q`, `page`, `pageSize` (default 20, cap 100). |
-| `GET`  | `/api/admin/feedback/:id` | admin | Single item with raw `metadata` and screenshot. |
-| `PATCH`| `/api/admin/feedback/:id` | admin | Mutate `status` and/or `adminNote`. Writes audit log. |
-| `POST` | `/api/admin/feedback/:id/github` | admin | Publish to GitHub. 404 if GitHub not configured. Stores `gitHubIssueUrl` on success. |
-| `GET`  | `/api/feedback/status` | user | Public capability probe: `{ available: true, githubAvailable: boolean }`. Replaces `/api/bugreport/status`'s "configured: false" wall. |
-
-`apiSuccess` payloads use `confirmationNumber = id.slice(-6).toUpperCase()` so users can quote a short code without leaking the full cuid.
-
-## 5. UI
-
-### `/bugreport` (renamed conceptually to "Feedback", URL kept)
-- **Category** dropdown (Bug / Feature request / Question / Other).
-- **Subject** input (max 120 chars, required).
-- **Description** textarea (10–5000 chars, existing constraint).
-- **Screenshot** optional, same upload control as today, ≤ 5 MB, EXIF stripped client-side before base64 encoding.
-- **Submit** — always enabled when authenticated. No more "not configured" wall.
-- On success: toast "Thanks for your feedback — reference #ABC123".
-
-### Admin section `/admin#feedback`
-- Table: created, category badge, subject, status badge, submitter, actions.
-- Filters: status (OPEN/ACK/RESOLVED/ARCHIVED), category, free-text search over `subject`/`description`.
-- Detail dialog: full description, screenshot preview, raw `metadata` JSON, admin note textarea, action buttons **Ack** / **Resolve** / **Archive** / **Publish to GitHub** (last one only when `githubAvailable`).
-- Empty states (no feedback yet, no results for filter) with translated copy.
-
-## 6. Screenshot Handling
-
-- **Storage:** base64 in the `screenshotBase64` column. Hard cap **5 MB per item** (matching the current `bugReportSchema.screenshot` limit) and a soft per-user **20 MB total quota** rejected at submit with a 413.
-- **EXIF stripping** in the browser via canvas re-encode before upload — prevents inadvertent GPS leak.
-- **PII warning** in the form copy: "Your screenshot may contain personal data. Crop it before uploading if unsure."
-- **Risk acknowledged in §13** — DB bloat is the obvious downside; v2 moves blobs to object storage.
-
-## 7. Abuse & Safety
-
-- Rate-limit via `src/lib/rate-limit.ts`: `feedback:submit:${user.id}` → 5 per rolling hour. Admin endpoints rate-limited too (`feedback:admin:${user.id}`, 60/min).
-- Description and subject are **plain text** — no HTML, no Markdown rendering on display in the admin inbox (use `<pre>` or a plain `<div>` with `whitespace-pre-wrap`). When publishing to GitHub we apply the same backtick-escape sanitization as the current bugreport route.
-- Length caps enforced in Zod and at the DB level (`@db.VarChar(200)` for subject).
-- **Auto-archive job** in `src/lib/jobs/`: daily pg-boss job marks `RESOLVED` items older than 180 days as `ARCHIVED`, and deletes `ARCHIVED` items older than 365 days. Configurable via `AppSettings`.
-- Inbox-size soft cap (e.g., 10 000 OPEN rows) surfaces a banner in the admin UI prompting cleanup.
-
-## 8. Migration
-
-- Additive Prisma migration only (new enum, new table). No existing data touched.
-- `/api/bugreport` route stays for **two release cycles**, internally calls the new feedback pipeline, and emits a `Deprecation` response header pointing to `/api/feedback`.
-- `/api/bugreport/status` keeps responding for legacy clients but its `configured` field now means "feedback works" (always `true` for authenticated users), with `hasGithub` exposed separately.
-- No data backfill required.
-
-## 9. Notifications
-
-- On a successful `POST /api/feedback`, dispatch through `src/lib/notifications/dispatcher.ts` to whichever admin channels are configured (email-first for v1; Telegram/ntfy/web-push fall out for free since they share the dispatcher).
-- Payload: category, subject, submitter username, deep link `/admin#feedback?id=...`. **No description body** in the notification — keeps PII out of email/push transports.
-- `notifiedEmail = true` after a successful send so retries don't double-fire.
-- If no channel is configured, dispatch is a no-op (logged as an info annotation, not a warning).
-
-## 10. i18n
-
-New translation namespace `feedback.*` in `messages/en.json` and `messages/de.json`:
-- Category names (`feedback.category.bug` etc.), status names, form labels, admin-inbox column headers, action button labels, empty states, toast/confirmation copy, PII warning text, deprecation banner on legacy bugreport endpoint.
-- Existing `bugreport.*` keys stay until the route is removed; new UI does not depend on them.
-
-## 11. GitHub Publish
-
-- Refactor the GitHub-issue creation in `src/app/api/bugreport/route.ts` into `src/lib/feedback/publish-github.ts` — pure function `publishToGithub(feedback): Promise<{ issueNumber, issueUrl }>`. Reused by both the deprecated bugreport route (transparently) and the new `POST /api/admin/feedback/:id/github`.
-- Idempotency: if `gitHubIssueUrl` is already set on the feedback row, return 409 with the existing URL.
-- Admin can append optional context via a textarea in the publish dialog; this is prepended to the issue body and **not** stored on the feedback row.
-
-## 12. Nyquist Validation
-
-Acceptance scenarios that must pass before sign-off:
-- Submit while logged out → 401.
-- Submit 6 times in an hour → 6th returns 429 with rate-limit headers.
-- Screenshot > 5 MB → 413, no DB row created.
-- Cumulative user quota > 20 MB → 413 with quota-specific error code.
-- Non-admin hits `/api/admin/feedback*` → 403.
-- Publish-to-GitHub round-trip: feedback row gains `gitHubIssueUrl`, repeat call returns 409.
-- Auto-archive job marks correct rows after fast-forwarding clock in test.
-- Notification dispatch is silent when no channel configured (info event, not warning).
-- Plain-text rendering verified — submitting `<script>alert(1)</script>` displays escaped in admin UI.
-- Wide Event payload includes `action.name=feedback.submit`, `meta.category`, `meta.has_screenshot`.
-
-## 13. Risks
-
-- **DB bloat from base64 screenshots.** Mitigation: per-item + per-user quotas now, object storage migration (S3/MinIO/Coolify volume) tracked as a follow-up. Schema is forward-compatible — `screenshotBase64` becomes nullable alongside a future `screenshotKey` column.
-- **Email transport coupling.** If the dispatcher fails, submission must still succeed; notifications are fire-and-forget after the DB row commits.
-- **Admin-inbox UX scaling** past a few hundred items needs server-side filtering (already in the API spec).
-
-## 14. Out of Scope
-
-- User-to-user comment threads on feedback items.
-- Voting / upvoting feedback.
-- Public read-only feedback board.
-- Anonymous (logged-out) submissions — schema-ready, intentionally not enabled in v1.
-- Importing existing GitHub issues back into the inbox.
-
-## 15. Effort
-
-**M** — one Prisma migration, ~6 new API routes (most thin), one form refactor, one new admin section, refactor of existing GitHub call into a helper, dispatcher hookup, one pg-boss job, ~30 i18n keys × 2 locales.

docs/superpowers/specs/2026-04-18-custom-thresholds-design.md

@@ -1,227 +0,0 @@
-# User-Configurable Health Thresholds — Design Spec
-
-**Datum:** 2026-04-18
-**Status:** Draft
-**Scope:** Per-user override layer for the metric target ranges currently rendered on `/targets` and used across analytics.
-
-## 1. Problem
-
-HealthLog computes target ranges from established medical guidelines:
-
-- Weight from BMI 18.5–24.9 (WHO) via `getWeightRange` / `buildWeightBandsFromHeight`
-- BP targets age-personalized per ESC/ESH 2018 (`bp-targets.ts`, `getBpTargetsByAge`)
-- Pulse from CDC/NCHS percentiles or AHA fallback (`pulse-targets.ts`)
-- Body fat from ACE thresholds (`classifyBodyFat`)
-- Sleep duration from AASM/SRS (`getSleepDurationRange`)
-- Steps from WHO (`getStepsRange`)
-
-These are sane defaults, but real patients receive **doctor-recommended individual targets**. A diabetic with autonomic neuropathy may have a BP target of 110/65–135/80; a marathoner may have a personal "green" pulse band of 38–55 that the AHA bands flag as bradycardia; a recovering anorexia patient may have a clinically supervised weight floor above the BMI-18.5 line. Today the UI exposes computed ranges with **no override mechanism**, and analytics, alerts, and the doctor-report PDF all silently use the guideline values.
-
-## 2. Why (User Intent)
-
-- Users may have doctor-recommended personalized targets that differ from the default ESC/ESH / WHO / AHA guidelines.
-- Current UI shows computed defaults with no override mechanism.
-- User wants a dedicated settings page where thresholds can be overridden per metric, with the default still visible for comparison and one-click reset.
-
-## 3. Requirements
-
-1. **Per-metric override** for the full set: `WEIGHT` (min/max), `BLOOD_PRESSURE_SYS` (low/high), `BLOOD_PRESSURE_DIA` (low/high), `PULSE` (min/max), `BODY_FAT` (min/max), `SLEEP_DURATION` (min/max in hours), `ACTIVITY_STEPS` (min/max). Reserve slots for `BLOOD_GLUCOSE_FASTING` and `BLOOD_GLUCOSE_POSTPRANDIAL` even though they are not yet measured — the schema should not need a migration when the metric ships.
-2. **Optional yellow zone**: each metric may carry a separate `warnMin/warnMax` (orange band) in addition to `min/max` (green band). Falls back to the default's orange computation (currently `±30%` span via `buildTrafficRange`) if absent.
-3. **Comparable to default**: every UI surface that renders a range must be able to show "Default: X / Your override: Y" — the API therefore returns `defaults`, `overrides`, and `effective` together.
-4. **Reset to default per metric** — single-click, no confirm needed unless overrides existed (see §11).
-5. **Source-of-truth precedence**: `effective = override ?? default(profile)`. Default still recomputes when profile (height, age, gender) changes, so users who never override see no change in behavior.
-6. **Server-side validation** — overrides must satisfy `min < max`, sit within hard sanity bounds, and pass plausibility checks (out-of-normal-range warns, see §11).
-7. **All consumers must use one helper** — no analytics module should call the raw default-computer directly anymore (see §6).
-8. **Audit trail** for every change (medical data, see §8).
-
-## 4. Data Model
-
-### Decision: JSON column on `User`, not a new table
-
-Two options were considered:
-
-**Option A — `UserThreshold` table** (one row per user/metric):
-- Pro: query-friendly, easy partial indexes, future reporting per metric.
-- Con: 9+ rows per user for a feature that is read together every page load; joins on every targets fetch; migration friction when adding metrics.
-
-**Option B — JSON column on `User`** (`thresholdsJson Json?`):
-- Pro: read-with-user is one row, atomic write, schema-less for new metrics, mirrors Prisma 7 / Postgres `jsonb` strengths, validated by Zod at the application layer.
-- Con: cannot index individual thresholds in the DB (acceptable — there is no use case for "find all users whose pulse cap > 110").
-
-**Choose Option B.** A `UserSetting` model does not currently exist, so we add the column directly to `User`:
-
-```
-// prisma/schema.prisma — additive
-model User {
-  ...
-  thresholdsJson Json? @map("thresholds_json")
-}
-```
-
-### JSON shape (TypeScript, source of truth in `src/lib/validations/thresholds.ts`)
-
-```ts
-type ThresholdOverride = {
-  min?: number;
-  max?: number;
-  warnMin?: number;   // optional yellow zone lower bound
-  warnMax?: number;   // optional yellow zone upper bound
-  updatedAt: string;  // ISO-8601, set server-side on every PUT
-};
-
-type ThresholdsJson = {
-  WEIGHT?: ThresholdOverride;
-  BLOOD_PRESSURE_SYS?: ThresholdOverride;
-  BLOOD_PRESSURE_DIA?: ThresholdOverride;
-  PULSE?: ThresholdOverride;
-  BODY_FAT?: ThresholdOverride;
-  SLEEP_DURATION?: ThresholdOverride;
-  ACTIVITY_STEPS?: ThresholdOverride;
-  BLOOD_GLUCOSE_FASTING?: ThresholdOverride;     // reserved
-  BLOOD_GLUCOSE_POSTPRANDIAL?: ThresholdOverride; // reserved
-};
-```
-
-An override is "active" when `min` and `max` are both numbers; partial-only objects are rejected by Zod. Absence of a key === use default.
-
-## 5. API
-
-### `GET /api/user/thresholds`
-
-Response (envelope `{ data, error, meta }`):
-```
-data: {
-  defaults:  { WEIGHT: { min, max, warnMin, warnMax, source }, ... },
-  overrides: { PULSE:  { min, max, warnMin?, warnMax?, updatedAt }, ... },
-  effective: { WEIGHT: { min, max, warnMin, warnMax, isOverride: false }, ... },
-  profile:   { heightCm, age, gender }
-}
-```
-`defaults` is always populated (even for metrics the user has not measured, so the UI can render an empty slot with the default visible). `overrides` only contains keys the user has actually customized. `effective` is the merged result every analytics consumer should think in.
-
-### `PUT /api/user/thresholds`
-
-Body: partial map of metric → override (Zod-validated). Replaces only the listed metrics; unspecified keys are untouched.
-```
-{ "PULSE": { "min": 50, "max": 95 },
-  "BLOOD_PRESSURE_SYS": { "min": 110, "max": 130, "warnMin": 105, "warnMax": 140 } }
-```
-Per-metric Zod rules (`src/lib/validations/thresholds.ts`):
-- `min < max`
-- if `warnMin` set: `warnMin <= min`; if `warnMax` set: `warnMax >= max`
-- hard sanity bounds (reject obviously broken input):
-  - `WEIGHT`: 30–300 kg
-  - `BLOOD_PRESSURE_SYS`: 70–220 mmHg
-  - `BLOOD_PRESSURE_DIA`: 40–140 mmHg
-  - `PULSE`: 30–220 bpm
-  - `BODY_FAT`: 3–60 %
-  - `SLEEP_DURATION`: 3–14 h
-  - `ACTIVITY_STEPS`: 0–50000
-  - `BLOOD_GLUCOSE_FASTING`: 50–250 mg/dL
-  - `BLOOD_GLUCOSE_POSTPRANDIAL`: 70–350 mg/dL
-- soft "out-of-normal-range" check returns a Zod warning (not error) — surfaced to the UI to trigger the confirm dialog (see §11).
-
-### `DELETE /api/user/thresholds/:metric`
-
-Removes one key from `thresholdsJson`. Returns the new `effective` block so the client can refresh without a second roundtrip.
-
-All three routes are wrapped by `apiHandler` and `requireAuth()`, log Wide Events, and emit AuditLog entries (§8).
-
-## 6. Integration Points
-
-A single helper becomes the only public entry for "what is the target range":
-
-```
-src/lib/analytics/effective-range.ts
-  getEffectiveRange(metric, user, overrides?) → { min, max, warnMin, warnMax, source, isOverride }
-```
-
-It internally calls the existing default computers (`getWeightRange`, `getBpTargets`, `getPersonalizedPulseTarget`, `classifyBodyFat`'s table, `getSleepDurationRange`, `getStepsRange`) and applies any matching override. `source` becomes `"User override"` when `isOverride === true`, otherwise the existing guideline string.
-
-Refactor in scope:
-- `src/lib/analytics/classifications.ts` — `classifyBP`, `classifyPulse`, `classifyBodyFat`, `classifySleepDuration`, `classifySteps`, `getWeightRange`, `getPulseRange`, `getSleepDurationRange`, `getBpTargetsByAge`: keep as pure default computers, but stop being called from feature code. Add thin `classifyXWithRange(value, range)` variants that take the resolved range.
-- `src/lib/analytics/value-bands.ts` — `buildTrafficRange` and `buildWeightBandsFromHeight` accept an optional `override` argument and prefer it over the BMI-derived band.
-- `src/lib/analytics/pulse-targets.ts` — `getPersonalizedPulseTarget` stays as the default; new `resolvePulseTarget(user, overrides)` lives in `effective-range.ts`.
-- `src/lib/analytics/bp-targets.ts` — `getBpTargets` likewise stays; `effective-range.ts` wraps it.
-- `src/app/api/insights/targets/route.ts` (the API behind `/targets`) reads `thresholdsJson` once and passes it to `getEffectiveRange` per metric, then returns the `effective` block to the client. The `source` field already shown on `TargetCard` flips to "User override" automatically.
-- Doctor-report PDF (`src/lib/doctor-report-pdf.ts`) and Wide-Event annotations include `isOverride` so reports clearly mark customized targets.
-
-## 7. Migration
-
-Additive only — single Prisma migration adds `users.thresholds_json jsonb`. Existing users get `NULL`, which `getEffectiveRange` treats as "no overrides → behave exactly as before". No data backfill, no flag rollout.
-
-## 8. Auditing
-
-Every `PUT` and `DELETE` writes one `AuditLog` row (model already exists at `prisma/schema.prisma:391`):
-
-- `action`: `"thresholds.update"` or `"thresholds.reset"`
-- `details` (JSON string): `{ metric, before: {min,max,warnMin,warnMax} | null, after: {...} | null, reason?: "user" | "out_of_range_confirmed" }`
-- `userId`, `ipAddress`, `location` from session context (already populated by `apiHandler`).
-
-The `before` value is read from the current `thresholdsJson` *or* the computed default (so the audit trail captures the implicit baseline a user customized away from). Reset writes `after: null`.
-
-## 9. i18n Keys
-
-New section under `messages/en.json` and `messages/de.json`:
-
-| Key | EN | DE |
-|---|---|---|
-| `thresholds.title` | "Custom thresholds" | "Eigene Zielwerte" |
-| `thresholds.intro` | "Override the medical default ranges with values your doctor recommended. Defaults stay visible for comparison and you can reset any metric to the guideline at any time." | "Ersetze die medizinischen Standardbereiche durch arztempfohlene Werte. Die Standardwerte bleiben sichtbar und du kannst jeden Wert jederzeit auf die Leitlinie zurücksetzen." |
-| `thresholds.defaultLabel` | "Default" | "Standard" |
-| `thresholds.overrideLabel` | "Your override" | "Eigener Wert" |
-| `thresholds.enableToggle` | "Use custom value" | "Eigenen Wert verwenden" |
-| `thresholds.warnZoneLabel` | "Yellow zone (optional)" | "Gelber Bereich (optional)" |
-| `thresholds.minLabel` | "Min" | "Min" |
-| `thresholds.maxLabel` | "Max" | "Max" |
-| `thresholds.resetButton` | "Reset to default" | "Auf Standard zurücksetzen" |
-| `thresholds.resetPrompt` | "Reset {metric} to the medical default?" | "{metric} auf den medizinischen Standardwert zurücksetzen?" |
-| `thresholds.saved` | "Thresholds saved" | "Zielwerte gespeichert" |
-| `thresholds.outOfRangeWarn` | "This value lies outside the typical medical range. Please confirm only if your doctor recommended it." | "Dieser Wert liegt außerhalb des üblichen medizinischen Bereichs. Bitte nur bestätigen, wenn dein Arzt das empfohlen hat." |
-| `thresholds.notMedicalAdvice` | "HealthLog does not provide medical advice. Custom thresholds are stored as-is." | "HealthLog ersetzt keine ärztliche Beratung. Eigene Zielwerte werden unverändert gespeichert." |
-| `thresholds.validation.minLessMax` | "Min must be less than max" | "Min muss kleiner als Max sein" |
-| `thresholds.validation.warnEnvelope` | "Yellow zone must surround the green zone" | "Der gelbe Bereich muss den grünen Bereich umschließen" |
-| `thresholds.validation.outOfBounds` | "Value outside allowed range ({min}–{max} {unit})" | "Wert außerhalb des erlaubten Bereichs ({min}–{max} {unit})" |
-
-Existing `targets.*` keys stay; the targets page gains a small "Customize" link routing to `/settings#thresholds`.
-
-## 10. UI
-
-New section in the existing settings shell at `/settings#thresholds`:
-
-- One card per metric. Header shows the metric label + icon (reuses `TYPE_ICONS` from `targets/page.tsx`).
-- Body left: read-only "Default: 60 – 100 bpm" with the source citation (same external link logic as `getTargetSourceLink`).
-- Body right: an "Use custom value" toggle. When on, two number inputs (min, max) plus an optional collapsible "Yellow zone" with `warnMin`/`warnMax`.
-- Inline validation via React Hook Form + Zod (the same schema the server uses).
-- Footer: "Reset to default" button (visible only when an override exists).
-- Out-of-range soft warnings render as an inline orange callout with a "I confirm my doctor recommended this" checkbox required to enable Save.
-- Persistent disclaimer banner at the top: `thresholds.notMedicalAdvice`.
-
-## 11. Nyquist Validation (tests in `src/lib/analytics/__tests__/effective-range.test.ts` and route tests)
-
-- `getEffectiveRange` returns the override when present and the default when absent (one test per metric).
-- Boundary tests: `min === max` rejected; `warnMin === min` accepted; off-by-one above/below the hard sanity bounds rejected/accepted.
-- Profile-change test: removing `heightCm` collapses the WEIGHT default to "no range", but a present override survives.
-- API contract: `GET` returns `defaults`, `overrides`, `effective`, `profile`. `PUT` with partial body leaves untouched metrics intact. `DELETE :metric` removes only that key.
-- AuditLog firing: spy that one row is written per `PUT`/`DELETE`, with correct `before`/`after`. Confirm `details` JSON parses.
-- Out-of-range confirmation: PUT with a value flagged "out_of_normal_range" requires `?confirm=1` query param (or a body flag) — without it the route returns `400 confirmation_required`.
-- i18n parity test: every new EN key has a DE counterpart (re-uses the existing parity test if present, else add).
-
-## 12. Risks & Mitigations
-
-- **Users set unhealthy targets.** Hard sanity bounds reject obvious nonsense; soft "out-of-normal-range" warns and demands explicit confirmation. Persistent banner ("not medical advice"). Audit trail enables forensic review.
-- **Insights/AI prompts may quote a user-customized range as if it were the medical guideline.** The provider prompts must receive the `source` field and explicitly distinguish "User override" from a guideline citation. Update `src/lib/ai/prompts/*` accordingly.
-- **Doctor-report PDF.** Mark each customized range with a small "(custom)" tag so a treating physician sees that the report's coloring reflects the patient's own targets, not the guideline.
-- **Default drift over time.** If we update guidelines (e.g. ESC/ESH 2024), users with overrides are unaffected — but users without overrides will see their colored bands shift. Document in the changelog.
-
-## 13. Out of Scope
-
-- Sharing thresholds between users / household.
-- Doctor export of overrides (a treating physician downloading the override JSON to reuse) — could come later as part of the doctor report.
-- Time-bounded thresholds ("until 2026-12-31"), seasonal thresholds, schedule-based thresholds.
-- Per-medication or per-condition threshold packs.
-- Threshold suggestions from AI insights.
-
-## 14. Effort
-
-**M (medium).** One Prisma migration, one new helper module, three new API routes, refactoring of ~5 analytics consumers to go through `getEffectiveRange`, one new settings card, ~14 i18n keys per locale, and one new test file. No external integrations, no UI primitive work (existing shadcn `Card`/`Input`/`Switch`/`Button` cover everything). Estimated 1.5–2 focused days for a senior dev including tests and audit-log wiring.

docs/superpowers/specs/2026-04-18-dashboard-customization-design.md

@@ -1,117 +0,0 @@
-# Dashboard Customization — Design Spec
-
-**Status:** Proposed (v1.2+)
-**Date:** 2026-04-18
-**Owner:** TBD
-
-## Why
-
-- Users have different health focus areas. Someone not tracking blood pressure shouldn't see an empty BP card.
-- Current "hide if no data" rule (`showBodyFatCard = (bf?.count ?? 0) > 0`, etc. in `src/app/page.tsx`) is implicit — users can't pin the cards they care about, and a card vanishes the moment they delete the last entry.
-- This is for a v1.2+ release, not part of the current bugfix push.
-
-## 1. Problem Statement
-
-The dashboard at `src/app/page.tsx` renders a fixed set of trend cards and charts (weight, BP sys/dia, pulse, body fat, mood, BMI) in a hard-coded order. Visibility is implicit (derived from data presence), ordering is non-negotiable. Narrowly-focused users carry visual noise; users with strong preferences cannot reorder. We need explicit, server-persisted, per-user control over which widgets appear and in what order.
-
-## 2. Requirements
-
-- **Per-user widget visibility.** Each chart and trend card is a "widget" that the user can show or hide independently.
-- **Widget ordering — list-based reorder with up/down buttons + numeric position.** Defended below.
-- **"Reset to defaults" action** that restores the v1.0 behavior (everything visible, default order).
-- **Server-persisted** so settings follow the user across devices (web + PWA on phone). localStorage only acts as an optimistic cache.
-- **i18n-friendly.** Widget IDs are stable English keys; display labels resolve through existing `dashboard.*` translation keys (`messages/en.json`, `messages/de.json`).
-
-**Reorder UX choice:** list-based (up/down arrows) over drag-and-drop. Reasons: (a) mobile-first PWA — drag-on-touch with scroll containers is fragile; (b) keyboard/screen-reader accessible by default; (c) no extra dep (`@dnd-kit` ~30 KB). DnD can be added later behind a flag.
-
-## 3. Data Model
-
-**Decision: extend `User` with a `dashboardWidgets Json?` column.** No new table.
-
-```prisma
-model User {
-  // ...
-  dashboardWidgets Json? @map("dashboard_widgets")
-}
-```
-
-Shape (validated by Zod on read/write):
-```ts
-type DashboardWidgetState = {
-  version: 1;
-  widgets: Array<{ id: WidgetId; visible: boolean; order: number }>;
-};
-```
-
-`WidgetId` is a string-literal union seeded from a server-side registry (`src/lib/dashboard/widgets.ts`):
-`"weight" | "bp" | "pulse" | "body_fat" | "mood" | "bmi"`.
-
-**Tradeoffs vs. dedicated `DashboardWidget` model:** JSON wins because the widget set is small (<20 forecast), state is read once per dashboard load, and we never need to query "which users hide widget X." A table would cost a migration + FK + N writes per reorder for ~6 rows, with no queryability payoff. Cost: schema drift risk — mitigated by the Zod gate and the `version` field, which lets us evolve the shape without a SQL migration.
-
-## 4. API
-
-Two routes under `src/app/api/dashboard/widgets/route.ts`, both wrapped in `apiHandler` and `requireAuth()`.
-
-**`GET /api/dashboard/widgets`** — returns merged state (stored values overlaid on the registry; new widgets appear at the end with `visible: true`):
-```json
-{ "data": { "version": 1, "widgets": [
-  { "id": "weight", "visible": true, "order": 0 },
-  { "id": "mood",   "visible": false, "order": 5 }
-]}, "error": null, "meta": {...} }
-```
-
-**`PUT /api/dashboard/widgets`** — replaces full state. Zod schema in `src/lib/validations/dashboard.ts`:
-```ts
-const dashboardWidgetsSchema = z.object({
-  version: z.literal(1),
-  widgets: z.array(z.object({
-    id: z.enum(WIDGET_REGISTRY.map(w => w.id)),
-    visible: z.boolean(),
-    order: z.int().min(0),
-  })).min(1),
-}).refine(s => new Set(s.widgets.map(w => w.id)).size === s.widgets.length);
-```
-Unknown IDs and duplicates are rejected. Mutations invalidate `queryKeys.dashboardLayout()`.
-
-**`DELETE /api/dashboard/widgets`** — clears the column → user gets defaults again ("Reset to defaults").
-
-## 5. UI
-
-**Location:** new section in `/settings` named **"Dashboard"** (matches existing settings architecture: Profile, Notifications, Integrations, etc.). Plus a small **"Customize"** icon button on the dashboard header next to the "Add" dropdown that deep-links to `/settings/dashboard`.
-
-**Flow** (settings page):
-1. Header "Dashboard widgets" + subhead "Choose which cards and charts appear on your dashboard."
-2. Ordered list of shadcn `Card` rows — translated label (`t("dashboard.weight")`), short description, `Switch` for visibility, `ChevronUp`/`ChevronDown` reorder buttons (disabled at list ends).
-3. Sticky footer: outline "Reset to defaults" (confirm via `AlertDialog`) + primary "Save" (disabled until dirty).
-4. Optimistic update via TanStack Query mutation; on error, rollback + toast.
-
-**Dashboard read path:** `src/app/page.tsx` becomes a thin orchestrator — fetch layout via `useQuery(queryKeys.dashboardLayout())`, sort by `order`, filter `visible`, render through a `<DashboardWidget id="…" />` switch. Existing data-presence guards stay as a safety net.
-
-## 6. Migration
-
-- Prisma migration: `ALTER TABLE users ADD COLUMN dashboard_widgets jsonb`.
-- No backfill. Null = "use defaults" = the v1.0 behavior frozen as `DEFAULT_LAYOUT` constant in `src/lib/dashboard/widgets.ts`. The `GET` endpoint synthesizes this on the fly.
-- First save writes the full normalized blob.
-- Existing users see no change until they open settings.
-
-## 7. Nyquist Validation Criteria
-
-- **Vitest:** Zod rejects duplicate IDs, unknown IDs, negative order, missing version.
-- **Vitest:** layout merger appends new registry widgets with `visible: true` when user state predates them.
-- **Vitest:** `DELETE` then `GET` returns `DEFAULT_LAYOUT`.
-- **API integration:** unauth `PUT` → 401; valid `PUT` → 200 + persisted; payload >50 KB → 413.
-- **Manual UAT:** hide BP on desktop → reload on phone PWA → BP gone. Reorder weight to last → reload → still last. Reset → defaults restored.
-- **A11y:** keyboard nav on reorder buttons, `aria-label` on Up/Down, screen-reader announces position changes.
-- **Perf:** dashboard initial render does not regress (React Profiler check).
-
-## 8. Out of Scope
-
-- Custom user-defined widgets / per-widget chart config (color, range, time window).
-- Widgets for future measurement types (blood glucose, SpO2, sleep stages, steps) — added to registry when those features ship.
-- Multiple dashboards or tabs; sharing layouts between users.
-- Drag-and-drop reorder (revisit if list UX gets complaints).
-- Per-widget grid size (1x/2x spans).
-
-## 9. Estimated Effort
-
-**M** — roughly 1–2 days. Schema + Zod + registry ~2h, API + tests ~3h, Settings UI ~4h, dashboard refactor ~3h, i18n + polish + UAT ~2h.

docs/superpowers/specs/2026-04-18-multi-provider-ai-design.md

@@ -1,216 +0,0 @@
-# Multi-provider AI Insights — Design Spec
-
-**Date:** 2026-04-18
-**Status:** Draft
-**Scope:** Add Anthropic Claude and self-hosted (OpenAI-compatible) LLM endpoints alongside the existing OpenAI / ChatGPT Codex providers. Per-user provider choice, admin-level fallback, encrypted credential storage.
-
-## 1. Problem
-
-Today HealthLog can only talk to OpenAI — either the user's ChatGPT subscription via Codex OAuth, or an admin-managed OpenAI API key. That ties insight generation to a single vendor and to the public internet.
-
-> "I'd like to pick my provider per user. OpenAI for some accounts, Claude for me, and on my home server I want to point HealthLog at a local Ollama instance — none of my BP readings should leave the LAN."
-> — User intent
-
-Consequences of the single-vendor model:
-- No way to use Anthropic Claude despite better medical-reasoning answers.
-- Privacy-sensitive users (BP, mood, medication) have no on-prem option.
-- Vendor outages or quota exhaustion bring all insights down (already observed with OpenAI quota).
-
-## 2. Current state
-
-`src/lib/ai/provider.ts` exposes `resolveProvider(userId)` returning an `AIProvider`. The contract in `src/lib/ai/types.ts` is small and provider-agnostic:
-
-```ts
-export type ProviderType = "codex" | "admin-key" | "none";
-export interface AIProvider {
-  type: ProviderType;
-  generateCompletion(params: CompletionParams): Promise<CompletionResult>;
-}
-export interface CompletionParams {
-  systemPrompt: string;
-  userPrompt: string;
-  temperature?: number;
-  maxTokens?: number;
-}
-export interface CompletionResult {
-  content: string;
-  tokensUsed: number | null;
-  model: string;
-  providerType: ProviderType;
-}
-```
-
-Implementations: `OpenAIClient` (Chat Completions, `response_format: json_object`, captures upstream body excerpt for diagnostics), `CodexClient` (chatgpt.com Responses API with refresh-on-401). Selection is hard-coded: Codex if connected, else admin OpenAI key, else `NoProvider`.
-
-What needs to change:
-- Widen `ProviderType` to include `anthropic` and `local`.
-- Add per-user provider choice (currently only Codex is per-user).
-- Add per-user model + base-URL + API key fields, mirrored on `AppSettings`.
-- Two new clients (`AnthropicClient`, `LocalOpenAICompatibleClient`).
-- New selection function that honors user preference before admin defaults.
-
-## 3. Target abstraction
-
-The `AIProvider` interface stays exactly as-is. New concrete clients implement it without touching call-sites in `src/app/api/insights/*`.
-
-```
-ProviderType = "codex" | "openai" | "anthropic" | "local" | "admin-key" | "none"
-```
-(`"admin-key"` retained for back-compat with already-cached `InsightResult.providerType` strings.)
-
-Selection order in `resolveProvider(userId)`:
-1. **User explicit choice** (`User.aiProvider`) with valid credentials.
-2. **Codex OAuth** if user picked `CHATGPT_OAUTH` and tokens are present (existing path).
-3. **Admin default** (`AppSettings.adminAiProvider` + admin key) for users with no personal config.
-4. **`NoProvider`** — surface a clear error to the route handler.
-
-The function is the single boundary: every call that needs an LLM goes through it. No client is constructed elsewhere.
-
-## 4. Data model
-
-`User` model additions (all nullable; user keeps current behaviour until they opt in):
-
-```prisma
-aiProvider                String?  @map("ai_provider")               // OPENAI | ANTHROPIC | LOCAL | CHATGPT_OAUTH
-aiModel                   String?  @map("ai_model")                  // e.g. claude-sonnet-4-6
-aiBaseUrl                 String?  @map("ai_base_url")               // local endpoint
-aiOpenAiKeyEncrypted      String?  @map("ai_openai_key_encrypted")
-aiAnthropicKeyEncrypted   String?  @map("ai_anthropic_key_encrypted")
-aiLocalKeyEncrypted       String?  @map("ai_local_key_encrypted")    // optional bearer for local
-```
-
-`AppSettings` mirrors:
-
-```prisma
-adminAiProvider             String   @default("OPENAI") @map("admin_ai_provider")
-adminAiAnthropicKeyEncrypted String? @map("admin_ai_anthropic_key_encrypted")
-adminAiAnthropicModel        String? @default("claude-sonnet-4-6") @map("admin_ai_anthropic_model")
-adminAiLocalBaseUrl          String? @map("admin_ai_local_base_url")
-adminAiLocalKeyEncrypted     String? @map("admin_ai_local_key_encrypted")
-adminAiLocalModel            String? @map("admin_ai_local_model")
-```
-
-The existing `adminAiKeyEncrypted` / `adminAiModel` / `adminAiBaseUrl` fields stay and represent the OpenAI configuration. One Prisma migration adds the columns; existing users have `aiProvider = NULL` and route through admin default exactly like today.
-
-## 5. New clients
-
-### AnthropicClient
-- `POST {baseUrl}/v1/messages` with `x-api-key` and `anthropic-version: 2023-06-01`.
-- `system` parameter for `params.systemPrompt`; `messages: [{ role: "user", content: params.userPrompt }]`.
-- Structured JSON via **tool use**: declare a single `record_insight` tool whose `input_schema` mirrors `insightResultSchema`. Set `tool_choice: { type: "tool", name: "record_insight" }`. Read JSON from the `tool_use` block's `input` and serialize to a string for `CompletionResult.content`.
-- Prompt caching: send the system prompt with `cache_control: { type: "ephemeral" }`. Insights re-run the same multi-paragraph medical preamble per metric — empirically ~90% cost reduction on cached reads.
-- Tokens: sum `usage.input_tokens + usage.output_tokens` (incl. `cache_read_input_tokens`).
-- Errors: capture body excerpt like `OpenAIClient` already does, scrub any `sk-ant-...` substrings before logging.
-
-Default models (selectable in UI):
-- `claude-sonnet-4-6` (default — quality / cost balance)
-- `claude-opus-4-7` (highest quality)
-- `claude-haiku-4-5` (cheap, fast)
-
-### LocalOpenAICompatibleClient
-- Same wire format as `OpenAIClient` (`/chat/completions`, optional `Authorization: Bearer ...` only if a key is set).
-- `baseUrl` is required and user-configurable (e.g. `http://localhost:11434/v1` for Ollama, `http://lm-studio.lan:1234/v1`).
-- Some local backends reject `response_format: { type: "json_object" }`. Strategy: feature-detect on first failure (HTTP 400 with body containing `response_format`), persist `User.aiLocalSupportsJsonMode = false`, and re-issue without the field. Append `"Return JSON only, no prose."` to the user prompt and run output through `jsonrepair` before `JSON.parse`.
-- No-telemetry mode: never set `User-Agent` beyond `HealthLog/local`, never include user IDs in headers, do not send the request body to Wide Event annotation when provider is `local` (only `model`, `latencyMs`, `tokensUsed`).
-
-## 6. UI — `/settings#ai`
-
-Single dropdown `aiProvider` with options OpenAI / Anthropic Claude / Local LLM / ChatGPT (OAuth). Conditional fields:
-
-| Provider     | Visible fields                                                  |
-| ------------ | --------------------------------------------------------------- |
-| OpenAI       | API key, model (default `gpt-4o-mini`)                          |
-| Anthropic    | API key, model dropdown (sonnet/opus/haiku)                     |
-| Local        | Base URL, model name, optional API key, "Disable JSON mode" hint |
-| ChatGPT OAuth| Existing Codex connect button                                   |
-
-Each provider section has a **Test connection** button that POSTs to `/api/insights/test` with a tiny prompt (`"Reply with {\"ok\":true}"`), surfacing the upstream status + body excerpt on failure.
-
-Admin settings page gains the same dropdown for the global default plus an explanatory note: *"Used only for users who have not configured their own provider."*
-
-## 7. Backward compatibility
-
-- Migration is additive — no column drops, no data rewrites.
-- `User.aiProvider IS NULL` ⇒ behave exactly as today (Codex if connected, else admin OpenAI).
-- `CompletionResult.providerType = "admin-key"` continues to be emitted by `OpenAIClient` so cached insights and analytics dashboards keep working. New clients use new strings.
-- Existing tests in `src/lib/ai/__tests__` keep passing; new tests are additive.
-
-## 8. Error handling
-
-Each client follows the `OpenAIClient` pattern: capture up to 500 chars of the upstream body, attach `{ httpStatus, upstream, model }` to the thrown `Error`, let `apiHandler` log it as a Wide Event. Per-provider mapping in `src/lib/ai/errors.ts`:
-
-| Upstream                                | User-facing message (i18n key)            |
-| --------------------------------------- | ----------------------------------------- |
-| Anthropic 401 / `invalid_api_key`       | `insights.error.anthropicInvalidKey`      |
-| Anthropic 429 / `rate_limit_error`      | `insights.error.anthropicRateLimited`     |
-| Anthropic 529 / `overloaded_error`      | `insights.error.anthropicOverloaded`      |
-| Local fetch ECONNREFUSED                | `insights.error.localUnreachable`         |
-| Local 400 mentioning `response_format`  | auto-retry once, then `insights.error.localNoJsonMode` |
-| OpenAI 429 `insufficient_quota`         | existing key                              |
-
-## 9. Internationalisation
-
-New keys (EN + DE) under `settings.ai.*` and `insights.error.*`:
-
-```
-settings.ai.providerLabel               "AI Provider" / "KI-Anbieter"
-settings.ai.providerOpenAI              "OpenAI"
-settings.ai.providerAnthropic           "Anthropic Claude"
-settings.ai.providerLocal               "Local LLM"
-settings.ai.providerChatGptOAuth        "ChatGPT (OAuth)"
-settings.ai.baseUrlLabel                "Endpoint URL" / "Endpunkt-URL"
-settings.ai.baseUrlHint.local           "z.B. http://localhost:11434/v1"
-settings.ai.modelLabel                  "Model" / "Modell"
-settings.ai.testConnection              "Test connection" / "Verbindung testen"
-settings.ai.testSuccess                 "Connection OK ({model}, {ms} ms)"
-settings.ai.testFailure                 "Failed: {detail}"
-settings.ai.localPrivacyNote            "Requests stay on your network. Bodies are not logged."
-insights.error.anthropicInvalidKey      "Anthropic key rejected. Check Settings → AI."
-insights.error.anthropicRateLimited     "Anthropic rate-limited. Try again shortly."
-insights.error.anthropicOverloaded      "Anthropic is overloaded. Try again in a minute."
-insights.error.localUnreachable         "Local LLM endpoint not reachable: {url}"
-insights.error.localNoJsonMode          "Local model rejected JSON mode — falling back to text parsing."
-```
-
-## 10. Security
-
-- All keys stored via existing AES-256-GCM helpers in `src/lib/crypto.ts`. Never persist plaintext.
-- Anthropic keys begin with `sk-ant-`. The Wide Event redactor (`src/lib/logging/event-builder.ts`) gets a regex `/sk-ant-[A-Za-z0-9_\-]{20,}/g` → `"sk-ant-***"` applied to all `externalCalls[].errorBody`.
-- Local provider runs with `next/server` `fetch` against arbitrary URLs — validate that `aiBaseUrl` parses as `http`/`https`, reject `file://`, `data://`, and (in production) bare IPs in private ranges *unless* `LOCAL_LLM_ALLOW_PRIVATE=true` (default true on self-hosted, false on `apps-01` build).
-- Test-connection endpoint is `requireAuth` and rate-limited (5 req/min/user) to prevent SSRF probing.
-- Admin keys remain admin-only via `requireAdmin()`.
-
-## 11. Nyquist validation
-
-- **Unit (Vitest)** — one `*.test.ts` per new client, mocking `fetch`:
-  - `anthropic-client.test.ts`: success path returns parsed JSON from tool_use; 401 maps to error; cache_control header present.
-  - `local-client.test.ts`: success path; auto-retry on `response_format` 400; ECONNREFUSED handled; bearer header omitted when no key.
-- **Integration** — extend `provider.test.ts`:
-  - User with `aiProvider = ANTHROPIC` and key → returns `AnthropicClient`.
-  - User with no preference falls back to admin default of each kind.
-  - Codex still wins when user picks `CHATGPT_OAUTH` and is connected.
-- **End-to-end smoke** — manual: switch provider in `/settings#ai`, hit `/api/insights/general-status`, verify `providerType` in cached `InsightResult`.
-
-## 12. Risks & mitigations
-
-- **Admin changes default provider, breaks users.** Mitigated by precedence rule: any user with `aiProvider != NULL` is unaffected. Migration backfills nothing — admin only impacts opted-out users.
-- **Local model returns malformed JSON.** Two-layer defence: tool-use where supported, `jsonrepair` fallback otherwise; on persistent failure surface `dataQuality.confidence = "gering"` and the raw text in a debug field.
-- **Cached insight from old provider.** Cache key already includes `providerType`; switching provider invalidates naturally on next generate.
-- **Anthropic prompt-caching cost regression** if system prompt is rebuilt per request without cache_control. Mitigation: emit a Wide Event metric `ai.cache_read_tokens` and add a Grafana panel.
-
-## 13. Out of scope
-
-- Vendor-specific features beyond JSON output (Anthropic citations, OpenAI function-calling tool registries, Google Gemini).
-- Streaming responses to the UI (insights are batch-generated).
-- Multi-region routing or load-balancing across providers.
-- Per-metric provider override (one provider per user, applied to all metrics).
-- Cost dashboards beyond the existing `tokensUsed` field.
-
-## 14. Effort
-
-**M–L.** ~2 days dev:
-- 0.5d schema migration + `resolveProvider` rewrite + types.
-- 0.5d `AnthropicClient` (tool-use, caching, errors).
-- 0.5d `LocalOpenAICompatibleClient` + JSON-mode feature detection + jsonrepair.
-- 0.25d settings UI + test-connection endpoint.
-- 0.25d i18n + tests + docs.

docs/ui-guidelines.md

@@ -0,0 +1,464 @@
+# HealthLog UI Guidelines
+
+> Single source of truth for visual & interaction patterns in the HealthLog
+> PWA. Consult this document before adding a new component, page, or
+> setting. If a pattern below doesn't fit your case, propose an addition
+> here in the same PR.
+
+Last updated: 2026-05-08 (v1.4 cycle)
+
+---
+
+## 1. Foundations
+
+### 1.1 Theme
+
+HealthLog is a Dracula-themed app with a light counterpart (Alucard). Both
+themes share the same six-color signal palette (purple, pink, green, cyan,
+orange, red, yellow, lavender), exposed as CSS variables and as Tailwind
+`dracula-*` color tokens. Use the semantic tokens (`--primary`,
+`--destructive`, `--card`, …) for chrome and the `--dracula-*` tokens for
+data viz only.
+
+| Surface                      | Token              |
+| ---------------------------- | ------------------ |
+| App background               | `--background`     |
+| Card / popover surface       | `--card`           |
+| Primary action               | `--primary`        |
+| Destructive action           | `--destructive`    |
+| Secondary / muted background | `--secondary`      |
+| Border                       | `--border`         |
+| Focus ring                   | `--ring`           |
+| Chart series 1–5             | `--chart-1`…`-5`   |
+| Brand signal: purple         | `--dracula-purple` |
+| Brand signal: green (good)   | `--dracula-green`  |
+| Brand signal: orange (warn)  | `--dracula-orange` |
+| Brand signal: red (alert)    | `--dracula-red`    |
+| Brand signal: cyan (info)    | `--dracula-cyan`   |
+
+Dark mode is the default. The theme switcher in the sidebar three-dot menu
+toggles `.dark` / `.light` on `:root`. Always test both modes before
+shipping a component.
+
+### 1.2 Spacing
+
+Tailwind's default 4-pixel scale. Reach for these stops first:
+
+| Use                                  | Token         | Pixels |
+| ------------------------------------ | ------------- | ------ |
+| Inline gap between icon and label    | `gap-1`       | 4      |
+| Tight stack inside a card            | `gap-2`       | 8      |
+| Default form-field stack             | `space-y-3`   | 12     |
+| Section block (heading + body)       | `space-y-4`   | 16     |
+| Page section separator               | `space-y-6`   | 24     |
+| Dashboard tile-row gap, hero spacing | `gap-4`       | 16     |
+| Page-edge padding (mobile / desktop) | `px-4 / px-6` |        |
+
+Avoid arbitrary `space-y-5`, `gap-3.5`, etc. unless aligning to a fixed
+external constraint.
+
+### 1.3 Typography
+
+The app uses the Tailwind defaults inherited via shadcn/ui. Reach for
+these classes first:
+
+| Use                                | Class                                   |
+| ---------------------------------- | --------------------------------------- |
+| Page title (h1)                    | `text-2xl font-semibold tracking-tight` |
+| Section heading (h2)               | `text-lg font-semibold`                 |
+| Card title                         | `text-base font-medium`                 |
+| Body text                          | `text-sm`                               |
+| Muted helper / metadata            | `text-sm text-muted-foreground`         |
+| Microcopy / footer                 | `text-xs text-muted-foreground`         |
+| Tabular data (latency, large nums) | `font-mono tabular-nums`                |
+
+Never use `font-bold` for emphasis — bump to `font-semibold` instead and
+let the design system breathe.
+
+### 1.4 Radius and elevation
+
+`--radius: 0.625rem` (10px) is the default. The Tailwind tokens
+`rounded-md` (`--radius-md` ≈ 8px) and `rounded-lg` (`--radius` ≈ 10px)
+cover 95% of cases. Use `rounded-2xl` only for hero cards or large
+modals.
+
+Elevation is achieved via `shadow-xs`, `shadow-sm`, or
+`shadow-[0_1px_0_rgba(255,255,255,0.04)]` for very subtle separators on
+dark backgrounds. Avoid Tailwind's heavy shadows (`shadow-lg`+) in chrome.
+
+---
+
+## 2. Components
+
+This section is **prescriptive, not exhaustive**. Each entry pairs a
+Radix/shadcn primitive with the cases it's the right answer for and the
+cases where another primitive should win.
+
+### 2.1 Buttons
+
+Every button comes from `@/components/ui/button`. Pick by purpose:
+
+| Purpose                                               | Variant       | Size              |
+| ----------------------------------------------------- | ------------- | ----------------- |
+| Primary action on a page or dialog                    | `default`     | `default`         |
+| Cancel, dismiss, secondary action next to primary     | `outline`     | `default`         |
+| Tertiary in-row action (edit, copy, snooze)           | `ghost`       | `sm`              |
+| Destructive (delete, revoke, disconnect)              | `destructive` | `default` or `sm` |
+| Icon-only action (toolbar, chart toggles, table rows) | `ghost`       | `icon-sm`         |
+| Inline link to external help docs                     | `link`        | `sm`              |
+| Toolbar / table row action when space is tight        | `outline`     | `xs`              |
+
+**Position rules.**
+
+- Forms (full-width or modal): primary on the **right**, cancel/back on
+  the **left**. Match shadcn dialog defaults.
+- Settings sections: a single sticky `Save` button at the **right end**
+  of the section header _or_ per-row inline `Save`. Never both in the
+  same section.
+- Test buttons (Telegram test, AI ping, etc.): immediately to the right
+  of the related Save / Apply control. Never below — keeps the eye
+  motion horizontal.
+- Destructive actions live in their own confirm dialog with a
+  type-to-confirm input when the action is irreversible (delete account,
+  revoke API token, drop user data).
+
+**Disabled state.** A disabled button must always come with a tooltip or
+helper text explaining why. Silent disabled buttons frustrate users.
+
+### 2.2 Inputs and forms
+
+We use `react-hook-form` + Zod schemas from `src/lib/validations/`.
+Wrap inputs in `<label>` (visible) plus `aria-describedby` for helper text.
+
+- **Text / number / email**: `<Input>`. Always set `autocomplete`. See §4.4.
+- **Multi-line**: shadcn `<Textarea>` (add via `pnpm dlx shadcn@latest add textarea` if missing).
+- **Single choice ≤4 options**: prefer `<RadioGroup>` or a SegmentedControl
+  pattern using `<Tabs>`. Never use `<Select>` for tiny enums — extra clicks.
+- **Single choice 5–15 options**: `<Select>` (shadcn).
+- **Single choice >15 options**: `<Combobox>` (shadcn `<Command>` + `<Popover>`)
+  with type-ahead.
+- **Multi choice**: `<Checkbox>` group, or shadcn `<MultiSelect>` when 7+ choices.
+- **Date / datetime**: shadcn `<Calendar>` inside a `<Popover>`. Always
+  label the timezone (Europe/Berlin).
+- **Numeric range**: `<Slider>` only when the value space is continuous
+  _and_ the user routinely sweeps. For most thresholds and counts, an
+  `<Input type="number">` plus stepper buttons is faster and less
+  fiddly. See §6 (Slider audit) for the migration path.
+- **Boolean toggle**: `<Switch>` for "applies immediately" settings (e.g.
+  enable Telegram). `<Checkbox>` for "applies on Save" lists (e.g. select
+  measurements to export).
+
+**Validation.** Inline messages below the field. Field gets
+`aria-invalid="true"` and a destructive border. Form-level errors land
+in a `<Alert variant="destructive">` at the top. Never show a toast for
+a field-level error.
+
+### 2.3 Dialog vs Sheet vs Drawer
+
+The wrong choice here is the most visible UX mistake we make. Pick by
+intent, not by hand-feel.
+
+| Use                                                             | Primitive                      | Rationale                                                        |
+| --------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| Confirm a destructive or irreversible action                    | `Dialog` (`AlertDialog` shape) | Modal blocks accidental dismiss; user must read.                 |
+| Inspect a single item's details with no edit                    | `Dialog`                       | Centered, focused, dismissible.                                  |
+| Edit a single item with ≤6 fields                               | `Dialog`                       | Tight focus, quick save.                                         |
+| Edit a single item with 7+ fields, or with deep sub-sections    | `Sheet` (right)                | Wide working surface, scrollable, doesn't crop on tall content.  |
+| Mobile bottom-up sub-action (filter, sort, multi-select picker) | `Sheet` (bottom)               | Thumb-friendly, dismiss by swipe.                                |
+| Multi-step wizard                                               | Full route                     | Page transitions communicate progress better than a stuck modal. |
+| Side-by-side compare or trend deep-dive                         | Full route                     | Charts need the viewport.                                        |
+
+Never nest Dialogs. If a Dialog needs another modal action, escalate the
+inner step to a separate route or use shadcn's `<AlertDialog>` chained on
+top of a `<Sheet>`.
+
+### 2.4 Cards and lists
+
+- **Card**: a self-contained unit of content. Use `<Card>` from
+  shadcn. Header, body, footer follow Pretendard-style hierarchy.
+- **Tile**: a _small_ card showing a single metric on the dashboard.
+  See §3.2 for the one-row constraint. Tiles must include current value,
+  unit, optional sparkline, and a single tap-target area.
+- **List row**: `<div className="flex items-center justify-between gap-3 px-3 py-2 hover:bg-accent/40 rounded-md">` — left side has icon + primary
+  - meta, right side has trailing controls. Never put primary actions in
+    the right-side ellipsis menu — only secondary or destructive.
+- **Empty state**: every list and tile has an explicit empty-state
+  component with an icon, a one-sentence explanation, and a single
+  primary action ("Add measurement", "Connect Withings"). See §5.
+
+### 2.5 Tables
+
+`<Table>` (shadcn) for tabular data only — measurements list, audit log,
+admin views. Default to `<Card>` + list rows for everything else;
+tables on mobile collapse poorly. When you must use a table on mobile,
+swap to a vertical list at `sm:` breakpoint.
+
+### 2.6 Status indicators
+
+Use the same color taxonomy across the app:
+
+| State     | Color token          | Examples                                       |
+| --------- | -------------------- | ---------------------------------------------- |
+| Good      | `--dracula-green`    | Connected, in target, healthy                  |
+| Info      | `--dracula-cyan`     | Up-to-date, neutral signal                     |
+| Caution   | `--dracula-orange`   | Mildly out of range, expiring token, slow sync |
+| Alert     | `--dracula-red`      | Out of range, sync failed, critical            |
+| Pending   | `--muted-foreground` | Loading, indeterminate                         |
+| Highlight | `--dracula-purple`   | New / featured / promoted                      |
+
+Show a colored dot **plus** a label. Never rely on color alone.
+
+---
+
+## 3. Layouts
+
+### 3.1 Page shell
+
+Every authenticated page is wrapped by `<TopBar>` + `<SidebarNav>` (left)
+
+- `<BottomNav>` (mobile). Don't reinvent these on a per-page basis.
+
+* Mobile breakpoint: `<sm` shows bottom-nav, hides sidebar.
+* `sm`–`md`: sidebar in icons-only mode.
+* `md+`: sidebar full mode unless user has collapsed it
+  (`localStorage:healthlog-sidebar-collapsed`).
+
+Page content goes in `<main className="mx-auto max-w-5xl px-4 sm:px-6 py-6 space-y-6">` unless the page is a full-bleed dashboard or settings shell.
+
+### 3.2 Dashboard tiles — one-row rule
+
+Tiles at the top of the dashboard live in a **single row**. Width caps
+at the chart's width directly below. **Never** wrap to a second row.
+
+If the user enables more tiles than fit, the dashboard surfaces a banner
+inviting them to deactivate or reorder via Settings → Dashboard. The
+layout editor in Settings shows a live preview of the constraint and
+flags overflow before save.
+
+CSS: `grid-cols-N` where N = active tile count, capped by
+`Math.min(activeTiles, maxTilesForViewport(width))`. Drag-reorder via
+`@dnd-kit/sortable`. Toggle-show via the layout editor only — not in the
+tile itself, to avoid accidental hide.
+
+### 3.3 Settings — `/settings/[section]`
+
+The 1.4 release splits the legacy 3150-LOC settings monolith into one
+route per top-level section:
+
+- `/settings/account` — profile, password, passkeys, account deletion.
+- `/settings/integrations` — Withings, moodLog, Telegram, ntfy, Web Push.
+- `/settings/notifications` — channel matrix + quiet hours + reminders.
+- `/settings/dashboard` — tile layout editor, default ranges, threshold
+  overrides.
+- `/settings/ai` — AI provider selection + connection + test.
+- `/settings/api` — API tokens for headless ingest + Bearer issuance.
+- `/settings/advanced` — exports, imports, danger zone.
+- `/settings/about` — version, build, license, links to docs/changelog.
+
+Each section's component lives at `src/components/settings/<section>.tsx`
+and stays under 400 LOC. Cross-section search lives in the section
+sidebar header.
+
+The legacy `/settings` route 301-redirects to `/settings/account`.
+
+### 3.4 Admin — `/admin/[section]`
+
+Same shape as Settings, with the right-hand sidebar listing:
+
+- Users
+- Integrations status
+- Monitoring (Wide Events, GlitchTip, Umami)
+- Backups
+- Maintenance
+- Audit log
+
+Status badges use the §2.6 color taxonomy. Each section opens to a card
+grid, never a long fluid list.
+
+---
+
+## 4. Patterns
+
+### 4.1 Loading states
+
+- **Page-level**: a `<Skeleton>` matching the final layout. Never show a
+  full-screen spinner. Mount the skeleton inside the same `<main>` shell
+  the loaded page renders into.
+- **Inline**: button loading state shows a spinner + label change
+  ("Saving…", "Testing…"). Disable other form controls while pending.
+- **Long-running**: progress bar with a remaining-step count; for
+  background tasks (export, backup), surface in a toast that links to
+  the operation log instead of blocking the UI.
+
+Skeletons must respect `prefers-reduced-motion: reduce`.
+
+### 4.2 Empty states
+
+A reusable `<EmptyState>` shape:
+
+```tsx
+<EmptyState
+  icon={<Plus className="size-6" />}
+  title={t("empty.measurements.title")}
+  description={t("empty.measurements.description")}
+  action={<Button>{t("empty.measurements.add")}</Button>}
+/>
+```
+
+Every list, every chart, every dashboard tile that can be empty has an
+explicit, translated empty-state. No "No data" placeholder strings.
+
+### 4.3 Error states
+
+- **Form errors**: inline below the offending field; aggregate at the
+  top of the form for global errors (e.g. "Server unreachable").
+- **Page errors**: Next.js `error.tsx` boundaries with a friendly
+  recovery action ("Retry", "Go home"). Send the error to GlitchTip
+  through the existing client.
+- **Network errors during save**: `<Alert variant="destructive">` at
+  the top of the form _plus_ a retry button. Never silently fail.
+
+### 4.4 Forms and password managers
+
+- Measurement, medication, and mood form fields use
+  `autocomplete="off"` on every input that browsers keep guessing wrong.
+- API-token inputs and AI-provider key inputs use
+  `autocomplete="new-password"` so the browser doesn't autofill the
+  user's account password.
+- Honey-pot fields (offscreen `<input>` with `autocomplete="email"` and
+  `tabIndex={-1}`) sit at the top of measurement forms to catch
+  aggressive autofill.
+- Forms always include a hidden `<input type="text" name="username"
+autocomplete="username" value={user.email} readOnly tabIndex={-1}>`
+  inside password change and passkey screens so password managers
+  attribute saved credentials correctly.
+
+### 4.5 Test buttons (every integration)
+
+Each configurable integration ships a Test button next to its Save
+control. Behavior:
+
+- **Trigger**: ad-hoc API call to the integration with a small,
+  identifiable payload ("HealthLog test ping").
+- **State**: button shows a spinner with localized "Testing…" label.
+  Result lands inline in a `<StatusCallout>` directly below — green for
+  success with the relevant detail (last sync, message ID, response
+  status) or red for the error (sanitized message — never leak the
+  upstream URL or API key).
+- **History**: each test writes a row to a tiny per-integration log
+  visible in the section. Last 5 tests, timestamp + result.
+- **Coverage**: required for Telegram, ntfy, Web Push, AI provider,
+  Withings, moodLog, GlitchTip, Umami, email (when wired), backup
+  target. Headless E2E asserts presence + working call for each.
+
+### 4.6 Server actions and mutations
+
+We use `react-hook-form` + TanStack Query mutations, never raw fetch
+calls in components. Every mutation:
+
+1. Optimistically updates the cache with a rollback handler.
+2. Toast on success ("Saved" — translated) and on error (with retry).
+3. Re-validates queries it touches.
+
+For multi-step flows, write a typed `apiClient` helper in
+`src/lib/api/clients/` rather than re-doing fetch in three places.
+
+### 4.7 Inline help
+
+A small `?` `<Tooltip>` next to the label is the default for non-trivial
+fields (e.g. "Why does this default to ESH 2023?"). Tooltips must be
+keyboard-accessible (Radix handles this) and translated.
+
+For long explanations, link out to `https://docs.healthlog.dev/...` —
+never embed multi-paragraph help inline.
+
+---
+
+## 5. Accessibility
+
+We aim for **WCAG 2.1 AA**, with the following non-negotiables:
+
+- Color contrast ≥ 4.5:1 for normal text, 3:1 for large text and UI
+  components. Verified by `@axe-core/playwright` in CI on every page.
+- Touch targets ≥ 44×44 CSS px on bottom-nav and primary action buttons
+  (WCAG 2.5.5).
+- Focus is always visible: shadcn's `focus-visible:ring` is preserved on
+  every customized component.
+- Every interactive element has an accessible name. Icon-only buttons
+  get `<span className="sr-only">` labels and `aria-label`.
+- `prefers-reduced-motion: reduce` disables animations beyond a 200 ms
+  fade.
+- Charts include text-equivalent summaries (`aria-describedby` linked to
+  a `<p className="sr-only">` summary) and exposed data via the visible
+  legend / table view toggle.
+
+CI fails on any `serious` or `critical` axe-core violation.
+
+---
+
+## 6. Slider audit and migration
+
+Sliders look pretty but are a poor fit for most numeric inputs because
+they sacrifice precision. The 1.4 audit catalogues every `<Slider>` in
+the codebase and migrates the inappropriate ones:
+
+| Setting                             | Current control | Better control                  |
+| ----------------------------------- | --------------- | ------------------------------- |
+| Mood intensity (0–10)               | Slider          | SegmentedControl                |
+| Notification quiet-hours range      | Two sliders     | Two `<Input type="time">`       |
+| Threshold-override numeric values   | Slider          | `<Input type="number">` + steps |
+| AI insight depth (1–5 levels)       | Slider          | `<RadioGroup>` cards            |
+| Export retention days (7/30/90/365) | Slider          | `<Select>` with preset options  |
+
+A slider stays appropriate for "scrub through history" or "set chart
+zoom range" — operations where the value is continuous and live preview
+is the point.
+
+---
+
+## 7. Internationalization
+
+All user-facing strings come from `messages/en.json` (default) and
+`messages/de.json`. Use `useTranslations()` on the client and
+`getServerTranslator()` (`src/lib/i18n/server-translator.ts`) on the
+server. Numbers, dates, currencies, and units always go through
+`useFormatters()` — never hand-roll `Intl.NumberFormat(...)` with a
+fixed locale.
+
+Server-rendered content (PDFs, notifications, server-issued category
+labels) must use the locale of the user the content is for, not the
+locale of the request that triggered the job.
+
+---
+
+## 8. Motion
+
+Default transitions: `transition-all duration-150 ease-out`. Heavier
+animations (insight cards, dialog enter/exit) use the shadcn defaults.
+Reduce-motion always wins.
+
+Loading skeletons pulse via Tailwind `animate-pulse`. Don't introduce
+custom keyframes without adding a `prefers-reduced-motion` fallback.
+
+---
+
+## 9. Component checklist (for new features)
+
+Before opening a PR for a new component or page, walk through:
+
+- [ ] Uses tokens from §1, not hard-coded hex/rgba.
+- [ ] Buttons follow §2.1 variant + position rules.
+- [ ] Inputs follow §2.2; correct `autocomplete`; honey-pots where needed.
+- [ ] Dialog vs Sheet vs Drawer per §2.3.
+- [ ] Loading, empty, and error states from §4.1–4.3 implemented.
+- [ ] All strings via `t()`; numbers via formatters.
+- [ ] Mobile viewport tested (Chrome DevTools 375×667 and 414×896).
+- [ ] Light + Dark mode tested.
+- [ ] Keyboard navigation: Tab order, Enter to submit, Esc to dismiss.
+- [ ] axe-core clean (no serious/critical).
+- [ ] Headless screenshot test added if UI is non-trivial.
+
+---
+
+_Maintained as part of the v1.4 release cycle. Propose changes alongside
+the code that motivates them._

e2e/README.md

@@ -0,0 +1,21 @@
+# `e2e/`
+
+End-to-end browser tests. Playwright 1.60 drives a production build of the app against a real PostgreSQL, with `@axe-core/playwright` for accessibility assertions. This is the heaviest test tier; CI runs it on every PR, and locally it is worth running when a change touches a UI flow.
+
+## Running
+
+```bash
+pnpm e2e
+```
+
+The Playwright config (`../playwright.config.ts`) builds the app (`next build`) and brings up Postgres before the specs run; `setup/global-setup.ts` seeds the auth + fixture state. The suite is not part of the fast local gate (`typecheck` / `lint` / `test`) — it surfaces at PR CI, so expect responsive/wizard/nav reworks to flag here first.
+
+## Layout
+
+- **`setup/`** — `global-setup.ts` (auth + DB seeding), `test-helpers.ts` (shared login + navigation helpers).
+- **`utils/`** — fixtures such as `mock-dashboard-snapshot.ts`.
+- **`*.spec.ts`** — one spec per flow: auth/login/redirect, dashboard, charts, the medication-wizard cadences (`medications-wizard-*`), insights generation + scroll restoration, doctor report, settings, mobile-viewport consistency, locale switch, accessibility (`a11y.spec.ts`), and the `v1427-*` regression set.
+
+## Convention
+
+Assert against stable `data-*` attributes (`data-slot`, `data-display-step`, root display attrs), not viewport-dependent visible text. Responsive `sm:hidden` UI changes break `getByText` on desktop while the underlying element is still present — anchoring on data attributes keeps the specs stable across breakpoints. See [`../CLAUDE.md`](../CLAUDE.md).

e2e/a11y.spec.ts

@@ -0,0 +1,168 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * Accessibility regression gate — fails the build if any WCAG 2.1 AA
+ * violation lands in the `serious` or `critical` bucket. v1.5 phase-5
+ * re-enables the `/admin` surface that phase-3 had parked while phase-4b
+ * restructured the admin into per-section dynamic routes:
+ *
+ *   - `/auth/login`             (public)
+ *   - `/`                        (dashboard, authenticated)
+ *   - `/settings/integrations`   (authenticated)
+ *   - `/admin`                   (admin overview — `<StatusCardGrid>`)
+ *   - `/admin/system-status`     (representative admin sub-route)
+ *   - `/admin/users`             (admin users management — icon-only buttons)
+ *
+ * The seeded user (`e2e-tester`) is provisioned with `role: ADMIN` in
+ * `e2e/setup/global-setup.ts` so the same fixture covers both regular
+ * and admin surfaces without a second user.
+ */
+
+function reportBlocking(
+  blocking: Awaited<ReturnType<AxeBuilder["analyze"]>>["violations"],
+) {
+  if (blocking.length === 0) return;
+  // Pretty-print so failures are actionable in CI logs.
+  console.log(
+    "axe violations:\n" +
+      blocking
+        .map(
+          (v) =>
+            `  - [${v.impact}] ${v.id}: ${v.help}\n    ${v.nodes.length} node(s)\n    ${v.helpUrl}`,
+        )
+        .join("\n"),
+  );
+}
+
+async function runAxe(page: import("@playwright/test").Page) {
+  const results = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+    .analyze();
+  return results.violations.filter(
+    (v) => v.impact === "serious" || v.impact === "critical",
+  );
+}
+
+test.describe("axe-core public surfaces", () => {
+  for (const path of ["/auth/login"]) {
+    test(`${path} has no serious or critical a11y violations`, async ({
+      page,
+    }) => {
+      await page.goto(path);
+      await page.waitForLoadState("networkidle");
+
+      const blocking = await runAxe(page);
+      reportBlocking(blocking);
+      expect(blocking).toHaveLength(0);
+    });
+  }
+});
+
+test.describe("axe-core authenticated surfaces", () => {
+  // Reuse the cookie jar captured by `e2e/setup/global-setup.ts`. Login
+  // ran once in global-setup so we don't burn auth rate-limit attempts.
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  // Stable mocks so the auth'd pages render deterministically — axe scans
+  // need fully-painted DOM, and a flaky API would otherwise stall the
+  // analyse() call until the 30s test timeout.
+  test.beforeEach(async ({ page }) => {
+    // v1.4.39.3 — match `/api/analytics` AND any sliced variant
+    // (`?slice=summaries`); the v1.4.39.2 dashboard split fires both
+    // in parallel and the literal string glob misses the query-
+    // string form.
+    await page.route(/\/api\/analytics(\?|$)/, (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { summaries: {}, bpInTargetPct: null, glucoseByContext: {} },
+          error: null,
+        }),
+      }),
+    );
+    await page.route("**/api/mood/analytics", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { entries: [], summary: { count: 0 } },
+          error: null,
+        }),
+      }),
+    );
+  });
+
+  for (const path of [
+    "/",
+    "/settings/integrations",
+    "/admin",
+    "/admin/system-status",
+    "/admin/users",
+  ]) {
+    test(`${path} has no serious or critical a11y violations`, async ({
+      page,
+    }) => {
+      await page.goto(path, { waitUntil: "domcontentloaded" });
+      await page.waitForLoadState("networkidle");
+
+      const blocking = await runAxe(page);
+      reportBlocking(blocking);
+      expect(blocking).toHaveLength(0);
+    });
+  }
+
+  // The keyboard-only "skip to content" link is fixed at the top-left
+  // corner of every authenticated page. Marc reported it intercepting
+  // logo clicks in v1.4.14 — the fix combines `pointer-events-none`
+  // with `-translate-y-full` so the element sits offscreen until
+  // focused. Regression guard: with no keyboard focus, the logo's own
+  // bounding box must accept the click.
+  test("skip-link does not block logo click outside focus", async ({
+    page,
+    viewport,
+  }) => {
+    // The desktop sidebar (and its logo) is `hidden md:flex` — the
+    // mobile profile (Pixel 5) hides it by design. The skip-link
+    // regression Marc originally reported in v1.4.14 was a desktop-
+    // only artifact (mobile uses the topbar logo, which is a
+    // different DOM node). Skip the mobile project so we don't
+    // flake on a contract that doesn't apply there.
+    test.skip(
+      (viewport?.width ?? 0) < 768,
+      "desktop sidebar logo is hidden on mobile by design",
+    );
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // Find the desktop sidebar logo link — `<Logo>` is rendered inside
+    // a `<Link href="/">` and the only logo at the absolute top-left
+    // of the layout. We resolve it by role / accessible name to avoid
+    // brittle selectors.
+    const logoLink = page
+      .locator("a[href='/']")
+      .filter({ hasText: "HealthLog" })
+      .first();
+    await expect(logoLink).toBeVisible();
+
+    const logoBox = await logoLink.boundingBox();
+    expect(logoBox).not.toBeNull();
+    if (!logoBox) return;
+
+    // Click the centre of the logo. If the skip-link is intercepting
+    // pointer events, Playwright's auto-waiting click would either time
+    // out or report the wrong element. The defensive `force: false`
+    // (default) ensures we go through the full hit-test pipeline.
+    await logoLink.click({
+      position: { x: logoBox.width / 2, y: logoBox.height / 2 },
+    });
+
+    // Logo points at "/", so we either stay on "/" or get a no-op
+    // reload. Either way the URL must remain on the dashboard.
+    await page.waitForURL(/\/$/);
+  });
+});

e2e/achievements.spec.ts

@@ -0,0 +1,224 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.4.15 phase-B4 — /achievements navigation smoke.
+ *
+ * The page itself has unit-test coverage for the locked-vs-unlocked
+ * card render; this spec answers the higher-level "can the user reach
+ * the page from the global nav?" question. We mock
+ * `/api/gamification/achievements` so the assertion does not depend on
+ * the seed user actually having any achievement data — the routing +
+ * sidebar wiring is what matters here, not the data freshness.
+ *
+ * v1.4.18 — added a second describe-block exercising the four card
+ * states (unlocked / locked-earnable / hidden-locked / hidden-unlocked)
+ * and asserting that hidden cards never leak their real strings to the
+ * DOM.
+ */
+test.describe("achievements page is reachable from the sidebar", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page }) => {
+    await page.route("**/api/gamification/achievements", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            summary: {
+              unlockedCount: 0,
+              totalCount: 38,
+              earnedPoints: 0,
+              totalPoints: 9999,
+              completionPercent: 0,
+              nextAchievement: null,
+            },
+            achievements: [
+              {
+                id: "intake-total-1",
+                metric: "totalTakenIntakes",
+                category: "medication",
+                titleKey: "achievements.badges.intakeTotal1.title",
+                descriptionKey: "achievements.badges.intakeTotal1.description",
+                icon: "Pill",
+                format: "count",
+                target: 1,
+                current: 0,
+                points: 8,
+                unlocked: false,
+                progressPercent: 0,
+                completedAt: null,
+              },
+            ],
+            metrics: {},
+          },
+          error: null,
+        }),
+      }),
+    );
+  });
+
+  test("desktop sidebar exposes the achievements link", async ({
+    page,
+    viewport,
+  }) => {
+    // The sidebar nav is hidden on small viewports (`md:flex`). The
+    // chromium-mobile profile (Pixel 5, 393 px wide) cannot satisfy
+    // this contract by design — skip there so the spec only runs in
+    // the chromium-desktop project (1280×720). Without this guard
+    // every push fails 1 / 4 specs purely because the same suite is
+    // sharded across both projects.
+    test.skip(
+      (viewport?.width ?? 0) < 768,
+      "sidebar is hidden on mobile by design (md:flex breakpoint)",
+    );
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    // Match by aria-label so we don't accidentally pick up a tooltip.
+    const sidebar = page.locator('aside[aria-label="Sidebar"]');
+    await expect(sidebar).toBeVisible();
+    await sidebar.getByRole("link", { name: "Achievements" }).click();
+    await expect(page).toHaveURL(/\/achievements\b/);
+    // Page title from the loaded route. The unit test guards the
+    // grouped + locked-card render shape; here we only assert the route
+    // mounted and rendered the heading.
+    await expect(
+      page.getByRole("heading", { name: "Achievements" }),
+    ).toBeVisible({ timeout: 5000 });
+  });
+});
+
+test.describe("achievements page renders all four card states", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page }) => {
+    await page.route("**/api/gamification/achievements", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            summary: {
+              unlockedCount: 2,
+              totalCount: 4,
+              earnedPoints: 43,
+              totalPoints: 200,
+              completionPercent: 50,
+              nextAchievement: null,
+            },
+            achievements: [
+              // Unlocked public
+              {
+                id: "intake-total-1",
+                metric: "totalTakenIntakes",
+                category: "medication",
+                titleKey: "achievements.badges.intakeTotal1.title",
+                descriptionKey: "achievements.badges.intakeTotal1.description",
+                icon: "Pill",
+                format: "count",
+                target: 1,
+                current: 5,
+                points: 8,
+                unlocked: true,
+                progressPercent: 100,
+                completedAt: "2026-04-15T12:00:00.000Z",
+                isHidden: false,
+              },
+              // Locked-earnable public (mood streak — user has mood data)
+              {
+                id: "mood-streak-7",
+                metric: "moodDayStreak",
+                category: "mood",
+                titleKey: "achievements.badges.moodStreak7.title",
+                descriptionKey: "achievements.badges.moodStreak7.description",
+                icon: "Smile",
+                format: "days",
+                target: 7,
+                current: 3,
+                points: 50,
+                unlocked: false,
+                progressPercent: 42,
+                completedAt: null,
+                isHidden: false,
+              },
+              // Hidden + locked → opaque placeholder
+              {
+                id: "hidden-night-owl",
+                metric: "nightOwlCount",
+                category: "hidden",
+                titleKey: "achievements.badges.hiddenNightOwl.title",
+                descriptionKey:
+                  "achievements.badges.hiddenNightOwl.description",
+                icon: "Moon",
+                format: "count",
+                target: 1,
+                current: 0,
+                points: 25,
+                unlocked: false,
+                progressPercent: 0,
+                completedAt: null,
+                isHidden: true,
+              },
+              // Hidden + unlocked → real strings revealed
+              {
+                id: "hidden-doctor-pdf",
+                metric: "doctorPdfCount",
+                category: "hidden",
+                titleKey: "achievements.badges.hiddenDoctorPdf.title",
+                descriptionKey:
+                  "achievements.badges.hiddenDoctorPdf.description",
+                icon: "FileText",
+                format: "count",
+                target: 1,
+                current: 1,
+                points: 35,
+                unlocked: true,
+                progressPercent: 100,
+                completedAt: "2026-04-30T10:00:00.000Z",
+                isHidden: true,
+              },
+            ],
+            metrics: {},
+          },
+          error: null,
+        }),
+      }),
+    );
+  });
+
+  test("renders unlocked, locked-earnable, hidden-locked and hidden-unlocked cards", async ({
+    page,
+  }) => {
+    await page.goto("/achievements", { waitUntil: "domcontentloaded" });
+
+    // Page heading present
+    await expect(
+      page.getByRole("heading", { name: "Achievements" }),
+    ).toBeVisible({ timeout: 5000 });
+
+    // Unlocked public — title visible
+    await expect(page.getByText("First intake")).toBeVisible();
+
+    // Locked-earnable public — title visible AND criterion hint
+    // visible (3 / 7 days for mood-streak-7).
+    await expect(page.getByText("Mood diarist 7d")).toBeVisible();
+
+    // Hidden-locked — opaque placeholder visible. The real title /
+    // description must NOT appear in the rendered HTML.
+    await expect(page.getByText("Hidden achievement").first()).toBeVisible();
+    const html = await page.content();
+    expect(html).not.toContain("Night owl");
+    expect(html).not.toContain("between 02:00");
+    expect(html).not.toContain("nightOwlCount");
+
+    // Hidden-unlocked — title revealed once earned
+    await expect(page.getByText("House call")).toBeVisible();
+
+    // The opaque hidden card carries the data-slot for E2E hooks
+    await expect(
+      page.locator('[data-slot="achievement-card-hidden"]'),
+    ).toBeVisible();
+  });
+});

e2e/admin-api-tokens-mobile.spec.ts

@@ -0,0 +1,229 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.4.16 A3 — `/admin/api-tokens` must not produce horizontal page
+ * overflow on a Pixel-5 viewport (393 CSS px). v1.4.15 added column-
+ * hide breakpoints + tighter card padding, but Marc still saw a
+ * scrollbar on prod. The v1.4.16 fix swaps the desktop `<table>` for a
+ * mobile card-list at <md, mirroring `<UserManagementSection>`.
+ *
+ * Mobile-only spec — the desktop project skips it.
+ */
+test.describe("/admin/api-tokens mobile no-overflow", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(({}, testInfo) => {
+    test.skip(testInfo.project.name !== "chromium-mobile", "mobile-only spec");
+  });
+
+  test("Pixel-5 viewport: no horizontal page scroll on /admin/api-tokens", async ({
+    page,
+  }) => {
+    // Mock the admin tokens endpoint with a moderately wide payload —
+    // a token with multiple permissions, a long name, and timestamps.
+    // This is the realistic worst case Marc hit on prod.
+    await page.route("**/api/admin/tokens", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: [
+            {
+              id: "tok1",
+              name: "iOS app device-AABBCCDDEEFF",
+              permissions: ["measurements:write", "medications:read", "*"],
+              lastUsedAt: "2026-05-08T12:00:00Z",
+              expiresAt: null,
+              createdAt: "2026-05-01T08:00:00Z",
+              revoked: false,
+              user: { id: "u1", username: "marc-the-very-long-username" },
+            },
+            {
+              id: "tok2",
+              name: "Native client xyz",
+              permissions: ["*"],
+              lastUsedAt: null,
+              expiresAt: "2026-08-01T00:00:00Z",
+              createdAt: "2026-04-15T08:00:00Z",
+              revoked: false,
+              user: { id: "u1", username: "marc-the-very-long-username" },
+            },
+          ],
+          error: null,
+        }),
+      }),
+    );
+
+    await page.goto("/admin/api-tokens", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // The mobile card-list must be visible and the desktop table must
+    // be display:none at this viewport.
+    await expect(page.getByTestId("admin-tokens-mobile-list")).toBeVisible({
+      timeout: 10_000,
+    });
+
+    const dims = await page.evaluate(() => ({
+      scrollWidth: document.documentElement.scrollWidth,
+      innerWidth: window.innerWidth,
+    }));
+    expect(
+      dims.scrollWidth,
+      `scrollWidth=${dims.scrollWidth}, innerWidth=${dims.innerWidth}`,
+    ).toBeLessThanOrEqual(dims.innerWidth + 1);
+  });
+
+  // v1.4.18 phase A2 — production probe at Pixel-5 viewport pinned the
+  // visible "scrollbar" Marc reported for the third time as the
+  // `<AdminShell>` mobile section strip, NOT the api-tokens table. The
+  // strip carries 13 admin sections so its scrollWidth (~1700 CSS px)
+  // permanently exceeds clientWidth (~360 CSS px). Adding the
+  // `no-scrollbar` utility class (`globals.css`) suppresses the
+  // painted bar while preserving swipe + keyboard-arrow scrolling.
+  // This regression guard fails if a future refactor drops the class.
+  test("Pixel-5 viewport: admin section strip suppresses its painted scrollbar", async ({
+    page,
+  }) => {
+    await page.route("**/api/admin/tokens", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ data: [], error: null }),
+      }),
+    );
+
+    await page.goto("/admin/api-tokens", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // Find the mobile strip (`<nav aria-label>` matches both English
+    // "Admin sections" and German "Admin-Bereiche").
+    const strip = page.locator("nav.no-scrollbar.overflow-x-auto").first();
+    await expect(strip).toBeAttached();
+
+    // The strip itself must declare `no-scrollbar` so the painted
+    // horizontal scrollbar — which production showed at Pixel-5 — is
+    // suppressed.
+    const cls = await strip.getAttribute("class");
+    expect(cls ?? "").toContain("no-scrollbar");
+    expect(cls ?? "").toContain("overflow-x-auto");
+
+    // And the strip must still carry useful overflow internally
+    // (clientWidth < scrollWidth), proving scroll behaviour isn't
+    // disabled — only the bar is invisible.
+    const stripDims = await strip.evaluate((el) => ({
+      scrollWidth: (el as HTMLElement).scrollWidth,
+      clientWidth: (el as HTMLElement).clientWidth,
+    }));
+    expect(stripDims.scrollWidth).toBeGreaterThan(stripDims.clientWidth);
+  });
+
+  // v1.4.19 phase A7 (4th attempt) — even with the mobile-strip
+  // `no-scrollbar` fix from v1.4.18, Marc still reported a painted
+  // scrollbar. The card body itself must not contribute any
+  // horizontal-overflow culprit: every element inside the api-tokens
+  // section must satisfy `scrollWidth <= clientWidth + 1`. Pads with
+  // a long token name + long username + a long permission to exercise
+  // the worst case.
+  test("Pixel-5 viewport: nothing inside the api-tokens card overflows horizontally", async ({
+    page,
+  }) => {
+    await page.route("**/api/admin/tokens", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: [
+            {
+              id: "tok1",
+              name: "iOS auto-login 2026-05-05T19:42:11Z device-AABBCCDDEEFF-marathon",
+              permissions: [
+                "measurements:write:audit:legacy:extended",
+                "medications:read",
+                "*",
+              ],
+              lastUsedAt: "2026-05-08T12:00:00Z",
+              expiresAt: null,
+              createdAt: "2026-05-01T08:00:00Z",
+              revoked: false,
+              user: {
+                id: "u1",
+                username: "marc-the-very-long-username-that-overflows",
+              },
+            },
+          ],
+          error: null,
+        }),
+      }),
+    );
+
+    await page.goto("/admin/api-tokens", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+    await expect(page.getByTestId("admin-tokens-mobile-list")).toBeVisible({
+      timeout: 10_000,
+    });
+
+    // Walk every element inside the mobile card-list and assert no
+    // child has a wider scrollWidth than its container. This is the
+    // Pixel-5 worst-case Marc kept hitting.
+    //
+    // Elements clamped via `truncate` (Tailwind's `overflow:hidden +
+    // text-overflow:ellipsis + white-space:nowrap` shorthand) are by
+    // design `scrollWidth > clientWidth` whenever the underlying text
+    // is longer than the parent column — that IS the truncation, not
+    // an overflow leak. Skip those so the assertion only fires on real
+    // layout culprits (a span without a width clamp pushing its parent
+    // wider). The page-level `dims.scrollWidth <= dims.innerWidth + 1`
+    // assertion below remains the authoritative no-scrollbar guard.
+    const culprits = await page
+      .getByTestId("admin-tokens-mobile-list")
+      .evaluate((root) => {
+        const isTruncated = (el: Element): boolean => {
+          const cs = window.getComputedStyle(el);
+          if (cs.textOverflow === "ellipsis" && cs.overflowX !== "visible") {
+            return true;
+          }
+          // Tailwind's `truncate` shorthand and any explicit overflow
+          // clamp also legitimately keep the visible content inside
+          // clientWidth even though scrollWidth measures full content.
+          if (cs.overflowX === "hidden" || cs.overflowX === "clip") {
+            return true;
+          }
+          return false;
+        };
+        const out: Array<{
+          tag: string;
+          klass: string;
+          scrollWidth: number;
+          clientWidth: number;
+        }> = [];
+        for (const el of root.querySelectorAll("*")) {
+          if (el.scrollWidth > el.clientWidth + 1 && !isTruncated(el)) {
+            out.push({
+              tag: el.tagName,
+              klass:
+                typeof el.className === "string"
+                  ? el.className.slice(0, 80)
+                  : "",
+              scrollWidth: el.scrollWidth,
+              clientWidth: el.clientWidth,
+            });
+          }
+        }
+        return out;
+      });
+    expect(
+      culprits,
+      `overflow culprits: ${JSON.stringify(culprits, null, 2)}`,
+    ).toEqual([]);
+
+    // Document-level horizontal overflow — the page must not paint
+    // any horizontal scroll, period.
+    const dims = await page.evaluate(() => ({
+      scrollWidth: document.documentElement.scrollWidth,
+      innerWidth: window.innerWidth,
+    }));
+    expect(dims.scrollWidth).toBeLessThanOrEqual(dims.innerWidth + 1);
+  });
+});

e2e/ai-provider-dropdown.spec.ts

@@ -0,0 +1,116 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.4.16 phase B2 — AI provider settings UX with single dropdown
+ * driving the form below. Three things to lock in here:
+ *
+ *   1. /settings/ai exposes the active-provider Pulldown
+ *      (`data-testid="ai-active-provider-select"`).
+ *   2. Switching the dropdown changes the rendered config form below
+ *      it: Codex form vs. OpenAI form vs. Anthropic form vs. Local
+ *      form. Each form carries a stable `data-testid` so we don't
+ *      lean on i18n labels.
+ *   3. The fallback chain card surfaces with stable
+ *      `data-chain-row="<providerType>"` markers per row.
+ */
+test.describe("Settings → AI provider dropdown UX (B2)", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("dropdown switch changes the rendered config form", async ({ page }) => {
+    // Stable mocks for every endpoint the section reads. The chain
+    // mirrors the default order (codex first) so the rows render
+    // deterministically and the dropdown defaults to codex.
+    await page.route("**/api/insights/settings", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            codexStatus: "disconnected",
+            codexConnectedAt: null,
+            hasAdminKey: false,
+            codexOauthConfigured: true,
+            privacyMode: "aggregated",
+            lastInsightAt: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.route("**/api/user/ai-provider", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            provider: null,
+            model: null,
+            baseUrl: null,
+            hasAnthropicKey: false,
+            anthropicKeyPreview: null,
+            hasLocalKey: false,
+            hasOpenaiKey: false,
+            openaiKeyPreview: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.route("**/api/insights/provider-chain", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            activeProvider: "codex",
+            cachedActiveProvider: null,
+            configuredChain: [
+              { providerType: "codex", available: true },
+              { providerType: "openai", available: true },
+              { providerType: "anthropic", available: true },
+              { providerType: "local", available: true },
+            ],
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.goto("/settings/ai", { waitUntil: "domcontentloaded" });
+
+    // 1. Dropdown surfaces on the page.
+    const select = page.getByTestId("ai-active-provider-select");
+    await expect(select).toBeVisible({ timeout: 10_000 });
+
+    // 2a. Default → Codex form rendered.
+    await expect(page.getByTestId("ai-provider-config-codex")).toBeVisible();
+    await expect(page.getByTestId("ai-provider-config-openai")).toHaveCount(0);
+
+    // 2b. Switch to OpenAI → OpenAI form rendered, Codex form gone.
+    await select.selectOption("openai");
+    await expect(page.getByTestId("ai-provider-config-openai")).toBeVisible();
+    await expect(page.getByTestId("ai-provider-config-codex")).toHaveCount(0);
+    await expect(page.getByTestId("ai-openai-api-key")).toBeVisible();
+    await expect(page.getByTestId("ai-openai-model")).toBeVisible();
+
+    // 2c. Switch to Anthropic → Anthropic form rendered.
+    await select.selectOption("anthropic");
+    await expect(
+      page.getByTestId("ai-provider-config-anthropic"),
+    ).toBeVisible();
+
+    // 2d. Switch to Local → Local form rendered.
+    await select.selectOption("local");
+    await expect(page.getByTestId("ai-provider-config-local")).toBeVisible();
+
+    // 3. Fallback chain card surfaces with the four chain rows.
+    await expect(page.getByTestId("ai-fallback-chain")).toBeVisible();
+    for (const slug of ["codex", "openai", "anthropic", "local"]) {
+      await expect(page.locator(`[data-chain-row="${slug}"]`)).toBeVisible();
+    }
+  });
+});

e2e/auth-redirect.spec.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * The proxy at src/proxy.ts is the single gate enforcing auth on every
+ * non-public path. A regression that accidentally adds a route to
+ * PUBLIC_PATHS, or breaks the redirect, would expose unauthenticated
+ * surfaces. Verify a few representative routes round-trip to /auth/login.
+ */
+test.describe("proxy auth gate", () => {
+  for (const path of [
+    "/",
+    "/dashboard",
+    "/medications",
+    "/admin",
+    "/insights",
+  ]) {
+    test(`${path} redirects to /auth/login when no session`, async ({
+      page,
+    }) => {
+      const response = await page.goto(path, { waitUntil: "domcontentloaded" });
+      expect(response).not.toBeNull();
+      // Either the proxy hands back a 307/308, or the navigation lands
+      // at /auth/login after redirect; both are acceptable proof.
+      expect(page.url()).toMatch(/\/auth\/login(\?|$)/);
+    });
+  }
+
+  test("public paths are reachable without a session", async ({ page }) => {
+    // /auth/login is in PUBLIC_PATHS — must be served, not bounced anywhere.
+    await page.goto("/auth/login");
+    expect(page.url()).toMatch(/\/auth\/login(\?|$)/);
+    await expect(page.locator("body")).toBeVisible();
+  });
+});

e2e/chart-overlay-controls.spec.ts

@@ -0,0 +1,154 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+import {
+  mockDashboardSnapshot,
+  WEIGHT_ONLY_SUMMARIES,
+} from "./utils/mock-dashboard-snapshot";
+
+/**
+ * v1.4.18 — per-chart overlay-controls popover.
+ *
+ * Marc reverted v1.4.16's always-on chart overlays (gradient fill,
+ * personal-baseline line, target-zone shading) and asked for per-chart
+ * switches that the user can flip on or off. This spec exercises the
+ * end-to-end behaviour against the seeded test user:
+ *
+ *   1. Dashboard renders with a chart.
+ *   2. The chart card has a settings cog in its header.
+ *   3. Clicking the cog opens a popover with three switches.
+ *   4. Toggling "Target range" on triggers a PUT /api/dashboard/chart-overlay-prefs.
+ */
+test.describe("chart overlay controls", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page }) => {
+    // v1.7.2 — snapshot flag default-ON; mock the snapshot cell with a
+    // WEIGHT-only populated summary so the weight chart card paints.
+    // Legacy mocks below stay for the reversible `=false` path.
+    await mockDashboardSnapshot(page, { summaries: WEIGHT_ONLY_SUMMARIES });
+
+    // Mock analytics + measurements so the dashboard paints at least
+    // one chart card. Same seed shape the dashboard.spec.ts uses.
+    //
+    // v1.4.39.3 — match `/api/analytics` AND any sliced variant
+    // (`?slice=summaries`). See the comment on dashboard.spec.ts for
+    // the underlying minimatch-vs-query-string gap; the regex form
+    // catches both the thick and slim slice URLs the dashboard now
+    // mounts in parallel.
+    await page.route(/\/api\/analytics(\?|$)/, (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            summaries: {
+              WEIGHT: {
+                latest: 78.5,
+                avg7: 78.2,
+                avg30: 77.9,
+                slope30: { slope: -0.05, direction: "down" },
+                count: 30,
+              },
+            },
+            bpInTargetPct: 0,
+            glucoseByContext: {},
+          },
+          error: null,
+        }),
+      }),
+    );
+    await page.route("**/api/mood/analytics", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { entries: [], summary: { count: 0 } },
+          error: null,
+        }),
+      }),
+    );
+    await page.route("**/api/measurements*", (route) => {
+      const measurements = Array.from({ length: 10 }, (_, i) => ({
+        id: `m_${i}`,
+        type: "WEIGHT",
+        value: 78 + (i % 3) - 1,
+        measuredAt: new Date(Date.now() - i * 86_400_000).toISOString(),
+        notes: null,
+      }));
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { measurements, meta: { total: measurements.length } },
+          error: null,
+        }),
+      });
+    });
+  });
+
+  test("opens the overlay-controls popover and saves a toggle change", async ({
+    page,
+  }) => {
+    let putRequestCount = 0;
+    await page.route("**/api/dashboard/chart-overlay-prefs", async (route) => {
+      if (route.request().method() === "PUT") {
+        putRequestCount += 1;
+      }
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ data: { saved: true }, error: null }),
+      });
+    });
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+
+    // Wait for the dashboard tile-strip to settle so we know the user
+    // is past initial auth + layout-fetch.
+    await expect(
+      page.locator('[data-slot="dashboard-tile-strip"]'),
+    ).toBeVisible({ timeout: 10_000 });
+
+    // The weight chart is one of the always-visible default charts and
+    // it ships an overlay-controls trigger because the dashboard plumbs
+    // a chartKey into it.
+    const trigger = page
+      .locator('[data-slot="chart-overlay-controls-trigger"]')
+      .first();
+    await expect(trigger).toBeVisible({ timeout: 10_000 });
+
+    // Scroll the trigger into view before opening the dropdown so the
+    // Radix Popper places its portalled content inside the viewport.
+    // On the seeded test user the dashboard renders multiple stacked
+    // chart cards, and the first cog can sit near the bottom edge of
+    // the desktop 1280×720 viewport — opening the popover then drops
+    // the toggle below the fold and Playwright refuses to click an
+    // off-viewport element after auto-scrolling.
+    await trigger.scrollIntoViewIfNeeded();
+    await trigger.click();
+
+    // The popover content paints three switches.
+    const targetRangeToggle = page.locator(
+      '[data-slot="chart-overlay-toggle-target-range"]',
+    );
+    await expect(targetRangeToggle).toBeVisible({ timeout: 5_000 });
+
+    // Toggle target-range on. Radix Switch is a button[role=switch].
+    // The Radix dropdown content portals to the body root and can land
+    // below the viewport on a 393×851 Pixel 5 (or near the bottom edge
+    // on the 1280×720 desktop profile). Playwright's `click({force:true})`
+    // still computes the element's bbox against the viewport and refuses
+    // to dispatch the click when it falls outside, so neither
+    // `scrollIntoViewIfNeeded()` on the portalled content nor `force`
+    // can rescue the action.  `dispatchEvent('click')` synthesises a DOM
+    // click on the element without any viewport / actionability check,
+    // which is exactly the semantic we want for an off-screen portalled
+    // Radix Switch — and it still fires the onCheckedChange handler that
+    // the surface listens for.
+    await targetRangeToggle.dispatchEvent("click");
+
+    // The PUT fires once for the toggle change.
+    await expect.poll(() => putRequestCount).toBeGreaterThan(0);
+  });
+});

e2e/charts-mobile.spec.ts

@@ -0,0 +1,282 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+import { mockDashboardSnapshot } from "./utils/mock-dashboard-snapshot";
+
+/**
+ * v1.4.19 A2 — mobile-viewport regression spec for chart cards.
+ *
+ * Two assertions per chart visible in the dashboard's initial paint:
+ *
+ *   1. Header layout integrity — the range tabs (`7 pts / 30 pts /
+ *      90 pts / All`) and the cog dropdown sit on a SINGLE horizontal
+ *      row inside the chart card. Pre-fix the bucket-aggregation chip
+ *      ("Weekly avg" / "Monthly avg") + comparison caption pushed the
+ *      tabs onto a second row on Pixel 5 (and 3-4 rows on Galaxy Fold
+ *      compact). The fix stacks title + chips above tabs + cog on
+ *      mobile so the tabs always own the full controls row.
+ *
+ *   2. X-axis tick density — Recharts' default rendered ONE tick per
+ *      data point, so a 30-day Pixel 5 window painted 30 overlapping
+ *      labels. The universal helper `chooseTickInterval` caps that at
+ *      6 ticks for ≤ 480px viewports.
+ *
+ * The spec runs only on the `chromium-mobile` project (Pixel 5,
+ * 393×851). Desktop sizes are exercised separately by the unit-test
+ * suite for the helper.
+ */
+
+test.describe("charts — mobile-viewport regression", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page }, testInfo) => {
+    test.skip(testInfo.project.name !== "chromium-mobile", "mobile-only spec");
+
+    // v1.7.2 — snapshot flag default-ON; mock the snapshot cell with the
+    // same populated four-metric set so the charts paint. Legacy mocks
+    // below stay for the reversible `=false` path.
+    await mockDashboardSnapshot(page);
+
+    // Mock analytics + measurements so the chart wrappers all clear
+    // their data-floor gates. Same pattern as `dashboard.spec.ts`.
+    //
+    // v1.4.39.3 — match `/api/analytics` AND any sliced variant
+    // (`?slice=summaries`). The v1.4.39.2 dashboard split mounts the
+    // slim slice in parallel; the literal `**/api/analytics` glob
+    // misses the query-string form and dropped the request through to
+    // the real route, blanking the tile strip + chart cards.
+    await page.route(/\/api\/analytics(\?|$)/, (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            summaries: {
+              WEIGHT: {
+                latest: 78.5,
+                avg7: 78.2,
+                avg30: 77.9,
+                slope30: { slope: -0.05, direction: "down" },
+                count: 30,
+              },
+              BLOOD_PRESSURE_SYS: {
+                latest: 124,
+                avg7: 122,
+                avg30: 121,
+                slope30: { slope: 0.1, direction: "flat" },
+                count: 30,
+              },
+              BLOOD_PRESSURE_DIA: {
+                latest: 80,
+                avg7: 79,
+                avg30: 78,
+                slope30: { slope: 0.05, direction: "flat" },
+                count: 30,
+              },
+              PULSE: {
+                latest: 68,
+                avg7: 70,
+                avg30: 71,
+                slope30: { slope: -0.2, direction: "down" },
+                count: 30,
+              },
+            },
+            bpInTargetPct: 78,
+            glucoseByContext: {},
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.route("**/api/mood/analytics", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { entries: [], summary: { count: 0 } },
+          error: null,
+        }),
+      }),
+    );
+
+    // Return 30 days of measurements per type so each chart paints a
+    // line with enough points that tick-density actually matters.
+    await page.route("**/api/measurements*", (route) => {
+      const url = new URL(route.request().url());
+      const type = url.searchParams.get("type") ?? "WEIGHT";
+      const baseValue =
+        type === "BLOOD_PRESSURE_SYS"
+          ? 124
+          : type === "BLOOD_PRESSURE_DIA"
+            ? 80
+            : type === "PULSE"
+              ? 70
+              : 78.5;
+      const measurements = Array.from({ length: 30 }, (_, i) => ({
+        id: `m_${type}_${i}`,
+        type,
+        value: baseValue + (i % 5) - 2,
+        measuredAt: new Date(Date.now() - i * 86_400_000).toISOString(),
+        notes: null,
+      }));
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { measurements, meta: { total: measurements.length } },
+          error: null,
+        }),
+      });
+    });
+
+    // Medication compliance — return 30 days of mostly-perfect
+    // compliance so the chart clears the sparse-data threshold and
+    // paints a line with the full window.
+    await page.route("**/api/medications/intake*", (route) => {
+      const points = Array.from({ length: 30 }, (_, i) => {
+        const d = new Date(Date.now() - i * 86_400_000);
+        const yyyy = d.getUTCFullYear();
+        const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+        const dd = String(d.getUTCDate()).padStart(2, "0");
+        return {
+          date: `${yyyy}-${mm}-${dd}`,
+          scheduled: 2,
+          taken: i % 7 === 0 ? 1 : 2,
+        };
+      });
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ data: points, error: null }),
+      });
+    });
+  });
+
+  test("chart header keeps range tabs on a single row at Pixel 5", async ({
+    page,
+  }) => {
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // Wait for at least one chart-range-tab to mount.
+    await page
+      .locator("[data-slot=chart-range-tab]")
+      .first()
+      .waitFor({ timeout: 10_000 });
+
+    // Group the visible range tabs by their card and assert each
+    // card's tabs share a single Y coordinate (== one row).
+    const findings = await page.evaluate(() => {
+      const cards = Array.from(document.querySelectorAll("div.bg-card")).filter(
+        (c) => c.querySelector("[data-slot=chart-range-tab]") !== null,
+      );
+      return cards.map((card) => {
+        const title =
+          card
+            .querySelector("h3, [data-slot=card-title]")
+            ?.textContent?.trim() ?? "(unknown)";
+        const tabs = Array.from(
+          card.querySelectorAll("[data-slot=chart-range-tab]"),
+        );
+        const tops = tabs.map((t) => Math.round(t.getBoundingClientRect().top));
+        const uniqueRows = new Set(tops).size;
+        const rect = card.getBoundingClientRect();
+        return {
+          title,
+          tabCount: tabs.length,
+          uniqueRows,
+          overflow: card.scrollWidth > card.clientWidth + 1,
+          width: rect.width,
+        };
+      });
+    });
+
+    // We must find at least one charted card.
+    expect(findings.length, "no chart cards detected").toBeGreaterThan(0);
+
+    for (const f of findings) {
+      expect(
+        f.uniqueRows,
+        `${f.title}: tabs split across ${f.uniqueRows} rows (expected 1)`,
+      ).toBe(1);
+      expect(f.overflow, `${f.title} card overflows horizontally`).toBe(false);
+    }
+  });
+
+  test("chart x-axis paints ≤ 7 ticks at Pixel 5 with a 30-day window", async ({
+    page,
+  }) => {
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // Wait for at least one chart card to mount, then scroll it into
+    // view so Recharts' ResponsiveContainer measures its parent and
+    // paints the SVG. On Pixel 5 the dashboard ships several stacked
+    // tiles above the first chart card; the bottom-positioned axis
+    // sits below the initial fold and reports as `hidden` to a raw
+    // `.recharts-xAxis` visibility probe before scroll.
+    const firstChartCard = page
+      .locator("div.bg-card")
+      .filter({ has: page.locator("[data-slot=chart-range-tab]") })
+      .first();
+    await firstChartCard.waitFor({ state: "visible", timeout: 10_000 });
+    await firstChartCard.scrollIntoViewIfNeeded();
+    // After scroll, give the chart a beat to lay out under the new
+    // measured size before counting ticks. The chart card on Pixel-5
+    // is taller than the 851-px viewport, so `scrollIntoViewIfNeeded`
+    // brings the card's TOP into view but the bottom-anchored x-axis
+    // labels can remain below the fold — `state: "attached"` is
+    // sufficient and stable against viewport overflow.
+    //
+    // Recharts 3.x DOM shift (v1.4.25): tick labels are no longer
+    // nested inside `.recharts-xAxis`. They render in a separate
+    // ZIndexLayer container `.recharts-xAxis-tick-labels` that sits
+    // as a sibling of the axis-line layer. Each label is a
+    // `.recharts-cartesian-axis-tick-label` <g> wrapping a
+    // <text class="recharts-text recharts-cartesian-axis-tick-value">.
+    // Wait on the label container's text node so the assertion is
+    // class-position-independent.
+    await page
+      .locator(".recharts-xAxis-tick-labels text")
+      .first()
+      .waitFor({ state: "attached", timeout: 10_000 });
+
+    // Count rendered x-axis tick labels per wrapper. We scope to
+    // `.recharts-wrapper` so each chart is counted once, and read
+    // labels from `.recharts-xAxis-tick-labels` — the new (3.x)
+    // sibling container that holds the visible tick text. Empty
+    // structural ticks live in `.recharts-xAxis-tick-lines` and
+    // never carry text, so the labels-container is the right axis
+    // for legibility.
+    const tickCounts = await page.evaluate(() => {
+      const wrappers = Array.from(
+        document.querySelectorAll(".recharts-wrapper"),
+      );
+      return wrappers
+        .map((wrapper) => {
+          const labels = Array.from(
+            wrapper.querySelectorAll(
+              ".recharts-xAxis-tick-labels .recharts-cartesian-axis-tick-label",
+            ),
+          );
+          const visibleLabels = labels.filter(
+            (l) => (l.textContent?.trim() ?? "").length > 0,
+          );
+          return visibleLabels.length;
+        })
+        .filter((n) => n > 0);
+    });
+
+    expect(tickCounts.length, "no recharts axes detected").toBeGreaterThan(0);
+
+    for (const count of tickCounts) {
+      // Pixel 5 = 393 px → max 6 ticks per the helper. Allow 7 for
+      // Recharts' preserveStartEnd interaction.
+      expect(
+        count,
+        `axis paints ${count} ticks (max 7 allowed)`,
+      ).toBeLessThanOrEqual(7);
+    }
+  });
+});

e2e/codex-flow.spec.ts

@@ -0,0 +1,121 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * Settings → KI Codex device-flow spec. The real OAuth handshake bounces
+ * through chatgpt.com, which we deliberately do NOT hit from CI; instead
+ * we mock the three relevant endpoints (`device-start`, `device-poll`,
+ * `insights/settings`) so the assertion focuses on the UI state machine:
+ *
+ *   1. "Connect with ChatGPT" CTA visible
+ *   2. After click → device-code panel showing userCode + verificationUrl
+ *   3. After mocked poll flips to `connected` → "ChatGPT connected" badge
+ */
+test.describe("settings AI codex device flow (mocked)", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("button → device-code panel → connected state", async ({ page }) => {
+    let connected = false;
+
+    // Status endpoint — flips to "connected" once `connected` is set.
+    await page.route("**/api/insights/settings", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            codexStatus: connected ? "connected" : "disconnected",
+            codexConnectedAt: connected ? new Date().toISOString() : null,
+            hasAdminKey: false,
+            codexOauthConfigured: true,
+            privacyMode: "aggregated",
+            lastInsightAt: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    // device-start — returns the user-facing code + verification URL.
+    await page.route("**/api/auth/codex/device-start", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            userCode: "WXYZ-7890",
+            verificationUrl: "https://chatgpt.com/codex/device",
+            intervalSeconds: 1,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    // device-poll — first call returns `pending`; flips to `connected`
+    // after a short delay so the test can assert the transition.
+    let pollCount = 0;
+    await page.route("**/api/auth/codex/device-poll", (route) => {
+      pollCount += 1;
+      const status = pollCount >= 2 ? "connected" : "pending";
+      if (status === "connected") connected = true;
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { status },
+          error: null,
+        }),
+      });
+    });
+
+    // Mock the user AI provider endpoint — the AI section renders a
+    // sub-panel that fetches this; we want it to resolve quickly so the
+    // page is interactive.
+    await page.route("**/api/user/ai-provider", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            provider: null,
+            model: null,
+            baseUrl: null,
+            hasAnthropicKey: false,
+            anthropicKeyPreview: null,
+            hasLocalKey: false,
+            hasOpenaiKey: false,
+            openaiKeyPreview: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.goto("/settings/ai", { waitUntil: "domcontentloaded" });
+
+    // Step 1 — CTA visible
+    const cta = page.getByRole("button", {
+      name: /connect with chatgpt|mit chatgpt verbinden/i,
+    });
+    await expect(cta).toBeVisible({ timeout: 10_000 });
+    await cta.click();
+
+    // Step 2 — device-code panel shows the userCode and the verificationUrl
+    await expect(page.getByText("WXYZ-7890")).toBeVisible({ timeout: 5_000 });
+    await expect(
+      page.getByRole("link", { name: /chatgpt\.com\/codex\/device/i }),
+    ).toBeVisible();
+
+    // Step 3 — once the polling loop hits `connected`, the badge appears.
+    // The poll runs at the device-flow `intervalSeconds` (1 second).
+    await expect(page.getByText(/chatgpt connected/i).first()).toBeVisible({
+      timeout: 15_000,
+    });
+
+    // The device-code panel should disappear once connected (the
+    // settings card swaps to the connected layout).
+    await expect(page.getByText("WXYZ-7890")).toBeHidden({ timeout: 5_000 });
+  });
+});

e2e/dashboard.spec.ts

@@ -0,0 +1,189 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+import { mockDashboardSnapshot } from "./utils/mock-dashboard-snapshot";
+
+/**
+ * Authenticated dashboard render — proves the seed user can reach the
+ * home dashboard and the core widgets paint without uncaught client
+ * errors.
+ *
+ * The dashboard self-gates each tile on (visible AND has data), so a
+ * fresh seed user with zero measurements would render an empty strip
+ * and skip all charts. Rather than seed measurements before this spec
+ * runs (which couples the spec to a particular signature of the
+ * `/api/measurements` shape), we mock `/api/analytics` and
+ * `/api/dashboard/widgets` to return a deterministic dataset. The
+ * widget layout + chart wrappers are pure enough that asserting on the
+ * mocked-data render exercises the same code paths as a real session.
+ */
+test.describe("authenticated dashboard render", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page }) => {
+    // v1.7.2 — the dashboard snapshot flag is default-ON, so the page
+    // reads every tile from `/api/dashboard/snapshot` and ignores the
+    // legacy cells below. Mock the snapshot with the same populated
+    // four-metric set so the tile strip + charts paint. The legacy
+    // `/api/analytics` + `/api/mood/analytics` mocks stay for the
+    // reversible `NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false` path.
+    await mockDashboardSnapshot(page);
+
+    // Mock analytics with a populated weight summary so the weight tile
+    // and chart render. `count` must be >0 for the tile to clear the
+    // data-floor gate in `src/app/page.tsx`.
+    //
+    // v1.4.39.3 — match `/api/analytics` AND any sliced variant
+    // (`?slice=summaries`). The v1.4.39.2 dashboard split mounts two
+    // parallel `useAnalyticsQuery` calls; the slim variant carries a
+    // `?slice=summaries` query string that the literal string glob
+    // `**/api/analytics` (Playwright minimatch) refuses to match,
+    // dropping the request to the real route. The seeded test user has
+    // no measurements so the real route returns empty summaries, and
+    // the dashboard's slim-first merge then blanked the tile strip.
+    // The same trap bit `onboarding-flicker` and `mobile-viewport` in
+    // v1.4.37 W-CI; the regex form is the durable fix.
+    await page.route(/\/api\/analytics(\?|$)/, (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            summaries: {
+              WEIGHT: {
+                latest: 78.5,
+                avg7: 78.2,
+                avg30: 77.9,
+                slope30: { slope: -0.05, direction: "down" },
+                count: 30,
+              },
+              BLOOD_PRESSURE_SYS: {
+                latest: 124,
+                avg7: 122,
+                avg30: 121,
+                slope30: { slope: 0.1, direction: "flat" },
+                count: 25,
+              },
+              BLOOD_PRESSURE_DIA: {
+                latest: 80,
+                avg7: 79,
+                avg30: 78,
+                slope30: { slope: 0.05, direction: "flat" },
+                count: 25,
+              },
+              PULSE: {
+                latest: 68,
+                avg7: 70,
+                avg30: 71,
+                slope30: { slope: -0.2, direction: "down" },
+                count: 25,
+              },
+            },
+            bpInTargetPct: 78,
+            glucoseByContext: {},
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.route("**/api/mood/analytics", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { entries: [], summary: { count: 0 } },
+          error: null,
+        }),
+      }),
+    );
+
+    // The chart's per-type fetch reads `json.data.measurements` and
+    // expects a `meta.total`. Return a small dataset so the chart has
+    // points to plot — otherwise Recharts mounts a placeholder instead
+    // of the recharts-wrapper SVG and the assertion below times out.
+    await page.route("**/api/measurements*", (route) => {
+      const url = new URL(route.request().url());
+      const type = url.searchParams.get("type") ?? "WEIGHT";
+      const baseValue =
+        type === "BLOOD_PRESSURE_SYS"
+          ? 124
+          : type === "BLOOD_PRESSURE_DIA"
+            ? 80
+            : type === "PULSE"
+              ? 70
+              : 78.5;
+      const measurements = Array.from({ length: 10 }, (_, i) => ({
+        id: `m_${type}_${i}`,
+        type,
+        value: baseValue + (i % 3) - 1,
+        measuredAt: new Date(Date.now() - i * 86_400_000).toISOString(),
+        notes: null,
+      }));
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { measurements, meta: { total: measurements.length } },
+          error: null,
+        }),
+      });
+    });
+
+    // v1.4.28 retired the InsightAdvisorCard surface. Coach drawer
+    // remains the conversational entry point on /insights, but the
+    // bottom-of-page card with its own summary container is gone. The
+    // dashboard render assertion below no longer touches /insights, so
+    // we don't need to mock /api/insights/comprehensive or
+    // /api/insights/generate any more (the iOS-consumed POST endpoint
+    // is preserved server-side; only the web mount retired).
+  });
+
+  test("dashboard tile strip + chart + insight card render", async ({
+    page,
+  }) => {
+    const consoleErrors: string[] = [];
+    page.on("pageerror", (err) => {
+      consoleErrors.push(err.message);
+    });
+    page.on("console", (msg) => {
+      if (msg.type() === "error") consoleErrors.push(msg.text());
+    });
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+
+    // Tile strip — `data-slot="dashboard-tile-strip"` is the stable hook
+    // the dashboard exposes. The component sets `data-tile-count` to the
+    // active tile count; assert it's >0 so we know at least one tile
+    // cleared the visibility + data-floor gate.
+    const strip = page.locator('[data-slot="dashboard-tile-strip"]');
+    await expect(strip).toBeVisible({ timeout: 10_000 });
+    const tileCount = Number(await strip.getAttribute("data-tile-count"));
+    expect(tileCount).toBeGreaterThan(0);
+
+    // At least one chart must render. Recharts mounts a `<svg>` with
+    // `class="recharts-surface"` (or a `<div class="recharts-wrapper">`
+    // around it). Use the recharts class so we don't accidentally match
+    // an aria-hidden lucide-react icon.
+    await expect(
+      page.locator(".recharts-wrapper, .recharts-surface").first(),
+    ).toBeVisible({ timeout: 10_000 });
+
+    // v1.4.28 — the bottom-of-page InsightAdvisorCard retired; the
+    // dashboard spec no longer asserts on its summary slot. The hero
+    // strip and the Coach drawer carry the differentiator on /insights
+    // and are covered by their own specs.
+
+    // Filter out a small set of known-noise messages — we care about
+    // real React/JS uncaught errors only. 404s from optional assets
+    // (manifest icons, prefetched chunks for unrendered routes) are
+    // explicitly tolerated; they don't affect the dashboard render.
+    const significant = consoleErrors.filter(
+      (msg) =>
+        !/ResizeObserver loop|Download the React DevTools|Warning: |\[Fast Refresh\]|Failed to load resource|net::ERR_/i.test(
+          msg,
+        ),
+    );
+    expect(significant, significant.join("\n")).toEqual([]);
+  });
+});

e2e/doctor-report.spec.ts

@@ -0,0 +1,98 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * Doctor-report PDF flow. The real flow:
+ *   1. User clicks "Configure & generate" on `/settings/export`
+ *      (relocated from `/settings/advanced` in v1.4.16 phase B7)
+ *   2. The dialog opens; user picks dates and submits.
+ *   3. Frontend POSTs `/api/doctor-report` to fetch aggregated data
+ *   4. Frontend dynamic-imports `src/lib/doctor-report-pdf.ts` and
+ *      generates the PDF client-side via jsPDF; calls `doc.save(...)`
+ *      which triggers a download.
+ *
+ * This spec mocks step 3 (so we don't need 90 days of seeded data) and
+ * captures step 4's download via Playwright's download API. We then
+ * confirm the file is non-empty and starts with `%PDF` magic bytes.
+ */
+test.describe("doctor report PDF generation", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("button click triggers a non-empty PDF download", async ({ page }) => {
+    // Mock the data endpoint with a minimal-but-shape-correct payload.
+    // The shape below mirrors the `ReportData` interface in
+    // `src/lib/doctor-report-pdf.ts` — empty stats / medications / mood
+    // is enough to exercise the table-rendering path without 90 days
+    // of seeded readings.
+    await page.route("**/api/doctor-report", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            period: {
+              days: 90,
+              since: new Date(Date.now() - 90 * 86_400_000).toISOString(),
+            },
+            patient: {
+              username: "e2e-tester",
+              dateOfBirth: "1985-06-15T00:00:00.000Z",
+              gender: "MALE",
+              heightCm: 180,
+            },
+            stats: {},
+            bmi: null,
+            compliance: {},
+            medications: [],
+            mood: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    // Capture page errors so a failed dynamic-import surfaces in the
+    // test output instead of timing out silently.
+    const pageErrors: string[] = [];
+    page.on("pageerror", (err) => pageErrors.push(`pageerror: ${err.message}`));
+    page.on("console", (msg) => {
+      if (msg.type() === "error")
+        pageErrors.push(`console.error: ${msg.text()}`);
+    });
+
+    await page.goto("/settings/export", { waitUntil: "domcontentloaded" });
+
+    // v1.4.37 renamed the trigger testid from `export-action-doctor-report`
+    // to `export-hero-doctor-report-action` when the card was lifted to a
+    // hero block on the export page.
+    const reportBtn = page.getByTestId("export-hero-doctor-report-action");
+    await expect(reportBtn).toBeVisible({ timeout: 10_000 });
+
+    // Click opens the dialog; the dialog's submit button triggers the PDF
+    // generation. Trigger the download and capture the resulting Download
+    // object once the user confirms.
+    const downloadPromise = page.waitForEvent("download", { timeout: 30_000 });
+    await reportBtn.click();
+    // Submit the dialog with the default dates (last 90 days).
+    const submitBtn = page.getByRole("button", {
+      name: /generate pdf|pdf generieren/i,
+    });
+    await expect(submitBtn).toBeVisible({ timeout: 5_000 });
+    await submitBtn.click();
+    const download = await downloadPromise.catch((err) => {
+      throw new Error(
+        `Download did not fire. Page errors:\n${pageErrors.join("\n")}\n\nOriginal: ${err}`,
+      );
+    });
+
+    const path = await download.path();
+    expect(path).toBeTruthy();
+
+    // Read first 4 bytes — a valid PDF starts with `%PDF`.
+    const fs = await import("node:fs/promises");
+    const buf = await fs.readFile(path!);
+    expect(buf.byteLength).toBeGreaterThan(1024);
+    expect(buf.subarray(0, 4).toString("ascii")).toBe("%PDF");
+  });
+});

e2e/insights-generate.spec.ts

@@ -0,0 +1,110 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * Insights generation flow — `/settings/ai` exposes a "Regenerate
+ * insights" button that POSTs `/api/insights/generate` and re-renders
+ * the AI-generated text in the surrounding cards.
+ *
+ * The real endpoint hits an AI provider (OpenAI / Codex) which we can't
+ * call from CI. We mock it with the schema documented in
+ * `src/app/api/insights/generate/route.ts`:
+ *
+ *   { data: { insights: { changed, stable, drivers, nextSteps,
+ *     confidence, limitations }, cached: false }, error: null }
+ *
+ * We then confirm the success message lands AND a query invalidation
+ * fires on the insight-fetching endpoints (we re-mock those to assert
+ * they're touched after the regenerate call).
+ */
+test.describe("insights generation flow (mocked)", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("regenerate button updates insight cards", async ({ page }) => {
+    // Settings endpoint — return "connected" so the regenerate button
+    // is rendered (the section gates it on hasProvider).
+    await page.route("**/api/insights/settings", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            codexStatus: "connected",
+            codexConnectedAt: new Date().toISOString(),
+            hasAdminKey: false,
+            codexOauthConfigured: true,
+            privacyMode: "aggregated",
+            lastInsightAt: new Date().toISOString(),
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.route("**/api/user/ai-provider", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            provider: null,
+            model: null,
+            baseUrl: null,
+            hasAnthropicKey: false,
+            anthropicKeyPreview: null,
+            hasLocalKey: false,
+            hasOpenaiKey: false,
+            openaiKeyPreview: null,
+          },
+          error: null,
+        }),
+      }),
+    );
+
+    let generateCalls = 0;
+    await page.route("**/api/insights/generate", (route) => {
+      generateCalls += 1;
+      return route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: {
+            insights: {
+              changed:
+                "Blood-pressure averages dropped by 4/2 mmHg over the last 30 days.",
+              stable: "Pulse and weight unchanged within natural variance.",
+              drivers:
+                "Likely driven by improved medication compliance (88% vs 72% prior).",
+              nextSteps:
+                "Continue current routine; revisit BMI target in 30 days.",
+              confidence: "mittel",
+              limitations:
+                "Sample size for systolic readings remains below 60.",
+            },
+            cached: false,
+          },
+          error: null,
+        }),
+      });
+    });
+
+    await page.goto("/settings/ai", { waitUntil: "domcontentloaded" });
+
+    const regenerateBtn = page.getByRole("button", {
+      name: /regenerate (insights|reports)|insights aktualisieren|neu erstellen|berichte/i,
+    });
+    await expect(regenerateBtn).toBeVisible({ timeout: 10_000 });
+    await regenerateBtn.click();
+
+    // The settings page surfaces an inline alert after the mutation
+    // completes. The exact copy comes from i18n, so match permissively.
+    await expect(
+      page.getByText(
+        /reports? regenerated|insight.*regenerated|berichte.*aktualisiert|generated successfully|erfolgreich/i,
+      ),
+    ).toBeVisible({ timeout: 10_000 });
+
+    expect(generateCalls).toBeGreaterThanOrEqual(1);
+  });
+});

e2e/insights-scroll-restoration.spec.ts

@@ -0,0 +1,91 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.4.28 R3a FB-D3 — `/insights` scroll restoration + tab-strip
+ * gesture handling.
+ *
+ * Two regressions the maintainer hit walking through v1.4.27:
+ *
+ *   (a) Returning from a sub-page to `/insights` landed the viewport
+ *       partway down the page because the mother page had no scroll
+ *       reset on mount and the sub-page's `SubPageShell` had already
+ *       reset it for the sub-page only.
+ *
+ *   (b) Vertical swipes that started on the sticky `<InsightsTabStrip>`
+ *       were eaten by the strip's `overflow-x-auto` scroll container,
+ *       so the page "felt stuck" until the gesture lifted.
+ *
+ * Both fixes land in the same commit. This spec is the regression
+ * lock — failure here means a future refactor re-introduced one of
+ * the two roots.
+ */
+test.describe("v1.4.28 — insights scroll restoration", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test.fixme(
+    "returning to /insights from a sub-page lands at the top",
+    async ({ page }) => {
+    await page.goto("/insights", { waitUntil: "domcontentloaded" });
+    // Force the mother page tall enough that scrolling has somewhere
+    // to go even on a sparse seed; the rendered Insights overview
+    // already runs ~1500 px tall on the demo seed.
+    await page.evaluate(() => window.scrollTo({ top: 600, behavior: "auto" }));
+
+    // Click the first available sub-page pill.
+    const subPagePill = page
+      .locator("[data-slot='insights-tab-strip-pill']")
+      .nth(1);
+    await expect(subPagePill).toBeVisible();
+    await subPagePill.click();
+    await page.waitForURL(/\/insights\//);
+
+    // Back to the mother page via the overview pill (pill index 0).
+    await page
+      .locator("[data-slot='insights-tab-strip-pill']")
+      .first()
+      .click();
+    await page.waitForURL(/\/insights\/?$/);
+
+    // The mother page's mount-effect deferred a `scrollTo(0)` to the
+    // next animation frame. Wait a tick for it to land.
+    await page.waitForTimeout(50);
+    const y = await page.evaluate(() => window.scrollY);
+    expect(y).toBeLessThan(50);
+    },
+  );
+
+  test("the sticky tab strip declares touch-action pan-y so vertical swipes pass through", async ({
+    page,
+  }) => {
+    await page.goto("/insights", { waitUntil: "domcontentloaded" });
+    const nav = page.locator("[data-slot='insights-tab-strip']");
+    await expect(nav).toBeVisible();
+    const touchAction = await nav.evaluate(
+      (el) => (el as HTMLElement).style.touchAction || getComputedStyle(el).touchAction,
+    );
+    expect(touchAction).toContain("pan-y");
+  });
+
+  test("the tab strip's horizontal scroll lives on an inner row, not on the outer nav", async ({
+    page,
+  }) => {
+    await page.goto("/insights", { waitUntil: "domcontentloaded" });
+    const nav = page.locator("[data-slot='insights-tab-strip']");
+    const navOverflowX = await nav.evaluate(
+      (el) => getComputedStyle(el).overflowX,
+    );
+    // The outer `<nav>` no longer scrolls horizontally — the inner row
+    // owns that responsibility now so vertical swipes outside the row
+    // reach the document.
+    expect(navOverflowX).not.toBe("auto");
+    expect(navOverflowX).not.toBe("scroll");
+
+    const innerScroller = nav.locator("> div > div").first();
+    const innerOverflowX = await innerScroller.evaluate(
+      (el) => getComputedStyle(el).overflowX,
+    );
+    expect(innerOverflowX).toMatch(/auto|scroll/);
+  });
+});

e2e/locale-switch.spec.ts

@@ -0,0 +1,54 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Locale-key drift smoke check — switch the cookie between EN and DE
+ * and assert the login page (the only public surface that's translated)
+ * never shows raw i18n keys like `auth.welcomeBack`.
+ *
+ * Drift catches: a typo'd t("foo.bar") with no key in either locale
+ * file would make the raw key surface in the DOM. messages/de.json and
+ * messages/en.json key parity is enforced by unit tests; this is the
+ * runtime cousin.
+ */
+test.describe("locale switch", () => {
+  for (const locale of ["en", "de"] as const) {
+    test(`renders /auth/login in ${locale} without raw i18n keys`, async ({
+      page,
+      context,
+    }) => {
+      // Cookies must be addressable to a real origin — `page.url()` on
+      // a fresh context returns `about:blank`, which Playwright rejects.
+      // Anchor at the configured base URL explicitly.
+      const baseURL =
+        test.info().project.use.baseURL ?? "http://localhost:3000";
+      await context.addCookies([
+        {
+          name: "healthlog-locale",
+          value: locale,
+          url: baseURL,
+        },
+      ]);
+      await page.goto("/auth/login");
+
+      const bodyText = await page.locator("body").innerText();
+
+      // i18n keys look like `section.subkey` — letters, numbers,
+      // underscores, dots — and are never wrapped in normal sentences,
+      // so a regex match anywhere in body text is a sign the lookup
+      // fell through.
+      const rawKeyPattern = /\b[a-z]+(?:[A-Z][a-z]+)?\.[a-z][A-Za-z0-9_.]+\b/;
+      const match = bodyText.match(rawKeyPattern);
+
+      // Whitelist: filenames or version strings can look like keys,
+      // skip those by requiring at least one camelCase segment.
+      if (match) {
+        const candidate = match[0];
+        const looksLikeKey = /\.[a-z][A-Z]/.test(candidate);
+        expect(
+          looksLikeKey,
+          `Possible raw i18n key in ${locale}: ${candidate}`,
+        ).toBe(false);
+      }
+    });
+  }
+});

e2e/login.spec.ts

@@ -0,0 +1,73 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Smoke checks on the login surface — must render, must wire the
+ * password-manager autofill hints (autoComplete="username" /
+ * "current-password"), must let the user submit.
+ *
+ * These do NOT log in (no DB seed required); the password-flow
+ * roundtrip is exercised by the integration test in
+ * tests/integration/auth-flow.test.ts.
+ */
+async function openPasswordForm(page: import("@playwright/test").Page) {
+  await page.goto("/auth/login");
+  // The login page defaults to passkey mode; the password form is
+  // mounted only after clicking the "Login with password" / "Mit
+  // Passwort anmelden" outline button.
+  await page
+    .getByRole("button", {
+      name: /sign in with password|login with password|mit passwort/i,
+    })
+    .click();
+}
+
+test.describe("login page", () => {
+  test("renders username + password inputs with the right autoComplete", async ({
+    page,
+  }) => {
+    await openPasswordForm(page);
+
+    const username = page
+      .getByLabel(/username|benutzername|email|e-mail/i)
+      .first();
+    await expect(username).toBeVisible();
+    await expect(username).toHaveAttribute("autoComplete", /username|email/);
+
+    const password = page.locator('input[type="password"]').first();
+    await expect(password).toBeVisible();
+    await expect(password).toHaveAttribute("autoComplete", "current-password");
+  });
+
+  test("rejects an obviously-wrong credential pair", async ({ page }) => {
+    await openPasswordForm(page);
+
+    await page
+      .getByLabel(/username|benutzername|email|e-mail/i)
+      .first()
+      .fill("nobody-here");
+    await page.locator('input[type="password"]').first().fill("not-the-pw");
+
+    // Intercept the API call so the test does not depend on a real
+    // backend rejecting the credentials. The login form's error
+    // surfacing is what we actually want to prove here.
+    await page.route("**/api/auth/login", (route) =>
+      route.fulfill({
+        status: 401,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "Invalid credentials" }),
+      }),
+    );
+
+    // The form has multiple buttons matching /sign in/ — both the
+    // passkey CTA and the password submit. Filter to the submit button
+    // so the click lands on the right one.
+    await page
+      .locator('button[type="submit"]')
+      .filter({ hasText: /login|anmelden|sign in/i })
+      .click();
+
+    await expect(
+      page.getByText(/invalid credentials|ungültig|falsch/i),
+    ).toBeVisible({ timeout: 5_000 });
+  });
+});

e2e/measurement-flow.spec.ts

@@ -0,0 +1,170 @@
+import { expect, test } from "@playwright/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * Add-measurement flow — exercises the dashboard's quick-entry dropdown,
+ * the dialog-mounted MeasurementForm, the POST to /api/measurements, and
+ * the resulting query invalidation that surfaces the row on
+ * `/measurements`.
+ *
+ * Weight is the simplest type (single numeric input + datetime), so it
+ * keeps the spec focused on the round-trip rather than the BP three-field
+ * batched submit.
+ */
+test.describe("add measurement flow", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creating a weight reading surfaces it in the list", async ({
+    page,
+  }) => {
+    // Capture the POST payload so we can assert against it independently
+    // of any list-fetch response Playwright might cache. Match both
+    // `/api/measurements` (POST creates a reading) and the list query
+    // `/api/measurements?type=...&limit=...&offset=...` (GET).
+    let postedBody: unknown = null;
+    await page.route("**/api/measurements*", async (route) => {
+      const req = route.request();
+      if (req.method() === "POST") {
+        postedBody = JSON.parse(req.postData() ?? "null");
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            data: { id: "m_e2e_1", success: true },
+            error: null,
+          }),
+        });
+        return;
+      }
+      // GET — return the just-posted reading so the list view shows it.
+      // The list expects `data.measurements: Measurement[]` plus
+      // `data.meta.total`; chart fetches use the same envelope.
+      const body = postedBody as {
+        type?: string;
+        value?: number;
+        measuredAt?: string;
+      } | null;
+      // The list-page `Measurement` shape requires `unit` and `source`
+      // — without them the row crashes the render and the e2e poll
+      // never sees "78.4". Mock with the same fields a real reading
+      // carries.
+      const measurements = body
+        ? [
+            {
+              id: "m_e2e_1",
+              type: body.type,
+              value: body.value,
+              unit: body.type === "WEIGHT" ? "kg" : "",
+              source: "MANUAL",
+              measuredAt: body.measuredAt,
+              notes: null,
+            },
+          ]
+        : [];
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { measurements, meta: { total: measurements.length } },
+          error: null,
+        }),
+      });
+    });
+
+    // Dashboard's analytics fetch — empty summaries are fine; we only
+    // need the page to render so we can click "Add".
+    //
+    // v1.4.39.3 — match `/api/analytics` AND any sliced variant
+    // (`?slice=summaries`). The v1.4.39.2 dashboard split fires both
+    // requests in parallel; the previous string glob missed the slim
+    // variant which then fell through to the real route and slowed
+    // the page paint enough that the post-mutation list query never
+    // surfaced inside the 10 s window.
+    await page.route(/\/api\/analytics(\?|$)/, (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { summaries: {}, bpInTargetPct: null, glucoseByContext: {} },
+          error: null,
+        }),
+      }),
+    );
+    await page.route("**/api/mood/analytics", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { entries: [], summary: { count: 0 } },
+          error: null,
+        }),
+      }),
+    );
+
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    // Open the "Add" dropdown — the dashboard's quick-entry trigger sits
+    // at the top-right of `<main>`. Scope the locator there so we don't
+    // accidentally match an "Add" button on the sidebar.
+    const main = page.locator("main");
+    await main
+      .getByRole("button", { name: /^add$|hinzufügen|hinzufuegen/i })
+      .first()
+      .click();
+
+    // v1.5 phase-5: the menu items now have distinct labels — the
+    // measurement entry says "Measurement" / "Messung" instead of "Add",
+    // so we can target it directly.
+    await page.getByRole("menuitem", { name: /measurement|messung/i }).click();
+
+    // Form should be visible inside the dialog. Switch type to WEIGHT
+    // (combo-box defaults to BLOOD_PRESSURE).
+    const dialog = page.getByRole("dialog");
+    await expect(dialog).toBeVisible();
+
+    // The Select trigger renders the current label — click to open and
+    // pick the weight option.
+    await dialog.getByRole("combobox").first().click();
+    await page
+      .getByRole("option", { name: /weight|gewicht/i })
+      .first()
+      .click();
+
+    // Weight is single-value mode — fill the value field with 78.4 kg.
+    const valueInput = dialog.locator("#value");
+    await valueInput.fill("78.4");
+
+    // Save
+    await dialog.getByRole("button", { name: /save|speichern/i }).click();
+
+    // Dialog closes when the mutation succeeds
+    await expect(dialog).toBeHidden({ timeout: 5_000 });
+
+    // Assert the POST went through with the expected shape
+    expect(postedBody).toMatchObject({
+      type: "WEIGHT",
+      value: 78.4,
+    });
+
+    // Navigate to the list and confirm the entry surfaces. The list
+    // page renders entries from /api/measurements which we've mocked
+    // to echo the just-posted row.
+    await page.goto("/measurements", { waitUntil: "domcontentloaded" });
+
+    // The list renders a desktop table AND a mobile card grid (one is
+    // hidden via `md:hidden`/`hidden md:block`). At least one match
+    // means our row landed in the DOM regardless of viewport.
+    await expect
+      .poll(
+        async () =>
+          await page
+            .locator("main")
+            .getByText(/78[.,]4/)
+            .count(),
+        { timeout: 10_000 },
+      )
+      .toBeGreaterThanOrEqual(1);
+  });
+});

e2e/medications-wizard-biweekly.spec.ts

@@ -0,0 +1,96 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  mockMedicationsApi,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — bi-weekly cadence (every N
+ * weeks).
+ *
+ * Walks the 8-step recurring path with "Alle X Wochen" picked on
+ * Step 5, then the interval input filled with 2 and Monday toggled
+ * on the weekday chips of Step 6. Emits
+ * `FREQ=WEEKLY;INTERVAL=2;BYDAY=MO`.
+ */
+test.describe("medication wizard — bi-weekly", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates an every-2-weeks Monday medication end-to-end", async ({
+    page,
+  }) => {
+    await stubDashboardAnalytics(page);
+    const capture = mockMedicationsApi(page, {
+      id: STUB_MEDICATION_ID,
+      name: "Methotrexat",
+      dose: "10 mg",
+      rrule: "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO",
+      rollingIntervalDays: null,
+      oneShot: false,
+    });
+
+    await openCreateWizard(page);
+
+    await fillStep1Name(page, { name: "Methotrexat" });
+    await clickNext(page);
+
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "other");
+    await clickNext(page);
+
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "10" });
+    await clickNext(page);
+
+    await expectStep(page, 4);
+    await clickNext(page);
+
+    await expectStep(page, 5, 8);
+    await pickCadenceRow(page, "everyNWeeks");
+    await clickNext(page);
+
+    await expectStep(page, 6, 8);
+    await page.locator("#wizard-interval-weeks").fill("2");
+    const moChip = page.locator(
+      '[data-slot="wizard-weekday-chip"][data-token="MO"]',
+    );
+    if ((await moChip.getAttribute("data-active")) === "false") {
+      await moChip.click();
+    }
+    await clickNext(page);
+
+    await expectStep(page, 7, 8);
+    await clickNext(page);
+
+    await expectStep(page, 8, 8);
+    const summary = page.locator('[data-slot="wizard-summary"]');
+    await expect(summary).toContainText(/zwei Wochen/i);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Methotrexat",
+      oneShot: false,
+      schedules: [{ rrule: "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO" }],
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Methotrexat",
+      withNextDueChip: true,
+    });
+  });
+});

e2e/medications-wizard-compose.spec.ts

@@ -0,0 +1,179 @@
+import { expect, test, type Route } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — compose-mode.
+ *
+ * Walks the create flow through to Step 8, then taps
+ * "Weiteren Zeitplan hinzufügen" to append a second weekly Wednesday
+ * schedule on the same medication. The list view surfaces both
+ * summary cards before save, and the POST body carries both
+ * schedules so the route can persist them in parallel.
+ *
+ * Use case the maintainer cares about: short-acting + long-acting
+ * insulin on a single medication. Today the wizard collapses to one
+ * schedule on save; compose-mode closes that data-loss gap.
+ */
+test.describe("medication wizard — compose-mode", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates a 2-schedule medication end-to-end", async ({ page }) => {
+    await stubDashboardAnalytics(page);
+
+    const listEntry = {
+      id: STUB_MEDICATION_ID,
+      name: "Insulin",
+      dose: "10 IE",
+      category: "DIABETES",
+      active: true,
+      notificationsEnabled: true,
+      pausedAt: null,
+      lastTakenAt: null,
+      startsOn: null,
+      endsOn: null,
+      oneShot: false,
+      schedules: [
+        {
+          id: "sch_e2e_1",
+          windowStart: "08:00",
+          windowEnd: "09:00",
+          label: null,
+          dose: null,
+          daysOfWeek: null,
+          timesOfDay: ["08:00"],
+          rrule: "FREQ=DAILY",
+          rollingIntervalDays: null,
+          reminderGraceMinutes: null,
+        },
+        {
+          id: "sch_e2e_2",
+          windowStart: "20:00",
+          windowEnd: "21:00",
+          label: null,
+          dose: null,
+          daysOfWeek: null,
+          timesOfDay: ["20:00"],
+          rrule: "FREQ=WEEKLY;BYDAY=WE",
+          rollingIntervalDays: null,
+          reminderGraceMinutes: null,
+        },
+      ],
+    };
+
+    const capture: { postBody: unknown } = { postBody: null };
+    void page.route("**/api/medications**", async (route: Route) => {
+      const req = route.request();
+      const url = new URL(req.url());
+      if (url.pathname !== "/api/medications") {
+        await route.fallback();
+        return;
+      }
+      if (req.method() === "POST") {
+        capture.postBody = JSON.parse(req.postData() ?? "null");
+        await route.fulfill({
+          status: 201,
+          contentType: "application/json",
+          body: JSON.stringify({ data: { ...listEntry }, error: null }),
+        });
+        return;
+      }
+      if (req.method() === "GET") {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ data: [listEntry], error: null }),
+        });
+        return;
+      }
+      await route.fallback();
+    });
+
+    await openCreateWizard(page);
+
+    // Steps 1-4 — medication-global.
+    await fillStep1Name(page, { name: "Insulin" });
+    await clickNext(page);
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "diabetes");
+    await clickNext(page);
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "10" });
+    await clickNext(page);
+    await expectStep(page, 4);
+    await clickNext(page);
+
+    // Steps 5-7 — first schedule, daily cadence.
+    await expectStep(page, 5, 8);
+    await pickCadenceRow(page, "daily");
+    await expectStep(page, 5, 7);
+    await clickNext(page);
+    await expectStep(page, 6, 7);
+    await clickNext(page);
+
+    // Step 8 — list view with the first schedule rendered. Tap
+    // "Weiteren Zeitplan hinzufügen" to append a second draft.
+    await expectStep(page, 7, 7);
+    let cards = page.locator('[data-slot="wizard-schedule-card"]');
+    await expect(cards).toHaveCount(1);
+    await page.locator('[data-slot="wizard-schedule-add"]').click();
+
+    // Second schedule — weekdays on Wednesday.
+    await expectStep(page, 5);
+    await pickCadenceRow(page, "weekdays");
+    await clickNext(page);
+    await expectStep(page, 6);
+    const weChip = page.locator(
+      '[data-slot="wizard-weekday-chip"][data-token="WE"]',
+    );
+    if ((await weChip.getAttribute("data-active")) === "false") {
+      await weChip.click();
+    }
+    // Default MO chip — toggle off so the rrule is WE-only.
+    const moChip = page.locator(
+      '[data-slot="wizard-weekday-chip"][data-token="MO"]',
+    );
+    if ((await moChip.getAttribute("data-active")) === "true") {
+      await moChip.click();
+    }
+    await clickNext(page);
+    await expectStep(page, 7);
+    await clickNext(page);
+
+    // Back on Step 8 — both summary cards should land before save.
+    await expectStep(page, 8);
+    cards = page.locator('[data-slot="wizard-schedule-card"]');
+    await expect(cards).toHaveCount(2);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Insulin",
+      oneShot: false,
+      schedules: [
+        { rrule: "FREQ=DAILY" },
+        { rrule: "FREQ=WEEKLY;BYDAY=WE" },
+      ],
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Insulin",
+      withNextDueChip: true,
+    });
+  });
+});

e2e/medications-wizard-daily.spec.ts

@@ -0,0 +1,101 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  mockMedicationsApi,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — daily cadence.
+ *
+ * Walks the 7-step daily path through the modal dialog. The dialog
+ * mounts when `/medications/new` redirects to `/medications?new=1`.
+ * The DE label surface (Marc's primary locale) is the assertion
+ * surface — "Schritt N von 7" tracks the visible counter.
+ */
+test.describe("medication wizard — daily", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates a daily medication end-to-end", async ({ page }) => {
+    await stubDashboardAnalytics(page);
+    const capture = mockMedicationsApi(page, {
+      id: STUB_MEDICATION_ID,
+      name: "Vitamin D",
+      dose: "1000 I.E.",
+      rrule: "FREQ=DAILY",
+      rollingIntervalDays: null,
+      oneShot: false,
+    });
+
+    await openCreateWizard(page);
+
+    // Step 1 — name.
+    await fillStep1Name(page, { name: "Vitamin D" });
+    await clickNext(page);
+
+    // Step 2 — treatment class.
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "vitamin");
+    await clickNext(page);
+
+    // Step 3 — dose.
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "1000" });
+    await page.locator("#wizard-dose-unit").click();
+    await page.getByRole("option", { name: /I\.E\./ }).click();
+    await clickNext(page);
+
+    // Step 4 — course window (today by default).
+    await expectStep(page, 4);
+    await expect(
+      page.locator('[data-slot="course-window-starts"]'),
+    ).toHaveValue(/^\d{4}-\d{2}-\d{2}$/);
+    await clickNext(page);
+
+    // Step 5 — cadence: "Täglich".
+    await expectStep(page, 5, 8);
+    await pickCadenceRow(page, "daily");
+    // After picking daily, the path compresses to 7 steps; step 5
+    // sits at slot 5 of 7.
+    await expectStep(page, 5, 7);
+    await clickNext(page);
+
+    // Step 7 — times of day (08:00 default chip).
+    await expectStep(page, 6, 7);
+    await expect(
+      page.locator('[data-slot="times-of-day-chip"][data-time="08:00"]'),
+    ).toBeVisible();
+    await clickNext(page);
+
+    // Step 8 — summary + create.
+    await expectStep(page, 7, 7);
+    const summary = page.locator('[data-slot="wizard-summary"]');
+    await expect(summary).toContainText(/Jeden Tag/i);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Vitamin D",
+      oneShot: false,
+      schedules: [{ rrule: "FREQ=DAILY" }],
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Vitamin D",
+      withNextDueChip: true,
+    });
+  });
+});

e2e/medications-wizard-helpers.ts

@@ -0,0 +1,270 @@
+import { expect, type Page, type Route } from "@playwright/test";
+
+/**
+ * v1.5.4 — shared helpers for the modal medication-wizard specs.
+ *
+ * The six specs (daily / weekdays / biweekly / monthly / rolling /
+ * oneshot) walk the same dialog with different cadence-specific
+ * inputs. The shared pieces — POST + GET stubs, list-page entry
+ * check, dialog open + step-indicator assertions — live here so
+ * the per-cadence specs only carry the cadence-specific selectors.
+ *
+ * The path counter follows the user's path:
+ *   one-shot   = 5 steps (1, 2, 3, 4, 8)
+ *   daily      = 7 steps (1, 2, 3, 4, 5, 7, 8)
+ *   recurring  = 8 steps (1, 2, 3, 4, 5, 6, 7, 8)
+ *
+ * `expectStep(page, displayIndex, totalSteps)` pins the visible
+ * "Schritt X von Y" string the dialog header renders.
+ */
+
+export const STUB_MEDICATION_ID = "med_e2e_wizard";
+
+interface StubbedMedication {
+  id: string;
+  name: string;
+  dose: string;
+  rrule: string | null;
+  rollingIntervalDays: number | null;
+  oneShot: boolean;
+}
+
+export function mockMedicationsApi(page: Page, stubbed: StubbedMedication) {
+  const capture: { postBody: unknown } = { postBody: null };
+
+  const listEntry = {
+    id: stubbed.id,
+    name: stubbed.name,
+    dose: stubbed.dose,
+    category: "OTHER",
+    active: true,
+    notificationsEnabled: true,
+    pausedAt: null,
+    lastTakenAt: null,
+    startsOn: null,
+    endsOn: null,
+    oneShot: stubbed.oneShot,
+    schedules: [
+      {
+        id: "sch_e2e_1",
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        label: null,
+        dose: null,
+        daysOfWeek: null,
+        timesOfDay: ["08:00"],
+        rrule: stubbed.rrule,
+        rollingIntervalDays: stubbed.rollingIntervalDays,
+        reminderGraceMinutes: null,
+      },
+    ],
+  };
+
+  void page.route("**/api/medications**", async (route: Route) => {
+    const req = route.request();
+    const url = new URL(req.url());
+    if (url.pathname !== "/api/medications") {
+      await route.fallback();
+      return;
+    }
+    if (req.method() === "POST") {
+      capture.postBody = JSON.parse(req.postData() ?? "null");
+      await route.fulfill({
+        status: 201,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: { ...listEntry },
+          error: null,
+        }),
+      });
+      return;
+    }
+    if (req.method() === "GET") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          data: [listEntry],
+          error: null,
+        }),
+      });
+      return;
+    }
+    await route.fallback();
+  });
+
+  return capture;
+}
+
+export async function stubDashboardAnalytics(page: Page): Promise<void> {
+  await page.route(/\/api\/analytics(\?|$)/, (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        data: { summaries: {}, bpInTargetPct: null, glucoseByContext: {} },
+        error: null,
+      }),
+    }),
+  );
+  await page.route("**/api/mood/analytics", (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        data: { entries: [], summary: { count: 0 } },
+        error: null,
+      }),
+    }),
+  );
+}
+
+/**
+ * Open the wizard dialog by hitting `/medications/new` (which
+ * redirects to `/medications?new=1` and opens the create dialog).
+ */
+export async function openCreateWizard(page: Page): Promise<void> {
+  // Pin the German locale for the wizard flow. The app default locale is
+  // English; these specs assert the "Schritt N von M" counter and other
+  // German label surfaces, which only render when the `healthlog-locale`
+  // cookie resolves to "de". Both the server layout and the client i18n
+  // provider read this exact cookie name, so setting it before the first
+  // navigation makes the dialog render German on first paint. Scoped here
+  // rather than in the shared auth state so English-asserting specs keep
+  // the default locale.
+  await page.context().addCookies([
+    {
+      name: "healthlog-locale",
+      value: "de",
+      url: page.url().startsWith("http")
+        ? new URL(page.url()).origin
+        : "http://localhost:3000",
+    },
+  ]);
+  await page.goto("/medications/new", { waitUntil: "domcontentloaded" });
+  await expect(
+    page.locator('[data-slot="medication-wizard-dialog"]'),
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+/**
+ * Fill the Step 1 name input. The dialog's first step asks only for
+ * the medication name — the dose moved to Step 3.
+ */
+export async function fillStep1Name(
+  page: Page,
+  { name }: { name: string },
+): Promise<void> {
+  await expectStep(page, 1);
+  await page.locator("#wizard-name").fill(name);
+}
+
+/** Pick a Step 2 treatment-class row by its row identifier. */
+export async function pickTreatmentRow(
+  page: Page,
+  row:
+    | "bloodPressure"
+    | "diabetes"
+    | "hormone"
+    | "glp1"
+    | "painRelief"
+    | "allergy"
+    | "vitamin"
+    | "supplement"
+    | "antibiotic"
+    | "other",
+): Promise<void> {
+  await page
+    .locator(`[data-slot="wizard-class-row"][data-row="${row}"]`)
+    .click();
+}
+
+/** Fill the Step 3 dose amount input. */
+export async function fillStep3Dose(
+  page: Page,
+  { amount }: { amount: string },
+): Promise<void> {
+  await page.locator("#wizard-dose-amount").fill(amount);
+}
+
+/** Pick a Step 5 cadence row by its row identifier. */
+export async function pickCadenceRow(
+  page: Page,
+  row: "daily" | "weekdays" | "everyNWeeks" | "monthly" | "rolling" | "oneShot",
+): Promise<void> {
+  await page
+    .locator(`[data-slot="wizard-cadence-row"][data-row="${row}"]`)
+    .click();
+}
+
+/** Click Next. Pinned by data-slot. */
+export async function clickNext(page: Page): Promise<void> {
+  await page.locator('[data-slot="wizard-next"]').click();
+}
+
+/** Click Save (last step CTA on create + edit). */
+export async function clickSave(page: Page): Promise<void> {
+  await page.locator('[data-slot="wizard-save"]').click();
+}
+
+/**
+ * Assert the wizard sits on a given visible step counter.
+ * `displayIndex` is the visible 1-based index; `totalSteps` is the
+ * path length for the active mode + cadence.
+ */
+export async function expectStep(
+  page: Page,
+  displayIndex: number,
+  totalSteps?: number,
+): Promise<void> {
+  // The "Schritt X von Y" caption is mobile-only (`sm:hidden`) since the dot
+  // stepper landed, so it is hidden on the desktop e2e viewport. Assert the
+  // viewport-independent root data-attributes the dialog always carries.
+  const root = page.locator('[data-slot="medication-wizard-dialog"]');
+  await expect(root).toHaveAttribute("data-display-step", String(displayIndex), {
+    timeout: 5_000,
+  });
+  if (totalSteps != null) {
+    await expect(root).toHaveAttribute("data-total-steps", String(totalSteps));
+  }
+}
+
+/**
+ * Verify the post-submit URL settles on `/medications/<id>` (create
+ * path; the dialog navigates there on success).
+ */
+export async function expectRedirectToMedication(
+  page: Page,
+  id: string,
+): Promise<void> {
+  await expect
+    .poll(() => new URL(page.url()).pathname, { timeout: 10_000 })
+    .toBe(`/medications/${id}`);
+}
+
+/**
+ * Navigate to the list and assert the just-created medication
+ * appears. The recurring variants surface a "Nächste Einnahme:" chip;
+ * the one-shot variant does not.
+ */
+export async function expectMedicationOnList(
+  page: Page,
+  { name, withNextDueChip }: { name: string; withNextDueChip: boolean },
+): Promise<void> {
+  // Pin the clock to a fixed afternoon before rendering the list. The
+  // recurring stub schedules an 08:00–09:00 window; the card derives its
+  // header from the real clock, so when CI happens to run inside that
+  // window the card shows the "take now" (in_window) pill and the
+  // "Nächste Einnahme:" next-due line is correctly suppressed — making the
+  // chip assertion below depend on the wall-clock. A fixed afternoon puts
+  // the morning window in the past so the next-due line always renders.
+  await page.clock.setFixedTime(new Date("2026-06-04T13:00:00Z"));
+  await page.goto("/medications", { waitUntil: "domcontentloaded" });
+  const main = page.locator("main");
+  await expect(main.getByText(name).first()).toBeVisible({ timeout: 10_000 });
+  if (withNextDueChip) {
+    await expect(main.getByText(/Nächste Einnahme:/i).first()).toBeVisible({
+      timeout: 10_000,
+    });
+  }
+}

e2e/medications-wizard-monthly.spec.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  mockMedicationsApi,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — monthly cadence.
+ *
+ * Walks the 8-step recurring path with "Monatlich" picked on Step 5
+ * and dayOfMonth = 15 set on Step 6. Emits
+ * `FREQ=MONTHLY;BYMONTHDAY=15`.
+ */
+test.describe("medication wizard — monthly", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates a monthly-on-day-15 medication end-to-end", async ({
+    page,
+  }) => {
+    await stubDashboardAnalytics(page);
+    const capture = mockMedicationsApi(page, {
+      id: STUB_MEDICATION_ID,
+      name: "Vitamin B12",
+      dose: "1000 µg",
+      rrule: "FREQ=MONTHLY;BYMONTHDAY=15",
+      rollingIntervalDays: null,
+      oneShot: false,
+    });
+
+    await openCreateWizard(page);
+
+    await fillStep1Name(page, { name: "Vitamin B12" });
+    await clickNext(page);
+
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "vitamin");
+    await clickNext(page);
+
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "1000" });
+    await clickNext(page);
+
+    await expectStep(page, 4);
+    await clickNext(page);
+
+    await expectStep(page, 5, 8);
+    await pickCadenceRow(page, "monthly");
+    await clickNext(page);
+
+    await expectStep(page, 6, 8);
+    await page.locator("#wizard-day-of-month").fill("15");
+    await clickNext(page);
+
+    await expectStep(page, 7, 8);
+    await clickNext(page);
+
+    await expectStep(page, 8, 8);
+    const summary = page.locator('[data-slot="wizard-summary"]');
+    await expect(summary).toContainText(/Monatlich/i);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Vitamin B12",
+      oneShot: false,
+      schedules: [{ rrule: "FREQ=MONTHLY;BYMONTHDAY=15" }],
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Vitamin B12",
+      withNextDueChip: true,
+    });
+  });
+});

e2e/medications-wizard-oneshot.spec.ts

@@ -0,0 +1,98 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  mockMedicationsApi,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — one-shot cadence.
+ *
+ * Picking "Einmalig" on Step 5 collapses the path onto the 5-step
+ * one-shot route ([1, 2, 3, 4, 8]). The wizard skips Steps 6 + 7
+ * because the dose date already lives in Step 4 (course window).
+ * Step 4's CourseWindowRow locks endsOn to startsOn for one-shot.
+ *
+ * The list-page "Nächste Einnahme:" chip is suppressed because the
+ * design-synthesis lifecycle deactivates one-shot medications once
+ * the single intake is logged. The spec only asserts the row name
+ * appears on the list.
+ */
+test.describe("medication wizard — one-shot", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates a single-dose medication end-to-end", async ({ page }) => {
+    await stubDashboardAnalytics(page);
+    const capture = mockMedicationsApi(page, {
+      id: STUB_MEDICATION_ID,
+      name: "Grippeimpfung",
+      dose: "0.5 ml",
+      rrule: null,
+      rollingIntervalDays: null,
+      oneShot: true,
+    });
+
+    await openCreateWizard(page);
+
+    await fillStep1Name(page, { name: "Grippeimpfung" });
+    await clickNext(page);
+
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "other");
+    await clickNext(page);
+
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "0.5" });
+    await page.locator("#wizard-dose-unit").click();
+    await page.getByRole("option", { name: /^ml$/i }).click();
+    await clickNext(page);
+
+    // Step 4 — course window. Set startsOn to a deterministic date so
+    // the post body assertion below is stable.
+    await expectStep(page, 4);
+    await page.locator('[data-slot="course-window-starts"]').fill("2026-10-15");
+    await clickNext(page);
+
+    // Step 5 — pick Einmalig. The path compresses to 5 steps the
+    // moment the row is picked; the visible counter follows.
+    await expectStep(page, 5, 8);
+    await pickCadenceRow(page, "oneShot");
+    // After the pick the path is [1, 2, 3, 4, 8]; the cadence pick
+    // step (raw step 5) sits between slots 4 and 5 of 5, so the
+    // counter pins on slot 4 of 5 until Next.
+    await expectStep(page, 4, 5);
+    await clickNext(page);
+
+    await expectStep(page, 5, 5);
+    const summary = page.locator('[data-slot="wizard-summary"]');
+    await expect(summary).toContainText(/Einmaldosis/i);
+    await expect(summary).toContainText(/2026-10-15/);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Grippeimpfung",
+      oneShot: true,
+      startsOn: "2026-10-15",
+      endsOn: "2026-10-15",
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Grippeimpfung",
+      withNextDueChip: false,
+    });
+  });
+});

e2e/medications-wizard-rolling.spec.ts

@@ -0,0 +1,97 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  STUB_MEDICATION_ID,
+  clickNext,
+  clickSave,
+  expectMedicationOnList,
+  expectRedirectToMedication,
+  expectStep,
+  fillStep1Name,
+  fillStep3Dose,
+  mockMedicationsApi,
+  openCreateWizard,
+  pickCadenceRow,
+  pickTreatmentRow,
+  stubDashboardAnalytics,
+} from "./medications-wizard-helpers";
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * v1.5.4 — Medication wizard end-to-end — rolling cadence.
+ *
+ * Walks the 8-step recurring path with "Flexibel ab letzter
+ * Einnahme" picked on Step 5 and rollingDays = 7 set on Step 6.
+ * Emits `rollingIntervalDays: 7` (no rrule). The cadence row also
+ * surfaces Marc's literal "Counter startet neu" copy directly below
+ * the row label — the assertion below pins the phrase so a future
+ * copy edit can't silently drop the rolling explainer.
+ */
+test.describe("medication wizard — rolling", () => {
+  test.use({ storageState: STORAGE_STATE_PATH });
+
+  test("creates an every-7-days-from-last-intake medication end-to-end", async ({
+    page,
+  }) => {
+    await stubDashboardAnalytics(page);
+    const capture = mockMedicationsApi(page, {
+      id: STUB_MEDICATION_ID,
+      name: "Mounjaro",
+      dose: "5 mg",
+      rrule: null,
+      rollingIntervalDays: 7,
+      oneShot: false,
+    });
+
+    await openCreateWizard(page);
+
+    await fillStep1Name(page, { name: "Mounjaro" });
+    await clickNext(page);
+
+    await expectStep(page, 2);
+    await pickTreatmentRow(page, "glp1");
+    await clickNext(page);
+
+    await expectStep(page, 3);
+    await fillStep3Dose(page, { amount: "5" });
+    await clickNext(page);
+
+    await expectStep(page, 4);
+    await clickNext(page);
+
+    await expectStep(page, 5, 8);
+    // The rolling row surfaces the Counter-Reset explainer right
+    // under the row label, not in a tooltip.
+    const rollingRow = page.locator(
+      '[data-slot="wizard-cadence-row"][data-row="rolling"]',
+    );
+    await expect(rollingRow).toContainText(/Counter/i);
+    await pickCadenceRow(page, "rolling");
+    await clickNext(page);
+
+    await expectStep(page, 6, 8);
+    await page.locator("#wizard-rolling-days").fill("7");
+    await clickNext(page);
+
+    await expectStep(page, 7, 8);
+    await clickNext(page);
+
+    await expectStep(page, 8, 8);
+    const summary = page.locator('[data-slot="wizard-summary"]');
+    await expect(summary).toContainText(/letzten Einnahme/i);
+
+    await clickSave(page);
+
+    await expectRedirectToMedication(page, STUB_MEDICATION_ID);
+    expect(capture.postBody).toMatchObject({
+      name: "Mounjaro",
+      oneShot: false,
+      schedules: [{ rollingIntervalDays: 7 }],
+    });
+
+    await expectMedicationOnList(page, {
+      name: "Mounjaro",
+      withNextDueChip: true,
+    });
+  });
+});