Merge pull request #1270 from MBombeck/release/v1.44.2

Release v1.44.2

.env.example

@@ -178,6 +178,14 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # leave the host unencrypted.
 # LOG_INCLUDE_STACK="true"
 
+# Heap diagnostics, off by default. HEALTHLOG_HEAP_SNAPSHOT=1 writes ONE heap
+# snapshot the first time the heap reaches 85 % of its limit, into
+# HEALTHLOG_DIAG_DIR (default /tmp). A snapshot contains decrypted health data
+# and keys; enable it only to chase a crash and delete the file afterwards.
+# See docs/ops/heap-diagnostics.md.
+# HEALTHLOG_HEAP_SNAPSHOT="1"
+# HEALTHLOG_DIAG_DIR="/tmp"
+
 # Optional: ship Wide Events to Loki. Leave blank for stdout-only logging.
 # LOKI_ENDPOINT="http://loki:3100"
 # LOKI_USERNAME=""

.env.production.example

@@ -49,6 +49,11 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # "<NEXT_PUBLIC_APP_URL>/api/google-health/callback"; it must stay same-origin
 # with NEXT_PUBLIC_APP_URL or the handshake is refused.
 # GOOGLE_HEALTH_REDIRECT_URI=""
+#
+# How many years back the history backfill reads after a connect: a whole
+# number from 1 to 100, 20 when unset. A data type whose history goes further
+# back ends at that point, and the integration card names the date.
+# GOOGLE_HEALTH_BACKFILL_HORIZON_YEARS="20"
 
 
 # -----------------------------------------------------------------------------
@@ -70,6 +75,12 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # for a self-hosted Nightscout that is not reachable from the public internet.
 # NIGHTSCOUT_PRIVATE_ORIGINS=""
 
+# Dawarich instances on your own network that the movement-context connection
+# may reach, comma-separated exact origins (e.g. "http://dawarich.lan:3000").
+# Each entry is one scheme://host[:port], never a suffix or a range. A public
+# Dawarich instance needs nothing here.
+# DAWARICH_PRIVATE_ORIGINS=""
+
 
 # -----------------------------------------------------------------------------
 # Notification targets on a private network -- optional
@@ -142,9 +153,11 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # Oura Cloud v2 -- optional integration (full OAuth, shared app from env)
 # -----------------------------------------------------------------------------
 # Register an app at https://cloud.ouraring.com/oauth/applications and set its
-# redirect URI to `${NEXT_PUBLIC_APP_URL}/api/oura/callback`. Both vars together
-# enable the Oura connect button. Oura uses refresh tokens; the sync refreshes
-# reactively on a 401. OURA_REDIRECT_URI overrides the derived callback.
+# redirect URI to `${NEXT_PUBLIC_APP_URL}/api/oura/callback`. Enable the Daily,
+# Personal, SpO2, Heart health and Stress permissions on it; HealthLog asks for
+# exactly those. Both vars together enable the Oura connect button. Oura uses
+# refresh tokens; the sync refreshes reactively on a 401. OURA_REDIRECT_URI
+# overrides the derived callback.
 # OURA_CLIENT_ID=""
 # OURA_CLIENT_SECRET=""
 # OURA_REDIRECT_URI=""
@@ -327,6 +340,13 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # docs/integrations/ai-providers.md.
 # DOCUMENT_AI_LIMIT_PER_HOUR=""
 
+# Minimum hours between two regenerations of a status card after a sync
+# (optional). A watch or an integration delivers readings all day, and each
+# delivery would otherwise regenerate the cards it touches every hour. Hand
+# entries keep a one-hour gap. Default 6, whole hours from 1 to 48. The value
+# under Admin > Coach wins over this one. See docs/integrations/ai-providers.md.
+# AI_SYNC_REGEN_GAP_HOURS=""
+
 # Hourly upload ceiling for each document-upload token (optional). Applies
 # only to uploads made with a token minted under Settings > API & Tokens >
 # Document tokens: a Paperless workflow or the import script. Every upload
@@ -450,6 +470,19 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # for the heaviest legitimate read (the live-aggregate analytics fallback on a
 # large account). Set "0" to disable it and restore unbounded behaviour.
 # DATABASE_STATEMENT_TIMEOUT_MS="60000"
+#
+# Postgres `work_mem` applied to every app session, as a Postgres size string.
+# Default 16MB. Large sorts and aggregates that exceed it spill to disk; each
+# sort step of each pooled connection may use this much memory, so raise it
+# with the pool size in mind.
+# DATABASE_WORK_MEM="16MB"
+#
+# Both settings above reach Postgres as the libpq `options` startup
+# parameter. PgBouncer refuses that parameter ("unsupported startup
+# parameter: options") unless it is listed in its ignore_startup_parameters.
+# Behind such a pooler, set this to 1, true or yes to send no session
+# settings at all; the pooler's or the database's own defaults then apply.
+# DATABASE_SESSION_OPTIONS_DISABLED="1"
 
 
 # -----------------------------------------------------------------------------
@@ -500,9 +533,11 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # TRUST_CF_CONNECTING_IP="1"
 
 # Memory cap of the app container (read by docker-compose.yml, not by the app).
-# Node sizes its heap from it: 1536m (the default) gives 792 MB, 1g only 524 MB,
-# which a long-used account fills in normal operation. Lower it on a host with
-# 2 GB or less, raise it on a busy instance.
+# Node sizes its heap from it: 1536m (the default) gives 792 MB. 1536m is the
+# supported floor: below it a long-used account fills the heap in normal
+# operation, and the boot log, the support report and Admin > System status
+# say the app runs below the supported floor. The host needs 3 GB of RAM,
+# 4 GB recommended. Raise it on a busy instance; do not lower it.
 # APP_MEMORY_LIMIT="1536m"
 
 # -----------------------------------------------------------------------------
@@ -592,6 +627,16 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # force the public-host guard, so an internal instance is not blocked).
 # OPENMETEO_BASE_URL="https://archive-api.open-meteo.com"
 # OPENMETEO_GEOCODING_URL="https://geocoding-api.open-meteo.com"
+#
+# Air quality, pollen and UV come from the Open-Meteo air-quality API, which
+# serves the Copernicus Atmosphere Monitoring Service (CAMS) models. CAMS data
+# is free to use with attribution, which the app shows next to the values.
+# Like the URLs above this one is optional and can point at a self-hosted
+# Open-Meteo instance. Set ENVIRONMENT_AIR_QUALITY_DISABLED to 1, true or yes
+# to stop the air-quality requests for the whole instance; weather and
+# daylight keep working, and no user can turn air quality back on.
+# OPENMETEO_AIR_QUALITY_URL="https://air-quality-api.open-meteo.com"
+# ENVIRONMENT_AIR_QUALITY_DISABLED="1"
 
 # ── Native canvas renderer (document thumbnails, scanned-PDF rasterization) ──
 # The bundled renderer's x64 build uses AVX2 CPU instructions. On x86-64 hosts
@@ -617,6 +662,15 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # LOG_SLOW_THRESHOLD_MS="3000"
 # LOG_INCLUDE_STACK="false"
 
+# Heap diagnostics, off by default. The process always logs its heap
+# (runtime.heap.sampled) and, at 85 % of the limit, one report of the work in
+# flight (runtime.heap.pressure). HEALTHLOG_HEAP_SNAPSHOT=1 additionally writes
+# ONE heap snapshot at that moment into HEALTHLOG_DIAG_DIR (default /tmp). A
+# snapshot contains decrypted health data and keys; enable it only to chase a
+# crash and delete the file afterwards. See docs/ops/heap-diagnostics.md.
+# HEALTHLOG_HEAP_SNAPSHOT="1"
+# HEALTHLOG_DIAG_DIR="/tmp"
+
 # Optional log shipping to a Loki instance. LOKI_ENDPOINT turns shipping on.
 # Either form works: the base URL (http://loki:3100) or the full push URL
 # (http://loki:3100/loki/api/v1/push). A Loki on your own network is fine,

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,7 +15,7 @@ body:
     id: version
     attributes:
       label: HealthLog version
-      description: Output of `/api/version` or the tag of the GHCR image you're running.
+      description: Settings, About shows it, as does `/api/version`, or the tag of the GHCR image you're running.
       placeholder: "1.4.19"
     validations:
       required: true
@@ -55,11 +55,27 @@ body:
         3. See error
     validations:
       required: true
+  - type: input
+    id: error-id
+    attributes:
+      label: Error ID
+      description: If the failure showed an error ID (eight characters, e.g. `3f9a2c1b`), paste it here. The operator finds the event with it under Admin, App logs.
+      placeholder: "3f9a2c1b"
+  - type: textarea
+    id: support-info
+    attributes:
+      label: Support info / support report
+      description: |
+        Everyone: Settings, About, "Copy support info".
+        Operators: Admin, System status, "Support report", then Copy.
+        Both are redacted (no names, emails, values or tokens); read them before you paste.
+        See https://github.com/MBombeck/HealthLog/blob/main/docs/self-hosting/support.md
+      render: text
   - 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.
+      label: Screenshots / other logs
+      description: Attach screenshots, or paste other log output if you have it. Redact secrets and personal data first.
       render: shell
   - type: input
     id: browser

.github/ISSUE_TEMPLATE/translation.yml

@@ -1,12 +1,12 @@
 name: Translation feedback
-description: Report a wording, grammar, or register problem in HealthLog's AI-initial locales (FR / ES / IT / PL).
+description: Report a wording, grammar, or register problem in HealthLog's AI-initial locales (FR / ES / IT / PL / KO / NL).
 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.
+        HealthLog ships German and English as maintainer-curated translations. French, Spanish, Italian, Polish, Korean, and Dutch 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.
 
@@ -20,6 +20,8 @@ body:
         - Spanish (es)
         - Italian (it)
         - Polish (pl)
+        - Korean (ko)
+        - Dutch (nl)
         - Other (specify under "Surface")
     validations:
       required: true

.github/dependabot.yml

@@ -10,6 +10,41 @@ updates:
         applies-to: security-updates
         update-types:
           - "patch"
+      # One weekly pull request per dependency kind instead of a trickle of
+      # single bumps: patch and minor updates travel together and pass the
+      # same checks once. Majors stay single so each gets its own review.
+      #
+      # The Next.js line travels alone. Its bumps are the ones that move
+      # URL state after history traversal (see the note on 16.4 below), and a
+      # red Next bump inside the group would hold every harmless update in
+      # it red as well.
+      production-weekly:
+        dependency-type: "production"
+        update-types:
+          - "patch"
+          - "minor"
+        exclude-patterns:
+          - "next"
+      development-weekly:
+        dependency-type: "development"
+        update-types:
+          - "patch"
+          - "minor"
+        exclude-patterns:
+          - "eslint-config-next"
+          - "@next/bundle-analyzer"
+    # No ignore for the Next.js line any more. 16.4.0 lost URL state after
+    # history traversal: with a sheet opened through `?doc=`, Back left it
+    # open, and `[` / `]` sometimes did not move `?day=` (3 of 40 repeated
+    # runs of three end-to-end journeys, 0 of 80 on 16.3.8). 16.4.2 does the
+    # same (the day keys lost a step in 2 of 20 runs locally, the `?doc=`
+    # journey failed once in CI). Both were ours to fix: the sheet followed
+    # `useSearchParams`, which 16.4 updates after the write it copies, and a
+    # day step wrote the URL before Next had adopted the previous step, whose
+    # late adoption then put the older URL back. The sheet now follows the
+    # address bar and a step waits for the layer. Measured after both fixes:
+    # 200 of 200 repeated runs of the three journeys, and another 80 of 80
+    # each for the `?doc=` and day-key journeys.
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/coach-eval.yml

@@ -26,7 +26,7 @@ permissions:
 jobs:
   coach-eval:
     name: Coach eval — deterministic floor (always) + live judge (opt-in)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
 
     # Map the opt-in secret to a job-level env so the live-judge steps can gate
@@ -41,7 +41,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: pnpm

.github/workflows/codeql.yml

@@ -36,7 +36,7 @@ concurrency:
 jobs:
   analyze:
     name: Analyse javascript-typescript
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 30
     permissions:
       contents: read
@@ -60,7 +60,7 @@ jobs:
       # minutes and can produce nothing actionable, because nobody edits
       # it and the fix for anything found there is `pnpm prisma generate`.
       - name: Initialise CodeQL
-        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           languages: javascript-typescript
           build-mode: none
@@ -75,6 +75,6 @@ jobs:
               - public
 
       - name: Analyse
-        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           category: "/language:javascript-typescript"

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

@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   auto-merge:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.actor == 'dependabot[bot]'
     permissions:
       contents: write
@@ -22,7 +22,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: "pnpm"

.github/workflows/docker-publish.yml

@@ -39,7 +39,7 @@ concurrency:
 jobs:
   release-policy:
     name: Validate release policy
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     permissions:
       actions: read
@@ -121,7 +121,7 @@ jobs:
       matrix:
         include:
           - platform: linux/amd64
-            runner: ubuntu-latest
+            runner: ubuntu-24.04
             cache_scope: amd64
           - platform: linux/arm64
             runner: ubuntu-24.04-arm
@@ -296,7 +296,7 @@ jobs:
 
       - name: Upload digest artifact
         if: github.event_name != 'pull_request'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: digest-${{ matrix.cache_scope }}
           path: /tmp/digests/*
@@ -313,7 +313,7 @@ jobs:
   # the registry instead of on one cross-emulated runner.
   merge:
     name: Merge multi-arch manifest
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name != 'pull_request'
     needs: [build]
     timeout-minutes: 10
@@ -334,7 +334,7 @@ jobs:
 
     steps:
       - name: Download digest artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           path: /tmp/digests
           pattern: digest-*
@@ -449,7 +449,7 @@ jobs:
   promote:
     name: Promote verified image to Coolify
     needs: [merge, verify-published-image]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     permissions:
       contents: read

.github/workflows/e2e.yml

@@ -23,9 +23,16 @@ jobs:
   # Two shards grew to 14–19 minutes against the 20-minute cap once the
   # mobile route sweep landed, and a slow runner tipped them over; three
   # shards with a 30-minute cap leave room for both.
+  # Every Playwright job runs inside Microsoft's Playwright image, which ships
+  # the browsers with their system libraries: installing them from apt at run
+  # time stalled shards for 29 minutes twice, once for WebKit and once for
+  # Chromium alone.
   shard:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    needs: playwright-version
     timeout-minutes: 30
+    container:
+      image: mcr.microsoft.com/playwright:v${{ needs.playwright-version.outputs.version }}-noble
     strategy:
       fail-fast: false
       matrix:
@@ -38,8 +45,6 @@ jobs:
           POSTGRES_USER: healthlog
           POSTGRES_PASSWORD: healthlog
           POSTGRES_DB: healthlog
-        ports:
-          - 5432:5432
         options: >-
           --health-cmd "pg_isready -U healthlog"
           --health-interval 5s
@@ -47,7 +52,8 @@ jobs:
           --health-retries 10
 
     env:
-      DATABASE_URL: postgresql://healthlog:healthlog@localhost:5432/healthlog?schema=public
+      # Inside a job container the service is reached by its name.
+      DATABASE_URL: postgresql://healthlog:healthlog@postgres:5432/healthlog?schema=public
       ENCRYPTION_KEYS: '{"v1":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'
       ENCRYPTION_ACTIVE_KEY_ID: v1
       API_TOKEN_HMAC_KEY: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
@@ -56,13 +62,19 @@ jobs:
       AUTH_RP_ORIGIN: http://localhost:3000
       SESSION_COOKIE_SECURE: "false"
       NODE_ENV: production
+      # The WebKit spec runs in the `webkit` job below.
+      E2E_SKIP_WEBKIT: "1"
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      # The image runs as root while the checkout belongs to the runner user;
+      # git refuses such a tree, and the prepare hook calls git.
+      - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: pnpm
@@ -73,16 +85,6 @@ jobs:
 
       - run: pnpm db:migrate:deploy
 
-      - name: Cache Playwright browsers
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        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
-
       # `pnpm build` (not bare `next build`): the prebuild hook generates
       # the versioned service-worker stamp AND the static i18n catalog
       # assets (public/i18n/<locale>.js) the client boots from — without
@@ -106,7 +108,7 @@ jobs:
 
       - name: Upload Playwright HTML report
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: playwright-report-shard-${{ matrix.shard }}
           path: playwright-report/
@@ -117,26 +119,123 @@ jobs:
       # job below. Only uploaded when the shard ran to completion, so a missing
       # artifact there means a shard that did not finish, not an empty suite.
       - name: Upload Playwright JSON report
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: playwright-json-shard-${{ matrix.shard }}
           path: playwright-json/results.json
           retention-days: 7
           if-no-files-found: error
 
+  # The Playwright image must carry the browsers of the exact Playwright the
+  # lockfile resolves, or the run refuses them. Read the version from the
+  # lockfile so a dependency bump moves the image with it.
+  playwright-version:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.read.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          sparse-checkout: pnpm-lock.yaml
+          sparse-checkout-cone-mode: false
+      - id: read
+        run: |
+          version=$(grep -m1 -E "^  playwright-core@[0-9]" pnpm-lock.yaml | sed -E "s/^  playwright-core@([0-9.]+):.*/\1/")
+          if [ -z "$version" ]; then echo "playwright-core not found in pnpm-lock.yaml"; exit 1; fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  # The WebKit spec (`bottom-sheet.spec.ts`, project `webkit-iphone`), in the
+  # same image as the shards.
+  webkit:
+    runs-on: ubuntu-24.04
+    needs: playwright-version
+    timeout-minutes: 30
+    name: e2e webkit
+    container:
+      image: mcr.microsoft.com/playwright:v${{ needs.playwright-version.outputs.version }}-noble
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: healthlog
+          POSTGRES_PASSWORD: healthlog
+          POSTGRES_DB: healthlog
+        options: >-
+          --health-cmd "pg_isready -U healthlog"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      # Inside a job container the service is reached by its name.
+      DATABASE_URL: postgresql://healthlog:healthlog@postgres:5432/healthlog?schema=public
+      ENCRYPTION_KEYS: '{"v1":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'
+      ENCRYPTION_ACTIVE_KEY_ID: v1
+      API_TOKEN_HMAC_KEY: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+      AUTH_RP_NAME: HealthLog
+      AUTH_RP_ID: localhost
+      AUTH_RP_ORIGIN: http://localhost:3000
+      SESSION_COOKIE_SECURE: "false"
+      NODE_ENV: production
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # The image runs as root while the checkout belongs to the runner user;
+      # git refuses such a tree, and the prepare hook calls git.
+      - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm db:migrate:deploy
+
+      - run: NODE_OPTIONS=--max-old-space-size=8192 pnpm build
+
+      - run: pnpm exec playwright test --project=webkit-iphone
+        env:
+          E2E_BASE_URL: http://localhost:3000
+
+      - name: Upload Playwright HTML report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: playwright-report-webkit
+          path: playwright-report/
+          retention-days: 7
+          if-no-files-found: ignore
+
+      - name: Upload Playwright JSON report
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: playwright-json-shard-webkit
+          path: playwright-json/results.json
+          retention-days: 7
+          if-no-files-found: error
+
   # Branch protection requires a check named exactly "e2e". This job carries
-  # that name and answers for both shards: it fails when any shard failed or
-  # was cancelled, so a half-green matrix cannot satisfy the gate.
+  # that name and answers for every shard and the WebKit job: it fails when
+  # any of them failed or was cancelled, so a half-green run cannot satisfy
+  # the gate.
   e2e:
-    runs-on: ubuntu-latest
-    needs: shard
+    runs-on: ubuntu-24.04
+    needs: [shard, webkit]
     if: always()
     timeout-minutes: 5
     steps:
       - name: Every shard finished green
         run: |
-          if [ "${{ needs.shard.result }}" != "success" ]; then
-            echo "shard result: ${{ needs.shard.result }}"
+          if [ "${{ needs.shard.result }}" != "success" ] || [ "${{ needs.webkit.result }}" != "success" ]; then
+            echo "shard result: ${{ needs.shard.result }}, webkit result: ${{ needs.webkit.result }}"
             exit 1
           fi
 
@@ -146,10 +245,10 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           sparse-checkout: scripts
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           pattern: playwright-json-shard-*
           path: playwright-json

.github/workflows/env-check.yml

@@ -21,7 +21,7 @@ permissions:
 jobs:
   env-check:
     name: pnpm check-env against .env.production.example
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
       - name: Checkout
@@ -31,7 +31,7 @@ jobs:
         uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Set up Node
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: pnpm

.github/workflows/integration-long.yml

@@ -0,0 +1,45 @@
+name: Integration tests (long)
+
+# The integration tests that take their size from the environment run small
+# on every pull request and at full size here, once a night. Today that is
+# the Google Health multi-year backfill: 120 and 160 days of heart rate on a
+# pull request, three and four years (some 3.7 million readings, over twenty
+# minutes) here. See the header of
+# tests/integration/google-health-backfill-multi-year.test.ts.
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  long:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 75
+    name: integration long
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm exec vitest run --config vitest.integration.config.mts tests/integration/google-health-backfill-multi-year.test.ts
+        env:
+          HEALTHLOG_BACKFILL_TEST_DAYS: "1095"
+          # Under the production heap ceiling, which the test's heap check
+          # is about.
+          NODE_OPTIONS: "--max-old-space-size=524"
+          # Quoted for the reason given in integration.yml.
+          API_TOKEN_HMAC_KEY: "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+          ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
+          SESSION_SECRET: "integration-tests"

.github/workflows/integration.yml

@@ -22,7 +22,7 @@ jobs:
   # job timeout only needs to catch a container that never boots. Each shard
   # boots its own Postgres testcontainer.
   shard:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 40
     strategy:
       fail-fast: false
@@ -34,7 +34,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: pnpm
@@ -67,7 +67,7 @@ jobs:
   # carries that name and answers for every shard: it fails when any shard
   # failed or was cancelled, so a half-green matrix cannot satisfy the gate.
   integration:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     needs: shard
     if: always()
     timeout-minutes: 5

.github/workflows/knip.yml

@@ -12,7 +12,7 @@ permissions:
 jobs:
   knip:
     name: Dead-code gate
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 10
 
     steps:
@@ -20,7 +20,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: pnpm

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

@@ -16,7 +16,7 @@ jobs:
   # future contributor reintroduces the pattern.
   grep:
     name: Forbidden marker grep
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

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

@@ -45,7 +45,7 @@ permissions:
 jobs:
   verify:
     name: Pull and smoke-test exact published image
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 10
     env:
       IMAGE_REF: ${{ inputs.image_ref }}

.github/workflows/scorecard.yml

@@ -25,7 +25,7 @@ permissions: read-all
 jobs:
   analysis:
     name: Score supply-chain practices
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
     permissions:
       # Write the findings into the repository's code-scanning alerts.
@@ -47,14 +47,14 @@ jobs:
           persist-credentials: false
 
       - name: Run analysis
-        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
         with:
           results_file: scorecard-results.sarif
           results_format: sarif
           publish_results: true
 
       - name: Upload results
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: scorecard-results.sarif
           category: scorecard

.github/workflows/security.yml

@@ -17,7 +17,7 @@ permissions:
 jobs:
   quality:
     name: Lint, Typecheck & Test
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name != 'schedule'
 
     steps:
@@ -25,7 +25,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: "pnpm"
@@ -100,7 +100,7 @@ jobs:
   # published image daily.
   dependency-audit:
     name: Dependency Audit
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     # Runs on pull requests too, but advisory: an advisory published against a
     # dependency the branch did not touch must not block the branch. The push
     # run on main and the daily schedule stay blocking, and a tag is only ever
@@ -112,7 +112,7 @@ jobs:
 
       - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
           cache: "pnpm"
@@ -130,7 +130,7 @@ jobs:
 
   secret-scan:
     name: Secret Scanning
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name != 'schedule'
 
     steps:
@@ -145,7 +145,7 @@ jobs:
 
   docker-security:
     name: Container Security
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 
     steps:

.github/workflows/synthetic-journey.yml

@@ -45,13 +45,13 @@ permissions:
 jobs:
   journey:
     name: Sign in, write a reading, read it back
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 10
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
 

.github/workflows/trivy.yml

@@ -30,7 +30,7 @@ concurrency:
 jobs:
   filesystem:
     name: Lockfile (including dev dependencies)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
       contents: read
@@ -88,14 +88,14 @@ jobs:
           skip-dirs: src/generated
 
       - name: Upload results
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: trivy-filesystem.sarif
           category: trivy-filesystem
 
   published-image:
     name: Published image
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
       contents: read
@@ -145,7 +145,7 @@ jobs:
           exit-code: "0"
 
       - name: Upload results
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         with:
           sarif_file: trivy-published-image.sarif
           category: trivy-published-image

CONTRIBUTING.md

@@ -121,7 +121,7 @@ Contributors: branch off `main`; PRs target `main`.
 
 ## Translations
 
-HealthLog ships with English (`en`) and German (`de`) maintained by the project, plus French (`fr`), Spanish (`es`), Italian (`it`), Polish (`pl`), and Korean (`ko`) 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.
+HealthLog ships with English (`en`) and German (`de`) maintained by the project, plus French (`fr`), Spanish (`es`), Italian (`it`), Polish (`pl`), Korean (`ko`), and Dutch (`nl`) 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
 
@@ -136,7 +136,7 @@ To suggest a fix or improvement:
 
 ### Adding a new locale
 
-If you want to introduce a locale that isn't shipped (e.g. `nl`, `pt-BR`, `cs`):
+If you want to introduce a locale that isn't shipped (e.g. `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`.

Dockerfile

@@ -76,6 +76,15 @@ ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV TZ=Europe/Berlin
 
+# When the heap runs out, Node writes a diagnostic report (the JavaScript
+# and native stacks, heap spaces, libuv handles) to stderr, where
+# `docker compose logs` and Loki keep it; without it the log holds one
+# line. Environment variables and network interfaces are left out, so no
+# key, password or address from the environment reaches the log. An
+# operator who sets NODE_OPTIONS replaces this value and should carry these
+# flags over (docs/ops/heap-diagnostics.md).
+ENV NODE_OPTIONS="--report-on-fatalerror --report-filename=stderr --report-exclude-env --report-exclude-network"
+
 # 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
@@ -202,14 +211,23 @@ COPY --from=builder /app/src/generated ./src/generated
 # `@node-rs/argon2` from the traced runtime tree. Scripts that import the
 # application graph (`@/…`, the generated Prisma client) run from a source
 # checkout instead. `src/__tests__/container-scripts-ship-guard.test.ts` holds
-# the runbooks and this list in step. Root-owned on purpose: the app user can
-# run them but not rewrite them.
+# the runbooks and the entrypoint against this list. `pending-migrations.mjs`
+# and `migrate-deploy.mjs` are the entrypoint's own: the first logs the
+# pending migration count, the second runs `migrate deploy` with its
+# lock-timeout retry. Root-owned on purpose: the app user can run them but not
+# rewrite them.
 COPY --from=builder /app/scripts/reset-password.mjs ./scripts/reset-password.mjs
+COPY --from=builder /app/scripts/pending-migrations.mjs ./scripts/pending-migrations.mjs
+COPY --from=builder /app/scripts/migrate-deploy.mjs ./scripts/migrate-deploy.mjs
 COPY --from=builder /app/src/lib/auth/argon2-params.mjs ./src/lib/auth/argon2-params.mjs
 COPY --from=builder /app/scripts/repair-intake-anomalies.ts ./scripts/repair-intake-anomalies.ts
 # Prove the reset CLI's imports resolve in this tree: with every import found
 # it stops at its own usage line; a missing module throws before reaching it.
 RUN node scripts/reset-password.mjs 2>&1 | grep -q "reset-password: usage:"
+# The boot notice parses, and the `pg` it loads on a real boot resolves here.
+RUN env -u DATABASE_URL node scripts/pending-migrations.mjs && \
+    node --input-type=module -e "await import('pg')" && \
+    node --input-type=module -e "await import('./scripts/migrate-deploy.mjs')"
 
 # Install the migration CLI, its config dependency, and a pinned launcher for
 # the maintenance scripts already shipped in the standalone tree. The Prisma
@@ -247,7 +265,7 @@ RUN mkdir -p /opt/prisma-cli && \
     npm pkg set 'overrides.mysql2=^3.22.0' && \
     npm pkg set 'overrides.@hono/node-server=^1.19.15' && \
     npm pkg set 'overrides.valibot=^1.4.2' && \
-    npm install --omit=dev prisma@7.10.0 @prisma/engines@7.10.0 tsx@4.23.1 dotenv@17.4.2 && \
+    npm install --omit=dev prisma@7.10.0 @prisma/engines@7.10.0 tsx@4.23.1 dotenv@18.0.6 && \
     ln -sfn /opt/prisma-cli/node_modules/.bin/tsx /usr/local/bin/healthlog-tsx && \
     ln -sfn /opt/prisma-cli/node_modules/dotenv /app/node_modules/dotenv && \
     ln -sfn /opt/prisma-cli/node_modules/prisma /app/node_modules/prisma && \
@@ -300,8 +318,13 @@ EXPOSE 3000
 ENV PORT=3000
 ENV HOSTNAME="0.0.0.0"
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1
+# Start period: the entrypoint migrates before the server listens, and a
+# migration waiting out a held lock retries for up to about eight minutes.
+# Five retries: a pool saturated for a minute during a boot storm makes the
+# probe's 2 s database check miss once or twice without marking the container
+# unhealthy (docker-compose.yml explains the numbers).
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10m --retries=5 \
+  CMD wget --no-verbose --tries=1 --timeout=4 --spider http://127.0.0.1:3000/api/health || exit 1
 
 ENTRYPOINT ["./docker-entrypoint.sh"]
 CMD ["node", "server.js"]

README.md

@@ -24,20 +24,16 @@
   <a href="https://testflight.apple.com/join/bucuTBpa">iOS TestFlight</a>
 </p>
 
-<img width="2434" height="1247" alt="HealthLog dashboard: health metric tiles with 7-day trends, blood-pressure and weight charts, dark theme" src="docs/assets/dashboard-hero.jpeg" />
+<img width="2400" height="1500" alt="HealthLog dashboard in dark theme: a lead sentence on the latest vitals, today's medications, sleep and cycle, the health score ring, worth-a-look cards, and metric tiles with 7-day trends" src="docs/assets/dashboard.jpeg" />
 <p align="center">
-  <img src="docs/assets/Insights.png"
-       alt="Insights"
-       width="23%">
-  <img src="docs/assets/resting-pulse.png"
-       alt="Insights RHR"
-       width="23%">
-  <img src="docs/assets/Medications.png"
-       alt="Medications"
-       width="23%">
-  <img src="docs/assets/Coach.png"
-       alt="Coach Chat"
-       width="23%">
+  <img src="docs/assets/timeline.jpeg" alt="Timeline: life events, conditions, medications, vaccinations, labs and cycles on one time axis, above blood pressure, weight and resting heart rate" width="32%">
+  <img src="docs/assets/day-panel.jpeg" alt="Blood pressure insights with the day panel open: what was running that day, its values and scores" width="32%">
+  <img src="docs/assets/resting-heart-rate.jpeg" alt="Resting heart rate insights: summary, usual range and the full history chart" width="32%">
+</p>
+<p align="center">
+  <img src="docs/assets/medications.jpeg" alt="Medications with next and last intake, adherence and streaks" width="32%">
+  <img src="docs/assets/labs.jpeg" alt="Lab results with reference ranges and trend sparklines" width="32%">
+  <img src="docs/assets/coach.jpeg" alt="Coach: a conversation about the week's recovery, grounded in the recorded data" width="32%">
 </p>
 
 ## Why HealthLog
@@ -60,7 +56,7 @@ Try the [live demo](https://demo.healthlog.dev) to see a working install — sig
 - **AI insights you own.** Daily briefing, health scores, correlations, and a conversational coach grounded in your own measurements and interpreted against cited guideline reference bands — where a value sits and what that means in plain words, never a diagnosis. The coach proposes concrete if-then plans you accept or decline, and suppresses proactive check-ins when there's nothing genuine to say. Bring your own OpenAI or Anthropic key, or point at a local endpoint (Ollama, LM Studio, vLLM) so AI requests stay on your network.
 - **Clinician-ready output.** A doctor-report PDF rendered on your server, a read-only HL7 FHIR R4 API, and scoped, time-limited share links you revoke after the visit.
 - **Private by construction.** AES-256-GCM encryption at rest for notes and other free text, documents, questionnaire answers, AI-written text and credentials, with zero-downtime key rotation. Measurement values, lab values, medication names and mood scores are stored unencrypted in the database, so the database volume and its backups need the same protection as the host. Passkey login, server-side sessions, strict CSP, and no third-party tracking anywhere.
-- **Built to be lived in.** Installable PWA with offline support, medication reminders over APNs, Telegram, ntfy, and Web Push, a sub-second dashboard on years of imported history — in English, German, Spanish, French, Italian, Polish, and Korean end to end.
+- **Built to be lived in.** Installable PWA with offline support, medication reminders over APNs, Telegram, ntfy, and Web Push, a sub-second dashboard on years of imported history — in English, German, Spanish, French, Italian, Polish, Korean, and Dutch end to end.
 
 The full feature tour, integration guides, and API reference live at [docs.healthlog.dev](https://docs.healthlog.dev).
 

bundle-budget.json

@@ -1,12 +1,14 @@
 {
-  "$comment": "Client-bundle budgets, enforced by scripts/check-bundle-budget.mjs (--check) after `next build` in CI. Values are KB gzip and include every emitted lazy route and locale chunk, while route budgets include the shared rootMainFiles baseline. Re-measured at v1.37.2: / 455, /insights 443, /measurements 441, /insights/mood 453, total 3328, baseline 130, lazy catalogs 849. Every per-route ceiling is unchanged. The /insights overview crept a kilobyte over its 445 ceiling when the ECG teaser began importing its overview cap from the classification module, dragging that module's label map and helpers into the eager page; the cap now lives in its own value-only module, and the Health Score's single provenance entry is split out of the full metric-provenance map, so the overview imports the bare number and citation it renders rather than every metric's label map behind them. Both are back under 445 with room to spare. The 42 KB aggregate rise from 3286 (v1.35.0) is all locale-catalog strings: v1.36 and v1.37 added the encounter, mood-context, mood-prognosis, practitioner, workout-batch and account-sharing surfaces, and their copy lands across the six locale catalogs the whole-build sum counts independently (804 to 849 KB). The non-catalog client chunks are flat against v1.35.0, so nothing a person downloads on a given route grew beyond its own ceiling. The aggregate cap therefore moves from 3310 to 3352 (24 KB headroom, matching the previous margin); per-route ceilings, the static-catalog guard and the one-Recharts-chunk guard remain unchanged. v1.37.4's honest-error-state charge then added recoverable read-failure handling to thirteen surfaces (the shared QueryErrorCard and QueryErrorRow primitives plus an isError branch per surface) and rewrote the MCP scope note and the managed-record error copy across the six locales; the measured total rose to 3404 while every per-route ceiling stayed met (/page 457, /insights 445, /measurements 443, /insights/mood 455). The aggregate cap moves from 3352 to 3428, keeping the same margin; nothing a person downloads on a given route grew beyond its ceiling. v1.37.15's async-truth charge then added the refresh settling state with its two-locale-key copy, the index-outcome plain-words line (seven keys across the six catalogs) and the reindex-count wiring; the measured total rose to 3429 while every per-route ceiling stayed met (/page 456, /insights 445, /measurements 442, /insights/mood 455). The aggregate cap moves from 3428 to 3452, keeping the same margin; nothing a person downloads on a given route grew beyond its ceiling. v1.37.27 found /insights sitting a few hundred bytes under 445 on main and a few hundred over it on the release branch — the page had been at its ceiling for three releases and the release only had to breathe on it. The weight it was carrying was not its own: the authenticated shell imported one destination predicate from the `@/lib/record-settings` barrel, and the barrel also re-exports the managed settings-patch schemas, so Zod, the module registry and three validation modules rode into the eager bundle of every authenticated route for a function that reads a URL slug. The shell imports the `classification` leaf now. Measured across all 585 client-rendered routes: none grew by a byte, 100 fell, by 4.7 KB at the median and 8.1 KB at the most; /insights 444 to 437, /measurements 442 to 435, / 456 to 450, /insights/mood 455 to 450. The whole-build sum moved the other way, 3451 to 3476, and that direction is the metric rather than the change: the aggregate counts each emitted chunk once, so a graph that leaves the chunk group every route shares gets counted again wherever it lands — here inside the deferred settings chunks that actually use it. Bytes on disk rose 25 KB; bytes a reader downloads only ever fell. The aggregate cap moves from 3452 to 3500, the same 24 KB headroom as the four re-measurements before it. Per-route ceilings keep their old values rather than tightening to the new floor: the CI runner measures each route about 1.5 KB heavier than a local arm64 build does, and a ceiling set from a local number would fail on a build that had not regressed. The static-catalog guard and the one-Recharts-chunk guard remain unchanged. Raised to 3700 at v1.37.32 for the seventh interface language (Korean): the lazy message catalogs went 6->7 chunks (1026 KB gz measured), pushing the aggregate to 3631 against the old 3500. The raise is entirely the new catalog; no route budget moved, and the four eager route ceilings are unchanged and still passing. Most of the aggregate is the dynamic locale-switch and fallback path that a first paint never loads (see issue #253), so this ceiling guards bytes almost no visitor requests; 3700 leaves ~69 KB for ordinary drift until that double-count is cleaned up. v1.38.14 re-measures the four eager routes and changes what the number means. The ceilings had been re-stated but never re-based since v1.37.4, so /inLine truncated
+  "$comment": "Client-bundle budgets, enforced by scripts/check-bundle-budget.mjs (--check) after `next build` in CI. Values are KB gzip and include every emitted lazy route and locale chunk, while route budgets include the shared rootMainFiles baseline. Re-measured at v1.37.2: / 455, /insights 443, /measurements 441, /insights/mood 453, total 3328, baseline 130, lazy catalogs 849. Every per-route ceiling is unchanged. The /insights overview crept a kilobyte over its 445 ceiling when the ECG teaser began importing its overview cap from the classification module, dragging that module's label map and helpers into the eager page; the cap now lives in its own value-only module, and the Health Score's single provenance entry is split out of the full metric-provenance map, so the overview imports the bare number and citation it renders rather than every metric's label map behind them. Both are back under 445 with room to spare. The 42 KB aggregate rise from 3286 (v1.35.0) is all locale-catalog strings: v1.36 and v1.37 added the encounter, mood-context, mood-prognosis, practitioner, workout-batch and account-sharing surfaces, and their copy lands across the six locale catalogs the whole-build sum counts independently (804 to 849 KB). The non-catalog client chunks are flat against v1.35.0, so nothing a person downloads on a given route grew beyond its own ceiling. The aggregate cap therefore moves from 3310 to 3352 (24 KB headroom, matching the previous margin); per-route ceilings, the static-catalog guard and the one-Recharts-chunk guard remain unchanged. v1.37.4's honest-error-state charge then added recoverable read-failure handling to thirteen surfaces (the shared QueryErrorCard and QueryErrorRow primitives plus an isError branch per surface) and rewrote the MCP scope note and the managed-record error copy across the six locales; the measured total rose to 3404 while every per-route ceiling stayed met (/page 457, /insights 445, /measurements 443, /insights/mood 455). The aggregate cap moves from 3352 to 3428, keeping the same margin; nothing a person downloads on a given route grew beyond its ceiling. v1.37.15's async-truth charge then added the refresh settling state with its two-locale-key copy, the index-outcome plain-words line (seven keys across the six catalogs) and the reindex-count wiring; the measured total rose to 3429 while every per-route ceiling stayed met (/page 456, /insights 445, /measurements 442, /insights/mood 455). The aggregate cap moves from 3428 to 3452, keeping the same margin; nothing a person downloads on a given route grew beyond its ceiling. v1.37.27 found /insights sitting a few hundred bytes under 445 on main and a few hundred over it on the release branch — the page had been at its ceiling for three releases and the release only had to breathe on it. The weight it was carrying was not its own: the authenticated shell imported one destination predicate from the `@/lib/record-settings` barrel, and the barrel also re-exports the managed settings-patch schemas, so Zod, the module registry and three validation modules rode into the eager bundle of every authenticated route for a function that reads a URL slug. The shell imports the `classification` leaf now. Measured across all 585 client-rendered routes: none grew by a byte, 100 fell, by 4.7 KB at the median and 8.1 KB at the most; /insights 444 to 437, /measurements 442 to 435, / 456 to 450, /insights/mood 455 to 450. The whole-build sum moved the other way, 3451 to 3476, and that direction is the metric rather than the change: the aggregate counts each emitted chunk once, so a graph that leaves the chunk group every route shares gets counted again wherever it lands — here inside the deferred settings chunks that actually use it. Bytes on disk rose 25 KB; bytes a reader downloads only ever fell. The aggregate cap moves from 3452 to 3500, the same 24 KB headroom as the four re-measurements before it. Per-route ceilings keep their old values rather than tightening to the new floor: the CI runner measures each route about 1.5 KB heavier than a local arm64 build does, and a ceiling set from a local number would fail on a build that had not regressed. The static-catalog guard and the one-Recharts-chunk guard remain unchanged. Raised to 3700 at v1.37.32 for the seventh interface language (Korean): the lazy message catalogs went 6->7 chunks (1026 KB gz measured), pushing the aggregate to 3631 against the old 3500. The raise is entirely the new catalog; no route budget moved, and the four eager route ceilings are unchanged and still passing. Most of the aggregate is the dynamic locale-switch and fallback path that a first paint never loads (see issue #253), so this ceiling guards bytes almost no visitor requests; 3700 leaves ~69 KB for ordinary drift until that double-count is cleaned up. v1.38.14 re-measures the four eager routes and changes what the number means. The ceilings had been re-stated but never re-based since v1.37.4, so /inLine truncated
   "routeBaselineKbGz": {
-    "/page": 429,
-    "/insights/page": 368,
-    "/measurements/page": 411,
-    "/insights/mood/page": 379
+    "/page": 355,
+    "/insights/page": 323,
+    "/measurements/page": 335,
+    "/insights/mood/page": 334,
+    "/settings/[section]/page": 307
   },
   "routeDriftAllowanceKbGz": 20,
-  "totalClientKbGz": 4155,
-  "maxRechartsChunks": 1
+  "totalClientKbGz": 3900,
+  "maxRechartsChunks": 1,
+  "maxCatalogKbGz": 210
 }

docker-compose.yml

@@ -72,6 +72,11 @@ x-healthlog-env: &healthlog_env
   # (default 60000; 0 disables it and restores the unbounded behaviour).
   # Raise it if a very large account's analytics fallback is being cut off.
   DATABASE_STATEMENT_TIMEOUT_MS: "${DATABASE_STATEMENT_TIMEOUT_MS:-}"
+  # Postgres work_mem for every app session (default 16MB).
+  DATABASE_WORK_MEM: "${DATABASE_WORK_MEM:-}"
+  # 1 sends neither of the two settings above (they ride the libpq `options`
+  # startup parameter, which PgBouncer refuses by default).
+  DATABASE_SESSION_OPTIONS_DISABLED: "${DATABASE_SESSION_OPTIONS_DISABLED:-}"
   WITHINGS_WEBHOOK_SECRET: "${WITHINGS_WEBHOOK_SECRET:-}"
   # Overrides the derived `${NEXT_PUBLIC_APP_URL}/api/withings/callback`;
   # set it when the URL registered with Withings differs from the app's own
@@ -221,10 +226,19 @@ x-healthlog-env: &healthlog_env
   # the authorization code somewhere else.
   FITBIT_REDIRECT_URI: "${FITBIT_REDIRECT_URI:-}"
   GOOGLE_HEALTH_REDIRECT_URI: "${GOOGLE_HEALTH_REDIRECT_URI:-}"
+  # How many years back the Google Health history backfill reads (a whole
+  # number from 1 to 100; 20 when unset). A data type whose history goes
+  # further ends there, and the integration card says so.
+  GOOGLE_HEALTH_BACKFILL_HORIZON_YEARS: "${GOOGLE_HEALTH_BACKFILL_HORIZON_YEARS:-}"
   # Nightscout origins on your own network that the per-user connection
   # validator should accept, comma-separated (e.g. "http://nightscout.lan").
   # Without it a LAN/private Nightscout URL is refused as an SSRF target.
   NIGHTSCOUT_PRIVATE_ORIGINS: "${NIGHTSCOUT_PRIVATE_ORIGINS:-}"
+  # Dawarich instances on your own network that the movement-context
+  # connection may reach, comma-separated exact origins (e.g.
+  # "http://dawarich.lan:3000"). Without it a LAN/private Dawarich URL is
+  # refused as an SSRF target; a public instance needs nothing here.
+  DAWARICH_PRIVATE_ORIGINS: "${DAWARICH_PRIVATE_ORIGINS:-}"
   # Webhook (Gotify, Home Assistant, n8n) and ntfy targets on your own
   # network, comma-separated exact origins (e.g. "https://gotify.example.com,
   # http://ntfy.lan:8080"). Without it a target that resolves to a private
@@ -244,6 +258,11 @@ x-healthlog-env: &healthlog_env
   # the coordinate lookups off a third party.
   OPENMETEO_BASE_URL: "${OPENMETEO_BASE_URL:-}"
   OPENMETEO_GEOCODING_URL: "${OPENMETEO_GEOCODING_URL:-}"
+  # Air quality, pollen and UV (CAMS via Open-Meteo). Same hosted default and
+  # self-host option as above; ENVIRONMENT_AIR_QUALITY_DISABLED=1 stops the
+  # air-quality requests for the whole instance.
+  OPENMETEO_AIR_QUALITY_URL: "${OPENMETEO_AIR_QUALITY_URL:-}"
+  ENVIRONMENT_AIR_QUALITY_DISABLED: "${ENVIRONMENT_AIR_QUALITY_DISABLED:-}"
   # OIDC SSO login (self-hosted IdP: Authentik/Keycloak/Authelia/etc).
   # All three of ISSUER_URL/CLIENT_ID/CLIENT_SECRET together enable the
   # "Sign in with SSO" button; set none to leave it disabled. OIDC_ONLY
@@ -322,6 +341,11 @@ x-healthlog-env: &healthlog_env
   # (the `environment:` block is a whitelist). See
   # docs/integrations/ai-providers.md.
   DOCUMENT_AI_LIMIT_PER_HOUR: "${DOCUMENT_AI_LIMIT_PER_HOUR:-}"
+  # Minimum hours between two status-card regenerations after a sync
+  # (optional; default 6, whole hours 1-48; hand entries keep one hour). The
+  # value under Admin > Coach wins. Listed here so an operator value in .env
+  # reaches the container. See docs/integrations/ai-providers.md.
+  AI_SYNC_REGEN_GAP_HOURS: "${AI_SYNC_REGEN_GAP_HOURS:-}"
   # Hourly upload ceiling for each narrow document-upload token (a Paperless
   # workflow, the import script; optional; default 120, clamped 1-1000).
   # Uploads from the web app and the phone keep their own bucket. Listed here
@@ -389,6 +413,13 @@ x-healthlog-env: &healthlog_env
   LOG_SAMPLE_RATE: "${LOG_SAMPLE_RATE:-}"
   LOG_SLOW_THRESHOLD_MS: "${LOG_SLOW_THRESHOLD_MS:-}"
   LOG_INCLUDE_STACK: "${LOG_INCLUDE_STACK:-}"
+  # Heap diagnostics, off by default. HEALTHLOG_HEAP_SNAPSHOT=1 writes ONE
+  # heap snapshot the first time the heap reaches 85 % of its limit, into
+  # HEALTHLOG_DIAG_DIR (default /tmp inside the container). A snapshot holds
+  # decrypted health data and keys: turn it on only to chase a crash, then
+  # delete the file. See docs/ops/heap-diagnostics.md.
+  HEALTHLOG_HEAP_SNAPSHOT: "${HEALTHLOG_HEAP_SNAPSHOT:-}"
+  HEALTHLOG_DIAG_DIR: "${HEALTHLOG_DIAG_DIR:-}"
   # Optional log shipping to a Loki instance. Set LOKI_ENDPOINT to the base
   # URL or the full push URL to turn it on; a Loki on your own network works.
   # The username/password pair is only needed when your Loki is behind basic
@@ -472,20 +503,39 @@ services:
     # workload can grow large enough to starve Postgres on a shared host.
     # Node sizes its heap from this limit: 1g gives a 524 MB heap, which a
     # long-used account fills in normal operation, so garbage collection
-    # stalls requests for seconds and a weekly backup can crash the process.
-    # 1536m gives 792 MB. On a host with 2 GB or less, lower it with
-    # APP_MEMORY_LIMIT in .env; on a busy instance, raise it.
+    # stalls requests for seconds. 1536m gives 792 MB and is the supported
+    # floor (host: 3 GB RAM, 4 GB recommended). Below it the boot log, the
+    # support report and Admin > System status say so. On a busy instance,
+    # raise it with APP_MEMORY_LIMIT in .env; do not lower it.
     mem_limit: "${APP_MEMORY_LIMIT:-1536m}"
     healthcheck:
       test:
         [
           "CMD-SHELL",
-          "wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1",
+          "wget --no-verbose --tries=1 --timeout=4 --spider http://127.0.0.1:3000/api/health || exit 1",
         ]
       interval: 30s
       timeout: 5s
-      retries: 3
-      start_period: 30s
+      # Five misses in a row, two and a half minutes, before "unhealthy". The
+      # probe gives the database two seconds to answer SELECT 1 and says 503
+      # past that, so a boot storm that saturates the pool for a minute after
+      # the start period (backfills, a restore, another tenant's import) costs
+      # a probe or two, not the container's health and the proxy's routing.
+      # wget's own 4 s timeout ends the request inside Docker's 5 s, so a
+      # stalled connection reads as one clean miss rather than a killed probe.
+      # A database that stays away for 2.5 minutes is a real outage and shows.
+      retries: 5
+      # The entrypoint applies migrations before the server listens. A
+      # migration that waits out a held lock retries for up to about eight
+      # minutes (docs/ops/deploy.md), and failed probes in that time must not
+      # read as a dead container. The first probe that answers still ends
+      # the start period, so a normal boot is healthy within 30 seconds of
+      # listening. After it listens, the pg-boss worker starts in the
+      # background and /api/health answers 503 with reason "starting" until it
+      # is up (10–60 s under load, reported as "starting" for at most five
+      # minutes); inside the start period those probes do not count, so a slow
+      # worker start cannot mark the container unhealthy.
+      start_period: 10m
 
   # Optional dedicated worker container — uncomment + set
   # HEALTHLOG_PROCESS_TYPE=web on `app` to split the deployment.
@@ -533,6 +583,21 @@ services:
     # (concrete pin, active watch) from being dropped.
     image: postgres:16.15-alpine
     container_name: healthlog-db
+    # Loads pg_stat_statements so slow queries can be found from measurements
+    # instead of guesses. Loading the library only collects statistics; the
+    # view appears after a one-time `CREATE EXTENSION pg_stat_statements;`
+    # (docs/ops/query-statistics.md). Changing this line restarts the
+    # database once on the next `compose up`.
+    command:
+      - postgres
+      - -c
+      - shared_preload_libraries=pg_stat_statements
+      - -c
+      - pg_stat_statements.track=top
+    # Docker gives a container 64 MB of /dev/shm by default. Postgres keeps
+    # the shared memory of parallel queries and parallel maintenance there,
+    # and a larger plan fails with "could not resize shared memory segment".
+    shm_size: 256mb
     # cap_drop: [ALL] is deliberately NOT applied here (unlike `app`): the
     # official Postgres entrypoint starts as root, chowns the data
     # directory, and drops privileges to the `postgres` user itself, which

docker-entrypoint.sh

@@ -85,9 +85,15 @@ done
 echo "HealthLog: Database is reachable."
 
 # ── Run Prisma migrations ────────────────────────────────────
+# Say how many migrations this image is about to apply, with a reminder to
+# back up first. Reporting only: it never stops the boot.
+node scripts/pending-migrations.mjs || true
+# `migrate-deploy.mjs` runs `prisma migrate deploy` and retries only a
+# migration that timed out on a lock and is marked safe to re-run; any other
+# failure stops the boot with Prisma's exit code (docs/ops/deploy.md).
 echo "HealthLog: Running database migrations..."
 NODE_PATH=/opt/prisma-cli/node_modules \
-  node /opt/prisma-cli/node_modules/prisma/build/index.js migrate deploy
+  node scripts/migrate-deploy.mjs
 echo "HealthLog: Migrations complete."
 
 # ── Start application ────────────────────────────────────────

docs/README.md

@@ -33,7 +33,14 @@ notes, and machine-readable specs that ship alongside the source:
   three access levels, the eight sections a grant can be narrowed to,
   managed profiles for somebody with no login and the guardians who look
   after them, what revocation does and does not undo, and which trust
-  properties of the instance are unchanged by any of it.
+  properties of the instance are unchanged by any of it. And
+  [`self-hosting/support.md`](./self-hosting/support.md) — reporting a
+  problem: error ids, the support info every account can copy, the
+  operator's redacted support report, and finding an error in the admin log.
+- [`using/`](./using/) — notes on using the app that sit close to the
+  code. [`using/search.md`](./using/search.md) covers the command palette's
+  record search: opening it, what it finds, how matching works, and its
+  limits on very large and shared records.
 - [`migration/`](./migration/) — migration notes. Currently only
   v1.3 to v1.4; later releases are covered by `CHANGELOG.md` and
   <https://docs.healthlog.dev>.
@@ -49,7 +56,11 @@ notes, and machine-readable specs that ship alongside the source:
   — the iOS submission gate.
 - [`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.
+- [`contributing/ui-standards.md`](./contributing/ui-standards.md) — the
+  binding UI standards: card anatomy, spacing, text colour, tokens and
+  which primitive to use where. Read before touching any surface.
+- [`ui-guidelines.md`](./ui-guidelines.md) — UI / a11y house style; where
+  it disagrees with the UI standards, the standards win.
 
 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

docs/contributing/ui-standards.md

@@ -0,0 +1,185 @@
+# UI standards
+
+The binding reference for building or touching any surface of the web app. The rules are derived from the primitives' own contracts (`src/components/ui/card.tsx`, `tile-header.tsx`, `page-header.tsx`, `settings/_card-header.tsx`, `layout/auth-shell.tsx`) and from a review of every surface against them. When a rule here conflicts with an existing file, the file is drift: fix it when you touch it, don't copy it. Where an older code comment or [`docs/ui-guidelines.md`](../ui-guidelines.md) says otherwise, this document wins. A deviation needs a written reason in the pull request.
+
+---
+
+## 1. Card anatomy
+
+**The Card is gap-based, not padding-based** (`src/components/ui/card.tsx:24`): `flex flex-col gap-4 rounded-xl border py-4 md:gap-6 md:py-6`; header/content/footer carry `px-4 md:px-6`. The header→body distance comes from the **parent flex gap**, never from slot padding.
+
+- FORBIDDEN: `pb-*` on `CardHeader`, `pt-*` on `CardContent`. Under the gap model these add on top of the gap (or are no-ops) and invert their intent. Want a tighter card? Override the gap on the Card itself: `<Card className="gap-2">`.
+- Two densities, nothing else:
+  - `default`: Card as shipped: `py-4 md:py-6`, `gap-4 md:gap-6`.
+  - `compact`: `<Card density="compact">` (stat strips, assessment blocks, small tiles); resolves to `gap-2 py-3 md:gap-2 md:py-4`. Never spell it as a class list: the hand-written `gap-2 py-3 md:py-4` kept the base `md:gap-6` and opened 24 px on desktop (v1.43.8; `card-density.test.tsx` refuses the class list on a Card).
+  - No `md:py-5` half-steps.
+- Radius: cards are `rounded-xl` (tracks `--radius`). `rounded-md` = controls, `rounded-lg` = inner tiles, `rounded-full` = pills. `rounded-2xl` only as a deliberately marked identity surface (Coach hero/input).
+- Hand-rolled `bg-card … border … p-N` shells are legacy. New surfaces compose `<Card>` (or `SettingsCard` in Settings). If a hand-rolled shell must exist, its padding is exactly `p-4 md:p-6` or `p-3` (dense tile), never `p-5`, never a static `p-6`, never a `sm:` step (`SettingsCard`'s docblock explains why the breakpoint is `md:`).
+- **Insights overview sections use `InsightSectionCard`** (`src/components/insights/insight-section-card.tsx`). It composes `<Card>`, so the frame is the card contract, and pins the section's inner rhythm at one step (`gap-3`); the six hand-rolled copies it replaced had drifted to three different rhythms in the same column. A section whose body is an edge-to-edge divided list (rows owning their own inset) passes `flush`; everything else takes the padded body. Do not hand-roll a section shell beside it.
+- **The dashboard/insights hero band is a sanctioned identity surface.** Its translucent `bg-card/65 … backdrop-blur-sm` tiles are deliberate, not drift: the band reads as one glass surface behind the page's opening statement. It stays out of the shell sweep. Everything below the band is a plain card.
+
+### Header patterns; exactly three, pick by surface
+
+| Surface                            | Primitive                                                           | Contract                                                                                                                                                        |
+| ---------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Page title                         | `PageHeader` (`ui/page-header.tsx`)                                 | H1 `text-2xl font-bold tracking-tight`, description `text-muted-foreground text-sm`, `space-y-1.5`, **no icon beside the H1**, optional backLink + actions slot |
+| Settings card                      | `SettingsCard` + `SettingsCardHeader` (`settings/_card-header.tsx`) | icon `text-muted-foreground h-5 w-5`, title `h2 text-lg font-semibold`, status slot top-right, description muted below                                          |
+| Insights / dashboard / module tile | `Card` + `TileHeader` (`insights/tile-header.tsx`)                  | icon **`text-foreground` `h-5 w-5 shrink-0`**, title `CardTitle text-base`, `flex items-center gap-2`, optional `right` slot                                    |
+
+**Icon colour rule (both header contracts):** header icons are `text-foreground` (tiles) or `text-muted-foreground` (settings). Never `text-primary`, `text-info`, or any accent; primary/purple stays reserved for actions and highlight states. Pass the Lucide component (`icon={Target}`), never a pre-sized node; the primitive owns size and colour.
+
+The gaps this section used to list are closed: `TileHeader` carries a `size="sm"` variant for compact tiles and an optional `icon` for icon-less headers, and `InsightSectionCard` is the overview container mirroring `SettingsCard`. Use them; do not invent a fourth header language.
+
+## 2. Spacing scale
+
+> **Scroll height is shell-owned.** Only `AuthShell` owns the scroll container's height and bottom padding (`pb-20` wrapper + `<md` bottom-nav clearance on `<main>`). Pages/sections never add viewport-height reserves (`min-h-dvh`, `min-h-[calc(100dvh-…)]`), `h-full` chains, or bottom gutters inside the scrolling `<main>`; nested reserves stack on the shell budget and scroll past the last card. One sanctioned exception: the settings-shell grid floor (budget-derived, documented; retune it when shell paddings change). Lists that need their own scrolling use `max-h-* overflow-y-auto overscroll-contain`. Guard: `e2e/settings-overscroll.spec.ts`.
+
+- **Allowed steps:** `1 / 1.5 / 2 / 2.5 / 3 / 3.5 / 4 / 6 / 8 / 10`. `2.5` and `3.5` are allowed: the medication card's rhythm is built on them, and the in-between steps earn their keep in dense card interiors. `5` (20 px), as in `py-5` or `p-5`, is not allowed; replace it when you touch a file that still has it. `7` (28 px) is not allowed either: it was the old Settings and Admin `pl-7` body gutter, which is gone (§13).
+- **Page frame:** exactly one authenticated container, owned by `AuthShell` (`layout/auth-shell.tsx:318`): `mx-auto max-w-screen-xl px-4 pt-6 pb-20 md:px-6`. Never re-implement it in a page; full-bleed pages opt out via a shell flag, not negative margins. Prose pages (about/privacy/legal): `mx-auto max-w-3xl px-4 py-8 md:px-6 md:py-12`.
+- **Page rhythm:** root of every page is `space-y-6`. Grouped card sections: `space-y-10` between groups, `space-y-4` inside a group (notifications/integrations pattern). Insights sub-pages join `space-y-6`.
+- **Left reading edge:** page-level text (H1, explainer, section headings) sits at the container edge. Only surfaces that paint a visible border/background may inset their content (`px-4 md:px-6`). A block without a border must not carry horizontal padding.
+- **Grids:** grids **of** cards/tiles = `gap-4`; value read-outs **inside** one card = `gap-x-3 gap-y-2`; form field grids = `gap-4`.
+- **Anchors:** `scroll-mt-28`, single token (31-to-1 in the tree already).
+
+## 3. Text colour rules
+
+The base tokens are AA-tuned in both themes (`--muted-foreground`: 5.0–6.4:1, documented in `globals.css`). The system is two tiers:
+
+- **`text-foreground` = content.** Everything the user came to read: values, chart labels the reading depends on, AI narrative bodies, consent/safety copy, and **all user-entered data** (notes, journal text, free-text fields). User data is never muted.
+- **`text-muted-foreground` = meta.** Timestamps, units, provenance, counts, placeholders, one-sentence descriptions under a heading. Heading-in-foreground + short-description-in-muted is the app-wide convention (CardDescription, PageHeader, SettingsCardHeader); keep it; do not "fix" it to foreground.
+- **Description slots hold exactly one meta sentence, guideline ≤ 120 characters.** One sentence, one full stop, no paragraph stack. 120 characters is the guideline, not a hard cut: it is the p75 of the descriptions that already read well, and a description that needs 130 characters to stay true is fine while a two-sentence one never is. Multi-sentence explainer prose goes in the body as `<p className="text-sm">` (foreground), not into a muted description slot; if the body would not carry it either, the sentence is not needed on the surface at all and belongs in the docs. The description slot renders a single text run; it deliberately owns no vertical rhythm of its own, so a call site cannot stack paragraphs into it.
+- **One statement, one string.** A section's page subtitle and its card description must not say the same thing twice on one screen. When a section owns a single card, the subtitle carries the statement and the card header drops its description. Same rule for a field label and its field description: the label names the field, the description adds what the label cannot.
+- **FORBIDDEN: opacity modifiers on muted text.** `text-muted-foreground/70` ≈ 2.9–3.9:1 and `/80` ≈ 3.4–4.2:1, below AA, and they silently undo the token tuning. Full `text-muted-foreground` IS the de-emphasis tier; a further tier is expressed via size/weight, never via alpha. `text-foreground/80` is safe (≥6.7:1) and allowed. `/60` is icon-only (3:1 graphics floor).
+- **Disabled look:** `opacity-50` on the container + `aria-disabled`, not colour dimming on the text node.
+- **Size floor:** muted text is never smaller than `text-xs`. Below that, the one legal step is the `text-2xs` token (0.6875rem, minted in `globals.css`) and it is for chips, badges, and tabular-nums micro-labels with verified contrast, never for muted body or meta text. Arbitrary sizes (`text-[0.65rem]`, `text-[11px]`) are drift; chart-axis `text-[10px]`/`text-[11px]` stays tolerated as documented.
+- **Status colours** carry meaning, not decoration: `text-success` / `text-warning` / `text-info` / `text-destructive` (+ `bg-*/10` washes). All four are AA-retuned per theme.
+
+## 4. Colour token rules
+
+- **Semantic tokens only** in components: `--foreground/--muted-foreground/--primary/--success/--warning/--info/--destructive/--chart-1..5/--border/--card`. The light theme remaps them wholesale; anything outside the token layer is invisible to a retune.
+- **No raw `dracula-*` utilities in new code.** Only `--dracula-yellow` has a light override; `text-dracula-green` on a light card is 1.4:1. Status meaning → semantic token; brand identity (Coach gradient) → a named `--brand-*` token with per-theme values.
+- **No hex in JS props.** Chart colours are passed as `var(--token)` strings, never `color="#22c55e"`. Data series use the `--chart-1..5` tokens (`color="var(--chart-2)"`); status tokens (`--success`, `--warning`, `--destructive`, `--info`) only where the colour carries meaning, such as a target band, time in range or a mood scale (v1.42). Recharts `stroke`/`fill` likewise. This is the known lint blind spot; review for it explicitly until the rule covers it.
+- **No arbitrary-value colours** (`bg-[#…]`, `text-[oklch(…)]`).
+- Exemptions (documented at the definition site): `global-error.tsx` (renders without the stylesheet), the `themeColor` meta, the QR quiet-zone `bg-white`.
+
+## 5. Typography scale
+
+| Tier                     | Classes                                                             | Where                                                           |
+| ------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------- |
+| App H1                   | `text-2xl font-bold tracking-tight`                                 | every module page, via `PageHeader`: weight is **bold**, always |
+| Settings card title      | `text-lg font-semibold`                                             | via `SettingsCardHeader`                                        |
+| Tile title               | `text-base` on `CardTitle` (`font-semibold` from the primitive)     | via `TileHeader`                                                |
+| Chip / badge micro-label | `text-2xs` (11 px)                                                  | `TagChip`, `Badge`, tabular-nums counters: never muted prose    |
+| Section label            | `text-xs font-medium uppercase tracking-wide text-muted-foreground` | list group headings                                             |
+| Body                     | `text-sm` (foreground)                                              | default content                                                 |
+| Meta                     | `text-xs text-muted-foreground`                                     | timestamps, units, hints: the floor                             |
+| Prose-page H1            | `text-3xl md:text-4xl font-bold`                                    | about/privacy/landing tier only                                 |
+
+No `text-[9px]`. No off-scale sizes (`text-[28px]`); round to the neighbouring step. Icon sizes come from the five-step vocabulary `size-3 / 3.5 / 4 / 5 / 6`; prefer `size-N` over `h-N w-N` (identical CSS, one spelling).
+
+## 6. Component mapping; when to use which primitive
+
+| Situation                                                                                                                   | Use                                                                                                                                                                                                                                                                                                                                                                                                        | Never                                                                                                                                                                                                 |
+| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Page title + description + actions                                                                                          | `PageHeader`: `headingRef` + `focusable` for a title that takes focus after navigation, `titleAccessory` for a glyph or badge beside the H1 (outside its name)                                                                                                                                                                                                                                             | hand-rolled `text-2xl font-bold` H1 blocks (`page-header-h1-guard.test.ts` lists where another H1 is the point: heroes, sign-in, error and prose pages, first-run steps)                              |
+| A second copy of the page title in the same shell (mobile above the nav strip, desktop inside the grid)                     | `PageHeader headingAs="div"`: one real `<h1>`, one `role="heading" aria-level={1}`                                                                                                                                                                                                                                                                                                                         | a hand-rolled `role="heading"` div beside a hand-rolled `<h1>`                                                                                                                                        |
+| Settings card                                                                                                               | `SettingsCard` + `SettingsCardHeader` + `FieldGroup`                                                                                                                                                                                                                                                                                                                                                       | raw `Card` in Settings sections                                                                                                                                                                       |
+| Heading above a group of cards (Insights overview, Settings groups)                                                         | `SectionHeading` (`ui/section-heading.tsx`)                                                                                                                                                                                                                                                                                                                                                                | a `SettingsCardHeader` with no card under it, or a hand-rolled `h2`                                                                                                                                   |
+| Action row in a Settings / Admin card                                                                                       | `SettingsCardActions`                                                                                                                                                                                                                                                                                                                                                                                      | a hand-rolled `flex justify-end gap-2` div                                                                                                                                                            |
+| Admin mini stat tile                                                                                                        | `StatTile` (`admin/_stat-tile.tsx`)                                                                                                                                                                                                                                                                                                                                                                        | a hand-rolled `bg-muted/NN rounded-lg p-3` box                                                                                                                                                        |
+| Insights/dashboard tile                                                                                                     | `Card` + `TileHeader`                                                                                                                                                                                                                                                                                                                                                                                      | hand-rolled icon+title rows, `bg-card rounded-xl border p-4` divs                                                                                                                                     |
+| Insights overview section                                                                                                   | `InsightSectionCard`                                                                                                                                                                                                                                                                                                                                                                                       | a hand-rolled section shell beside it                                                                                                                                                                 |
+| Neutral label chip on a card header                                                                                         | `TagChip`                                                                                                                                                                                                                                                                                                                                                                                                  | a hand-copied `bg-muted … rounded-full` literal, or a `Badge` (that means status)                                                                                                                     |
+| Read-query failed (`isError` on a primary / list surface)                                                                   | `QueryErrorCard` with `error={query.error}` and `onRetry={refetch}`                                                                                                                                                                                                                                                                                                                                        | bare `text-destructive` paragraphs without retry; a card without `error`                                                                                                                              |
+| Read-query failed inside a dense metric strip, tile or supplementary block, where the tall card would dominate the geometry | `QueryErrorRow` with `error={query.error}` and `onRetry={refetch}`                                                                                                                                                                                                                                                                                                                                         | a hand-rolled row; a third read-failure primitive (`ReadFailureRow` was one and is gone)                                                                                                              |
+| Read-query failed inside a card that already has its frame and header (a tile body, a settings card section)                | `QueryErrorRow inset`: keeps the card and its title, no second border                                                                                                                                                                                                                                                                                                                                      | `QueryErrorCard` inside a card (card in card); replacing the card and its header with the error                                                                                                       |
+| Read-query failed on a chart body                                                                                           | `ChartErrorState` with `error={query.error}`: same decision as the other two                                                                                                                                                                                                                                                                                                                               | either of the above                                                                                                                                                                                   |
+| A list the server capped (`meta.truncated`)                                                                                 | `ListCapNotice` under the list, read through `apiGetList` / `apiPostList`                                                                                                                                                                                                                                                                                                                                  | a hand-written "showing the latest N" line; reading `data.truncated`                                                                                                                                  |
+| Mutation error inside a form/sheet                                                                                          | inline `role="alert"` text                                                                                                                                                                                                                                                                                                                                                                                 | `QueryErrorCard` (wrong shape)                                                                                                                                                                        |
+| Honest no-data state                                                                                                        | `EmptyState`                                                                                                                                                                                                                                                                                                                                                                                               | reusing error copy: a failed query must never fall through to "no data yet"                                                                                                                           |
+| Modal reachable on mobile                                                                                                   | `ResponsiveSheet` (bottom sheet on phones)                                                                                                                                                                                                                                                                                                                                                                 | raw `Dialog` (admin/desktop-only surfaces excepted)                                                                                                                                                   |
+| A sheet from the bottom edge (phones)                                                                                       | `<SheetContent side="bottom">` or `ResponsiveSheet`, both of which render `BottomSheetContent` (`ui/bottom-sheet.tsx`): grip, swipe to close, X on the title row. `preview="58dvh"` for a sheet that opens part-way and pulls up to 90 dvh (its footer `data-sheet-footer`, its scroll body `data-sheet-body`); `draggable={false}` only for a sheet that fills the window                                 | a hand-rolled grab handle or drag; a `fixed bottom-0` panel standing in for a sheet                                                                                                                   |
+| Date / time entry                                                                                                           | `DateField` / `TimeField` / `DateTimeField`                                                                                                                                                                                                                                                                                                                                                                | native `type="date                                                                                                                                                                                    | time | datetime-local"` inputs (browser-locale trap, v1.25.4) |
+| Small text action inside a line (Open schedule, Select all, View all, Retry, Learn more)                                    | `InlineAction` (`ui/inline-action.tsx`): tone `primary` / `muted` / `foreground`, size `xs` / `sm`, `asChild` for a `Link`; owns the focus ring and `pointer-coarse:min-h-11`                                                                                                                                                                                                                              | a hand-rolled underlined `<button>` / `<Link>` (`inline-action-guard.test.ts`)                                                                                                                        |
+| Mutually exclusive choice on one track (range, zoom, cards vs table, recent vs all)                                         | `Segmented` (`ui/segmented.tsx`): no track, the chosen segment filled in primary (the chart tabs' look; a muted track with a raised segment was tried in 1.43.8 and dropped in 1.43.10 as too heavy); `mode="radio"` (default, roving focus) or `"toggle"` (view switches, form sheets), `iconOnly` for icon segments, `size="sm"` for range rows in a chart header; 44 px per segment on a coarse pointer | a row of ghost/secondary Buttons, a fifth segmented variant (`segmented.test.tsx` holds the definition to one module)                                                                                 |
+| A grade beside a reading (confidence, score gain, band, lab range flag)                                                     | `ScorePill` (`ui/score-pill.tsx`): tone `success` / `info` / `warning` / `destructive` / `neutral`, `numeric` for figures; `CONFIDENCE_TONE` maps both confidence scales                                                                                                                                                                                                                                   | a hand-rolled `rounded-full px-2 py-0.5 text-xs bg-*/15` chip (`score-pill-guard.test.ts`); `TagChip` (neutral label) and `Badge` (connection/account state) stay what they are                       |
+| "This vital on these days vs those days" board                                                                              | `MetricCrosstab` (`insights/metric-crosstab.tsx`): caller formats the numbers, the board owns row, neutral signed delta, confidence chip, dismissal                                                                                                                                                                                                                                                        | a fourth copy of the crosstab list                                                                                                                                                                    |
+| A trend / stat tile in a grid (KPI strip, derived tiles, their skeletons and building states)                               | `TrendTile` (`ui/trend-tile.tsx`)                                                                                                                                                                                                                                                                                                                                                                          | the hand-spelled `bg-card border-border … p-4 md:p-6` frame                                                                                                                                           |
+| A whole card that points to another page                                                                                    | `CrossLinkCard` (`insights/cross-link-card.tsx`)                                                                                                                                                                                                                                                                                                                                                           | a `Link` styled as a card                                                                                                                                                                             |
+| Picking documents from the vault                                                                                            | `DocumentPickerSheet` (`documents/document-picker-sheet.tsx`); the caller decides what a toggle means                                                                                                                                                                                                                                                                                                      | a copy of the search + list sheet                                                                                                                                                                     |
+| A field / chart / list with nothing to show                                                                                 | `EmptyState variant="plain" size="compact"` (with `action` for the next step), `ChartEmptyState` on a chart body                                                                                                                                                                                                                                                                                           | a hand-written muted paragraph (`empty-state-ratchet.test.ts` freezes each remaining site as `path: key`, and a new one fails; the frozen ones are field-level "not recorded" lines and editor hints) |
+| A number shown to a person                                                                                                  | `useFormatters()` (`fmt.number` / `integer` / `percent`), `formatBytes(bytes, locale)` from `lib/format/bytes`                                                                                                                                                                                                                                                                                             | `toFixed()`, a locale-less `toLocaleString()`, `String(a / b)` (`healthlog/no-unlocalised-decimal`)                                                                                                   |
+| Numeric range entry (0–10 self-rating, any bounded scale)                                                                   | `Slider` / `SliderField` (`ui/slider.tsx`): `SliderField` when the scale has anchors, which is nearly always                                                                                                                                                                                                                                                                                               | a hand-rolled `input type="range"`, or an 11-button radiogroup (eleven 32 px targets overflow a 390 px viewport)                                                                                      |
+| Outbound fetch                                                                                                              | `safeFetch`                                                                                                                                                                                                                                                                                                                                                                                                | raw `fetch(` (lint-enforced)                                                                                                                                                                          |
+| TanStack query keys                                                                                                         | `src/lib/query-keys/` factory                                                                                                                                                                                                                                                                                                                                                                              | bare arrays (lint-enforced)                                                                                                                                                                           |
+
+**What a failed read offers is decided by the primitive, never the call site.** `QueryErrorCard`, `QueryErrorRow` and `ChartErrorState` take the query's `error` (required) and branch on `readFailureKind` (`src/lib/api/read-failure.ts`). It reads `meta.errorCode` first and the status second, because every error envelope carries a code (`http.*` when the route names none): a step-up or re-proof code on a 401 is a failure with retry, not an ended session; an unknown code falls back to the status.
+
+- **Session ended** (a session code, or a 401 without a more specific one) → one sentence and a Sign in button (back to the current page). Never a silent blank.
+- **403, refused** → the surface's `refused` state if it has one, otherwise nothing. A refusal is an answer, not a failure; no retry.
+- **429, throttled** → one sentence that the read budget is spent, no retry (an immediate retry would only be refused again).
+- **anything else** → the surface's message with Retry.
+
+The `queryFn` hands the `ApiError` through untouched: no `try { … } catch { throw new Error(t(…)) }` around the fetch, the surface's sentence goes in through `message`. A call site does not inspect `error.status` around a read-failure primitive, and does not pass `error={null}`. `query-error-error-prop-guard.test.ts` enforces the prop and the untouched error at every site, `read-failure-markup-guard.test.ts` refuses hand-rolled failure markup next to a read hook. Error codes become sentences through `src/lib/i18n/translate-code.ts`, never through a `t(key) === key` probe at the call site (`translate-probe-guard.test.ts`).
+
+## 7. Enforcement
+
+Live, all at `error`: `healthlog/queryKey-factory`, `healthlog/safe-fetch-required`, `healthlog/api-fetch-required`, `healthlog/no-raw-palette-color` (palette + colour-shaped JS props + arbitrary values), `healthlog/no-dracula-utility`, `healthlog/spacing-scale` (`pt-`/`pb-` on `CardHeader`/`CardContent`, and the banned `5` step on a `bg-card` + `border` shell), `healthlog/no-raw-card-shell` (since v1.43.8: `bg-card` + `border` + `rounded-xl` on one literal under `src/components` / `src/app` outside `ui/`; the files where a shell is the point (shell primitives, the hero, popovers, the chart frame shared by chart/skeleton/error state, table frames, sign-in and first-run screens) are the rule's `allow` list in `eslint.config.mjs`, each with its reason, no inline escape), `healthlog/no-unlocalised-decimal` (since v1.43.8; reasoned `eslint-disable-next-line` only, for SVG coordinates and number-input values).
+
+Structural tests (since v1.43.8): `inline-action-guard`, `score-pill-guard`, `empty-state-ratchet`, `page-header-h1-guard`, `card-density`, `segmented` (one definition), `client-route-zod-guard` (documents and Coach ship no zod in their static client graph).
+
+Planned (until it lands, this is a review-checklist item):
+
+1. A tile-header icon-colour check (`text-muted-foreground` / `text-primary` on a glyph inside a `CardTitle` or tile-header row).
+
+**PR checklist for any UI change:** both themes checked visually · no new `dracula-*`/hex/opacity-muted · headers via a primitive · card gap untouched by slot padding · `isError` → `QueryErrorCard` or `QueryErrorRow` by surface, with `error` · mobile modal = `ResponsiveSheet` · `pnpm format` + `pnpm lint` + `pnpm typecheck` green.
+
+---
+
+## 8. Insights left reading edge; two edges, one gutter
+
+Every text run on an Insights surface starts on one of exactly two vertical lines, and card headings offset from the card line by exactly one gutter:
+
+- **Edge A, reading edge (x = 0):** the AuthShell container inner edge (`px-4 md:px-6`). All **borderless page-level blocks** start here with **no extra horizontal padding**: the sub-page `<h1>` + explainer (`SubPageShell`), and every `SectionHeading`. If a sub-page heading must track the card body instead, it uses the responsive card inset `px-4 md:px-6`, **never** a flat `px-6` (that sat 8 px right of the card body on mobile and reopened the heading-vs-body step).
+- **Edge B, card edge (x = card `px`):** every `<Card>` insets header **and** body to `px-4 md:px-6`. No card inset with a static `p-5` (banned) or a `p-4`-only/`sm:` shell; header and body share one inset so the body left edge is identical on every tile.
+- **Heading gutter (Edge B + gutter):** every card heading routes through `TileHeader`. The icon's left edge sits on Edge B; the heading **text** sits at Edge B + gutter (icon box + `gap-2` = 28 px at `size="default"`, 24 px at `size="sm"`). Compact tiles use `TileHeader size="sm"`, never a bespoke `h-4` icon row. Tile header icons are `text-foreground` (never muted, never an accent) at both sizes.
+
+Forbidden on any Insights card: a hand-rolled icon+title row, a card title centred by default, an icon box outside `TileHeader`'s h-5/h-4 vocabulary, and a horizontal inset other than `px-4 md:px-6` (or the sanctioned `p-3` dense inner tile). Verify at 390 px: every card body shares one left x; every card heading text shares a second x one gutter to the right; the `<h1>` + any `SectionHeading` sit on the container edge.
+
+## 9. One scroll floor; sub-shells never re-declare bottom-space
+
+Reinforces §2's "scroll height is shell-owned". Only `AuthShell` owns the scroll container's bottom padding and any viewport-height reserve: the `<main>` clears the mobile bottom-nav (`pb-[calc(4rem+safe-area)]`) and its wrapper clears the Coach FAB (`pb-20`). **No page, section, or sub-shell** adds a `min-h-[calc(100dvh-…)]` / `min-h-dvh` reserve or a `pb-*` bottom gutter inside the scrolling `<main>`; a nested reserve stacks on the shell budget and scrolls past the last card.
+
+A two-column sub-shell that needs a "don't jump while loading" floor derives it from **one shared source**: `SUB_SHELL_GRID_FLOOR` (`src/components/layout/shell-metrics.ts`); applied to the **grid** (not a column), so the `1fr` content row stretches to fill without over-shooting. It never re-declares the floor per-shell (`AdminShell` drifting to a stale 12rem column reserve is exactly how this recurred). Guard: `e2e/settings-overscroll.spec.ts` covers Settings **and** Admin and measures against each element's content-box bottom, so a redundant sub-shell `pb-*` fails instead of inflating the allowed budget.
+
+## 10. Navigation; utilities live only in the user menu
+
+Settings + Notifications are **account utilities, not feature destinations**. They live ONLY in the user/avatar menu (mobile top-bar `DropdownMenu`; desktop sidebar avatar menu, with Settings additionally in the sidebar footer). The mobile "More" overflow hub carries **feature destinations only** (Measurements, Mood, Cycle, Labs, Coach, …), never Settings or Notifications. The hub is `mobileMoreHubDestinations()` = `visibleNavDestinations` minus the primary slots (`/`, `/medications`, `/insights`); it does **not** append the utility tail. `NAV_UTILITY_DESTINATIONS` (`visibleUtilityDestinations()`) feeds the sidebar footer + user menus, not the mobile overflow. Never surface a utility in two menus reachable from the same screen.
+
+## 11. Inline action row; the PageHeader pattern
+
+A title/sentence with an adjacent action is one row, not a wrapping stack: `flex items-start justify-between gap-3`, the text `min-w-0 flex-1` (wraps internally), the action `shrink-0` (stays beside the text, never pushed to its own line). This is the canonical `PageHeader` / `TileHeader` (`right` slot) shape; reuse it (e.g. the dashboard-hero verdict + CTA) instead of a one-off `flex-wrap` row whose `gap-y-*` drops the action below on a full sentence. Keep the mobile tap-target floor (`min-h-11 sm:min-h-9`).
+
+## 12. The action row; one place, one shape
+
+A card's actions live in **one** row, and that row is the **last thing in the card**. Reference implementations: `src/components/settings/score-section.tsx`, `src/components/settings/coach-prefs-section.tsx`.
+
+- **Use `SettingsCardActions`** (`settings/_card-actions.tsx`). It owns the row: `flex flex-wrap items-center gap-2`, `justify-end` by default. Never hand-roll a `flex justify-end gap-2` div in a Settings or Admin card.
+- **Primary action:** last child of the row (rightmost), `variant` default, `size="sm"` + `min-h-11`. One per card.
+- **Secondary action:** `outline`, before the primary in the same row. Cancel/reset are secondary, never `ghost` in the same row as a primary.
+- **Destructive card-wide action:** the same row, `variant="destructive"`. Never hand-tinted (`text-destructive border-destructive/30` on an `outline` is drift).
+- **Nothing follows the action row.** Status lines, result lists, and confirmations belong **above** it; a result set large enough to need its own frame becomes its own card or a collapsible.
+- **The header `status` slot carries status, not actions**; a badge, a pill, a switch. Not a primary, not a destructive, not a filter group. Filters get a toolbar row above the content.
+- **`outline` has exactly one meaning: secondary.** A card whose only actions are deep links out (privacy, about, export) has no primary; those links stay `outline size="sm"` and the row uses `align="start"`, because a navigation row reads with the text, not against it. That is the one documented exception, and `SettingsCardActions` spells it (`align="start"`).
+
+## 13. Settings + Admin card rhythm; owned by the container
+
+- **`SettingsCard` is gap-based**, like `Card`: `flex flex-col gap-4 p-4 md:p-6`. The header→body distance comes from the container's gap. A call site never adds `mt-4` to its first body child, never `mb-4` to the header, never `space-y-4` to the card. A denser card overrides the gap on the card itself (`className="gap-2"`), exactly as `Card` does.
+- **The body starts at the card edge.** The old `pl-7` gutter (icon box + `gap-2`) is abolished: it is off the scale in §2, it broke the moment two neighbouring cards disagreed, and it silently mis-aligned action rows against their own forms. Header text is offset from the card edge by the icon gutter; body content is not. This is the deliberate difference from §8's Insights gutter, where the tiles carry no body form.
+- **Group headings above a group of cards use `SectionHeading`** (`ui/section-heading.tsx`, the heading of the Insights overview, shared by every area), not a bare `SettingsCardHeader`. `text-base` on the group, `text-lg` on the card title: that step is what says which one labels which.
+- **Admin uses the Settings anatomy verbatim.** No admin-only card shell, no admin-only header, no admin-only mini tile; `SettingsCard`, `SettingsCardHeader`, `SettingsCardActions`, `StatTile` (`admin/_stat-tile.tsx`) are the whole vocabulary.
+- **A loading state paints the card and its header.** A section that renders a bare spinner while loading and a card afterwards moves the page under the cursor. Reference: `admin/coach-feedback-section.tsx`.
+
+### Enforcement
+
+The `p-5` / `py-5` / `px-5` / `space-y-5` family does not occur in the app, and `healthlog/spacing-scale` runs at `error` over `src/components/**` and `src/app/**`, so the step cannot come back unnoticed. `no-raw-card-shell` is described in §7. The header icon colour (§1) has no lint rule; check it in review.

docs/integrations/ai-providers.md

@@ -431,6 +431,31 @@ many documents against a generous provider budget; lower it on a
 tight one. The 429 names the actual wait (the window is an hour) and
 carries the reset instant in `X-RateLimit-Reset`.
 
+`AI_SYNC_REGEN_GAP_HOURS` (default `6`, whole hours from 1 to 48) is
+the minimum time between two regenerations of a status card after a sync
+at the `standard` AI usage level. A watch or an integration delivers
+readings all day, and each delivery moves today's figures, so without a
+gap every touched card regenerated about once an hour. A reading entered
+by hand keeps a one-hour gap, so it is still narrated the same day. The
+value set under Admin > Coach (AI usage levels) wins over the environment.
+
+Each account runs at one of three AI usage levels, chosen under
+Settings > AI within the bounds the operator sets under Admin > Coach (the
+highest level allowed and the default for accounts without a choice):
+
+|                                 | `frugal`           | `standard`           | `full`               |
+| ------------------------------- | ------------------ | -------------------- | -------------------- |
+| Status cards after a sync       | at most once a day | the gap above        | hourly               |
+| Status cards after a hand entry | every 6 hours      | hourly               | hourly               |
+| Snapshot size (compact JSON)    | 10 000 characters  | 14 000               | 14 000               |
+| Background reasoning            | off                | job default          | job default          |
+| Daily briefing                  | short form         | full                 | full                 |
+| Automatic document reading      | on request only    | the account's switch | the account's switch |
+| Supplement label photo          | not offered        | offered              | offered              |
+
+The Coach is the same at every level. Settings shows an estimate of
+tokens per day for each level, scaled from the account's last seven days.
+
 `LABS_OCR_LIMIT_PER_HOUR` (default `6`, clamped to 1–1000) does the
 same for lab-report scans. The photo or PDF scan and the browser-OCR
 text scan share one bucket per user, and a scan that fails before the

docs/integrations/apple-health.md

@@ -120,6 +120,14 @@ The HK quantity types that map to HealthLog metric types live in
 mapped set (for example workout routes) is counted as unsupported and
 not stored.
 
+Heart-rate variability comes in two measures, and they stay two types.
+`HeartRateVariabilitySDNN` becomes `HEART_RATE_VARIABILITY`;
+`HeartRateVariabilityRMSSD`, which iOS and watchOS 27 added, becomes
+`HRV_RMSSD`, the same type WHOOP, Oura and Polar write. RMSSD readings
+up to 300 ms are accepted. When both arrive, the HRV page charts each on
+its own and the Coach reads them apart, because one is not a stand-in for
+the other.
+
 ### ECG archive safety, privacy, and idempotency
 
 ECG support is source-agnostic: if HealthKit includes a valid
@@ -284,6 +292,9 @@ Concrete consequences:
   source tag — the lowest rank — is reserved for legacy CSV/JSON
   imports that pre-date the Apple Health passthrough.
 
+RMSSD HRV has its own ladder, **WHOOP ≻ OURA ≻ POLAR ≻ APPLE_HEALTH**,
+separate from the SDNN one.
+
 Override per-user via Settings → Sources (`/settings/sources`).
 
 ## Failure modes

docs/integrations/blueprints/healthlog-room-climate.yaml

@@ -0,0 +1,97 @@
+# Push a room's CO2, temperature and humidity to HealthLog every few minutes.
+#
+# Use it for one room. The readings carry no room name, so a second room would
+# land in the same series, and a push in the same minute is refused (409).
+#
+# Needs the `healthlog_room_climate` rest_command from
+# docs/integrations/home-assistant.md ("Room climate") and a measurement
+# ingest token. Every sensor is optional; a sensor that reports `unknown`,
+# `unavailable` or a non-number is left out of that push, and a push with
+# nothing left is skipped. Temperatures in °F are converted to °C.
+blueprint:
+  name: HealthLog room climate
+  description: >-
+    Sends indoor CO2 (ppm), temperature (°C) and relative humidity (%) to
+    HealthLog through a measurement ingest token. HealthLog keeps each
+    reading and shows the day's mean, low and high.
+  domain: automation
+  homeassistant:
+    min_version: 2024.10.0
+  source_url: https://github.com/MBombeck/HealthLog/blob/main/docs/integrations/blueprints/healthlog-room-climate.yaml
+  input:
+    co2_sensor:
+      name: CO2 sensor
+      description: A sensor reporting carbon dioxide in ppm.
+      default: ""
+      selector:
+        entity:
+          domain: sensor
+          device_class: carbon_dioxide
+    temperature_sensor:
+      name: Temperature sensor
+      description: A sensor reporting the room temperature (°C or °F).
+      default: ""
+      selector:
+        entity:
+          domain: sensor
+          device_class: temperature
+    humidity_sensor:
+      name: Humidity sensor
+      description: A sensor reporting relative humidity in %.
+      default: ""
+      selector:
+        entity:
+          domain: sensor
+          device_class: humidity
+    interval_minutes:
+      name: Interval
+      description: >-
+        Minutes between pushes, on the hour and every interval after it.
+        15 is plenty for a daily picture.
+      default: "15"
+      selector:
+        select:
+          options: ["5", "10", "15", "20", "30", "60"]
+
+mode: single
+
+variables:
+  co2_sensor: !input co2_sensor
+  temperature_sensor: !input temperature_sensor
+  humidity_sensor: !input humidity_sensor
+  interval_minutes: !input interval_minutes
+  # A list of readings (Home Assistant keeps a rendered list a list).
+  readings: >-
+    {% set at = now().replace(second=0, microsecond=0).isoformat() %}
+    {% set ns = namespace(items=[]) %}
+    {% for type, entity in [
+      ('INDOOR_CO2', co2_sensor),
+      ('INDOOR_TEMPERATURE', temperature_sensor),
+      ('INDOOR_HUMIDITY', humidity_sensor)
+    ] %}
+      {% if entity and is_number(states(entity)) %}
+        {% set v = states(entity) | float %}
+        {% if type == 'INDOOR_TEMPERATURE'
+              and state_attr(entity, 'unit_of_measurement') == '°F' %}
+          {% set v = ((v - 32) * 5 / 9) | round(2) %}
+        {% endif %}
+        {% set ns.items = ns.items
+          + [{'type': type, 'value': v, 'measuredAt': at}] %}
+      {% endif %}
+    {% endfor %}
+    {{ ns.items }}
+
+triggers:
+  - trigger: time_pattern
+    minutes: "/5"
+
+conditions:
+  - condition: template
+    value_template: >-
+      {{ now().minute % (interval_minutes | int(15)) == 0
+         and readings | count > 0 }}
+
+actions:
+  - action: rest_command.healthlog_room_climate
+    data:
+      readings: "{{ readings }}"

docs/integrations/dawarich.md

@@ -0,0 +1,82 @@
+# Dawarich integration
+
+HealthLog can read daily movement context from a [Dawarich](https://dawarich.app)
+instance: how far you moved, how much of it by car or by train, how many places
+you visited, how long you were away from home, and whether a day was spent in
+another country. It is part of the Environment module and runs only while that
+module is on.
+
+HealthLog never stores a coordinate, a track, a place name or a visit. It reads
+the day summaries and keeps one row of numbers per day. The place list is read
+live when you pick your home and is not saved.
+
+## What is read
+
+Once a night (03:20 Europe/Berlin) HealthLog fetches the last seven days, ending
+yesterday. Connecting fetches the last 30 days. Each request carries your API
+key as `Authorization: Bearer <key>`.
+
+| Dawarich endpoint       | What HealthLog keeps                                                                   |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| `GET /api/v1/timeline`  | total distance, distance by car (`driving`), distance by train, places visited         |
+| `GET /api/v1/visits`    | minutes spent at your home place, to work out time away from home                      |
+| `GET /api/v1/residency` | the country of each day, sealed at rest, and whether it differs from your home country |
+| `GET /api/v1/places`    | nothing; the list is shown once so you can pick your home                              |
+| `GET /api/v1/users/me`  | nothing; used to check the key                                                         |
+
+Time away from home is the day's length minus the time a visit at your home
+place covers. Without a home place, or on a day without a single visit, it is
+left empty rather than shown as zero. Dawarich leaves out a mode that moved
+less than half a kilometre; HealthLog then reads that mode as zero for the day.
+
+Residency needs API access on a hosted Dawarich plan; a self-hosted instance
+has it. Without it there are no travel days, and everything else still works.
+Dawarich keys residency by UTC date, so on a day that crosses a border late in
+the evening the country can be the next morning's.
+
+## Connect
+
+1. In Dawarich, open your account settings and copy the API key.
+2. In HealthLog, turn on the Environment module, then open
+   **Settings → Integrations → Dawarich**.
+3. Enter the address of the instance and the key, and connect.
+4. Pick your home place from the list, and set your home country if you like.
+   Without one, the country you spent most days in over the last year counts.
+
+Run Dawarich and HealthLog in the same time zone. Dawarich groups the
+timeline by its own zone, HealthLog by yours; if they differ, a day can come
+back without its distances.
+
+## A Dawarich instance on your own network
+
+A public instance works without any server setting. An instance on a private
+network (a LAN address, a `.lan` name, a container on the same host) is refused
+unless the operator lists its exact origin:
+
+```env
+DAWARICH_PRIVATE_ORIGINS="http://dawarich.lan:3000"
+```
+
+The grammar is the one `NIGHTSCOUT_PRIVATE_ORIGINS` uses
+([Nightscout](./nightscout.md)): one `scheme://host[:port]` per entry, comma
+separated, no path, no wildcard and no range. Listing a host does not open its
+subdomains or another port. The unspecified address, link-local and the
+cloud-metadata range can never be listed. Restart HealthLog after changing it.
+The variable is on the `environment:` whitelist in `docker-compose.yml`.
+
+## Where the values show up
+
+- The day view has an **On the move** section with the day's figures.
+- Time away from home and the distance travelled join the correlation scan as
+  two more factors.
+- Runs of at least two travel days that no trip covers yet are offered as
+  trips under **Settings → Environment → Location periods**. Using one fills
+  in the dates; you pick the place.
+- The Coach and the MCP `get_day` tool see the figures and whether it was a
+  travel day, never the country.
+
+## Disconnect
+
+Disconnecting stops the nightly fetch and keeps the stored days. **Disconnect
+and delete days** removes them as well. The days are part of the backup; the
+address and key are not, so a restored account connects again.

docs/integrations/fitbit.md

@@ -16,14 +16,24 @@ Settings. The internal integration key is `fitbit`.
 > consent screen with `unauthorized_client — Invalid client_id`, because Fitbit
 > and Google Cloud are separate client registries.
 
-> **Heads-up — new registrations are closed.** Fitbit has **discontinued
-> self-serve app registration**: the form at `dev.fitbit.com/apps/new` is
-> disabled for new applications, and the classic Fitbit Web API sunsets in
-> **September 2026**. If you already hold a registered Fitbit app, it keeps
-> working until the sunset and the setup below still applies. If you are
-> connecting Fitbit data for the first time, use the
-> [Google Health integration](google-health.md) instead — Fitbit devices sync
-> into Google's health stack, which HealthLog reads directly.
+> **The classic Fitbit Web API is turned off on 30 October 2026.** Google
+> ended support for it on 30 September 2026 and turns it off on
+> **30 October 2026**, after which it "will no longer function or sync data"
+> ([Google's migration guide](https://developers.google.com/health/migration)).
+> New app registrations at `dev.fitbit.com/apps/new` are already closed.
+>
+> From that day HealthLog stops calling the Web API for every Fitbit
+> connection: no hourly sync, no backfill, no token refresh, and no new
+> connection. Nothing is deleted. The connection and every reading it imported
+> stay, and the Fitbit card explains the move instead of asking for a
+> reconnect. To keep Fitbit and Pixel data coming, connect the
+> [Google Health integration](google-health.md). It reads the same devices,
+> but Google asks for consent once more: Fitbit tokens cannot be carried over.
+>
+> Both integrations can run side by side while you move. Where both deliver the
+> same day, the source-priority ladder keeps one of them per day (Fitbit ranks
+> just above Google Health by default), so steps, sleep and the other daily
+> values are not counted twice. After the turndown only Google Health delivers.
 
 ## 1. Use an existing Fitbit developer app
 

docs/integrations/google-health.md

@@ -2,9 +2,12 @@
 
 HealthLog reads Fitbit, Pixel Watch and Fitbit Air data through the **Google
 Health API** (`health.googleapis.com/v4`), the successor to the classic Fitbit
-Web API. Google retires the classic Fitbit Web API in **September 2026**, and
-Fitbit access/refresh tokens do not carry over — every account re-consents
-through Google OAuth. This integration is that path.
+Web API. Google ended support for the classic Fitbit Web API on 30 September
+2026 and turns it off on **30 October 2026**
+([migration guide](https://developers.google.com/health/migration)); from that
+day HealthLog's `fitbit` connection stops syncing and keeps what it imported.
+Fitbit access/refresh tokens do not carry over, so every account consents once
+more through Google OAuth. This integration is that path.
 
 The OAuth app is a **Google Cloud** OAuth client, not a Fitbit developer-console
 app. Credentials are brought **per user**: each user registers their own Google
@@ -120,6 +123,174 @@ GOOGLE_HEALTH_REDIRECT_URI="https://your-instance.example.com/api/google-health/
 
 The Google Cloud client id/secret are per-user (Settings), not env vars.
 
+## Backfill, the hourly sync and Google's rate limit
+
+Only one sync runs per account at a time. **Sync now** reports that a sync is
+already in progress while the history backfill that follows a connect is
+running, and shows its progress instead of starting a second one.
+
+The backfill reads the account's whole history. Heart rate is by far the
+largest part: a page holds up to 1,000 readings, so a watch that records once
+a minute fills some 525 pages a year, and one that records every few seconds
+(as many Pixel and Fitbit watches do during the day) several thousand; one
+account measured about 4,100 pages a year. It runs in
+slices: a slice reads for up to five minutes or 500 pages, writes what it
+read, notes how far it got and lets go of the account. The next slice starts
+a minute later where the last one stopped. Two kinds of note are kept: a data
+type read to the end is not read again, and a data type read page by page
+(heart rate, weight, body fat, blood glucose, core temperature) keeps the
+time of the oldest reading it has written, so the next slice asks Google only
+for what is older. A restart or an update in the middle loses at most the page
+that was being read.
+
+Asking for "what is older" uses an upper bound on the sample time, which
+Google's filter grammar allows but which a given account may still refuse. If
+Google answers that first resumed request with `400`, the slice reads the data
+type again without the bound, passes over the readings newer than its note
+without writing them, and carries on writing from there. The refusal is noted
+per data type, so later slices read without the bound straight away. The pages
+passed over are not counted against the slice's 500 pages, but they do run on
+its five minutes, and passing over stops after three minutes at most, so a
+slice never holds the account longer than a slice. Wherever the walk stops, on
+a limit or on a rate limit, it keeps Google's page token for the page it read
+last, and the next slice reads that one page again and goes on from there
+instead of passing over everything earlier slices wrote: the pages read stay
+in proportion to the history. If Google no longer takes the token, or the page
+it returns no longer reaches the noted reading, the slice starts again from the
+newest page and passes over as before. A `400` that names something else (the
+page size, or the page token of a walk that did not start from a kept one) is
+still a failure.
+
+The hourly sync waits for the slice that is running (up to eight minutes)
+instead of skipping the account, so recent data keeps arriving while an old
+history is still coming in. The hourly job stays inside its own fifteen-minute
+limit: the wait is cut short when the job's time runs low, the sync after it
+gets only what is left and leaves the rest of its window to the next hour, and
+an account the job reaches after its time is up waits for the next hour.
+
+Google limits how many requests one account may make per minute. When a sync
+reaches that limit Google answers `429`, and HealthLog waits and repeats the
+request. If Google asks for a longer wait than a minute, the slice ends there
+and the next one starts five minutes later. A server error (`500`, `502`,
+`503`, `504`), a request that times out and a dropped connection are repeated
+three times before they count as a failure. None of these mark the connection
+as needing a reconnect. Access tokens last an hour, and a long backfill renews
+its token as it goes.
+
+### How far back the backfill reads
+
+The backfill is not bounded by a number of pages, because how many pages a
+year of history fills depends on the device. Two bounds apply instead:
+
+- **The horizon.** It reads back at most 20 years. Set
+  `GOOGLE_HEALTH_BACKFILL_HORIZON_YEARS` to a whole number from 1 to 100 to
+  change that (it is on the compose `environment:` list; any other value
+  falls back to 20). A data type whose history goes back further is imported
+  up to the horizon and ends there.
+- **Progress.** A walk has to reach older readings as it goes. If Google
+  hands out 20 pages in a row that reach no further back than the ones before
+  them (the same page again, or a page token that goes round in a circle),
+  the walk stops where it got to. A passing fault in Google's paging looks
+  the same as the end of what it holds, so the first time this happens the
+  data type only waits: it keeps its place, the rest of the backfill goes
+  on, and a day later it is walked again from there. If that second attempt
+  also stops without getting anywhere, the data type's history ends at the
+  oldest reading written so far. If it moves on, it is an ordinary walk
+  again. A walk that stops before it has written a single reading notes no
+  end at all (there is no date it could be said to end at); the slice fails
+  as stuck and is retried like any other. A reconnect starts the backfill
+  over.
+
+Either way the data type counts as finished once its end is final, the
+backfill completes once every other type is in, and the integration card
+stops saying that older history is loading. Instead it says, per data type,
+how far back the import reaches and why it ends there. While a type waits
+for its second attempt the backfill is not complete, and the card still
+says older history is loading.
+
+Before 1.43.6 every page-by-page data type had a ceiling of pages counted
+across all slices (10,000 for heart rate, 1,000 for the others). A dense
+heart-rate history reaches 10,000 pages two to three years back, the count
+never reset, and from then on every slice stopped at the same place without
+the backfill ever completing. A backfill left in that state continues from
+where it stopped with the first slice after the update.
+
+A slice that moved nothing forward (no data type finished, no reading older
+than before) is a real failure: the job fails with the reason, pg-boss retries
+it a few times, and after that the next restart offers the backfill again.
+Everything already written stays.
+
+If an older version left your Google Health card asking for a reconnect after
+a backfill, the first sync after updating checks the stored grant and resumes
+on its own when the grant is still valid.
+
+### Reading the backfill in the logs
+
+Every slice writes one log line when it ends, with
+`"background":{"task_name":"job.integration_backfill"}`. The parts worth
+reading:
+
+- `meta.kind` is `google-health-backfill`, `meta.slice` the slice number
+  (0 for the first), `meta.job_id` the pg-boss job.
+- `external_calls` lists the requests the slice made to Google, one entry per
+  request: `method` names the data type and page (`fetchHeartRate(page=212)`),
+  `status` the HTTP status, `duration_ms` how long it took. A request that was
+  repeated carries a `note` (`rate_limited_retrying_in_ms=4000`,
+  `server_error_retrying_in_ms=2000`, `no_response_retrying_in_ms=2000`,
+  `token_rejected_retrying_with_fresh_token`,
+  `edge_filter_rejected_reading_without_it`); one that failed for good
+  carries an `error`. Successful requests are listed up to 60 per line and
+  everything up to 200; `external_calls_omitted` counts the rest.
+- `meta["googleHealth.backfill.slice"]` sums the slice up:
+  - `pages`, `elapsedMs` and `imported`: what the slice read, how long it
+    took, how many readings it wrote. `skippedPages` is the part of `pages`
+    read only to pass over readings already written, on a data type whose
+    upper-bound filter Google refused.
+  - `stopReason`: why it ended early. `time_budget` and `page_budget` are the
+    normal end of a slice, `rate_limited` means Google would not take more
+    requests for now, `job_budget` that the job itself ran out of time,
+    `lane_wanted` that the slice made room for another heavy job (a nightly
+    run, a backup, an upload) that was waiting; the next slice starts two
+    minutes later. `null` means the slice read everything it started.
+  - `collectionsDone` of `collectionsTotal`: data types read to the end so
+    far.
+  - `collections`: one entry per data type the slice touched, with its
+    `status` (`done`, `stopped` short on a budget or a rate limit,
+    `deferred` to the next slice, or `failed`), its `pages`, and for the
+    page-by-page types
+    `edgeFrom` and `edgeTo`, the oldest reading written before and after the
+    slice.
+  - `edges`: where every unfinished page-by-page data type stands now.
+  - `ended`: data types whose history ended short of its beginning, each
+    with its measurement `type`, the instant it ends at (`at`) and the
+    `reason` (`horizon` or `no_progress`). A `no_progress` entry also
+    carries `attempts` and `endedAt`; with one attempt it is waiting for
+    its second, a day after `endedAt`, and is not yet published.
+- `action: google_health.backfill.retry_scheduled` marks a slice that found
+  nothing left but a data type waiting for its second attempt and queued the
+  next slice for when it is due (`delaySeconds`).
+- `meta["googleHealth.backfill.ended"]` appears on the slice where a data
+  type ended short: the `collection`, its measurement `type`, the `reason`,
+  whether the end is `final`, how many data types have ended short so far
+  (`endedCount`) and of those for good (`finalCount`), and their `types`.
+  The full entries are in the slice report's `ended`. A walk stopped for lack of
+  progress also leaves a warning:
+  `fetchHeartRate: 20 pages in a row reached no further back than <instant>`.
+- `meta["googleHealth.backfill.edgeFilterUnsupported"]` appears on the slice
+  where Google refused the upper-bound filter, listing the data types noted
+  as refusing it.
+- `action.name` is `google_health.backfill.continued` for a slice that made
+  progress and queued the next one, `google_health.backfill.complete` for the
+  one that finished the history, and `google_health.backfill.stuck` for one
+  that moved nothing. A stuck slice also fails the job with a message that
+  names each unfinished data type and its status, for example
+  `no progress in slice 4, stopped on rate_limited; fetchHeartRate:stopped`.
+
+While a slice runs, the usual `job.progress` line for the
+`integration-backfill-admission` queue reports
+`google_health_backfill_slice`, `google_health_backfill_pages` and
+`google_health_backfill_collections_done` every two minutes.
+
 ## The 7-day re-consent caveat
 
 While the OAuth consent screen stays in **Testing** publishing mode, Google

docs/integrations/health-connect.md

@@ -0,0 +1,166 @@
+# Health Connect import
+
+HealthLog reads the export file of Android's Health Connect and folds
+it into the same timeline as every other source. There is no Android
+app and no live sync: you export from the phone, upload the file, and
+a background job imports it. Rows from this path carry the source
+`HEALTH_CONNECT`.
+
+## What you need
+
+- An Android phone with Health Connect and its export feature. The
+  export arrived with Android 15 and reaches Android 14 through a
+  system update; if you do not see it, update Health Connect first.
+- A cloud storage app on the phone (Google Drive, Dropbox, Nextcloud
+  or any other app that offers itself as a storage location). Health
+  Connect refuses to save its export to the phone's own storage or the
+  Downloads folder, so the file always goes through a cloud first.
+- A HealthLog account in a browser. The upload uses your normal
+  session; there is no token to create.
+
+## 1. Export on the phone
+
+1. Open Health Connect (in the system settings, or the Health Connect
+   app).
+2. Go to **Manage data**, then **Export and import**, then
+   **Scheduled export** or **Export now**, depending on the version.
+3. Pick the cloud storage app as the destination. You can choose how
+   often Health Connect exports again; HealthLog only ever reads the
+   file you upload.
+
+The result is a ZIP file named `Health Connect.zip` with a single
+entry, `health_connect_export.db`. That entry is a copy of the phone's
+Health Connect database (a SQLite file). Health Connect does not
+encrypt it, so treat the file like any other export of your health
+data.
+
+## 2. Upload to HealthLog
+
+Download the ZIP from the cloud to the computer or phone you use
+HealthLog on, open **Settings → Export & Import** and drop the file
+onto the **Health Connect export** card.
+
+The endpoint is `POST /api/import/health-connect-export`
+(`multipart/form-data`, field `file`). It:
+
+1. Allows three uploads per minute per account.
+2. Refuses anything above **1 GiB**, once against the declared
+   `Content-Length` and again while the body streams to disk.
+3. Streams the body to a temp file and hashes it with SHA-256 on the
+   way. Uploading the same bytes again returns the earlier job
+   (`idempotent: true`) instead of importing twice; a failed job never
+   blocks a retry.
+4. Runs one import per account at a time, Apple Health and Health
+   Connect together. A second upload while one runs answers `409` and
+   the file is discarded.
+5. Records the upload's size and hash in the audit log, and nothing
+   from inside the file.
+
+`GET /api/import/health-connect-export/status` answers the account's
+latest Health Connect job, or `null`. The card polls it while a job
+runs.
+
+## 3. What the import does
+
+The worker extracts `health_connect_export.db` (at most 4 GiB, with
+the same zip-bomb checks as the Apple Health importer) and opens it
+read-only. The file is treated as untrusted input:
+
+- It is opened with SQLite's `immutable` flag, so a database last
+  written in WAL mode opens without its `-wal` and `-shm` files, and
+  nothing is ever written next to it.
+- Views, triggers and generated columns in the file cannot call
+  functions with side effects (`trusted_schema=OFF`), and a view in
+  place of one of the record tables refuses the whole file.
+- Columns are looked up by name. Health Connect adds columns as its
+  schema version moves, so their order differs between phones.
+  Database versions below 9 are refused; versions above 27 (the newest
+  known when this was written) are read, with a warning on the job.
+  A table that lacks a column the importer needs is skipped and named
+  in the job's `warnings`.
+
+### What becomes what
+
+| Health Connect                                                 | HealthLog                                                                                                                  |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Weight, lean body mass (grams)                                 | `WEIGHT`, `LEAN_BODY_MASS` in kg                                                                                           |
+| Body fat                                                       | `BODY_FAT` in %                                                                                                            |
+| Blood pressure                                                 | `BLOOD_PRESSURE_SYS` and `BLOOD_PRESSURE_DIA`, one pair per reading                                                        |
+| Resting heart rate, heart-rate variability (RMSSD)             | `RESTING_HEART_RATE`, `HRV_RMSSD`                                                                                          |
+| Oxygen saturation, respiratory rate, body temperature, VO2 max | the matching types                                                                                                         |
+| Blood glucose (mmol/L)                                         | `BLOOD_GLUCOSE` in mg/dL, fasting and after-meal context kept                                                              |
+| Heart rate                                                     | per minute for the last 90 days; older history as hourly means with the hour's minimum and maximum                         |
+| Steps, active calories, distance                               | one total per day                                                                                                          |
+| Sleep sessions and stages                                      | one row per stage; light sleep becomes core sleep, both awake stages awake time; a session without stages counts as asleep |
+| Exercise sessions                                              | workouts, with the Health Connect exercise type kept on the workout                                                        |
+| Menstruation flow and periods                                  | cycle day logs (needs cycle tracking switched on)                                                                          |
+| Hydration and vitamins and minerals                            | daily nutrient totals (needs the Nutrients module)                                                                         |
+
+Left out on purpose: food energy and macronutrients, exercise routes,
+planned workouts, Health Connect's access logs, the "out of bed" sleep
+stage, and an "unknown" sleep stage inside a session that also has real
+stages.
+
+### When several apps write the same thing
+
+The export holds every app's data side by side. Summing them would
+count a step the phone and the watch both saw twice, so:
+
+- A day total (steps, calories, distance, water, nutrients) comes from
+  one app per day: the first one your Health Connect app priority
+  list names for that category, otherwise the app with the largest
+  total.
+- Heart rate comes from one app per hour, by the same rule.
+- Of two overlapping sleep sessions or workouts from different apps,
+  the one from the higher-ranked app is kept.
+- Two apps writing the same type at the same instant keep the
+  higher-ranked app's value.
+
+### Apps HealthLog already connects to
+
+If your account has the Withings, Fitbit, Google Health, Oura, Polar
+or WHOOP integration connected, that app's records in the export are
+left out: HealthLog already receives them directly, and importing them
+again would put every reading in twice. As a further safety net, a
+reading that matches one already stored under another source (same
+type and value within two seconds) is left out too. The job result
+lists how many records each app contributed and which apps were left
+out.
+
+### Importing again
+
+Every row is keyed by the record's Health Connect ID (`hc:<uuid>`),
+day totals and hourly means by their `stats:` ID. Importing the same
+export again writes nothing; a newer export that overlaps an older one
+adds only what is new. A value that changed on the phone is updated;
+a value you deleted in HealthLog stays deleted.
+
+Heart rate imported per minute ages the way Apple Health heart rate
+does: once a minute is older than 90 days, the nightly pass folds its
+hour into one hourly mean and removes the minutes. A later import of
+an export that still holds those minutes leaves them out, so an hour
+is never counted twice.
+
+## Privacy
+
+- The uploaded ZIP and the extracted database are deleted as soon as
+  the job ends, whether it succeeded or failed. A periodic sweep
+  removes anything a crash left behind.
+- The job result holds counts only: per measurement type and per app.
+  No value, no timestamp and no text from the file (notes, titles)
+  is stored on the job.
+
+## Operator notes
+
+- The worker uses Node's built-in `node:sqlite` module. It needs no
+  flag on Node 22 and prints one `ExperimentalWarning` per process.
+- Memory stays bounded: the database is read in batches of 500 rows
+  and aggregated inside SQLite, so what the import keeps alive does not
+  grow with the length of the history. Measured under a 792 MB heap,
+  one and three years of minute-by-minute heart rate peaked at about
+  160 MB of heap in total.
+- Split web and worker containers need a shared staging directory,
+  exactly as for the Apple Health import.
+- The status of a running job shows up under **Settings → Export &
+  Import**; a job interrupted by a restart is marked failed by the
+  same reconcile pass that watches Apple Health imports.

docs/integrations/home-assistant.md

@@ -109,20 +109,20 @@ a new weight:
 ```yaml
 automation:
   - alias: "Push weight to HealthLog"
-    trigger:
-      - platform: state
+    triggers:
+      - trigger: state
         entity_id: sensor.bathroom_scale_weight
-    condition:
+    conditions:
       - condition: template
         value_template: "{{ trigger.to_state.state not in ['unknown', 'unavailable'] }}"
-    action:
-      - service: rest_command.healthlog_measurement
+    actions:
+      - action: rest_command.healthlog_measurement
         data:
           type: WEIGHT
           value: "{{ trigger.to_state.state | float }}"
 ```
 
-The `condition` is not decoration. Home Assistant sensors publish `unknown` and
+The condition is not decoration. Home Assistant sensors publish `unknown` and
 `unavailable` as ordinary states, and forwarding one produces a 422 on every
 restart.
 
@@ -149,6 +149,89 @@ Units are derived server-side from the type, so send the number in the unit
 above and do not send a `unit` field. The full enum is in
 `docs/api/openapi.yaml` under `MeasurementType`.
 
+## Room climate
+
+Indoor CO₂, temperature and humidity are their own types, kept apart from the
+body temperatures and from the outdoor weather the environment module pulls:
+
+| What the sensor reports | `type`               | Unit expected |
+| ----------------------- | -------------------- | ------------- |
+| Carbon dioxide          | `INDOOR_CO2`         | ppm           |
+| Room temperature        | `INDOOR_TEMPERATURE` | °C            |
+| Relative humidity       | `INDOOR_HUMIDITY`    | %             |
+
+Each push is kept as a reading, and the day's mean, low and high are what the
+charts and the daily views read, so a sensor sampled every 15 minutes gives a
+clear picture without anything further on your side. Pushing every few seconds
+adds rows, not detail.
+
+Add a second `rest_command` that takes a ready-made list of readings, so one
+request carries all three:
+
+```yaml
+rest_command:
+  healthlog_room_climate:
+    url: "https://healthlog.example.com/api/measurements"
+    method: POST
+    headers:
+      Authorization: !secret healthlog_token
+      Content-Type: "application/json"
+    payload: "{{ readings | to_json }}"
+```
+
+Track one room, the one you sleep in: that is the one worth reading next to
+your sleep. The readings carry no room name, so a second room would land in the
+same series and blur both, and two pushes in the same minute collide on a 409
+(see below).
+
+Then import the blueprint (Home Assistant 2024.10 or newer), either from
+[`docs/integrations/blueprints/healthlog-room-climate.yaml`](./blueprints/healthlog-room-climate.yaml)
+or by its raw GitHub URL under Settings → Automations & scenes → Blueprints →
+Import blueprint, and create one automation from it for that room. It asks for
+the three sensors (each optional) and an interval of 5, 10, 15, 20, 30 or 60
+minutes, counted from the full hour. Every push:
+
+- leaves out a sensor that reports `unknown`, `unavailable` or anything that is
+  not a number, and skips the push when nothing is left;
+- converts a temperature reported in °F to °C;
+- stamps all readings with the current minute, so a retry of the same push is
+  refused with a 409 instead of written twice.
+
+If you would rather write the automation yourself, this is the same thing for a
+single room without the blueprint:
+
+```yaml
+automation:
+  - alias: "Push bedroom climate to HealthLog"
+    triggers:
+      - trigger: time_pattern
+        minutes: "/15"
+    variables:
+      readings: >-
+        {% set at = now().replace(second=0, microsecond=0).isoformat() %}
+        {% set ns = namespace(items=[]) %}
+        {% for type, entity in [
+          ('INDOOR_CO2', 'sensor.bedroom_co2'),
+          ('INDOOR_TEMPERATURE', 'sensor.bedroom_temperature'),
+          ('INDOOR_HUMIDITY', 'sensor.bedroom_humidity')
+        ] %}
+          {% if is_number(states(entity)) %}
+            {% set ns.items = ns.items + [{'type': type,
+              'value': states(entity) | float, 'measuredAt': at}] %}
+          {% endif %}
+        {% endfor %}
+        {{ ns.items }}
+    conditions:
+      - condition: template
+        value_template: "{{ readings | count > 0 }}"
+    actions:
+      - action: rest_command.healthlog_room_climate
+        data:
+          readings: "{{ readings }}"
+```
+
+One request takes up to five readings, so the room is one call.
+
 ## Sending several readings at once
 
 A bare array writes up to five readings in one request — the shape to use for

docs/integrations/withings.md

@@ -25,6 +25,56 @@ 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.
 
+## Withings API plans (October 2026)
+
+On 12 October 2026 Withings split its public API into plans
+([plans page](https://static.withings.com/content/api/plans/plans.html)).
+The developer app a self-hoster registers for HealthLog sits on the free
+**Start for Free** plan, which covers the core biomarkers: activity, sleep,
+body and heart. The FDA/CE-cleared biomarkers and a few body-composition
+extras now need the paid **Advanced Biomarkers** plan.
+
+A request that names anything outside the plan is refused as a whole with
+status 277 ("One of the data type requested in this API request is not
+available in your API plan"). Before v1.42.3 HealthLog asked for every type
+in one request, so from that date no Withings reading imported at all, and
+the connection showed "Reauthorisation required" although reconnecting could
+not help.
+
+**Still synced on the free plan:** weight, fat mass and fat-free mass, muscle
+mass, bone mass, body water, blood pressure, heart rate, a manual SpO2
+reading, body temperature, steps, distance and calories, and the sleep
+stages (duration, deep, light, REM, awake, wake-ups).
+
+**Needs the paid Advanced Biomarkers plan** (per Withings'
+[available health data](https://developer.withings.com/developer-guide/v3/data-api/all-available-health-data/)
+table): pulse wave velocity (meastype 91), vascular age (155), visceral fat
+(170), VO2 max (123), skin temperature (73), ECG recordings and AFib
+verdicts, and the sleep score, overnight HRV and overnight breathing rate
+from the sleep summary.
+
+**What HealthLog does about it, automatically:**
+
+- When Withings refuses a request with 277, HealthLog asks again without
+  the types Withings lists as advanced. If that is still refused, it
+  splits the remaining types until it has found the ones the plan
+  refuses, within a fixed number of requests. Everything the plan allows
+  imports as before.
+- The refused types are remembered per connection, so later syncs skip
+  them without a refused request. Once a week HealthLog asks for the full
+  set again, so a plan upgrade is picked up on its own.
+- ECG recordings are skipped quietly while the plan refuses them.
+- A plan refusal is never counted as a sync failure and never asks you to
+  reconnect. Connections that an earlier version parked over it are
+  released on the next hourly sync, and that sync imports everything since
+  the last successful one.
+- Settings → Integrations → Withings shows a short note naming the
+  readings your plan withholds, with a link to the Withings plans page.
+
+Nothing needs to be configured. If you move your developer app to the
+Advanced Biomarkers plan, the extra readings start arriving within a week,
+or right away after reconnecting Withings once.
+
 ## 1. Register a Withings developer app
 
 1. Sign in at <https://developer.withings.com/> and **create a new
@@ -167,6 +217,11 @@ fixes the mismatch by updating the URL Withings holds.
 
 ### Sync is stuck on "Reauthorisation required"
 
+If this started on or after 12 October 2026 and your version is older than
+v1.42.3, the cause is the API plan change, not your grant: see
+[Withings API plans (October 2026)](#withings-api-plans-october-2026).
+Updating is the fix; reconnecting is not needed.
+
 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

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

@@ -204,9 +204,11 @@ n8n, and Health Connect integrations need no change.
 ## 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.
+  → `/settings/integrations`, etc. A legacy `/settings#anchor` URL opens
+  Settings (`/settings` redirects to `/settings/account`), but the part
+  after `#` never reaches the server, so it cannot pick the section: update
+  bookmarks and links of the `/settings#thresholds` shape to the
+  per-section route.
 
 ## What landed in v1.4 vs v1.4.1
 

docs/ops/attempt-number-semantics.md

@@ -1,18 +1,24 @@
-# `attemptNumber` audit-row vs alert-signal semantics
+# `attempt_number` signal vs alert 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.
+Operators reading an `integrations.sync.failed` log line alongside an admin
+alert should expect the alert number to be smaller than (or equal to) the
+logged number, never the other way around.
+
+Since v1.43.7 a failed sync is a `warn` signal in the log store, not an
+audit-log row: the audit log records what a person or an admin did to an
+account, and a provider answering 503 is neither. The provider's message is
+not on the signal; it stays encrypted on the integration's status row and
+shows in the integration's settings.
 
 ## The two numbers
 
-`integrations.sync.failed` audit rows write
-`attemptNumber = transient + reauth_required + persistent` — the **sum**
+`integrations.sync.failed` signals carry
+`attempt_number = 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
+`0077`, v1.4.47). An operator looking at a single line sees one integer
 that captures how many failures the bucket ledger has accumulated since
 the last success.
 
@@ -27,14 +33,14 @@ 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
+2× reauth_required, then 1× persistent. The last signal shows
+`attempt_number: 5`. The alert number is `max(2, 2, 1) = 2`, which is below
+the default threshold of 3, so no page fires. From the 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
+Both readings are correct for their purpose. The signal 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 —
@@ -43,7 +49,7 @@ we want to wake someone up for.
 
 ## Runbook implication
 
-If you see an audit row with `attemptNumber >= threshold` but no alert
+If you see a signal with `attempt_number >= threshold` but no alert
 was dispatched, check the per-bucket counts on
 `IntegrationStatus.consecutiveFailuresByKind` (DB column
 `consecutive_failures_by_kind`) for that user/integration pair. The

docs/ops/backup-restore.md

@@ -230,6 +230,21 @@ rather than by the size of the record going through it: measured on the same
 died and the new one finished holding tens of megabytes, writing a 9.1 MB
 object that restores to the identical record.
 
+Up to 1.43.4 that held for the tables that are long in rows, not for the
+ones that are heavy in bytes. The stored documents and the ECG traces were
+still read whole, and a vault of 190 MB cost about five times that in heap:
+the bytes, their base64, the section's JSON and the preview's copies of each
+row. A single account with that many documents took a 524 MB process down on
+every weekly run, while 1.25 million measurements beside them fitted easily.
+Both writers now read the traces a page at a time and the documents one at a
+time, each document's bytes in slices of 1.5 MB. Measured on that account
+under `--max-old-space-size=524`, the peak went from 930 MB (a crash) to
+209 MB. The restore had the same problem in the other direction: it kept
+every document of the file in memory and peaked at 1.25 GB on the same copy.
+It now leaves the stored bytes out of its first read and writes the
+documents one at a time from a second one, and the copy restores every
+document byte for byte inside the 524 MB heap.
+
 One ceiling remains, and it is structural rather than a memory bound: a
 multipart upload carries 10 000 parts, so 80 GB is the largest object one
 account can produce. Past it the account's backup fails with a clear refusal,

docs/ops/deploy.md

@@ -13,6 +13,12 @@ Migrations land **before** the new app container takes traffic. The
 canonical command sequence on a single-instance host:
 
 ```sh
+# 0. Dump the database first. A migration is not undone by going back to
+#    the previous image; the dump is the way back. See "Updates" in
+#    docs/self-hosting/getting-started.md.
+docker compose exec -T db pg_dump -U healthlog healthlog \
+  | gzip > healthlog-before-update-$(date +%F).sql.gz
+
 # 1. Pull the new image. If you pin a version with HEALTHLOG_IMAGE_REF,
 #    set it to the new one first.
 docker compose pull app
@@ -34,6 +40,86 @@ not reachable". The entrypoint also runs the migrations on every boot, so
 step 2 is optional; it is there for when you want to see the migration
 result before the new container takes traffic.
 
+The entrypoint runs every migration in a UTC session, the zone the app's own
+connections use, whatever the database's default `TimeZone` is: it adds
+`-c TimeZone=UTC` to the `options` parameter of `DATABASE_URL` for the Prisma
+calls (an `options` value you set yourself is kept, with the pin after it).
+Behind a connection pooler that refuses `options`, the
+`DATABASE_SESSION_OPTIONS_DISABLED` switch turns this off along with the
+app's own session settings; set the database or role default to UTC there
+(`ALTER DATABASE healthlog SET timezone = 'UTC'`).
+
+### A migration that timed out on a lock
+
+Some migrations bound how long they wait for a table lock, so that a
+long-running holder (most often an autovacuum that is preventing
+transaction-ID wraparound, which does not step aside) cannot queue every
+write to that table behind the migration. Migration `0412` waits at most ten
+seconds for `measurements`. When the wait runs out, the boot log shows
+Prisma's report followed by a line from the entrypoint:
+
+```
+Error: P3018
+...
+Migration name: 0412_measurement_hot_updates
+
+Database error code: 55P03
+...
+HealthLog: migration 0412_measurement_hot_updates timed out waiting for a lock (55P03) and changed nothing; marking it rolled back and retrying in 15s (retry 1 of 5).
+```
+
+A marked migration that loses a deadlock against an app transaction
+(`Database error code: 40P01`) is in the same state, its block rolled back
+whole, and is handled the same way; the entrypoint's line then says
+`was cancelled in a deadlock (40P01)`.
+
+What happens on its own: such a migration is written so that a timed-out
+attempt changes nothing, and it says so in its file
+(`-- @retry-on-lock-timeout`). The entrypoint then marks that one migration
+rolled back (`prisma migrate resolve --rolled-back`) and runs
+`migrate deploy` again after 15, 30, 60, 120 and 240 seconds. The app starts
+as soon as an attempt gets the lock. A later boot that finds the attempt still
+on record (Prisma's `P3009`) reads the cause from `_prisma_migrations` and
+does the same. Nothing else is retried: any other failure, and a lock timeout
+in a migration that does not carry the marker, stops the boot exactly as
+before.
+
+The retries fit inside the container's health check: its start period is ten
+minutes (`docker-compose.yml` and the image's own `HEALTHCHECK`), so failed
+probes while the entrypoint is still migrating do not mark the container
+unhealthy. The first probe that answers ends the start period, so a normal
+boot is reported healthy within half a minute of the server listening.
+
+If all five retries time out, the log ends with
+`HealthLog: ERROR — migration … timed out on a lock 6 times in a row; giving
+up.` and the container exits. Something has held the table for about eight
+minutes. Find it:
+
+```sh
+docker compose exec db psql -U healthlog -c "
+  SELECT pid, backend_type, state, now() - xact_start AS running, query
+    FROM pg_stat_activity
+   WHERE pid IN (SELECT pid FROM pg_locks
+                  WHERE relation = 'measurements'::regclass)"
+```
+
+An `autovacuum: VACUUM … (to prevent wraparound)` row finishes on its own;
+wait for it to disappear and start the container again (a restart policy does
+that for you, and each boot retries). Anything else is a session you can
+judge: a stuck client may be ended with `SELECT pg_terminate_backend(<pid>)`.
+You never need to run `migrate resolve` by hand for this case.
+
+### v1.44.0 notes
+
+Migration `0430` drops the `insights_cached_text` column from `users`. A
+process still running the previous image selects that column on every full
+user read and fails once it is gone, so do not run old and new containers side
+by side across this release: stop the old app container, let the new one
+apply the migrations, then start it (the sequence above does this on a single
+host). A web/worker split deployment stops both roles before the first new
+container starts. Rolling back to an image older than v1.44.0 needs the column
+back first (see Rollback below).
+
 ### v1.11.0 notes
 
 Migrations `0110`–`0114` are additive (new tables / columns for the

docs/ops/encryption-key-rotation.md

@@ -43,12 +43,12 @@ under `v1` (the synthetic id assigned to the existing `ENCRYPTION_KEY`).
    retained.
 3. **Re-encrypt the stored data under the new key.** Open **Admin →
    Encryption** and press **Rotate now**. The button needs an admin account
-   with a second factor, confirmed recently; it queues one background run
+   with a second factor or a passkey, confirmed recently; it queues one background run
    (`POST /api/admin/encryption/rotate`) on the app's own worker, so it
    works on the published image with nothing else installed. The same page
    shows the per-column counts and the result of the last run.
 
-   Without a second factor on any admin account, run the rotation script
+   Without a second factor or a passkey on any admin account, run the rotation script
    instead. It imports the application code and the generated database
    client, so it runs from a source checkout of the same release, not
    inside the production container (the image has no package manager and

docs/ops/heap-diagnostics.md

@@ -0,0 +1,48 @@
+# Heap diagnostics
+
+A Node process that reaches its heap limit stops with `JavaScript heap out of memory` and writes nothing else: no stack, no record of what it was doing. HealthLog therefore logs its own heap while it is still alive.
+
+## What is always on
+
+Two background wide events, no configuration needed:
+
+- `runtime.heap.sampled` (info), every five minutes, and every minute while the heap is at or above 70 % of its limit. It goes to stdout and Loki but not to Admin > App logs, so it cannot push other events out of that page's 500-entry buffer. It carries `heap_used_mb`, `heap_total_mb`, `heap_limit_mb`, `heap_used_ratio`, the used size of each heap space (`new_space_mb`, `old_space_mb`, `code_space_mb`, `large_object_space_mb`, `new_large_object_space_mb`, `code_large_object_space_mb`, `trusted_space_mb`, `read_only_space_mb`, and `other_spaces_mb` for any space not named), `rss_mb`, `external_mb`, `array_buffers_mb`, `active_requests`, `active_jobs`, `in_flight_dropped` and `uptime_s`. The spaces add up to `heap_used_mb`: a large buffer or string (a profile picture held in memory, a long response body) shows in `large_object_space_mb`, not in `old_space_mb`, and memory outside the V8 heap shows in `external_mb` and `array_buffers_mb`.
+- `runtime.heap.pressure` (warn), the first time the heap reaches 85 % of its limit. Besides the figures above it lists the 50 oldest requests and jobs in flight (`in_flight_oldest`: kind, method, route, age in seconds, whether it was a server action) and the routes most of them share (`in_flight_by_route`). Routes are reduced to their shape: no query string, secret path segments replaced by `[REDACTED]`, ids by `:id`, anything unusual by `:x`. It writes again only after the heap has dropped below 70 % and thirty minutes have passed. One exception: when the heap reaches 95 %, the same report is written again at once, with `pressure_ratio: 0.95`, whatever the cooldown; that tier re-arms as soon as the heap is back under 85 %. A heap that climbs to its limit shortly after an 85 % report therefore still leaves a report naming the work that pushed it over.
+
+The heap is read every five seconds, a single call that takes microseconds. Tracking requests costs one map insert and one delete per request.
+
+To find the last lines before a crash:
+
+```sh
+docker compose logs app --since 2h | grep '"runtime.heap.'
+```
+
+## The report Node writes when the heap runs out
+
+The image sets `NODE_OPTIONS="--report-on-fatalerror --report-filename=stderr --report-exclude-env --report-exclude-network"`. When the process runs out of heap, Node writes a diagnostic report, about 10 KB of JSON with `"trigger": "OOMError"`, to stderr just before it exits: the JavaScript stack at the failed allocation, the native stack, the heap spaces and the open handles. It lands in the container log beside the `runtime.heap.*` lines:
+
+```sh
+docker compose logs app --since 2h | grep -A400 '"trigger": "OOMError"'
+```
+
+The two exclude flags keep environment variables (keys, passwords, the database URL) and network interfaces out of the report. If you set `NODE_OPTIONS` yourself, for example to raise `--max-old-space-size`, your value replaces the image's; add the four flags to it to keep the report.
+
+## Optional heap snapshot
+
+A snapshot shows what the heap is made of, which the events above cannot. Turn it on only while you are chasing a specific crash:
+
+```sh
+HEALTHLOG_HEAP_SNAPSHOT=1
+HEALTHLOG_DIAG_DIR=/tmp   # default; a path inside the container
+```
+
+With the switch set, the first `runtime.heap.pressure` event is followed by one `v8.writeHeapSnapshot()` and a `runtime.heap.snapshot` event naming the file. At most one snapshot is written per process. The file goes into a new directory with a random name, `healthlog-heap-XXXXXX`, created with mode 0700 and checked to be a real directory owned by the app's user before anything is written; the file itself is mode 0600. The event names the full path.
+
+**A heap snapshot contains everything the process held in memory: decrypted health records, session data, API tokens and the encryption keys.** Treat it like a database dump with the keys attached.
+
+- HealthLog never uploads or logs a snapshot. Only its path appears in the log.
+- Copy it off the container only to a machine you trust, for example `docker compose cp app:/tmp/healthlog-heap-XXXXXX ./`, and open it in Chrome DevTools (Memory tab, Load).
+- Delete it as soon as you are done, inside the container and wherever you copied it: `docker compose exec app rm -rf /tmp/healthlog-heap-XXXXXX`. A file under `/tmp` in the container also disappears when the container is recreated, not when it restarts.
+- Do not attach a snapshot to an issue or send it to anyone.
+
+Writing a snapshot blocks the process for several seconds and needs memory roughly the size of the heap on top of what is in use. Near the container's memory limit that can end the process sooner than the heap would have. The pressure report is written before the snapshot starts, so it is on record either way. Turn the switch off again when you have what you need.

docs/ops/intake-repair.md

@@ -33,9 +33,9 @@ metadata (`medication_schedules`):
 - After upgrading to v1.15.19+, when a user reports a compliance rate above
   100 %, duplicate entries in the medication history, or a dose shown as
   taken days away from its slot.
-- The compliance rollup counts DISTINCT slots since v1.15.19, so the
-  percentages self-correct on recompute even without running this script.
-  Running it additionally clears the phantom rows from the history view.
+- Compliance counts DISTINCT slots since v1.15.19, so the percentages are
+  right even without running this script. Running it additionally clears
+  the phantom rows from the history view.
 - The `intake-slot-dedup` worker already collapses canonical-slot
   duplicates at boot and on a daily cron; this script is the manual,
   immediately-observable fallback and the only path that surfaces the
@@ -104,13 +104,9 @@ healthlog-tsx scripts/repair-intake-anomalies.ts --fix
   as the duplicate losers). A medication without any derivable anchor
   (PRN-only / unscheduled) is skipped — there is nothing to compare
   against.
-- **Affected compliance rollups are recomputed** for every touched
-  `(user, medication, day)`. The script executes the same DISTINCT-slot
-  aggregation SQL the shared helper runs (a verbatim twin of
-  `recomputeMedicationComplianceForDay` in
-  `src/lib/rollups/medication-compliance-rollups.ts` — kept inline so
-  the script needs no app imports), so the scheduled/taken counts and
-  the rate self-correct immediately.
+- **No separate recompute is needed.** Every compliance reader folds the
+  rows that share one slot, so the scheduled/taken counts and the rate are
+  right as soon as the duplicates are tombstoned.
 
 The script is idempotent: a second `--fix` run finds zero duplicate groups
 and changes nothing. Exit code is 0 on success (including a clean

docs/ops/measurement-maintenance.md

@@ -0,0 +1,261 @@
+# Measurement table maintenance
+
+Since v1.42 the nightly folds of Apple Health data delete the raw samples they
+fold into hourly or daily rows, instead of keeping them as deleted rows for 75
+days. On an instance that has synced Apple Health for a while, those leftovers
+("compaction tombstones") were most of the `measurements` table and of its
+indexes. Three pieces deal with them, in this order:
+
+1. **The fold repair** runs by itself, once per account, before anything is
+   deleted. Up to v1.42 the folds could fold a day in two runs, and the
+   second run stored the mean of the later part of the day only. The repair
+   recomputes those hourly and daily means from all of the day's samples,
+   including the compaction tombstones, and corrects a stored mean only when
+   it differs. It does so only where every sample of the day is provably
+   still in the table: the last 75 days for daily means, and for hourly
+   means (folded 90 days late) the 75 days before that. Older days stay as
+   they are, because the deleted rows of their samples have passed the
+   75-day retention and what is left can be a fragment of the day. When it
+   has finished an account it records that in `measurement_fold_repairs`.
+2. **The backlog purge** runs by itself, after the repair. Every worker boot queues one
+   `compaction-tombstone-purge` job. It deletes the leftovers 5,000 rows at a
+   time, one account at a time, pausing briefly between batches, and stops
+   after 40 batches; a run that stopped with work left queues the next one a
+   minute later. Rows a person deleted are never touched by it: they keep the
+   75-day retention of the nightly tombstone cleanup. The purge leaves an
+   account alone until the repair has finished it, and a boot queues no purge
+   run while the repair has finished no account.
+3. **The table maintenance** is yours to start, after the purge. It runs
+   `VACUUM (ANALYZE)` on `measurements` and then rebuilds each of its indexes
+   with `REINDEX INDEX CONCURRENTLY`, largest first. The purge leaves the
+   indexes full of empty pages, and only a rebuild gives that space back.
+
+## Repair before purge
+
+The order matters because the purge deletes what the repair reads. Do not
+delete compaction tombstones by hand, and do not insert rows into
+`measurement_fold_repairs` to hurry the purge along: a mean the repair has not
+seen keeps its wrong value for good once its tombstones are gone.
+
+The repair reports every run on the wide event `job.measurement_fold_repair`
+(`fold_repair_means_checked`, `fold_repair_means_corrected`,
+`fold_repair_resting_corrected`, `fold_repair_skipped_beyond_horizon` for the
+older windows it left as they are, `fold_repair_samples_absorbed` for live
+samples it took into a checked mean, and `fold_repair_by_type` with the same
+counts per type; counts only, never a value). A second run over an account
+corrects nothing. It is finished when every account has a row:
+
+```sql
+SELECT count(*) AS accounts_left
+FROM users u
+LEFT JOIN measurement_fold_repairs r ON r.user_id = u.id
+WHERE r.user_id IS NULL;
+```
+
+Each run works on one account, a day at a time, and stops on its time budget
+with a follow-up that resumes at the next day; an account under restore is
+tried again five minutes later. While accounts are left, purge runs report
+them as `compaction_purge_awaiting_repair_accounts`.
+
+A restore of a backup exported before the account's repair finished writes
+the compaction tombstones back, removes the account's row and queues the
+repair again; the purge follows once the repair is through.
+
+## Is the purge finished?
+
+The purge reports every run on the wide event `job.compaction_tombstone_purge`
+(`compaction_purge_deleted`, `compaction_purge_drained`,
+`compaction_purge_deferred_accounts`). It is finished when a run reports
+`drained: true` and deletes nothing. From `psql`:
+
+```sql
+SELECT state, count(*)
+FROM pgboss.job
+WHERE name = 'compaction-tombstone-purge'
+GROUP BY state;
+```
+
+No `created`, `retry` or `active` rows means nothing is queued or running. The
+maintenance refuses to start while one is.
+
+## Before you start
+
+- **Pick a quiet window.** Reads and writes keep working during the rebuild,
+  but each rebuild reads the whole table twice and writes a full new copy of
+  the index.
+- **Free disk.** A concurrent rebuild needs room for one more copy of the
+  index it is rebuilding, plus the WAL it writes. Check the largest index:
+
+  ```sql
+  SELECT c.relname, pg_size_pretty(pg_relation_size(c.oid))
+  FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid
+  WHERE i.indrelid = 'measurements'::regclass
+  ORDER BY pg_relation_size(c.oid) DESC
+  LIMIT 3;
+  ```
+
+  Have at least twice the largest size free on the database volume.
+
+- **Take a backup** (Settings, Data, Backups), as before any operation on the
+  whole table.
+
+## Starting it
+
+In the admin area, or with a signed-in admin session:
+
+```sh
+curl -X POST https://<your-instance>/api/admin/maintenance/measurements \
+  -H 'content-type: application/json' \
+  --cookie 'healthlog_session=<session>' \
+  -d '{"vacuum": true, "reindex": true}'
+```
+
+The answer is `202` with `{ "enqueued": true }`, or `enqueued: false` when a
+run is already queued or running. A Bearer token is refused: the route is
+cookie-only, like every admin route. Without a background worker the route
+answers `503`.
+
+Either step can be left out (`"reindex": false` runs only the vacuum).
+
+## What it does, and what stops it
+
+The run uses a connection of its own: no statement timeout (a rebuild of a
+large index takes longer than the app's 60 seconds), `maintenance_work_mem`
+of 128 MB for this session only, and a lock timeout of five minutes, so a
+rebuild that cannot get its lock gives up instead of holding writers behind
+it.
+
+- It refuses to start while the purge is queued or running.
+- Before the first rebuild it drops any invalid `<index>_ccnew` copy an
+  interrupted earlier run left behind.
+- If a rebuild fails, most likely for lack of disk, it drops that rebuild's
+  half-built copy at once and stops. The remaining indexes keep working as
+  they are. Free some space and start it again; finished indexes are simply
+  rebuilt once more.
+- One run at a time. It is never retried automatically.
+
+## Reading the result
+
+The run's wide event `job.measurement_maintenance` carries
+`maintenance_outcome` (`completed`, `nothing_due` for the nightly check,
+`refused_purge_running`, `failed`), the live and dead rows the run started from, the
+table and index sizes before and after, and `maintenance_steps`, one entry
+per step with its target, size before and after, and duration. The same
+sizes from `psql`:
+
+```sql
+SELECT pg_size_pretty(pg_total_relation_size('measurements')) AS total,
+       pg_size_pretty(pg_indexes_size('measurements')) AS indexes;
+```
+
+## The nightly check
+
+Since v1.43.7 the same queue also runs by itself at 03:40 (Europe/Berlin).
+That run names no steps and changes nothing beyond dropping a retired index
+(next section): vacuuming the table is
+autovacuum's job, which migration 0412 starts at 5 % dead rows instead of
+Postgres's 20 %. The check reads the table's live and dead rows and warns
+(`maintenance_autovacuum_behind` on the wide event) when there are at least
+10,000 dead rows and more than one for every five live ones, four times the
+point at which autovacuum should already have run. That means autovacuum is
+not keeping up: look for a transaction left open for hours
+(`pg_stat_activity`, `state = 'idle in transaction'`) or for autovacuum
+workers busy elsewhere. The check never rebuilds an index. It shares the
+singleton key with the run you start, so the two never overlap. The admin
+card keeps showing only the runs you started.
+
+The check also measures how far the table file has grown past what its live
+rows need (`maintenance_bloat_factor` on the wide event, `bloat_factor` in the
+job result). Past 3 it adds a warning to the event: a vacuum makes the space
+reusable but does not shrink the file, and only `VACUUM FULL` does (see
+below).
+
+Why the table grew in the first place: until v1.43.7 an update that changed
+nothing still moved `updated_at`, which sits in an index, so no update could
+stay on its page. Migration 0412 keeps `updated_at` and `sync_version` on such
+an update and gives the table `fillfactor = 85` and a 5 % autovacuum
+threshold. To check that updates stay on their page:
+
+```sql
+SELECT n_tup_upd, n_tup_hot_upd, n_live_tup, n_dead_tup,
+       pg_size_pretty(pg_relation_size('measurements')) AS heap
+FROM pg_stat_user_tables WHERE relname = 'measurements';
+```
+
+`n_tup_hot_upd` should now grow along with `n_tup_upd`. The fill factor
+applies to pages written after the migration; a `VACUUM FULL` after the
+upgrade applies it to the whole table.
+
+## Retired indexes
+
+An index the schema no longer declares has to leave the database too, and on
+`measurements` the obvious migration is the wrong one. A plain `DROP INDEX`
+needs an exclusive lock on the table; `DROP INDEX CONCURRENTLY` blocks nobody
+but waits, without limit, for every transaction already running on the
+table. A migration runs at boot, so either one waits for whatever holds the
+table (a `pg_dump`, a long backfill, a `VACUUM FULL`); past the container's
+start period the container is replaced with the migration half done, and the
+next boot stops at `P3009` until someone runs `prisma migrate resolve`.
+
+So an index is retired in two halves (v1.43.8, migration 0416, for
+`measurements_user_id_type_measured_at_idx`):
+
+1. The migration tries a plain `DROP INDEX IF EXISTS` inside a `DO` block with
+   a two-second `lock_timeout` and catches the timeout
+   (`EXCEPTION WHEN lock_not_available`). When nothing holds the table the
+   index is gone at once; otherwise the migration still succeeds and the
+   index stays. The longest the table's other statements can wait behind the
+   attempt is those two seconds. A new database and Prisma's shadow database
+   always take the lock, so the migration history ends without the index,
+   exactly as the schema does, and `prisma migrate dev` / `migrate diff` see
+   no drift and generate nothing.
+2. The index name goes into `RETIRED_MEASUREMENT_INDEXES` in
+   `src/lib/jobs/measurement-maintenance.ts`. Every run of this job, the
+   nightly 03:40 check included, drops each name still present with
+   `DROP INDEX CONCURRENTLY IF EXISTS`, waiting at most 60 seconds for its
+   locks. A run that runs out of time leaves the index (possibly marked
+   invalid, which the next drop finishes), sets
+   `maintenance_retired_index_pending` on the wide event with a warning, and
+   the next night tries again. The index costs writes until then, as it did
+   before the release; nothing reads it.
+
+Until the job has run, the database holds one index the schema does not
+declare. Nothing compares the two at runtime, and the only place they are
+compared, a `migrate diff` against the migration history, never sees it. To
+check by hand:
+
+```sql
+SELECT indexname FROM pg_indexes
+ WHERE tablename = 'measurements'
+   AND indexname = 'measurements_user_id_type_measured_at_idx';
+```
+
+No row: it is gone. To drop it now rather than at night, start a run from the
+admin card (any steps), or run the same statement yourself:
+
+```sql
+SET lock_timeout = '60s';
+DROP INDEX CONCURRENTLY IF EXISTS "measurements_user_id_type_measured_at_idx";
+```
+
+For the next large index, follow the same two halves.
+`src/__tests__/migration-lock-timeout-guard.test.ts` refuses a
+`DROP INDEX CONCURRENTLY` in any migration and requires every retired name to
+have a migration that bounds its wait and catches the timeout.
+
+## "could not resize shared memory segment"
+
+Up to v1.42.0 the run could stop at once with `could not resize shared memory
+segment ... No space left on device`. Postgres ran the vacuum in parallel and
+kept its working memory in `/dev/shm`, which Docker limits to 64 MB per
+container unless `shm_size` is set. From v1.42.1 the maintenance connection
+runs single-process and needs no shared segment, and the bundled
+`docker-compose.yml` gives the database `shm_size: 256mb`. On v1.42.0, add
+`shm_size: 256mb` to the `db` service and restart the database container.
+
+## Not part of this
+
+`VACUUM FULL` would shrink the table file as well, but it locks the table for
+reads and writes while it runs, so no job starts it. When the nightly check
+warns about the bloat factor, run it yourself in a maintenance window with the
+app stopped.

docs/ops/migration-0409-plaintext-location.md

@@ -0,0 +1,98 @@
+# Upgrade stopped at migration 0409
+
+v1.43 removes the readable location columns that v1.42 replaced with sealed
+copies (`users.home_lat/home_lon/home_label`,
+`environment_contexts.lat/lon/location_label`,
+`environment_travel_locations.lat/lon/label`). Before it drops anything,
+migration `0409_drop_plaintext_location` checks that the v1.42 encryption
+backfill has sealed every one of those values. If any row still holds a
+readable location, the migration stops and the app container does not start.
+
+## What you see
+
+The container exits during the migration step with:
+
+```text
+A migration failed to apply. New migrations cannot be applied before the error is recovered from. ...
+Migration name: 0409_drop_plaintext_location
+Database error code: P0001
+Database error:
+ERROR: HealthLog migration 0409 stopped: 3 home location(s), 0 location period(s) and 12 daily location(s) are still stored in plaintext. ...
+```
+
+On every later start, Prisma refuses with `P3009` ("migrate found failed
+migrations in the target database") until the failed attempt is cleared.
+
+## What it means
+
+Nothing was lost and nothing was dropped. The check runs before any other
+statement in the migration, so the location columns and their values are all
+still there. The migrations before 0409 in the same image did apply; they only
+add tables, columns and enum values, so the previous release runs on top of
+them unchanged.
+
+The cause is a v1.42 instance that was not running long enough for its
+encryption backfill to reach every account, for example a host that went from
+v1.41 straight to v1.43, or one that was stopped soon after updating to v1.42.
+
+## How to recover
+
+The order matters: clear the failed attempt first, because the previous
+release runs `prisma migrate deploy` on start as well and refuses to boot
+while a failed migration is on record.
+
+```bash
+# 1. Mark the failed 0409 attempt as rolled back. The entrypoint is replaced
+#    so the container does not try to migrate first.
+docker compose run --rm --entrypoint sh app -c \
+  'NODE_PATH=/opt/prisma-cli/node_modules node /opt/prisma-cli/node_modules/prisma/build/index.js migrate resolve --rolled-back 0409_drop_plaintext_location'
+
+# 2. Start the previous release. Set this in the compose `.env` (or your
+#    platform's environment) and recreate the container.
+#      HEALTHLOG_IMAGE_REF=:v1.42.4
+docker compose up -d app
+```
+
+The previous release starts the encryption backfill about three minutes after
+boot and again once a day. It works through the accounts one at a time. Watch
+it with the three counts the migration checks; all three must reach 0:
+
+```bash
+docker compose exec -T db psql -U healthlog healthlog -c "
+  SELECT
+    (SELECT count(*) FROM users WHERE home_lat IS NOT NULL) AS home,
+    (SELECT count(*) FROM environment_travel_locations WHERE lat IS NOT NULL) AS periods,
+    (SELECT count(*) FROM environment_contexts WHERE lat IS NOT NULL) AS days;"
+```
+
+The app log shows each pass as
+`[free-text-encryption-backfill] user=... ` lines. If the counts stop going
+down, look for `[free-text-encryption-backfill] user=... failed` in the log;
+the error on the line after it names the cause.
+
+Once all three counts are 0:
+
+```bash
+# 3. Dump the database. This is the copy you go back to if anything else
+#    goes wrong; keep it with your encryption key.
+docker compose exec -T db pg_dump -U healthlog healthlog \
+  | gzip > healthlog-before-0409-$(date +%F).sql.gz
+
+# 4. Upgrade again: remove the pin (or set it to the new version) and
+#    recreate the container. Migration 0409 now runs through.
+docker compose pull app
+docker compose up -d app
+curl -s http://localhost:3000/api/version
+```
+
+## What not to do
+
+- Do not clear the readable columns by hand to get past the check. The
+  check exists because those values have no sealed copy yet; setting them to
+  `NULL` deletes the location for good.
+- Do not run `migrate resolve --applied 0409_drop_plaintext_location`. That
+  records the migration as done while the columns are still there, and the
+  v1.43 schema no longer matches the database.
+
+Background: [`deploy.md`](deploy.md) for the general update and rollback
+order, [`backup-restore.md`](backup-restore.md) for restoring a dump.

docs/ops/query-statistics.md

@@ -0,0 +1,29 @@
+# Query statistics (pg_stat_statements)
+
+From v1.42 the bundled database loads the `pg_stat_statements` library, so the time spent in each query shape can be read from the database itself. Loading the library only collects statistics in shared memory; nothing is sent anywhere.
+
+## Enable the view
+
+The library is loaded through the `command:` of the `db` service in `docker-compose.yml`. The first `docker compose up` after updating restarts the database once. Then create the extension once:
+
+```sh
+docker compose exec db psql -U healthlog -d healthlog -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements;"
+```
+
+## Read it
+
+The slowest query shapes by total time:
+
+```sh
+docker compose exec db psql -U healthlog -d healthlog -c "SELECT calls, round(total_exec_time) AS total_ms, round(mean_exec_time, 1) AS mean_ms, left(query, 120) AS query FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 15;"
+```
+
+The statements are stored with their parameters replaced by placeholders, so values from your records do not appear in the view.
+
+## Reset
+
+```sh
+docker compose exec db psql -U healthlog -d healthlog -c "SELECT pg_stat_statements_reset();"
+```
+
+If you run your own PostgreSQL instead of the bundled one, add `pg_stat_statements` to `shared_preload_libraries` in its configuration and restart it before creating the extension.

docs/self-hosting/account-sharing.md

@@ -189,9 +189,11 @@ no password, no passkey and no e-mail address, and it is never presented
 as something to log in as.
 
 - It is created from **Settings → Shared access**, under a fresh second
-  factor. An account with no second factor enrolled is refused rather than
-  waved through, because the act creates a permanent management
-  relationship over a person who cannot object to it.
+  factor. A passkey counts as one: a guardian who signs in with a passkey,
+  or confirms it in the dialog the app opens, gets through. An account with
+  neither a second factor nor a passkey is refused rather than waved
+  through, because the act creates a permanent management relationship
+  over a person who cannot object to it.
 - Creation takes a display name, optionally a real date of birth, and the
   language and timezone the record's own days and reminders are measured
   in. A year on its own is never turned into the first of January. The
@@ -231,11 +233,58 @@ as something to log in as.
   person it was sent to, so the admin notification diagnostic can answer
   "who was this for" and "whose record was it about" separately.
 
-There is no emancipation flow: no route, no control and no copy suggests
-a managed profile can be turned into an ordinary account. The data model
-leaves room for it (the credentials are nullable and the managed marker
-can be cleared) and clearing that marker stops the notification fan-out,
-but nothing in v1.37.0 exercises any of that.
+### Handing a record over to its person
+
+Since v1.42 a guardian can hand a managed profile over to the person it
+describes, so the record becomes their own account with its whole history.
+Nothing is copied or moved; the profile's row gets credentials, loses the
+managed marker, and stops fanning reminders out to its guardians.
+
+- A guardian with a fresh second factor creates a one-time link (valid for
+  one, seven or fourteen days, shown once) and proposes, for each guardian,
+  no access, view only or manage. Only a keyed hash of the link is stored,
+  at most one link per profile is open, and any guardian can withdraw it
+  without a second factor.
+- The person opens the link, sees the record's name, the expiry and who
+  keeps which access, and chooses how they sign in. The claim runs as one
+  transaction: the link is consumed, the proposals are applied, open
+  invitations the record offered are withdrawn, and the disclaimer,
+  onboarding and AI consent are reset so the person gives them themselves.
+  After the first sign-in they confirm or change each guardian's access.
+- How the person signs in depends on the instance:
+
+  | Instance                          | Ways in                    |
+  | --------------------------------- | -------------------------- |
+  | No SSO configured                 | Password                   |
+  | SSO configured, `OIDC_ONLY` unset | Password or single sign-on |
+  | `OIDC_ONLY="true"`                | Single sign-on only        |
+
+  The guardian's panel and the claim page both show which ways are open.
+
+- **Through single sign-on** (v1.43) the person picks a username and
+  continues to the identity provider. When they come back, the provider's
+  `(issuer, sub)` pair is bound to the record in the same transaction, the
+  address is taken from the provider only when it asserts
+  `email_verified: true` (otherwise the account has no address), and no
+  password is set. Refused, with the record left exactly as it was:
+  a provider identity that already signs in to an account on this instance
+  (one identity, one account; the refusal is audited on that account as
+  `auth.oidc.claim_conflict`), a verified address another account holds,
+  a username taken in the meantime, a link that was used, withdrawn,
+  replaced or expired while the person was at the provider, and a browser
+  that is signed in to another account.
+- The link never appears in a URL the server builds: the claim page sends it
+  in request bodies only, and the single-sign-on leg carries a sealed,
+  ten-minute, HttpOnly cookie that names the link by its id. The `/claim/`
+  path and `hlp_` tokens are scrubbed from logs.
+- The iOS app does not claim. The person claims in a browser and then signs
+  in to the app as usual (with SSO, through the app's own SSO sign-in).
+
+Audit rows: `managed_profile.handover.created` and `.revoked` on the record,
+`managed_profile.claim_sso.started` when a single-sign-on claim starts,
+`managed_profile.claimed` and `auth.claim` (with `method: "password"` or
+`"sso"`) when it lands, and `managed_profile.handed_over` on each guardian's
+own account.
 
 ## Seeing what happened
 
@@ -309,10 +358,11 @@ Four operational notes:
   and no address to look it up by.
 - **The second-factor requirement is not the same on both features, and
   the difference is deliberate.** Creating a managed profile, deleting
-  one and inviting a second guardian require a second factor
-  unconditionally: an account with none enrolled is refused and told to
-  set one up, because those acts create or end a permanent relationship
-  over somebody who cannot object. Offering manage access on an ordinary
-  invitation asks for a fresh factor only from an account that has one, so
+  one, handing it over and inviting a second guardian require a second
+  factor unconditionally, and a passkey counts as one there: an account
+  with neither is refused and told to set one up, because those acts
+  create or end a permanent relationship over somebody who cannot object.
+  Offering manage access on an ordinary invitation asks for a fresh factor
+  only from an account with TOTP or a security key, so
   an instance where nobody has enrolled a factor can still use every level
   of ordinary sharing. All of them are browser-only either way.

docs/self-hosting/environment.md

@@ -0,0 +1,110 @@
+# Weather, air quality and pollen
+
+The environment module stores, for each day, the weather and the outdoor air
+at a coarse location: temperature, sunshine, daylight, rain, pressure,
+humidity, and since v1.42 fine particles, ozone, nitrogen dioxide, the
+European and US air-quality indices, UV, Saharan dust and six kinds of
+pollen. Those days sit beside the person's own data: the correlations look
+for patterns between them and sleep, heart-rate variability, blood pressure,
+mood and symptoms, the Coach and connected MCP clients can read them, and the
+dashboard shows a quiet note on a day with high pollen, a warm night or very
+poor air.
+
+The module is on by default. Nothing leaves the host until a person sets a
+home location in Settings → Location & weather.
+
+## What leaves the host
+
+Three hosted Open-Meteo APIs, all keyless:
+
+| Host                             | What for                             | Variable to self-host it    |
+| -------------------------------- | ------------------------------------ | --------------------------- |
+| `archive-api.open-meteo.com`     | daily weather (ERA5 reanalysis)      | `OPENMETEO_BASE_URL`        |
+| `air-quality-api.open-meteo.com` | hourly air quality and pollen (CAMS) | `OPENMETEO_AIR_QUALITY_URL` |
+| `geocoding-api.open-meteo.com`   | the city search in settings          | `OPENMETEO_GEOCODING_URL`   |
+
+A request carries the coordinates rounded to one decimal (about 11 km, the
+size of a town), a date range and a timezone. No account id, no name, no
+health value. Open-Meteo is open source; an operator who wants no egress at
+all can run it and point the three variables at their own instance (a host
+on the LAN is allowed).
+
+## The data, and what it is not
+
+- Weather comes from the ERA5 reanalysis on a grid of 9 to 25 kilometres. It
+  settles over a few days, so the newest stored day is usually yesterday or
+  the day before. Nothing here is a forecast.
+- Air quality comes from the CAMS models: hourly on about 11 kilometres in
+  Europe, about 45 kilometres elsewhere. The feed starts in 2013; pollen, UV,
+  dust and aerosol depth only from about mid 2022, and pollen only in Europe.
+  A value the feed did not cover is stored as empty, never as zero.
+- Hourly values become a day by fixed rules: means and maxima only for a day
+  with at least 18 of 24 hours, ozone as the highest 8-hour running mean,
+  UV only when the midday hours are all there.
+- These are modelled outdoor conditions for an area, not anyone's personal
+  exposure. Every surface that shows them says so, and none of them says the
+  weather caused anything: a pattern is described as something that occurred
+  together.
+
+## Switches
+
+- **Per account:** Settings → Location & weather → Air quality and pollen.
+  On by default. Off stops the air-quality requests for that account and
+  leaves the air-quality values out of every surface; the days already
+  stored keep theirs.
+- **For the whole instance:** `ENVIRONMENT_AIR_QUALITY_DISABLED=1` turns the
+  air-quality part off for every account (`1`, `true`, `yes` or `on`). The
+  weather keeps working. Settings then says the operator turned it off.
+- The whole module is a normal module switch (Settings → Modules), and an
+  operator can make it unavailable like any other module.
+
+All four variables are on the compose `environment:` whitelist.
+
+## Request budget
+
+The hosted APIs are free for non-commercial use up to 600 calls a minute,
+5,000 an hour and 10,000 a day per instance, where a request for many
+variables or many days counts as several calls. HealthLog keeps its own
+counter in Postgres, shared by the web process and the worker, and stays
+below 500 a minute, 4,000 an hour and 8,000 a day. A request the counter
+refuses is not sent; the nightly run ends early and continues the next night.
+
+For scale: a full two-year backfill of one account is about 150 calls, the
+nightly refresh about 3 per account.
+
+## Nightly fetch and catching up
+
+The `environment-fetch` job runs at 02:10. For each account with a home it
+refreshes the last seven days (weather and air quality together), then fills
+up to 90 stored days that do not have air quality yet, newest first. An
+instance that upgrades to v1.42 with two years of weather per account
+catches up on air quality in about nine nights without any action. The
+backfill button in settings fetches both for the range it is given.
+
+## Locations are encrypted
+
+Since v1.42 the home, each dated location period and each stored day keep
+their coarse location sealed with the instance's encryption key (one value
+per row, `{ lat, lon, label }`, under the label
+`healthlog/environment-location/v1`). The boot-time encryption backfill seals
+rows written by older releases and clears their readable columns; the
+readable columns are dropped in a later release once the backfill reports
+zero rows everywhere. Key rotation (`scripts/rotate-encryption-key.ts`, or the
+in-app rotation) covers all three.
+
+What the person sees is unchanged: the settings page and
+`GET /api/environment` answer with the readable location, opened on the
+server. The Coach and MCP read (`get_environment`) carry no coordinate and no
+place name at all, only how many days were spent away from home.
+
+Backups follow the usual split: a portable export carries the location
+readable, a disaster-recovery backup carries it sealed, and a restore of
+either seals it under the receiving host's key.
+
+## Attribution
+
+Open-Meteo data is CC BY 4.0, and CAMS data asks for the notice "Contains
+modified Copernicus Atmosphere Monitoring Service information" (modified,
+because the hourly values are folded into days). The settings page lists
+both lines under the values, and the Coach and MCP read return them with
+every result.

docs/self-hosting/getting-started.md

@@ -11,14 +11,16 @@ already installed, longer if a TLS-fronted public hostname is in scope
   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. The app container is
-  capped at `APP_MEMORY_LIMIT`, `1536m` by default (Node then sizes its
-  heap at about 792 MB). On a 2 GB host that leaves too little for
-  Postgres and the system, so set `APP_MEMORY_LIMIT=1g` in `.env`
-  (a heap of about 524 MB); a long-used account then runs closer to
-  that heap, and the weekly backup with it.
+- **3 GB RAM (4 GB recommended), 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. The app
+  container is capped at `APP_MEMORY_LIMIT`, `1536m` by default (Node
+  then sizes its heap at about 792 MB), and Postgres and the system need
+  the rest. 1536 MB is the supported floor for the app container: do not
+  lower it to fit a smaller host. Below it, a long-used account or a large
+  import can fill the heap and restart the app; the app still starts, but
+  the boot log, the support report and Admin > System status say it runs
+  below the supported floor. On a busy instance, raise it.
 - **Outbound HTTPS** to `ghcr.io` (image pulls) plus whichever
   integration endpoints you plan to enable (Withings, OpenAI, etc.).
   The opt-in environmental-context module additionally reaches
@@ -77,6 +79,26 @@ process (`pnpm dev` against a host Postgres) or a **custom compose** that
 does not derive it — in that case uncomment and set `DATABASE_URL`
 explicitly in `.env` (see the commented example there).
 
+### Using an existing or shared Postgres
+
+HealthLog can live in a database on a Postgres instance you already run.
+It stores every time as UTC and pins each connection it opens to UTC
+(`TimeZone=UTC`, sent with the libpq `options` startup parameter), so the
+server's or the database's own `timezone` setting does not matter: an
+instance set to `Europe/Berlin` works the same as one set to UTC. The app
+checks the setting at startup and logs a warning naming the zone if a
+connection still reports something else.
+
+Behind PgBouncer with `DATABASE_SESSION_OPTIONS_DISABLED=1` (see
+[Scaling](./scaling.md#postgres-connection-pool-sizing)) the app pins the
+zone with `SET TIME ZONE 'UTC'` on each new connection instead; PgBouncer
+keeps that setting per client in transaction pooling too. If the startup
+warning still appears, set the database default as well:
+
+```sql
+ALTER DATABASE healthlog SET timezone TO 'UTC';
+```
+
 ## 3. Bring the stack up
 
 ```bash
@@ -198,6 +220,11 @@ NEXT_PUBLIC_DASHBOARD_SNAPSHOT=false pnpm build
 
 ## Troubleshooting
 
+- **Where to look.** For a bug report, copy the support report (Admin,
+  System status) and the support info (Settings, About), and note the error
+  id the failure showed. Admin, App logs finds the event behind an error id.
+  What each contains, and what it never contains, is in
+  [`support.md`](./support.md).
 - **`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 —
@@ -341,3 +368,46 @@ For off-host encrypted backups to S3/R2/B2 see
 [`docs/ops/backup-restore.md`](../ops/backup-restore.md); for rotating the
 encryption key safely (keep the old key until zero rows remain on it) see
 [`docs/ops/encryption-key-rotation.md`](../ops/encryption-key-rotation.md).
+
+## Updates
+
+A new image can bring database migrations, and `docker-entrypoint.sh`
+applies them on the first start of that image. Most are additive, but some
+rewrite data, and going back to the previous image does not undo them. The
+only way back from a migration that went wrong is the dump you took before
+it. So take one before every pull:
+
+```bash
+# 1. Dump the database (same command as under "Backup and restore").
+docker compose exec -T db pg_dump -U healthlog healthlog \
+  | gzip > healthlog-before-update-$(date +%F).sql.gz
+
+# 2. Pull the new image and recreate the app container.
+docker compose pull app
+docker compose up -d app
+
+# 3. Confirm the running build.
+curl -s http://localhost:3000/api/version
+```
+
+Keep the dump until the new version has run for a few days, and keep your
+encryption key with it: a dump without the key cannot be read.
+
+The start log says what is about to happen before the migrations run:
+
+```text
+HealthLog: 2 database migrations pending. Back up the database before updating (pg_dump, see the Updates section of docs/self-hosting/getting-started.md); a migration is not undone by going back to the previous image.
+HealthLog: Running database migrations...
+```
+
+or `HealthLog: Database schema is up to date.` when the image brings none.
+The line is a notice and does not pause the start: the migrations run right
+after it. So the dump belongs before step 2, not after you see the line; by
+then the database is already being migrated.
+
+If an update to v1.43 stops at migration `0409_drop_plaintext_location`,
+nothing was changed; the recovery is in
+[`docs/ops/migration-0409-plaintext-location.md`](../ops/migration-0409-plaintext-location.md).
+
+For the ordering on a host where you want the migration result before the
+new container takes traffic, see [`docs/ops/deploy.md`](../ops/deploy.md).

docs/self-hosting/mcp.md

@@ -30,7 +30,7 @@ Three things must be true before `/mcp` will answer:
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`APP_URL` is set**       | The endpoint fails closed without a pinned canonical origin. `APP_URL` (or `NEXT_PUBLIC_APP_URL`) is the origin every OAuth document and audience check is anchored to — `Host` is never trusted. Without it the surface stays invisible (`404`). |
 | **The global API is on**   | The operator's instance-wide API switch must be enabled (it is by default). With it off, every token path — including `/mcp` — returns `404`.                                                                                                     |
-| **The `mcp` module is on** | A per-account opt-in that ships off by default; you turn it on in Settings. Until then `/mcp` answers `404` for that account.                                                                                                                     |
+| **The `mcp` module is on** | A per-account opt-in that ships off by default; you turn it on in **Settings → Modules**. Until then `/mcp` answers `404` for that account.                                                                                                       |
 
 `APP_URL` is the same origin you already use for passkeys and invite
 links — for example `https://health.example`. It must be reachable by the
@@ -40,11 +40,15 @@ LAN-only origin works for Claude Desktop over stdio).
 
 ## 1. Enable the module
 
-In the app: **Settings → MCP**. The card has three parts:
+The switch lives with every other module: **Settings → Modules**, the
+**MCP** row. Turn it on and the `/mcp` endpoint goes live for your account.
 
-- **Enable** — the opt-in switch. Toggle it on; the `/mcp` endpoint goes
-  live for your account and the card shows your endpoint URL
-  (`<origin>/mcp`).
+**Settings → MCP** is where you use it. The page has three parts:
+
+- **State** — whether the module is on, with a link to its switch in
+  Modules, and your endpoint URL (`<origin>/mcp`). Turning the module off
+  pauses the endpoint; your tokens and connections stay and work again
+  once it is back on.
 - **Connections** — cloud connectors that completed the OAuth flow appear
   here; revoke any of them.
 - **Tokens** — manual connector tokens (see below).

docs/self-hosting/notifications.md

@@ -179,6 +179,12 @@ HealthLog publishes to that topic.
    **Server URL** (defaults to `https://ntfy.sh`; point it at your own
    server if you self-host ntfy) and **Topic**, then save.
 
+HealthLog publishes each message as JSON to the server's root URL (the topic
+travels in the body, see ntfy's
+[publish as JSON](https://docs.ntfy.sh/publish/#publish-as-json)), so titles
+and button labels in any language arrive as written. A reverse proxy in front
+of your own ntfy has to pass `POST /` through, not only `POST /<topic>`.
+
 If your ntfy server requires auth, an access token can be attached; the
 server URL is validated at save time and dialled through the egress guard
 (`src/lib/notifications/senders/ntfy.ts`). A self-hosted ntfy on your own
@@ -234,6 +240,8 @@ choice existed keeps sending:
   message are masked as they are on every other channel.
 - `priority` is a word: `urgent` for an event flagged urgent, `high` for
   medication reminders, `default` for everything else.
+- `url`, when `APP_URL` is set, is the page the notification leads to (see
+  [Tap targets](#what-tapping-a-notification-opens)). Absent otherwise.
 
 **Gotify** sends the body Gotify's `POST /message` endpoint expects:
 
@@ -450,6 +458,132 @@ Two gotchas worth knowing before you blame a stale token:
 > in the web UI. If you only run the PWA, ignore it entirely — your
 > medication reminders come from the server cron over the channels above.
 
+## Tap targets, content and quick answers
+
+### What tapping a notification opens
+
+Every notification leads somewhere in the app. The server decides where,
+once per event type, and every channel carries the same target:
+
+| Notification                                 | Opens                                                                              |
+| -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Mood reminder                                | `/mood`, with the mood entry sheet already open                                    |
+| Morning briefing                             | the dashboard                                                                      |
+| Medication reminder, low supply, shared dose | `/medications` (low supply opens the medication)                                   |
+| Check-up and measurement reminders           | `/checkups`                                                                        |
+| Proactive Coach nudge                        | the Coach conversation it started                                                  |
+| Cycle reminders                              | `/cycle` (the dashboard with discreet notifications on)                            |
+| New sign-in                                  | Settings, Security                                                                 |
+| Integration sync failing                     | Settings, Integrations (an admin alert about another account opens the admin page) |
+| Illness red flag                             | the illness episode                                                                |
+| Other system alerts                          | the dashboard, or the admin status page for operator alerts                        |
+
+How each channel carries it:
+
+- **ntfy**: the message's `click` field, so tapping the notification opens
+  the page.
+- **Telegram**: an **Open in HealthLog** button under the message, below any
+  action buttons. Telegram only accepts `https` button links on a public
+  host, so a plain-HTTP instance gets a text link instead, and an instance
+  on `localhost` gets no link.
+- **Web Push**: the service worker opens the page, or focuses an open
+  HealthLog tab and navigates it there.
+- **APNs**: the path rides the payload as `url`.
+- **Webhook**: the generic body gains a `url` field; the Gotify body gains
+  `extras["client::notification"].click.url`, which the Gotify app opens.
+- **Email**: a link line under the message.
+
+ntfy, Telegram, the webhook and email need an absolute link, built from
+`APP_URL` (or `NEXT_PUBLIC_APP_URL`). Without one those channels deliver as
+before, just without a link. A notification about a profile you look after
+as a Guardian opens the dashboard rather than the profile's page, because
+your session opens on your own record and the record switcher lives there.
+A discreet notification opens the dashboard as well, so its link names
+nothing. The silent background sync push for medication intake is the only
+notification without a link.
+
+### Health figures in notifications
+
+Settings, Notifications, **Health figures in notifications** decides what a
+notification may say on a lock screen:
+
+- **Off** (the default): a notification says what it is about and shows no
+  health figure. The morning briefing reads "Your morning briefing".
+- **On**: notifications add their figures. The morning briefing becomes
+  "Morning score 78" with the day's one-line summary underneath.
+
+Tap targets and quick answers work the same either way. The setting is
+stored as `content.detail` (`generic` or `detailed`) in the notification
+preferences (`PATCH /api/auth/me/notification-prefs`) and travels with the
+account backup.
+
+### Quick answers on the mood reminder
+
+On **ntfy** the mood reminder carries three buttons, **Good**, **Okay** and
+**Bad**. Tapping one logs a mood entry straight from the notification,
+without opening the app, and clears the notification. They map onto the
+five-point mood scale as Good = 4, Okay = 3, Bad = 2; the outer points
+stay in the app. The entry is marked with the source **Notification**.
+
+Each button calls `POST <APP_URL>/api/notifications/action/<token>`. The
+token is the only credential, so it is built to be harmless on its own:
+
+- it is signed with `API_TOKEN_HMAC_KEY` and names one account and one
+  answer, so it cannot be moved to another account or another answer;
+- it expires six hours after the reminder was sent;
+- the three answers of one reminder are one use between them: the first
+  tap logs, every later tap on that reminder is refused, and that stays
+  true when the logged entry is deleted and purged from the trash before
+  the six hours are up;
+- the route is rate-limited before it reads the token, refuses when the
+  mood module has been turned off, and the token is scrubbed from logs.
+
+The buttons need `APP_URL`, because the ntfy app calls the URL from your
+phone. Your phone has to reach the instance at that address.
+
+### Quick answers behind forward auth
+
+If the instance sits behind a forward-auth gateway (Authelia, Authentik,
+oauth2-proxy, Cloudflare Access and the like), the gateway answers the
+button's request with its login page and the answer is never logged: the
+ntfy app has no session with the gateway. Exempt the one path from the
+gateway:
+
+```
+/api/notifications/action/*
+```
+
+The route does not rely on the gateway. The signed token is its only
+credential, it is rate-limited before the token is read, and it can log one
+mood answer for one account and nothing else. Every other path stays behind
+the gateway.
+
+What the token cannot protect against is the topic itself. The button URLs,
+token included, travel through your ntfy server inside the message, and the
+message is delivered to everyone subscribed to the topic. For the six hours
+a token is valid, anyone who can read the topic can log that one answer on
+your behalf. On the public `ntfy.sh` the topic name is the only access
+control, so:
+
+- use a long, random topic name and do not share it;
+- better, run your own ntfy server with access control and give HealthLog
+  an access token that may only publish to your topic;
+- to invalidate every quick-answer token at once, rotate
+  `API_TOKEN_HMAC_KEY`. The same key also hashes API tokens and session
+  cookies, so rotating it invalidates every issued API token and signs out
+  every browser session and the iOS app as well (see
+  [getting started](./getting-started.md)).
+
+**Telegram** keeps its own keyboard on the mood reminder: the full 1 to 5
+scale, a note and a "later" button.
+
+**Web Push** offers no buttons. Most browsers show at most two actions,
+which cannot carry a three-way answer, and Safari on iPhone shows none.
+Tapping the notification opens the mood entry sheet instead.
+
+**APNs**: the iOS app draws its own buttons from the notification category
+it registers for the mood reminder.
+
 ## Which channel should I pick?
 
 | Your setup                                        | Recommended channel                                                                                                                                                                    |

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

@@ -90,8 +90,11 @@ different things depending on which button you press.
   it out and it is gone from the app, from exports, and from the doctor
   report. The row itself stays in PostgreSQL as a tombstone, which is
   what lets a phone that was offline at delete time learn that the entry
-  went away. No job removes cycle tombstones on a schedule, so the row
-  stays until one of the two actions below.
+  went away. A nightly job removes a tombstone 75 days after the delete
+  (the same horizon as the sync feed's); until then, or until one of the
+  two actions below, the row stays. A start that was folded into a later
+  cycle stays for as long as that cycle does, because deleting the later
+  cycle gives it back.
 - **Settings → Delete All Data** removes the rows outright, tombstones
   included. Everything the account owns goes except what you sign in
   with; the confirmation dialog lists it.

docs/self-hosting/scaling.md

@@ -79,9 +79,13 @@ Raise the limit on the container that runs the worker and re-upload:
 services:
   app:
     environment:
-      NODE_OPTIONS: --max-old-space-size=1024
+      NODE_OPTIONS: --max-old-space-size=1024 --report-on-fatalerror --report-filename=stderr --report-exclude-env --report-exclude-network
 ```
 
+Your `NODE_OPTIONS` replaces the image's, so carry the four `--report-*`
+flags over: they make an out-of-memory exit leave a diagnostic report in
+the container log (see `docs/ops/heap-diagnostics.md`).
+
 An import interrupted by a container restart or an out-of-memory kill
 does not stay stuck: the worker reconciles non-terminal import jobs at
 boot and every 15 minutes, flipping orphaned rows to `failed`
@@ -188,6 +192,20 @@ already`. Either raise `max_connections` on the Postgres side, lower
 `DATABASE_POOL_MAX`, or front the database with PgBouncer in
 transaction-pooling mode.
 
+The app sets its statement timeout, `work_mem` and `TimeZone=UTC` on every
+connection through the libpq `options` startup parameter. PgBouncer refuses that
+parameter (`unsupported startup parameter: options`) unless it is listed
+in `ignore_startup_parameters`. Either list it there, or set
+`DATABASE_SESSION_OPTIONS_DISABLED=1` so the app sends no session
+settings; set the timeout and `work_mem` on the database role instead
+(`ALTER ROLE healthlog SET work_mem = '16MB'`) if you still want them.
+The time zone is the exception: with the options off the app pins it with
+`SET TIME ZONE 'UTC'` on each new connection, which PgBouncer tracks per
+client, and warns at startup if a connection still reports another zone.
+The measurement maintenance job (Admin, System status) then applies its own
+settings with `SET` after connecting. Its concurrent index rebuild needs a
+session, so run it through a session-mode pool or a direct connection.
+
 ### Overriding the per-container pool ceiling
 
 With the bundled compose, set `DB_CONNECTION_LIMIT` in `.env`; it

docs/self-hosting/sso.md

@@ -112,6 +112,12 @@ Client registration essentials only — the IdP's own docs cover the rest.
   MFA in the IdP's policy engine — that is the point of delegating
   authentication. HealthLog-side 2FA remains available on top for the
   step-up gates above.
+- **Claiming a managed profile binds a fresh identity only.** When a
+  person claims a managed profile through SSO, their `(issuer, sub)` is
+  bound to that record, and only if no account on the instance already
+  holds it, and the provider's address is used only when it is verified
+  and not already taken. A claim can therefore never attach somebody's
+  existing sign-in to a second record or take over an existing account.
 - **Linking is once.** There is no unlink/relink flow in this cut; the
   pin is deliberately sticky. Moving an account to a new IdP identity is
   an operator decision (a manual `users.oidc_issuer` / `users.oidc_sub`
@@ -134,6 +140,10 @@ Consequences to accept before turning it on:
 - **Self-disabling on half-config.** The flag only takes effect while
   the three provider vars are fully set, so a typo in the provider group
   can never lock every user out.
+- **Managed profiles are still handed over** (v1.43). The person claims the
+  record through the identity provider instead of setting a password; the
+  password claim is refused. See
+  [Handing a record over to its person](account-sharing.md#handing-a-record-over-to-its-person).
 
 ### Break-glass (IdP down or misconfigured)
 

docs/self-hosting/support.md

@@ -0,0 +1,105 @@
+# Reporting a problem
+
+HealthLog does not send anything home, and nobody but the operator can read
+an instance's logs. So a bug report has to carry what is needed to find the
+fault. Two texts do that, and both are redacted before you see them.
+
+| Who      | Where                                    | What it is                                 |
+| -------- | ---------------------------------------- | ------------------------------------------ |
+| Everyone | Settings, About, **Copy support info**   | Your app version, settings and connections |
+| Operator | Admin, System status, **Support report** | The whole instance, accounts as numbers    |
+
+Add the **error id** of the failure if you have one, and paste both texts into
+the [bug report](https://github.com/MBombeck/HealthLog/issues/new?template=bug_report.yml).
+Read them before you post. They are built to contain nothing personal, but
+you are the one publishing them.
+
+## Error ids
+
+When the server fails (a 5xx answer), the message shows **Error ID** and
+eight characters, for example `3f9a2c1b`, with a copy button that copies the
+full id. A page that fails to render shows one too when the server has one
+to give: the request id of the failed call, or the digest the server printed
+beside the stack in its log.
+
+The id is the request id of the failing call. Every error answer of the API
+carries it in `meta.requestId` and in the `x-request-id` header. An incoming
+`x-request-id` is only adopted when it consists of letters, digits and hyphens
+(8 to 64 characters); anything else is replaced with a fresh id.
+
+The operator finds the event under **Admin, App logs** by typing the id (or
+its first 8 characters) into **Error ID**. A search by id reads the second log
+buffer, which keeps the last 1,000 warnings and errors of the process. Ordinary
+traffic cannot push them out, so an error stays findable for much longer than
+in the main buffer of 500 events. Both buffers live in memory: a restart
+empties them, and a split `web` / `worker` deployment has one per process.
+
+The same search works on the API:
+
+```
+GET /api/admin/app-logs?requestId=3f9a2c1b&ring=problems
+```
+
+A 4xx answer (a refused input, a missing permission) shows no id. Its message
+says what to change.
+
+## Support info (everyone)
+
+**Settings, About, Copy support info** puts together, in your browser:
+
+- server version and build, and your browser;
+- language, time zone and the modules you have switched on;
+- the AI state: whether a provider is set up, your usage level, and which AI
+  features are available and why not;
+- for each connected source (Withings, Oura, and so on), its health state,
+  reason, last success, newest data and the last recorded sync attempts;
+- the last five error ids of this browser session.
+
+It never contains your username, email address, name, server address,
+tokens, recorded values or record ids. Nothing is sent anywhere; the text
+goes to your clipboard.
+
+## Support report (operator)
+
+**Admin, System status, Support report** creates a text with **Copy** and
+**Download**. It is created when you press a button, not on page load, and
+shown above the buttons so you can read it first. It contains:
+
+- **Build:** version, build SHA, build time, Node, process type, heap limit,
+  uptime.
+- **Database:** PostgreSQL version, server time zone, size, last applied
+  migration, unfinished migrations.
+- **Configuration**, as yes or no only: secure cookie flag, OIDC, OIDC only,
+  Loki, GlitchTip, off-host backup, APNs, Web Push, SMTP, GeoLite2, the number
+  of `NOTIFICATION_PRIVATE_ORIGINS` entries, operator AI key, central Codex,
+  the AI provider types accounts chose, demo mode.
+- **Jobs:** whether the worker runs in this process and when it last
+  reported, the newest finished job, and every queue with failures in the
+  last 72 hours with an error class (`timeout`, `TypeError`, `P2002`,
+  `ECONNREFUSED`, an HTTP status), never the message.
+- **Connections:** per source, how many accounts are in each health state and
+  reason, which accounts are not `ok`, and open watchdog incidents.
+- **AI:** the usage level default and ceiling, accounts per usage level, and
+  the provider ledger per provider type (working, failing, credential
+  refused, paused).
+- **Notifications:** per channel, delivered, failed and skipped in the last 7
+  days, with the most frequent failure reasons.
+- **Backups:** newest in-database copy, the last weekly run, off-host
+  freshness, and the last restore drill.
+- **Recent warnings and errors:** the 20 most frequent action names in the
+  warning and error buffer of this process, with count, last seen and error
+  class.
+
+Accounts appear as `Account 1`, `Account 2` and so on, numbered by creation.
+The report never contains an email address, a username, an account id, a
+recorded value, a token, or the host name of another service. As a second
+layer, the finished text is scrubbed for the instance's own usernames,
+emails, names and ids, for tokens, URLs, email addresses, ids, IP addresses
+and host names before it is shown.
+
+## Logs beyond the report
+
+`docker compose logs app` prints every wide event as one JSON line;
+`LOG_LEVEL=debug` adds debug events. With `LOKI_ENDPOINT` set the same events
+go to Loki, and GlitchTip (Admin, General) receives unexpected server errors.
+Each line carries `request_id`, so an error id finds its line there too.

docs/self-hosting/truenas.md

@@ -13,7 +13,7 @@ one value you must keep yourself: the encryption key.
 | Port         | `3000` (HTTP)                                                                            |
 | User         | runs as uid `1001`; no extra capabilities, `no-new-privileges` is fine                   |
 | Health check | `GET /api/health`, `200` when ready                                                      |
-| Start period | at least 60 s, with more retries than the image's 3 × 30 s: migrations run at every boot |
+| Start period | at least 60 s, with more retries than the image's 5 × 30 s: migrations run at every boot |
 | Database     | PostgreSQL 16 (17 and later are not a drop-in), no extensions                            |
 | Volumes      | none for the app; the database gets its own dataset                                      |
 

docs/ui-guidelines.md

@@ -1,9 +1,10 @@
 # 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.
+> Visual & interaction patterns in the HealthLog PWA. The binding rules
+> for card anatomy, spacing, text colour, tokens and primitives live in
+> [`contributing/ui-standards.md`](./contributing/ui-standards.md); where
+> this document disagrees with them, the standards win. If a pattern
+> below doesn't fit your case, propose an addition in the same PR.
 
 Last updated: 2026-05-08 (v1.4 cycle)
 
@@ -132,7 +133,8 @@ 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/`.
+Forms keep a controlled draft in component state and validate it with the
+Zod schemas from `src/lib/validations/`; the server's schema is the authority.
 Wrap inputs in `<label>` (visible) plus `aria-describedby` for helper text.
 
 - **Text / number / email**: `<Input>`. Always set `autocomplete`. See §4.4.
@@ -425,8 +427,7 @@ control. Behavior:
 
 ### 4.6 Server actions and mutations
 
-We use `react-hook-form` + TanStack Query mutations, never raw fetch
-calls in components. Every mutation:
+Mutations go through TanStack Query, 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).

docs/using/search.md

@@ -0,0 +1,55 @@
+# Searching your record
+
+The command palette finds pages and settings, and it searches what you have
+recorded.
+
+## Opening it
+
+Press **⌘K** on a Mac or **Ctrl K** elsewhere, or tap the magnifier at the
+top right, and start typing.
+
+## What it finds
+
+Below the pages and settings, a section **In your records** lists the
+entries that match what you typed:
+
+- visits (procedures included)
+- conditions
+- documents, by title, file name and the text read from them
+- vaccinations
+- lab results
+- medications
+- symptoms
+- workouts
+- notes on mood entries, readings and illness days
+
+Each hit opens where the entry lives: a visit on the check-ups page, a lab
+result on its analyte, a note on a mood entry or a reading on its day, a note
+on an illness day in its illness.
+
+## How matching works
+
+Case and accents do not matter, so "schulter", "Schulter" and "Schülter"
+find the same entries. Umlauts can be typed as `ae`, `oe` and `ue` (and `ß`
+as `ss`), which helps on a keyboard without them.
+
+## Very large records
+
+The search reads each kind of entry newest first and stops after a fixed
+number of entries and a short time limit, so it stays quick on a record that
+holds years of data. When it stopped before reaching the oldest entries, the
+list says so. A more specific search term usually finds an older entry.
+
+## Shared records
+
+When someone has shared their whole record with you, the search works inside
+that record too. An account shared with you section by section cannot be
+searched: the search lays every section side by side, which a partial share
+does not open.
+
+## Privacy
+
+What you type is sent to your instance in the body of the request, not in the
+address, so it does not end up in a reverse proxy's access log or in the
+browser history. The server does not log the search text either, only its
+length and how many hits it found.

e2e/a11y.spec.ts

@@ -605,6 +605,35 @@ async function installA11yMocks(page: Page) {
       pdfSupported: true,
     }),
   );
+  // The lab list reads one row per marker from the overview route.
+  await page.route("**/api/labs/overview", (route) =>
+    fulfilJson(route, {
+      markers: [
+        {
+          key: "analyte:a11y ldl",
+          count: 1,
+          trend: [2.4],
+          latest: {
+            id: "a11y-lab",
+            biomarkerId: null,
+            panel: "A11y panel",
+            analyte: "A11y LDL",
+            value: 2.4,
+            valueText: null,
+            unit: "mmol/L",
+            referenceLow: 0,
+            referenceHigh: 3,
+            takenAt: "2026-07-19T12:00:00.000Z",
+            source: "MANUAL",
+            hasNote: false,
+            rangeStatus: "inRange",
+            createdAt: "2026-07-19T12:00:00.000Z",
+            updatedAt: "2026-07-19T12:00:00.000Z",
+          },
+        },
+      ],
+    }),
+  );
   await page.route("**/api/labs?*", (route) =>
     fulfilJson(route, {
       results: [

e2e/achievements.spec.ts

@@ -3,7 +3,7 @@ import { expect, test } from "./setup/test";
 import { STORAGE_STATE_PATH } from "./setup/global-setup";
 
 /**
- * v1.4.15 phase-B4 — /achievements navigation smoke.
+ * v1.4.15 — /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

e2e/activity-calendar.spec.ts

@@ -0,0 +1,68 @@
+import { expect, test } from "./setup/test";
+
+import { STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * The activity calendar on the workouts page (D1036), at phone width: the
+ * card renders a whole-week grid, pages back a period, switches to the week
+ * view, and the goals sheet saves a goal the calendar then reports.
+ */
+test.describe("activity calendar", () => {
+  test.use({
+    storageState: STORAGE_STATE_PATH,
+    viewport: { width: 390, height: 844 },
+  });
+
+  test("draws the month, pages back and switches to a week", async ({
+    page,
+  }) => {
+    await page.goto("/insights/workouts");
+    const card = page.locator('[data-slot="activity-calendar"]');
+    await expect(card).toBeVisible();
+    await expect(
+      page.locator('[data-slot="activity-calendar-label"]'),
+    ).not.toHaveText("");
+
+    const days = page.locator('[data-slot="activity-calendar-day"]');
+    const monthCount = await days.count();
+    if (monthCount > 0) expect(monthCount % 7).toBe(0);
+
+    const label = page.locator('[data-slot="activity-calendar-label"]');
+    const before = await label.textContent();
+    await page.locator('[data-slot="activity-calendar-previous"]').click();
+    await expect(label).not.toHaveText(before ?? "");
+
+    await expect(card).toHaveAttribute("data-period", "month");
+    await page.locator('[data-slot="activity-calendar-period-week"]').click();
+    await expect(card).toHaveAttribute("data-period", "week");
+    if ((await days.count()) > 0) await expect(days).toHaveCount(7);
+
+    // Nothing in the card pushes the page sideways on a phone.
+    const overflow = await page.evaluate(
+      () =>
+        document.documentElement.scrollWidth -
+        document.documentElement.clientWidth,
+    );
+    expect(overflow).toBeLessThanOrEqual(0);
+  });
+
+  test("saves a goal and shows its progress", async ({ page }) => {
+    await page.goto("/insights/workouts");
+    await page.locator('[data-slot="activity-calendar-set-goals"]').click();
+    const field = page.locator(
+      '[data-slot="activity-goals-form"] [data-goal-key="stepsPerMonth"]',
+    );
+    const goal = page.locator(
+      '[data-slot="activity-calendar-goal"][data-goal-key="stepsPerMonth"]',
+    );
+    await field.fill("150000");
+    await page.locator('[data-slot="activity-goals-save"]').click();
+    await expect(goal).toBeVisible();
+
+    // Clear it again so the account is left as it was found.
+    await page.locator('[data-slot="activity-calendar-set-goals"]').click();
+    await field.fill("");
+    await page.locator('[data-slot="activity-goals-save"]').click();
+    await expect(goal).toHaveCount(0);
+  });
+});

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

@@ -3,7 +3,7 @@ import { expect, test } from "./setup/test";
 import { STORAGE_STATE_PATH } from "./setup/global-setup";
 
 /**
- * v1.4.16 A3 — `/admin/api-tokens` must not produce horizontal page
+ * v1.4.16 — `/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 the maintainer still saw a
  * scrollbar on prod. The v1.4.16 fix swaps the desktop `<table>` for a
@@ -75,7 +75,7 @@ test.describe("/admin/api-tokens mobile no-overflow", () => {
     ).toBeLessThanOrEqual(dims.innerWidth + 1);
   });
 
-  // v1.4.18 phase A2 — production probe at Pixel-5 viewport pinned the
+  // v1.4.18 — production probe at Pixel-5 viewport pinned the
   // visible "scrollbar" the maintainer 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)
@@ -119,7 +119,7 @@ test.describe("/admin/api-tokens mobile no-overflow", () => {
     expect(stripDims.scrollWidth).toBeGreaterThan(stripDims.clientWidth);
   });
 
-  // v1.4.19 phase A7 (4th attempt) — even with the mobile-strip
+  // v1.4.19 (4th attempt) — even with the mobile-strip
   // `no-scrollbar` fix from v1.4.18, the maintainer still reported a painted
   // scrollbar. The card body itself must not contribute any
   // horizontal-overflow culprit: every element inside the api-tokens

e2e/ai-optional-account.spec.ts

@@ -74,7 +74,11 @@ test("J5: withdrawing AI consent deletes the notes written under it", async ({
   );
   await page.locator('[data-slot="ai-consent-withdraw-confirm"]').click();
   expect((await withdrawn).status()).toBe(200);
-  await expect(page.locator('[data-slot="ai-consent-grant"]')).toBeVisible();
+  // On a local model nothing needs the consent, so once withdrawn there is
+  // nothing to withdraw and nothing to ask.
+  await expect(page.locator('[data-slot="ai-consent-withdraw"]')).toHaveCount(
+    0,
+  );
 
   await openOverview(page);
   await expect(page.getByText(marker)).toHaveCount(0);

e2e/ai-provider-dropdown.spec.ts

@@ -3,7 +3,7 @@ import { expect, test } from "./setup/test";
 import { STORAGE_STATE_PATH } from "./setup/global-setup";
 
 /**
- * v1.4.16 phase B2 — AI provider settings UX with single dropdown
+ * v1.4.16 — 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

e2e/bottom-sheet.spec.ts

@@ -0,0 +1,536 @@
+import type { Locator, Page } from "@playwright/test";
+
+import { mockDay } from "./setup/day-mock";
+import { expect, test } from "./setup/test";
+import { MOBILE_ROUTES_STORAGE_STATE_PATH } from "./setup/global-setup";
+
+/**
+ * The bottom sheet's drag on WebKit with an iPhone profile (the
+ * `webkit-iphone` project), against the three kinds of bottom sheet the app
+ * has: the More sheet (a plain `<Sheet side="bottom">`), the day sheet (the
+ * preview step) and a capture form (`ResponsiveSheet` on a phone).
+ *
+ * Playwright can tap on WebKit but not move a touch, so a drag is dispatched
+ * through the page as the browser would deliver it: `pointerdown` /
+ * `pointermove` / `pointerup` with `pointerType: "touch"` and the matching
+ * `touchstart` / `touchmove` / `touchend`, on the element under the finger,
+ * paced in real time so the release speed is real. Nothing calls into the
+ * sheet's own code. What synthetic events cannot do is scroll natively, so
+ * "content scrolls first" is proven as "a scrolled body does not move the
+ * sheet", with the scroll position set the way a scroll would leave it.
+ *
+ * Stable hooks only: `bottom-nav-more` / `bottom-nav-more-sheet`,
+ * `day-panel` with `data-sheet-snap`, `day-body`, `day-footer`,
+ * `sheet-grip`, `sheet-close-button`, `sheet-overlay`, `capture-picker-*`.
+ */
+
+interface Drag {
+  dx?: number;
+  dy: number;
+  /** Duration of the movement, ms. */
+  ms: number;
+  steps?: number;
+  /** Rest before lifting the finger, ms (a slow, deliberate release). */
+  holdMs?: number;
+  /**
+   * After the rest, keep the finger down until the page has rendered this
+   * many frames. The sheet writes its position once per animation frame, and
+   * WebKit in the CI container can go a second or more without rendering a
+   * frame while timers and events run on (the trace shows the More sheet
+   * still sliding in 1.5 s after its animation reported finished). A check
+   * on where the sheet was drawn needs those frames; a check on where it
+   * ends up does not, because the release is decided from the touch alone.
+   */
+  holdFrames?: number;
+}
+
+/** A touch drag from (x, y), dispatched as WebKit delivers one. */
+async function touchDrag(page: Page, x: number, y: number, drag: Drag) {
+  await page.evaluate(
+    async ({ x, y, dx, dy, ms, steps, holdMs, holdFrames }) => {
+      const target = document.elementFromPoint(x, y);
+      if (!target) throw new Error(`nothing under ${x},${y}`);
+      const id = 11;
+      const touchAt = (cx: number, cy: number) => {
+        const init = {
+          identifier: id,
+          target,
+          clientX: cx,
+          clientY: cy,
+          pageX: cx,
+          pageY: cy,
+          screenX: cx,
+          screenY: cy,
+          radiusX: 4,
+          radiusY: 4,
+          force: 1,
+        };
+        try {
+          return new Touch(init);
+        } catch {
+          return init as unknown as Touch;
+        }
+      };
+      const touchEvent = (type: string, cx: number, cy: number) => {
+        const touch = touchAt(cx, cy);
+        const touches = type === "touchend" ? [] : [touch];
+        try {
+          return new TouchEvent(type, {
+            touches,
+            targetTouches: touches,
+            changedTouches: [touch],
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+          });
+        } catch {
+          const event = new Event(type, {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+          });
+          Object.defineProperty(event, "touches", { value: touches });
+          Object.defineProperty(event, "targetTouches", { value: touches });
+          Object.defineProperty(event, "changedTouches", { value: [touch] });
+          return event;
+        }
+      };
+      const fire = (
+        pointer: "pointerdown" | "pointermove" | "pointerup",
+        cx: number,
+        cy: number,
+      ) => {
+        target.dispatchEvent(
+          new PointerEvent(pointer, {
+            pointerId: id,
+            pointerType: "touch",
+            isPrimary: true,
+            clientX: cx,
+            clientY: cy,
+            buttons: pointer === "pointerup" ? 0 : 1,
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+          }),
+        );
+        const touch = {
+          pointerdown: "touchstart",
+          pointermove: "touchmove",
+          pointerup: "touchend",
+        }[pointer];
+        target.dispatchEvent(touchEvent(touch, cx, cy));
+      };
+      const wait = (t: number) => new Promise((r) => setTimeout(r, t));
+      fire("pointerdown", x, y);
+      for (let i = 1; i <= steps; i += 1) {
+        await wait(ms / steps);
+        fire("pointermove", x + (dx * i) / steps, y + (dy * i) / steps);
+      }
+      if (holdMs) await wait(holdMs);
+      for (let i = 0; i < holdFrames; i += 1) {
+        await new Promise((r) => requestAnimationFrame(() => r(null)));
+      }
+      fire("pointerup", x + dx, y + dy);
+    },
+    {
+      x,
+      y,
+      dx: drag.dx ?? 0,
+      dy: drag.dy,
+      ms: drag.ms,
+      steps: drag.steps ?? Math.max(4, Math.round(drag.ms / 16)),
+      holdMs: drag.holdMs ?? 0,
+      holdFrames: drag.holdFrames ?? 0,
+    },
+  );
+}
+
+/**
+ * The browser's pointer capture for a dispatched pointer. A real touch is
+ * captured by the browser; a dispatched one is not, and Radix's slider only
+ * follows a pointer it holds. This gives it the same bookkeeping, nothing
+ * more: events still go to the element they are dispatched on.
+ */
+async function emulateCapture(page: Page) {
+  await page.addInitScript(() => {
+    const held = new WeakMap<Element, Set<number>>();
+    Element.prototype.setPointerCapture = function (id: number) {
+      const set = held.get(this) ?? new Set<number>();
+      set.add(id);
+      held.set(this, set);
+    };
+    Element.prototype.hasPointerCapture = function (id: number) {
+      return held.get(this)?.has(id) ?? false;
+    };
+    Element.prototype.releasePointerCapture = function (id: number) {
+      held.get(this)?.delete(id);
+    };
+  });
+}
+
+async function centre(locator: Locator) {
+  const box = await locator.boundingBox();
+  if (!box) throw new Error("not on screen");
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2, box };
+}
+
+async function topOf(locator: Locator) {
+  return (await locator.boundingBox())?.y ?? NaN;
+}
+
+/** Waits for the sheet to come to rest (open slide or settle finished). */
+async function settled(locator: Locator) {
+  await expect
+    .poll(() =>
+      locator.evaluate((el) =>
+        el.getAnimations().every((a) => a.playState !== "running"),
+      ),
+    )
+    .toBe(true);
+  // A finished animation is not a drawn one: WebKit can report the slide
+  // done while it has not rendered a frame of it yet. Two frames, then rest.
+  await locator
+    .page()
+    .evaluate(
+      () =>
+        new Promise<void>((resolve) =>
+          requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+        ),
+    );
+  await locator.page().waitForTimeout(300);
+}
+
+const more = (page: Page) =>
+  page.locator('[data-testid="bottom-nav-more-sheet"]');
+
+async function openMore(page: Page) {
+  await page.locator('[data-testid="bottom-nav-more"]').tap();
+  await expect(more(page)).toBeVisible();
+  await settled(more(page));
+}
+
+function isoDaysAgo(days: number): string {
+  const d = new Date(Date.now() - days * 86_400_000);
+  return d.toISOString().slice(0, 10);
+}
+
+test.describe("the bottom sheet", () => {
+  test.use({ storageState: MOBILE_ROUTES_STORAGE_STATE_PATH });
+
+  test.beforeEach(async ({ page, context }, testInfo) => {
+    const baseURL = testInfo.project.use.baseURL ?? "http://localhost:3000";
+    await context.addCookies([
+      { name: "healthlog-locale", value: "en", url: baseURL },
+    ]);
+    await mockDay(page);
+  });
+
+  test("a slow drag past a quarter of its height closes it", async ({
+    page,
+  }) => {
+    await page.goto("/mood");
+    await openMore(page);
+    const title = more(page).getByRole("heading").first();
+    const { x, y } = await centre(title);
+    const { box } = await centre(more(page));
+    await touchDrag(page, x, y, {
+      dy: box.height * 0.4,
+      ms: 700,
+      holdMs: 160,
+    });
+    await expect(more(page)).toHaveCount(0);
+  });
+
+  test("a short drag springs back", async ({ page }) => {
+    await page.goto("/mood");
+    await openMore(page);
+    await expect(more(page)).toBeVisible();
+    const before = await topOf(more(page));
+    const { x, y } = await centre(more(page).getByRole("heading").first());
+    // Dragging: the sheet follows the finger and the backdrop lightens. A
+    // frame loop records the furthest the sheet travelled and the lightest
+    // the backdrop got for the whole gesture, so a slow runner cannot make
+    // a single fixed-time sample land before the drag has begun.
+    await page.evaluate(() => {
+      const w = window as unknown as {
+        __sheetDrag?: { moved: number; opacity: number; on: boolean };
+      };
+      w.__sheetDrag = { moved: 0, opacity: 1, on: true };
+      const tick = () => {
+        const rec = w.__sheetDrag!;
+        if (!rec.on) return;
+        const sheet = document.querySelector(
+          '[data-testid="bottom-nav-more-sheet"]',
+        ) as HTMLElement | null;
+        const overlay = document.querySelector(
+          '[data-slot="sheet-overlay"]',
+        ) as HTMLElement | null;
+        if (sheet) {
+          const moved = new DOMMatrix(getComputedStyle(sheet).transform).f;
+          rec.moved = Math.max(rec.moved, moved);
+        }
+        if (overlay) {
+          rec.opacity = Math.min(
+            rec.opacity,
+            Number(getComputedStyle(overlay).opacity),
+          );
+        }
+        requestAnimationFrame(tick);
+      };
+      requestAnimationFrame(tick);
+    });
+    // Two rendered frames with the finger still down: the first paints the
+    // sheet where the finger is, the second lets the recorder read it.
+    await touchDrag(page, x, y, {
+      dy: 60,
+      ms: 300,
+      holdMs: 200,
+      holdFrames: 2,
+    });
+    const seen = await page.evaluate(() => {
+      const w = window as unknown as {
+        __sheetDrag: { moved: number; opacity: number; on: boolean };
+      };
+      w.__sheetDrag.on = false;
+      return { moved: w.__sheetDrag.moved, opacity: w.__sheetDrag.opacity };
+    });
+    expect(seen.moved).toBeGreaterThan(40);
+    expect(seen.opacity).toBeLessThan(1);
+    await settled(more(page));
+    await expect(more(page)).toBeVisible();
+    expect(Math.abs((await topOf(more(page))) - before)).toBeLessThan(1);
+  });
+
+  test("a fast flick closes it", async ({ page }) => {
+    await page.goto("/mood");
+    await openMore(page);
+    const { x, y } = await centre(more(page).getByRole("heading").first());
+    const { box } = await centre(more(page));
+    // Well short of a quarter of the height, but fast.
+    await touchDrag(page, x, y, {
+      dy: Math.min(70, box.height * 0.2),
+      ms: 40,
+      steps: 4,
+    });
+    await expect(more(page)).toHaveCount(0);
+  });
+
+  test("the backdrop, the X and Escape close it; focus goes back to the trigger", async ({
+    page,
+  }) => {
+    await page.goto("/mood");
+    const trigger = page.locator('[data-testid="bottom-nav-more"]');
+
+    await openMore(page);
+    await page.touchscreen.tap(195, 40);
+    await expect(more(page)).toHaveCount(0);
+
+    await openMore(page);
+    const close = more(page).locator('[data-slot="sheet-close-button"]');
+    const closeBox = (await close.boundingBox())!;
+    expect(closeBox.width).toBeGreaterThanOrEqual(44);
+    expect(closeBox.height).toBeGreaterThanOrEqual(44);
+    await close.tap();
+    await expect(more(page)).toHaveCount(0);
+
+    // The keyboard path: open from the focused trigger, close with Escape.
+    await trigger.focus();
+    await page.keyboard.press("Enter");
+    await expect(more(page)).toBeVisible();
+    await expect(more(page)).toHaveAttribute("role", "dialog");
+    await expect(more(page)).toHaveAttribute("aria-modal", "true");
+    await expect(more(page)).toHaveAccessibleName(/more/i);
+    await expect
+      .poll(() =>
+        more(page).evaluate((el) => el.contains(document.activeElement)),
+      )
+      .toBe(true);
+    // Tab stays inside.
+    for (let i = 0; i < 14; i += 1) await page.keyboard.press("Tab");
+    expect(
+      await more(page).evaluate((el) => el.contains(document.activeElement)),
+    ).toBe(true);
+    await page.keyboard.press("Escape");
+    await expect(more(page)).toHaveCount(0);
+    await expect(trigger).toBeFocused();
+  });
+
+  test("the page behind keeps its scroll position and is never pulled to refresh", async ({
+    page,
+  }) => {
+    await page.goto("/");
+    const main = page.locator("#main-content");
+    await expect(main).toBeVisible();
+    await page.waitForTimeout(800);
+
+    // Watch for the refresh disc for the rest of the test.
+    await page.evaluate(() => {
+      (window as unknown as { ptrSeen: number }).ptrSeen = 0;
+      new MutationObserver(() => {
+        if (document.querySelector('[data-slot="pull-to-refresh-indicator"]')) {
+          (window as unknown as { ptrSeen: number }).ptrSeen += 1;
+        }
+      }).observe(document.body, { childList: true, subtree: true });
+    });
+    const ptrSeen = () =>
+      page.evaluate(() => (window as unknown as { ptrSeen: number }).ptrSeen);
+
+    // The control: the same pull on the page itself does arm the disc, so
+    // the watch above can see it (short of the refresh threshold).
+    await touchDrag(page, 195, 320, { dy: 90, ms: 400, holdMs: 120 });
+    await expect.poll(ptrSeen).toBeGreaterThan(0);
+    await page.waitForTimeout(300);
+    await page.evaluate(() => {
+      (window as unknown as { ptrSeen: number }).ptrSeen = 0;
+    });
+
+    // A pull on the sheet, short (it springs back) and long (it closes),
+    // from the dashboard at the top: the page behind never takes it.
+    await openMore(page);
+    const { x, y } = await centre(more(page).getByRole("heading").first());
+    await touchDrag(page, x, y, { dy: 60, ms: 400, holdMs: 150 });
+    await settled(more(page));
+    const { box } = await centre(more(page));
+    await touchDrag(page, x, y, { dy: box.height * 0.5, ms: 600, holdMs: 150 });
+    await expect(more(page)).toHaveCount(0);
+    expect(await ptrSeen()).toBe(0);
+
+    // Scrolled down, the page is where it was after the sheet has gone.
+    await main.evaluate((el) => el.scrollTo({ top: 400 }));
+    const before = await main.evaluate((el) => el.scrollTop);
+    expect(before).toBeGreaterThan(0);
+    await openMore(page);
+    const at = await centre(more(page).getByRole("heading").first());
+    const sheetBox = (await more(page).boundingBox())!;
+    await touchDrag(page, at.x, at.y, {
+      dy: sheetBox.height * 0.5,
+      ms: 600,
+      holdMs: 150,
+    });
+    await expect(more(page)).toHaveCount(0);
+    expect(await main.evaluate((el) => el.scrollTop)).toBe(before);
+    expect(await ptrSeen()).toBe(0);
+  });
+
+  test("the day opens on its preview step, rises on a pull up, and its content scrolls before it drags", async ({
+    page,
+  }) => {
+    // A short window, so the day's content is longer than its sheet on
+    // both steps and the body really scrolls.
+    await page.setViewportSize({ width: 390, height: 480 });
+    await page.goto(`/mood?day=${isoDaysAgo(3)}`);
+    const panel = page.locator('[data-slot="day-panel"]');
+    await expect(panel).toBeVisible();
+    await expect(panel).toHaveAttribute("data-shell", "bottom");
+    await expect(panel).toHaveAttribute("data-sheet-snap", "preview");
+    await settled(panel);
+    const viewport = page.viewportSize()!;
+
+    // On the preview step the footer stands on the window's bottom edge.
+    const footer = panel.locator('[data-slot="day-footer"]');
+    const footerBox = (await footer.boundingBox())!;
+    expect(
+      Math.abs(footerBox.y + footerBox.height - viewport.height),
+    ).toBeLessThan(2);
+
+    // A pull up on the content raises it to the full 90 dvh.
+    const body = panel.locator('[data-slot="day-body"]');
+    const b = await centre(body);
+    await touchDrag(page, b.x, b.y, { dy: -180, ms: 500, holdMs: 150 });
+    await expect(panel).toHaveAttribute("data-sheet-snap", "full");
+    await settled(panel);
+    expect(await topOf(panel)).toBeCloseTo(viewport.height * 0.1, -1);
+
+    // Scrolled content: a pull down scrolls (the browser's), the sheet stays.
+    const scrollable = await body.evaluate(
+      (el) => el.scrollHeight > el.clientHeight,
+    );
+    expect(scrollable).toBe(true);
+    await body.evaluate((el) => el.scrollTo({ top: 60 }));
+    const top = await topOf(panel);
+    const inner = await centre(body);
+    await touchDrag(page, inner.x, inner.y, {
+      dy: 260,
+      ms: 500,
+      holdMs: 150,
+    });
+    await settled(panel);
+    await expect(panel).toHaveAttribute("data-sheet-snap", "full");
+    expect(Math.abs((await topOf(panel)) - top)).toBeLessThan(1);
+
+    // At its very top the same pull drags the sheet: down to the preview
+    // step, and from there out.
+    await body.evaluate((el) => el.scrollTo({ top: 0 }));
+    await touchDrag(page, inner.x, inner.y - 60, {
+      dy: 150,
+      ms: 500,
+      holdMs: 150,
+    });
+    await expect(panel).toHaveAttribute("data-sheet-snap", "preview");
+    await settled(panel);
+    const grip = panel.locator('[data-slot="sheet-grip"]');
+    const g = await centre(grip);
+    await touchDrag(page, g.x, g.y, { dy: 300, ms: 600, holdMs: 150 });
+    await expect(panel).toHaveCount(0);
+    await expect(page).toHaveURL(/\/mood$/);
+  });
+
+  test("the grip is a button that switches the day's two heights", async ({
+    page,
+  }) => {
+    await page.goto(`/mood?day=${isoDaysAgo(3)}`);
+    const panel = page.locator('[data-slot="day-panel"]');
+    await expect(panel).toHaveAttribute("data-sheet-snap", "preview");
+    const grip = panel.locator('[data-slot="sheet-grip"]');
+    await expect(grip).toHaveAttribute("aria-expanded", "false");
+    await grip.tap();
+    await expect(panel).toHaveAttribute("data-sheet-snap", "full");
+    await expect(grip).toHaveAttribute("aria-expanded", "true");
+  });
+
+  test("a slider inside a sheet moves sideways and the sheet stays", async ({
+    page,
+  }) => {
+    await emulateCapture(page);
+    await page.goto("/mood");
+    await page.locator('[data-testid="bottom-nav-capture"]').tap();
+    await page.locator('[data-testid="capture-picker-symptom"]').tap();
+    const form = page.locator(
+      '[data-slot="responsive-sheet-content"][data-state="open"]',
+    );
+    await expect(form).toBeVisible();
+    await settled(form);
+    const slider = form.locator('[data-slot="slider"]').first();
+    await slider.scrollIntoViewIfNeeded();
+    await settled(form);
+    const top = await topOf(form);
+    const s = await centre(slider);
+    const thumb = form.locator('[role="slider"]').first();
+    const valueOf = async () =>
+      (await thumb.count()) ? thumb.getAttribute("aria-valuenow") : null;
+    const before = await valueOf();
+    // A sideways drag with a little vertical wobble, across the track.
+    await touchDrag(page, s.box.x + 8, s.y, {
+      dx: s.box.width * 0.7,
+      dy: 6,
+      ms: 400,
+    });
+    await expect.poll(valueOf).not.toBe(before);
+    await settled(form);
+    await expect(form).toBeVisible();
+    expect(Math.abs((await topOf(form)) - top)).toBeLessThan(1);
+  });
+
+  test("under reduced motion it opens without a slide", async ({ page }) => {
+    await page.emulateMedia({ reducedMotion: "reduce" });
+    await page.goto("/mood");
+    await page.locator('[data-testid="bottom-nav-more"]').tap();
+    await expect(more(page)).toBeVisible();
+    expect(
+      await more(page).evaluate(
+        (el) =>
+          el.getAnimations().filter((a) => a.playState === "running").length,
+      ),
+    ).toBe(0);
+  });
+});

e2e/central-codex.spec.ts

@@ -89,14 +89,6 @@ test.describe("central codex opt-in switch (mocked)", () => {
       }),
     );
 
-    await page.route("**/api/consent/ai/web", (route) =>
-      route.fulfill({
-        status: 200,
-        contentType: "application/json",
-        body: JSON.stringify({ data: { ok: true }, error: null }),
-      }),
-    );
-
     // The opt-in write — flips the mocked state so a re-read reflects it.
     await page.route("**/api/auth/me/use-central-codex", (route) => {
       useCentralCodex = true;

e2e/charts-mobile.spec.ts

@@ -4,7 +4,7 @@ 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.
+ * v1.4.19 — mobile-viewport regression spec for chart cards.
  *
  * Two assertions per chart visible in the dashboard's initial paint:
  *